Phase 2 start: worker scaffold, exit-code contract, provider-derived env allowlist

The worker is high-criticality (trust boundary, credentials, money), so it is built in
small verified slices. This first slice is the pure, security/money-critical core that
needs no GitHub App or Redis to test.

exit-code.mjs -- INT-RUNNER-EXIT-CODE-PROTOCOL from the worker's side. The container exit
code becomes BullMQ's throw-vs-return, which IS CONST-RETRY-INFRA-ONLY: only exit 1 (infra)
retries; 0 (agent ran, incl. "can't fix") and 2 (budget/policy) are determinate outcomes
that return. An unknown code is retried-then-visible, never silently accepted as done.

env-allowlist.mjs -- the container env is a CLOSED set, never a pass-through
(no-broad-env-into-container is a BLOCKER: ANTHROPIC_OAUTH_TOKEN silently outranks
ANTHROPIC_API_KEY, so one stray host var would redirect which credential every job spends).
The provider key variable is DERIVED from pi's own table via findEnvKeys(provider,
process.env), verified against the pinned pi-ai@0.80.7 tarball -- it returns the provider's
key var names PRESENT in the worker env, in precedence order (OAuth before API key), and
undefined when the provider is unconfigured, which becomes a pre-spend refusal. Deriving it
means any of pi's ~30 providers works with no code change and the list cannot drift when pi
adds one. A hand-copied table would be the reinvention no-reimplementing-pi forbids.

Tests: exit-code runs everywhere (no deps); env-allowlist imports pi-ai so it skips below
the 22.19 floor and CI sets PI_DISPATCH_REQUIRE_WORKER_TESTS=1 to make a skip a hard
failure. Verified with pi-ai actually present: 5/5 pass, and the allowlist forwards only the
provider key + declared vars, never a stray AWS_SECRET_ACCESS_KEY. CI paths and require flag
extended to cover worker/.

git-show materialisation of .pi/ (with the symlink/traversal guards sec-review flagged) and
the BullMQ processor follow, informed by research in flight.

Author: edgehero

.github/workflows/pi-upgrade-check.yml

@@ -18,12 +18,14 @@ on:
   push:
     paths:
       - "image/**"
+      - "worker/**"
       - "guardrails/**"
       - "package.json"
       - ".github/workflows/pi-upgrade-check.yml"
   pull_request:
     paths:
       - "image/**"
+      - "worker/**"
       - "guardrails/**"
       - "package.json"
       - ".github/workflows/pi-upgrade-check.yml"
@@ -78,9 +80,10 @@ jobs:
       # PI_DISPATCH_REQUIRE_LOADER_TESTS=1 turns a skip into a hard failure. A skipped assertion is
       # an UNVERIFIED assertion, and "skipped = pass" is precisely the reasoning that lets a
       # guardrail-less agent ship green.
-      - name: Guardrails present, hostile AGENTS.md absent, exit codes correct
+      - name: Contract tests -- guardrails, -nc, exit codes, env allowlist (all required)
         env:
           PI_DISPATCH_REQUIRE_LOADER_TESTS: "1"
+          PI_DISPATCH_REQUIRE_WORKER_TESTS: "1"
         run: npm test
 
   image:

package-lock.json

@@ -15,6 +15,6 @@
     "panel"
   ],
   "scripts": {
-    "test": "node --test \"image/runner/test/*.test.mjs\""
+    "test": "node --test \"image/runner/test/*.test.mjs\" \"worker/test/*.test.mjs\""
   }
 }

package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@pi-dispatch/worker",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "BullMQ worker: drains the queue, mints scoped tokens, runs one container per job.",
+  "license": "MIT",
+  "main": "src/index.mjs",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "scripts": {
+    "test": "node --test \"test/*.test.mjs\""
+  },
+  "dependencies": {
+    "@earendil-works/pi-ai": "0.80.7",
+    "@octokit/auth-app": "8.2.0",
+    "bullmq": "5.80.4"
+  }
+}

worker/package.json

@@ -0,0 +1,63 @@
+import { findEnvKeys } from "@earendil-works/pi-ai/compat";
+
+/**
+ * Build the EXACT environment a job container receives. Never a pass-through.
+ *
+ * `no-broad-env-into-container` is a BLOCKER, and for good reason: `ANTHROPIC_OAUTH_TOKEN`
+ * silently outranks `ANTHROPIC_API_KEY`, so one stray host variable would redirect which
+ * credential every job spends, with no error and no log line. So we forward a closed set.
+ *
+ * The provider key variable is DERIVED from pi's own table, not hardcoded. `findEnvKeys(provider,
+ * env)` returns the provider's key variable names that are actually PRESENT in `env`, in
+ * precedence order (OAuth before API key). Deriving it means:
+ *   - any of pi's ~30 providers works with no code change here;
+ *   - the list cannot drift when pi adds a provider (a hand-copied table would);
+ *   - `undefined` return === "this provider is not configured on this host" === refuse the job
+ *     BEFORE spending, rather than launch a container that will fail auth on the first call.
+ *
+ * `getApiKeyEnvVars` (the full candidate list) is intentionally NOT exported by pi; `findEnvKeys`
+ * against our own process.env is the right tool anyway, because we only ever forward keys we have.
+ */
+export function providerKeyVars(provider, hostEnv) {
+	return findEnvKeys(provider, hostEnv);
+}
+
+/**
+ * Assemble the container env. `hostEnv` is the worker's process.env; `job` carries the resolved
+ * config and the per-job scoped token (GitHub-backed jobs only).
+ *
+ * Throws if the provider is not configured -- a deterministic misconfiguration the caller maps to
+ * a pre-spend refusal, never a launched-then-failed container.
+ */
+export function buildContainerEnv({ provider, model, maxTurns, jobId, githubToken, hostEnv }) {
+	const keyVars = providerKeyVars(provider, hostEnv);
+	if (!keyVars || keyVars.length === 0) {
+		const error = new Error(`provider ${provider} has no configured credential in the worker environment`);
+		error.piDispatchConfig = true;
+		throw error;
+	}
+
+	const env = {
+		PI_PROVIDER: provider,
+		PI_MODEL: model,
+		PI_MAX_TURNS: String(maxTurns),
+		PI_JOB_ID: jobId,
+		// Baked into the image, but harmless to restate; kept here so the container contract is
+		// visible in one place. INT-CONTAINER-RUNTIME-CONTRACT.
+		PLAYWRIGHT_BROWSERS_PATH: "/ms-playwright",
+		PLAYWRIGHT_MCP_BROWSER: "chromium",
+		PLAYWRIGHT_MCP_SANDBOX: "false",
+	};
+
+	// The provider credential(s), by their real names, copied from the host by EXACT name. Passing
+	// the value under pi's expected variable name is what lets pi's own auth resolution find it.
+	for (const name of keyVars) {
+		env[name] = hostEnv[name];
+	}
+
+	// GitHub-backed jobs only. Local-folder jobs have no token (CONST-TOKEN-SCOPED-PER-JOB is
+	// scoped to GitHub jobs). Absent token => absent variable, never an empty one.
+	if (githubToken) env.GITHUB_TOKEN = githubToken;
+
+	return env;
+}

worker/src/env-allowlist.mjs

@@ -0,0 +1,32 @@
+/**
+ * INT-RUNNER-EXIT-CODE-PROTOCOL, worker side.
+ *
+ * The container's exit code is the ONLY channel telling "the agent ran and concluded something"
+ * from "the container died". The worker turns that into BullMQ's throw-vs-return, which IS
+ * CONST-RETRY-INFRA-ONLY: a thrown processor is retried, a returned one is not.
+ */
+export const EXIT_COMPLETED = 0; // agent ran, INCLUDING "I cannot fix this" -- a determinate success
+export const EXIT_INFRA = 1; // container died, network, provider 5xx/429 -- the only retryable class
+export const EXIT_POLICY = 2; // budget/turn cap/config -- a determinate refusal, never retried
+
+/**
+ * Decide whether the processor should RETURN (BullMQ records success, no retry) or THROW (BullMQ
+ * retries per `attempts`). Returns `{ retry }`; the caller returns on false and throws on true.
+ *
+ * Only exit 1 is retryable. 0 and 2 are both determinate outcomes -- the agent's verdict (or our
+ * own budget refusal) is the product, not a failure to paper over by paying for it again. An
+ * unknown code is treated as infra: a runner that exits with something we do not recognise is a
+ * runner we cannot reason about, and retrying-then-alerting beats silently accepting it as done.
+ */
+export function decideRetry(exitCode) {
+	switch (exitCode) {
+		case EXIT_COMPLETED:
+			return { retry: false, outcome: "completed" };
+		case EXIT_POLICY:
+			return { retry: false, outcome: "policy" };
+		case EXIT_INFRA:
+			return { retry: true, outcome: "infra" };
+		default:
+			return { retry: true, outcome: `unknown-exit-${exitCode}` };
+	}
+}

worker/src/exit-code.mjs

@@ -0,0 +1,79 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+// env-allowlist imports @earendil-works/pi-ai (for findEnvKeys). That needs node >=22.19.0 and
+// installed deps, so it skips on a below-floor dev box and runs in CI, where
+// PI_DISPATCH_REQUIRE_WORKER_TESTS=1 turns a skip into a hard failure. A skipped security test is
+// an unverified one -- the same discipline as the runner's loader tests.
+let mod;
+let importError;
+try {
+	mod = await import("../src/env-allowlist.mjs");
+} catch (error) {
+	importError = error;
+}
+if (!mod && process.env.PI_DISPATCH_REQUIRE_WORKER_TESTS === "1") {
+	throw new Error(`env-allowlist tests are REQUIRED here but pi-ai could not import.\n${importError}`);
+}
+const skip = mod ? false : `pi-ai not installed (node ${process.version} < 22.19.0); CI runs these`;
+const { buildContainerEnv, providerKeyVars } = mod ?? {};
+
+const HOST = {
+	ANTHROPIC_API_KEY: "sk-ant-real",
+	OPENAI_API_KEY: "sk-openai-real",
+	// The stray host variable no-broad-env-into-container exists to defend against:
+	AWS_SECRET_ACCESS_KEY: "must-not-leak",
+	HOME: "/root",
+	PATH: "/usr/bin",
+};
+
+test("derives the provider key var from the host env, in precedence order", { skip }, () => {
+	assert.deepEqual(providerKeyVars("anthropic", HOST), ["ANTHROPIC_API_KEY"]);
+	assert.deepEqual(providerKeyVars("openai", HOST), ["OPENAI_API_KEY"]);
+	// OAuth outranks API key -- the array order is the precedence.
+	assert.deepEqual(
+		providerKeyVars("anthropic", { ...HOST, ANTHROPIC_OAUTH_TOKEN: "oauth" }),
+		["ANTHROPIC_OAUTH_TOKEN", "ANTHROPIC_API_KEY"],
+	);
+});
+
+test("an unconfigured provider yields undefined (=> refuse before spend)", { skip }, () => {
+	assert.equal(providerKeyVars("google", HOST), undefined);
+});
+
+test("the container env is a CLOSED set: only the provider key, never the whole host", { skip }, () => {
+	const env = buildContainerEnv({
+		provider: "anthropic",
+		model: "claude-x",
+		maxTurns: 20,
+		jobId: "abc",
+		githubToken: "ghs_scoped",
+		hostEnv: HOST,
+	});
+	assert.equal(env.ANTHROPIC_API_KEY, "sk-ant-real");
+	assert.equal(env.GITHUB_TOKEN, "ghs_scoped");
+	assert.equal(env.PI_PROVIDER, "anthropic");
+	// The stray host secrets are NOT forwarded.
+	assert.equal(env.AWS_SECRET_ACCESS_KEY, undefined);
+	assert.equal(env.HOME, undefined);
+	assert.equal(env.OPENAI_API_KEY, undefined); // wrong provider's key not forwarded either
+});
+
+test("a local-folder job (no token) gets NO GITHUB_TOKEN var at all -- not an empty one", { skip }, () => {
+	const env = buildContainerEnv({
+		provider: "anthropic",
+		model: "m",
+		maxTurns: 5,
+		jobId: "j",
+		githubToken: undefined,
+		hostEnv: HOST,
+	});
+	assert.ok(!("GITHUB_TOKEN" in env), "absent token must mean absent variable");
+});
+
+test("an unconfigured provider throws a config-tagged error (=> pre-spend refusal)", { skip }, () => {
+	assert.throws(
+		() => buildContainerEnv({ provider: "google", model: "m", maxTurns: 5, jobId: "j", hostEnv: HOST }),
+		(e) => e.piDispatchConfig === true,
+	);
+});

worker/test/env-allowlist.test.mjs

@@ -0,0 +1,24 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { decideRetry, EXIT_COMPLETED, EXIT_INFRA, EXIT_POLICY } from "../src/exit-code.mjs";
+
+// INT-RUNNER-EXIT-CODE-PROTOCOL / CONST-RETRY-INFRA-ONLY. The whole point: only infra retries.
+
+test("exit 0 (agent ran, incl. 'can't fix') is success, NOT retried", () => {
+	assert.deepEqual(decideRetry(EXIT_COMPLETED), { retry: false, outcome: "completed" });
+});
+
+test("exit 2 (budget/policy) is determinate, NOT retried -- paying twice for a refusal is the bug", () => {
+	assert.equal(decideRetry(EXIT_POLICY).retry, false);
+});
+
+test("exit 1 (infra) is the ONLY retryable class", () => {
+	assert.equal(decideRetry(EXIT_INFRA).retry, true);
+});
+
+test("an unknown exit code is retried-then-visible, not silently accepted as done", () => {
+	// A runner we can't reason about must not be recorded as a clean success.
+	const d = decideRetry(137); // SIGKILL, e.g. OOM
+	assert.equal(d.retry, true);
+	assert.match(d.outcome, /unknown-exit-137/);
+});