@edgehero/pi-dispatch 0.1.0

package/src/processor.mjs

@@ -0,0 +1,360 @@
+import { checkTokenCap, recordTokenSpend, releaseBudget, reserveBudget } from "./budget.mjs";
+import { configError } from "./config.mjs";
+import { EXIT_COMPLETED, EXIT_INFRA, EXIT_POLICY } from "./exit-code.mjs";
+
+/**
+ * The job orchestration. Deliberately a pure-ish function over INJECTED side-effecting deps, so
+ * the money-safety ORDER can be tested without GitHub, Docker, or Redis.
+ *
+ * The order is the contract, and every step before `runContainer` must be free of provider spend:
+ *
+ *   0. refuse a job image this host does not have  -- INT-CONTAINER-RUNTIME-CONTRACT
+ *   1. mint a scoped token (GitHub jobs, and local jobs opted in via `github: true`)
+ *                                                 -- CONST-TOKEN-SCOPED-PER-JOB
+ *   2. REFUSE an unprotected default branch (GitHub jobs only -- a local job has no repo)
+ *                                                 -- REQ-BRANCH-PROTECTION-PRECONDITION
+ *   3. resolve the default-branch SHA (fresh API), clone at it, materialise .pi/, write the prompt
+ *   4. reserve a budget slot                      -- CONST-BUDGET-BEFORE-TOKENS
+ *   5. ONLY NOW run the container (the only step that spends provider tokens)
+ *   6. map the container exit code to retry-vs-success
+ *
+ * Budget is reserved as late as possible but strictly before the container, so a refusal from an
+ * earlier free gate (unprotected repo, clone failure) never consumes a daily slot. The container
+ * is the only thing that spends money, so "before tokens" means "before this line".
+ *
+ * Returns a result object on a non-retryable outcome; THROWS on a retryable (infra) one so BullMQ
+ * retries per `attempts`. The caller (the BullMQ processor) turns the thrown/returned distinction
+ * into the queue's retry behaviour -- that is INT-RUNNER-EXIT-CODE-PROTOCOL.
+ */
+export async function runJob(job, deps) {
+	const {
+		redis,
+		caps, // { day, week, month }; week/month null when that window is disabled (REQ-SPEND-CAPS-MULTI-WINDOW)
+		softHoldPct, // int 1-99 or null; the soft-hold band applied to every active window
+		tokenCap = null, // int or null; the daily TOKEN cap (issue #25). Check-AFTER, so it gates the NEXT job on prior spend
+		recordSpend = recordTokenSpend, // injected so the post-container INCRBY is testable/stubbable
+		// (job) => { ok } | { missing: <ref> } | { unavailable: <ref> }. The pre-spend check that the image
+		// this job names is on this host (image-preflight.mjs). Default admits everything, so a wiring that
+		// omits it behaves exactly as before -- the container's own failure stays the backstop.
+		imagePreflight = async () => ({ ok: true }),
+		// (session, { piVersion }) => { promoted, reason, bytes }. Promotes this job's transcript back into
+		// the store, on a COMPLETED exit only. Never throws. The default is a no-op so a wiring that omits
+		// it behaves exactly as before -- no store, no promotion, no session in the record.
+		promoteSession = () => null,
+		// (job) => scoped short-lived token. Takes the JOB, not the repo: which forge mints -- and therefore
+		// which credential the container gets -- is a property of `job.kind`, and only the wiring knows the
+		// map. Called for forge-backed jobs and for local jobs opted in via `github: true`; unflagged local
+		// jobs never mint (token stays null).
+		mintToken,
+		isDefaultBranchProtected, // (job, token) => boolean; same reason -- the forge is the job's, not the process's
+		prepareWorkspace, // (job, token) => { workspaceDir, jobDir }  (clone+materialise+prompt)
+		// runContainer({ job, token, prepared, name, signal }) => { code, aborted, turns, tokens, session, usage }. It MUST honour
+		// `signal`: stop the container on abort, and reject/exit promptly if `signal.aborted` is already
+		// true at entry (the timeout can fire during a slow prepare). The wiring injects name + signal.
+		runContainer,
+		cleanup, // (dirs) => void
+		comment, // (job, text) => void   (issue status; no-op for local jobs)
+		log = () => {},
+		// The outbox chain collector (INT-OUTBOX-CONTRACT). No-op default so a job whose wiring omits it --
+		// or a github job with no /outbox -- chains nothing. It NEVER throws (outbox.mjs), so its counts are
+		// additive telemetry that can never flip the parent's completed outcome (CONST-RETRY-INFRA-ONLY).
+		collectChain = async () => ({ enqueued: 0, refused: 0 }),
+		now = new Date(),
+	} = deps;
+
+	// "Forge-backed" is the negation of local, not an enumeration of forges: a job that is not editing a
+	// folder on this host is working against a remote, and every gate below applies for the same reason
+	// regardless of WHICH remote. Written this way so a new forge inherits the gates rather than having to
+	// be added to them -- the failure mode of an enumeration is a forge that silently skips a money gate.
+	const isForgeBacked = job.kind !== "local";
+	// A local job opted in via `github: true` (cron trigger opt-in, INT-TRIGGERS-FILE-CONTRACT) mints the
+	// same scoped per-job token the github path mints (CONST-TOKEN-SCOPED-PER-JOB). Unflagged local jobs
+	// stay tokenless, exactly as before.
+	const wantsForgeToken = isForgeBacked || job.github === true;
+	let token = null;
+	let prepared = null;
+	let reserved = false;
+
+	try {
+		// The job image must exist on THIS host before anything else happens. Free, determinate and
+		// credential-less, so it precedes the mint, the clone and the reservation: a host that cannot run the
+		// image refuses without minting a credential it will not use, cloning a repo it will not read, or
+		// burning a cap slot. Jobs run with --pull=never (docker-run.mjs), so an absent image is never
+		// fetched -- this refusal IS the whole diagnosis, not a race with a background pull.
+		const img = await imagePreflight(job);
+		// The image's declared pi version, read on the inspect the preflight already ran. Needed BEFORE the
+		// container starts, because a transcript written by a different pi may hold tool-call arguments the
+		// current schema no longer accepts -- so the resume has to be refused, not repaired mid-run. Null
+		// when the image declares none, which downstream means "never resume": the safe direction.
+		const piVersion = img.piVersion ?? null;
+		if (img.missing) {
+			await comment(job, `Refused: the job image "${img.missing}" is not present on the worker host. Not run.`);
+			log("refused_image_missing", { image: img.missing });
+			// The image ref is operator-authored config (PI_JOB_IMAGE), never payload, so naming it is PII-safe
+			// -- the same class as `repo` above.
+			// exitCode/turns/tokens null and budgetReserved false: refused pre-container AND pre-reserve.
+			// provider/model ride every terminal result from here down (INT-RUN-HISTORY-FILE-CONTRACT):
+			// runJob's `job` IS the effectiveJob (index.mjs), so these are the HOST-effective,
+			// overlay-resolved dispatch facts -- never anything a container printed -- and even a
+			// pre-container refusal attributes which (provider, model) it was dispatched for. There is
+			// deliberately NO `usage` key on the pre-container branches: no run, no ledger, and
+			// buildRecord defaults the absent field to null.
+			return { outcome: "policy", reason: "job-image-missing", exitCode: null, turns: null, tokens: null, provider: job.provider ?? null, model: job.model ?? null, budgetReserved: false }; // return => not retried
+		}
+		if (img.forgeUnsupported) {
+			// The image is present and says it cannot serve this forge -- it ships no CLI for it. Determinate,
+			// so a refusal rather than a retry, and pre-spend, because the alternative is a paid container
+			// that fails at step 3 on every single delivery with nothing to distinguish it from a bad run.
+			//
+			// The message names the LIKELY CAUSE rather than the label that detected it: a trigger that
+			// forgot `run.image`. The failure is upstream of the thing that noticed it, and an operator
+			// reading "the image does not declare azure" has further to walk than one reading "set run.image".
+			await comment(
+				job,
+				`Refused: the job image "${img.forgeUnsupported}" does not support ${img.kind} jobs (it declares: ${img.declared.join(", ")}). Set this trigger's \`run.image\` to an image that does. Not run.`,
+			);
+			log("refused_image_forge_unsupported", { image: img.forgeUnsupported, kind: img.kind, declared: img.declared });
+			return { outcome: "policy", reason: "job-image-forge-unsupported", exitCode: null, turns: null, tokens: null, provider: job.provider ?? null, model: job.model ?? null, budgetReserved: false }; // return => not retried
+		}
+		if (img.replicaUnsupported) {
+			// The image is present and does not declare replica support (REQ-REPLICA-RUNS), so its baked
+			// HARD_RULES.md predates the amendment and still hard-codes `pi/issue-<n>` as a SYSTEM rule --
+			// which the model treats as authoritative over the user prompt naming `pi/issue-<n>-r2`. Both
+			// replicas would push to one branch: not an error, just the push race the feature exists to
+			// avoid, with two runs billed and one pull request to show for it.
+			//
+			// Determinate, so a refusal rather than a retry, and pre-spend, because no version of this gets
+			// better by running. Like the forge branch above, the message names the FIX rather than the label
+			// that noticed it -- an operator reading "rebuild the image" is already where they need to be.
+			await comment(
+				job,
+				`Refused: the job image "${img.replicaUnsupported}" does not declare replica support (\`dev.pi-dispatch.capabilities\` ${img.declared.length > 0 ? `declares: ${img.declared.join(", ")}` : "is absent"}), so its baked guardrails would name the wrong branch. Rebuild the image from a version that has this feature. Not run.`,
+			);
+			log("refused_image_replicas_unsupported", { image: img.replicaUnsupported, declared: img.declared });
+			return { outcome: "policy", reason: "job-image-replicas-unsupported", exitCode: null, turns: null, tokens: null, provider: job.provider ?? null, model: job.model ?? null, budgetReserved: false }; // return => not retried
+		}
+		if (img.unavailable) {
+			// docker itself did not answer -- transient infra, NOT a determinate refusal. THROWN so BullMQ
+			// retries (CONST-RETRY-INFRA-ONLY). `container-never-started` is literally true here, and it reuses
+			// the refund path below: a no-op pre-reserve, and still honest if this gate ever moves.
+			// provider/model attribute even this pre-container death; no usage -- nothing ran to emit one.
+			throw new InfraRetry("docker unavailable, image preflight could not run", { reason: "container-never-started", provider: job.provider ?? null, model: job.model ?? null });
+		}
+
+		if (wantsForgeToken) {
+			token = await mintToken(job);
+
+			// Defense-in-depth at the DI seam: mintToken is injected, so we cannot assume it routed
+			// through get-token's own empty-token guard. An empty credential here would reach
+			// env-allowlist's `if (githubToken)` as a falsy value -> GITHUB_TOKEN omitted -> an
+			// anonymous paid run. Refuse before reserveBudget so a bad token burns no cap slot.
+			if (typeof token !== "string" || token.trim() === "") {
+				throw configError("mintToken returned an empty credential");
+			}
+		}
+
+		if (isForgeBacked) {
+			// REQ-BRANCH-PROTECTION-PRECONDITION. The agent's token can merge, so branch protection is the
+			// only technical barrier to a self-merge. Refuse before spending anything. Forge-backed jobs
+			// only: a local job has no remote branch to protect.
+			if (!(await isDefaultBranchProtected(job, token))) {
+				await comment(job, "Refused: the default branch is not protected. See SECURITY.md.");
+				log("refused_unprotected", { repo: job.repo });
+				// exitCode/turns/tokens null: refused pre-container, so no container exit, turn, or token count exists.
+				return { outcome: "policy", reason: "unprotected-branch", exitCode: null, turns: null, tokens: null, provider: job.provider ?? null, model: job.model ?? null, budgetReserved: false }; // return => not retried
+			}
+		}
+
+		prepared = await prepareWorkspace(job, token, { piVersion }); // resolves SHA, clones, materialises .pi/, writes prompt
+
+		// A determinate prepare refusal (e.g. sha-gone: the default branch advanced past the resolved
+		// tip) is POLICY -- return before reserveBudget so it burns no cap slot and is never retried.
+		// Mirrors the branch-protection policy return above. Spread-plus-attribution: the prepare
+		// result keeps its own reason and fields, and the host-effective provider/model land beside
+		// them exactly as on every other terminal result.
+		if (prepared?.outcome === "policy") {
+			return { ...prepared, provider: job.provider ?? null, model: job.model ?? null };
+		}
+
+		// Daily TOKEN cap (issue #25): the deliberate check-AFTER control. Token cost is only known
+		// post-run, so this cannot check-and-increment before the spend the way the job-count cap does
+		// (CONST-BUDGET-BEFORE-TOKENS). It is a read-only GET of prior jobs' recorded spend -- it consumes
+		// nothing, so it precedes reserveBudget's INCR and a refusal here burns no job-count slot. It can
+		// only stop the NEXT job once the day's accumulated spend has reached the cap; the actual INCRBY
+		// happens post-container via recordSpend. Reported before the job-count cap only because both are
+		// spend gates; the more-actionable branch-protection precondition is still reported first above --
+		// behind only the image check, which outranks it because a missing image blocks EVERY job of EVERY
+		// kind on this host, so it is the one the operator must fix first either way.
+		const tokenGate = await checkTokenCap(redis, { cap: tokenCap, now });
+		if (!tokenGate.allowed) {
+			await comment(job, `Over the daily token cap (${tokenGate.spent}/${tokenGate.cap} tokens). Not run.`);
+			log("over_token_budget", { spent: tokenGate.spent, cap: tokenGate.cap });
+			// budgetReserved false: refused before reserveBudget, so no job-count slot was consumed.
+			return { outcome: "policy", reason: "daily-token-cap", exitCode: null, turns: null, tokens: null, provider: job.provider ?? null, model: job.model ?? null, budgetReserved: false }; // return => not retried
+		}
+
+		// Budget last-but-before-container. A refusal here spends nothing (no container starts). Reserves across
+		// every active window (day + optional week/month) and the soft-hold band in one atomic pass.
+		const budget = await reserveBudget(redis, { caps, softHoldPct, now });
+		reserved = true;
+		if (!budget.allowed) {
+			const w = budget.blockedWindow;
+			const win = budget.windows[w];
+			if (budget.reason === "soft-hold") {
+				await comment(job, `Soft-hold: ${w} spend ${win.reserved}/${win.cap} is inside the ${softHoldPct}% hold band. New starts paused; not run.`);
+				log("soft_hold", { window: w, reserved: win.reserved, cap: win.cap, pct: softHoldPct });
+			} else {
+				await comment(job, `Over the ${w} budget cap (${win.cap}). Not run.`);
+				log("over_budget", { window: w, reserved: win.reserved, cap: win.cap });
+			}
+			// budgetReserved true: the slot is reserved above and kept (a refused reservation still counts). Both
+			// over-budget and soft-hold are POLICY, RETURNED (not retried) -- the agent never ran.
+			return { outcome: "policy", reason: budget.reason, exitCode: null, turns: null, tokens: null, provider: job.provider ?? null, model: job.model ?? null, budgetReserved: true }; // return => not retried
+		}
+
+		const { code, aborted, turns, tokens, session, usage } = await runContainer({ job, token, prepared });
+		log("container_exit", { exitCode: code, aborted });
+
+		// Record token spend post-run (the check-AFTER half of the lagging token cap). The container ran,
+		// so it spent real tokens on EVERY path that reaches here -- abort, completed, policy, AND the infra
+		// throws below (an exit-1 container still spent before failing). Record before classifying so all of
+		// them are accounted. Only when the cap is enabled (nothing reads the counter otherwise) and the run
+		// reported a positive total. NEVER throws: money is already spent, so a Redis blip here must not turn
+		// a completed paid job into a failure (mirrors the sink/comment/cleanup fault-isolation posture).
+		const tokensSpent = tokens?.total ?? 0;
+		if (tokenCap !== null && tokenCap !== undefined && tokensSpent > 0) {
+			await recordSpend(redis, tokensSpent, { now }).catch((err) => log("token_spend_error", { reason: err?.message }));
+		}
+
+		// A WORKER-initiated stop (30-min timeout via cancelJob, or graceful-shutdown docker stop) kills
+		// the container -> exit 143/137. That is our decision, not an infra fault: it is POLICY and must
+		// NOT retry, or a wedged job re-runs into a second PR / double spend. Keyed on the abort FLAG,
+		// not the code -- an unbidden 137 (kernel OOM) carries `aborted: false`, falls to the switch, and
+		// stays infra-retryable.
+		// exitCode/turns/tokens carry the container's own exit, turn count, and usage totals; budgetReserved true post-reserve.
+		if (aborted) return { outcome: "policy", reason: "worker-abort", exitCode: code, turns, tokens, provider: job.provider ?? null, model: job.model ?? null, session: mergeSession(prepared, session), budgetReserved: true };
+
+		switch (code) {
+			case EXIT_COMPLETED: {
+				// The SOLE chain-collection point. Read the completed parent's /outbox and enqueue children
+				// BEFORE the `finally` deletes jobDir -- the await resolves inside this case, so the read
+				// finishes before control leaves to cleanup. NOT reached on any other branch (policy, abort,
+				// over-budget, infra): an InfraRetry job is retried, so chaining there would double-enqueue.
+				// collectChain never throws; chainEnqueued/chainRefused are additive telemetry only.
+				const chain = await collectChain({ job, prepared });
+				// COMPLETED-ONLY PROMOTION, and the exclusivity is the point rather than an optimisation.
+				// A policy or infra exit leaves the canonical transcript byte-identical to what it was
+				// before this run, so a retry starts from exactly what the first attempt did -- promote on
+				// every exit and "retry" quietly stops meaning re-run and starts meaning continue
+				// (CONST-RETRY-INFRA-ONLY). Same completed-only rule INT-OUTBOX-CONTRACT already uses, and
+				// it sits beside the chain collection for the same reason: both must happen before the
+				// `finally` deletes jobDir. Never throws.
+				const promoted = prepared.session ? promoteSession(prepared.session, { piVersion }) : null;
+				return {
+					outcome: "completed",
+					exitCode: code,
+					turns,
+					tokens,
+					// The validated per-model ledger the sink rebuilt off the exit line (parseExitUsage), or
+					// null for a fallback-metered or pre-ledger runner. `?? null` keeps the result shape
+					// stable under an injected runContainer that predates the field.
+					usage: usage ?? null,
+					provider: job.provider ?? null,
+					model: job.model ?? null,
+					session: mergeSession(prepared, session, promoted),
+					budgetReserved: true,
+					chainEnqueued: chain.enqueued,
+					chainRefused: chain.refused,
+				};
+			}
+			case EXIT_POLICY:
+				// A policy exit still ran a paid container, so it carries the ledger like the completed
+				// branch does -- the spend is real whichever way the runner classified itself.
+				return { outcome: "policy", reason: "runner-policy", exitCode: code, turns, tokens, usage: usage ?? null, provider: job.provider ?? null, model: job.model ?? null, session: mergeSession(prepared, session), budgetReserved: true };
+			case EXIT_INFRA:
+				throw new InfraRetry(`infra failure, container exit ${code}`, { exitCode: code, turns, tokens, usage, provider: job.provider ?? null, model: job.model ?? null, session: mergeSession(prepared, session) });
+			case 125: // `docker run` itself failed (unusable image reference, bad flag)
+			case 126: // the entrypoint exists but is not executable
+			case 127: // the entrypoint was not found
+				// In all three docker never handed control to the runner, so NOTHING was spent -- which is
+				// exactly what `container-never-started` means, and it reuses the refund below rather than
+				// keeping a slot the agent never used. These used to fall to `default:`, which kept the slot
+				// AND retried, burning a second one. The preflight above converts the KNOWABLE case (an absent
+				// image) into a pre-spend policy refusal; a 125 that survives it is a race (the image was
+				// removed between the inspect and the run) or a docker-side fault we did not foresee --
+				// genuinely infra, and now with a retry that costs nothing.
+				throw new InfraRetry(`docker could not start the container, exit ${code}`, { reason: "container-never-started", exitCode: code, turns, tokens, usage, provider: job.provider ?? null, model: job.model ?? null, session: mergeSession(prepared, session) });
+			default:
+				throw new InfraRetry(`unknown container exit ${code}`, { exitCode: code, turns, tokens, usage, provider: job.provider ?? null, model: job.model ?? null, session: mergeSession(prepared, session) });
+		}
+	} catch (e) {
+		// A spawn fault (docker daemon down / binary missing) reserved a slot but never started a
+		// container, so nothing was spent -- give the slot back before the retry. Every other throw
+		// here (exit-1 infra, unknown exit) means the container ran and legitimately spent its slot,
+		// so `reason` gates the release to the never-started case only. Guarded on `reserved` and run
+		// once per invocation; a BullMQ retry reserves afresh, so this cannot double-release.
+		// budgetReserved reflects whether a slot stays spent: false when never-started refunds below,
+		// true for a real container that ran and spent (exit-1 infra / unknown exit).
+		if (e instanceof InfraRetry) e.budgetReserved = reserved && e.reason !== "container-never-started";
+		if (reserved && e instanceof InfraRetry && e.reason === "container-never-started") {
+			await releaseBudget(redis, { caps, now });
+		}
+		throw e;
+	} finally {
+		if (prepared) await cleanup(prepared).catch(() => {});
+	}
+}
+
+/** Thrown for the retryable (infra) class only. The BullMQ processor lets this propagate to retry. */
+/**
+ * The one `session` object the run record carries, from the host's intent and the container's report
+ * (INT-RUN-HISTORY-FILE-CONTRACT).
+ *
+ * Both halves matter and neither is sufficient. The host knows whether a key resolved and which gate
+ * refused; only the container knows what pi actually did with the file it was handed. A host that staged
+ * a transcript while the runner reports `resumed: false` is a real event -- a corrupt file, a degrade --
+ * and with one number alone it is indistinguishable from an ordinary cold start.
+ *
+ * The runner's verdict WINS on `resumed`, because it is the one that observed the outcome. The host's
+ * reason is kept when the runner has none to give (a container that died before its exit line).
+ *
+ * PII-free by construction: a boolean, a fixed enum, an integer. The key and the branch name are
+ * deliberately absent -- this record holds no attacker-chosen string, and a branch name is one.
+ */
+function mergeSession(prepared, fromRunner, promoted = null) {
+	const host = prepared?.session;
+	if (!host && !fromRunner) return null;
+	return {
+		resumed: fromRunner ? fromRunner.resumed : false,
+		// A promotion that was refused is the more useful reason to surface: "locked" or
+		// "not-a-regular-file" says why the NEXT run will cold-start, which is the thing an operator
+		// chasing "it never resumes" needs. It only ever replaces a reason on the completed path.
+		reason: (promoted && !promoted.promoted ? promoted.reason : null) ?? fromRunner?.reason ?? host?.reason ?? null,
+		bytes: promoted?.bytes ?? host?.bytes ?? null,
+	};
+}
+
+export class InfraRetry extends Error {
+	constructor(message, { cause, reason, exitCode, turns, tokens, session, usage, provider, model, budgetReserved } = {}) {
+		super(message, cause ? { cause } : undefined);
+		this.name = "InfraRetry";
+		this.piDispatchRetry = true;
+		this.reason = reason ?? message;
+		this.exitCode = exitCode ?? null;
+		this.turns = turns ?? null;
+		this.tokens = tokens ?? null;
+		// A deliberate in-passing repair: the EXIT_INFRA throw has passed `session` since the resume
+		// feature landed, but this destructure never read it, so every infra-retry record silently
+		// recorded session:null and a degrade seen only on a retried attempt left no trace. Latent
+		// because buildRecord's `?? null` made the drop indistinguishable from an honest absence.
+		this.session = session ?? null;
+		// The usage-ledger trio (INT-RUN-HISTORY-FILE-CONTRACT): carried on the throw path so a
+		// catch-path record attributes exactly what the return path would have.
+		this.usage = usage ?? null;
+		this.provider = provider ?? null;
+		this.model = model ?? null;
+		this.budgetReserved = budgetReserved ?? null;
+	}
+}
+
+export { EXIT_COMPLETED, EXIT_INFRA, EXIT_POLICY };

package/src/queue.mjs

@@ -0,0 +1,152 @@
+import { Queue } from "bullmq";
+import { chainedJobId, localJobId, deliveryJobId, gitlabDeliveryJobId, forgeDeliveryJobId } from "./job-id.mjs";
+import { targetSeparator } from "./forges.mjs";
+
+export const QUEUE = "pi-jobs";
+export { chainedJobId, localJobId, deliveryJobId, gitlabDeliveryJobId, forgeDeliveryJobId };
+
+export function makeQueue(connection) {
+	return new Queue(QUEUE, { connection });
+}
+
+/**
+ * Enqueue a local-folder job. Returns the jobId. The data shape is what the processor's runJob
+ * consumes (kind/folder/flow/task/provider/model/maxTurns).
+ *
+ * removeOnComplete keeps the dedup window ~= the retention. Unlike webhooks, local jobs are not
+ * redelivered, so a modest window is enough.
+ */
+export async function enqueueLocalJob(queue, { folder, flow, task, provider, model, maxTurns, image, chainDepth, parentJobId, jobId, now = new Date() }) {
+	const minute = now.toISOString().slice(0, 16); // YYYY-MM-DDTHH:MM -- the dedup window
+	// A caller-supplied jobId (the outbox collector's retry-idempotent chainedJobId) wins; otherwise the
+	// minute-windowed localJobId is the dedup key.
+	const id = jobId ?? localJobId({ folder, flow, task, minute });
+	// image/chainDepth/parentJobId land on `data` only when present, so a plain non-chained job's data is
+	// byte-identical. `image` is the container image this job runs in (INT-TRIGGERS-FILE-CONTRACT); absent
+	// resolves the deployment default at job start, never a value frozen here.
+	const data = {
+		kind: "local",
+		folder,
+		flow,
+		task,
+		provider,
+		model,
+		maxTurns,
+		...(image !== undefined && { image }),
+		...(chainDepth !== undefined && { chainDepth }),
+		...(parentJobId !== undefined && { parentJobId }),
+	};
+	await queue.add("local", data, {
+		jobId: id,
+		attempts: 2,
+		backoff: { type: "exponential", delay: 60_000 },
+		removeOnComplete: { age: 24 * 3600 },
+		removeOnFail: { age: 7 * 24 * 3600 },
+	});
+	return id;
+}
+
+// Coalesces rapid re-label spam; the GUID jobId + 31d retention handle exact redelivery, so this
+// window only needs to absorb burst re-labels, not the full redelivery window.
+const SEMANTIC_WINDOW_MS = 10 * 60 * 1000;
+
+/**
+ * Enqueue a GitHub-triggered job. Returns the jobId. The data shape is what prepare/runJob consumes
+ * for the github kind. No `sha` field: the commit is resolved fresh in prepare (C1), so baking a
+ * possibly-stale sha here would only race the branch head.
+ *
+ * `target` is the discriminated subject of the job -- `{ type:"issue"|"pull_request", number, title,
+ * body, ... }` -- built by the receiver's filter from the INT-WEBHOOK-PAYLOAD-SUBSET fields. Its `number`
+ * keys the semantic dedup window; GitHub issues and PRs share one per-repo number sequence, so the key is
+ * collision-free without encoding the type. That is a fact about GitHub, not about forges -- see
+ * `enqueueGitLabJob`, where they are separate sequences and the type has to be in the key.
+ *
+ * Two dedup layers, ADDITIVE and independent:
+ *   - `jobId` (the delivery GUID) is exact-per-delivery: a redelivered webhook resolves to the same
+ *     id and BullMQ's `EXISTS jobId` rejects it -- REQ-DEDUP-BY-DELIVERY-GUID.
+ *   - `deduplication` keys on `repo#number:flow` for SEMANTIC_WINDOW_MS: distinct GUIDs from rapid
+ *     re-labels or repeated PR pushes coalesce to one active job. It coexists with jobId; it does not
+ *     replace it.
+ */
+export async function enqueueGitHubJob(queue, fields) {
+	return await enqueueForgeJob(queue, "github", fields);
+}
+
+/**
+ * Enqueue a GitLab-triggered job. Structurally the twin of `enqueueGitHubJob` -- and now literally the
+ * same body, because everything that differs between them turned out to be two table entries.
+ *
+ * `projectId` rides the data because every GitLab API path the worker needs takes the numeric project id.
+ * A GitLab project path is `group/subgroup/project` with no fixed segment count, so the `owner/name` split
+ * the GitHub path uses does not merely fail on one, it SUCCEEDS wrongly: both halves come back non-empty
+ * and the project silently becomes its own parent group. Carrying the id sidesteps the grammar entirely;
+ * `repo` stays as the human-readable label for logs, run history and pause-window scopes.
+ */
+export async function enqueueGitLabJob(queue, fields) {
+	return await enqueueForgeJob(queue, "gitlab", fields);
+}
+
+/**
+ * Enqueue a forge-triggered job of any kind. Returns the jobId.
+ *
+ * The two named wrappers above are spellings of this. They were separate bodies until a third and fourth
+ * forge made that four copies of the retention window, the retry policy, the backoff and BOTH dedup
+ * layers -- four places for one of them to be quietly weakened while every test stayed green.
+ *
+ * The semantic dedup key encodes the TARGET TYPE through `targetSeparator`, which GitHub alone does not
+ * need: it numbers issues and pull requests from one per-repo sequence, so `repo#7` names exactly one
+ * thing. GitLab numbers them separately, so issue #5 and merge request !5 would collide on `project#5:flow`
+ * -- one silently coalescing into the other's 10-minute window and never running. The separator is each
+ * forge's own notation, and it lives in the table because it is a fact about the forge.
+ *
+ * Forge-specific data fields are listed EXPLICITLY rather than collected with a rest spread. A spread
+ * would persist whatever a caller happened to pass into durable job data, and this object is copied
+ * verbatim into `/job/event.json` -- a place where an unreviewed field has no business.
+ *
+ * REPLICAS (REQ-REPLICA-RUNS) are the one case where one delivery becomes more than one job, and BOTH dedup
+ * layers have to be told, not just the id. The caller loops and passes `replica` 1..N; each pass is an
+ * ordinary enqueue with a distinct id and a distinct semantic key. The `replica` suffix on the dedup id is
+ * added ONLY when a replica is set, so re-deliveries of each replica still coalesce within the 10-minute
+ * window, replicas never coalesce against each other, and an unflagged job's dedup id is the same string it
+ * has always been.
+ */
+export async function enqueueForgeJob(queue, kind, { repo, projectId, azure, target, flow, trigger, provider, model, maxTurns, packages, image, resume, replica, replicas }) {
+	const jobId = forgeDeliveryJobId(kind, trigger?.deliveryId, replica);
+	// `packages` (whether to load the operator-staged pi packages) and `image` (which container image to run)
+	// come off the MATCHED trigger (INT-TRIGGERS-FILE-CONTRACT / REQ-GLOBAL-PI-OVERLAY) and land on `data`
+	// only when the filter resolved one, exactly like chainDepth/parentJobId above, so an unflagged trigger's
+	// job data is byte-identical. Both sit at JOB level, never inside `trigger` -- that object is descriptive
+	// and is copied verbatim into /job/event.json, where an execution knob has no business.
+	const data = {
+		kind,
+		repo,
+		...(projectId !== undefined && { projectId }),
+		// Azure's org/project/repository triple, alongside the human-readable `repo` -- the same split gitlab
+		// makes with `projectId`, and for the same reason: every Azure API path takes ids and names this label
+		// cannot be reassembled into without guessing.
+		...(azure !== undefined && { azure }),
+		target,
+		flow,
+		trigger,
+		provider,
+		model,
+		maxTurns,
+		...(packages !== undefined && { packages }),
+		...(image !== undefined && { image }),
+		...(resume !== undefined && { resume }),
+		// Conditional for the same reason packages/image/resume are: an unflagged job's data must keep
+		// exactly the keys it has today. `replica` is this job's 1-based index and `replicas` the set size;
+		// both are integers, so the run record they land in stays PII-free by construction.
+		...(replica !== undefined && { replica }),
+		...(replicas !== undefined && { replicas }),
+	};
+	await queue.add(kind, data, {
+		jobId,
+		deduplication: { id: `${repo}${targetSeparator(kind, target?.type)}${target.number}:${flow}${replica !== undefined ? `:r${replica}` : ""}`, ttl: SEMANTIC_WINDOW_MS }, // ttl in ms
+		attempts: 2,
+		backoff: { type: "exponential", delay: 60_000 },
+		removeOnComplete: { age: 31 * 24 * 3600 }, // age in seconds -- do not cross units with the ms ttl above
+		removeOnFail: { age: 31 * 24 * 3600 },
+	});
+	return jobId;
+}

package/src/run-container.mjs

@@ -0,0 +1,133 @@
+import { spawn } from "node:child_process";
+import { buildDockerRunArgs, CONTAINER_SESSION_FILE } from "./docker-run.mjs";
+import { buildContainerEnv } from "./env-allowlist.mjs";
+import { resolveJobImage } from "./image-preflight.mjs";
+import { InfraRetry } from "./processor.mjs";
+
+/**
+ * The real `runContainer` the processor injects. Launches one job container and returns
+ * `{ code, aborted, turns, tokens, session, usage }`, where `aborted` records whether the WORKER initiated the stop (docker stop on
+ * the 30-min timeout or graceful shutdown), which the processor classifies as POLICY (no retry) per
+ * INT-RUNNER-EXIT-CODE-PROTOCOL. The numeric `code` alone cannot say this: a worker SIGKILL and a
+ * kernel OOM both surface as 137, so the abort FLAG -- not the code -- is the discriminator.
+ *
+ * `spawn` (not execFile) because a non-zero exit is NORMAL here: exit 1 (infra) and 2 (policy) are
+ * expected outcomes, not errors to reject on. The exit code comes from the `close` event.
+ *
+ * The container is stopped on abort by the worker wiring (index.mjs onAbort -> docker stop), which
+ * causes `docker run` to exit and this promise to resolve. We only handle the entry case here: if
+ * the signal is ALREADY aborted (the 30-min timeout fired during a slow prepare), do not start a
+ * container at all.
+ *
+ * Output is streamed to `onOutput` (default: the worker's stdout) so the operator watches the agent
+ * work on their own machine -- the natural local UX. When raw capture is enabled
+ * (`PI_CAPTURE_JOB_LOGS`), the same output is tee'd to a host-only, gitignored `logs/<jobId>.log`
+ * that is never mounted into the container and may contain agent-echoed issue text (PII). The
+ * worker's event log and the `.json` status record stay id-only.
+ */
+export function makeRunContainer({
+	image, // the DEPLOYMENT default (PI_JOB_IMAGE); a trigger's own run.image overrides it per job
+	hostEnv = process.env,
+	onOutput = (c) => process.stdout.write(c),
+	openJobLog = () => ({ write() {}, close: async () => ({ turns: null, tokens: null, session: null, usage: null }) }),
+	spawnFn = spawn,
+	globalPiDir = null, // REQ-GLOBAL-PI-OVERLAY: operator's global pi overlay dir, mounted :ro; null = off
+	allowGlobalExtensions = true, // REQ-GLOBAL-PI-OVERLAY: the staged overlay's extensions load unless PI_GLOBAL_ALLOW_EXTENSIONS=0
+	packagePaths = [], // REQ-GLOBAL-PI-OVERLAY: container paths of the operator-staged packages, resolved once at boot
+	forwardEnv = [],
+	authFromPi = false, // fall back to ~/.pi/agent/auth.json for the provider key when the env has none
+	forgeHosts = {}, // per-forge self-hosted instance URLs, so a forge CLI in the container talks to the right one
+}) {
+	// async so a synchronous throw (e.g. buildContainerEnv on an unconfigured provider) surfaces as
+	// a rejection, uniformly awaitable by the processor and by tests.
+	return async function runContainer({ job, token, prepared, name, signal }) {
+		if (signal?.aborted) return { code: 137, aborted: true, turns: null, tokens: null, session: null, usage: null }; // killed before it could start
+
+		// Closed env allowlist: only the provider key + the declared PI_* vars. Throws (config) if
+		// the provider is unconfigured -- the processor turns that into a pre-spend refusal.
+		const env = buildContainerEnv({
+			provider: job.provider,
+			model: job.model,
+			maxTurns: job.maxTurns,
+			maxTokens: job.maxTokens, // optional per-job token budget (issue #25); undefined => runner meter only
+			jobId: name,
+			githubToken: token ?? undefined,
+			// Which forge minted it, so the token lands in that forge's own variable names and no other.
+			forgeKind: job?.kind,
+			forgeHosts,
+			hostEnv,
+			allowGlobalExtensions, // REQ-GLOBAL-PI-OVERLAY: false emits the explicit PI_GLOBAL_ALLOW_EXTENSIONS=0 opt-out
+			// REQ-GLOBAL-PI-OVERLAY: the per-job value comes off `job` (like maxTurns), the staged set off
+			// the closure (like allowGlobalExtensions) -- so a trigger can withhold what the operator staged.
+			// `!== false`, because staged packages LOAD unless a trigger explicitly opts out
+			// (INT-TRIGGERS-FILE-CONTRACT). The strictness that used to live in this `=== true` did not
+			// disappear, it moved: parseTriggers refuses any non-boolean run.packages fail-loud at load, so a
+			// hand-edited string "false" never becomes job data this comparison could misread as an opt-out.
+			packagePaths: job.packages === false ? [] : packagePaths,
+			forwardEnv, // extra host var names to forward (e.g. a custom provider's key)
+			// REQ-RESUMABLE-SESSION: the fixed container path, emitted only when this job HAS a transcript.
+			// The constant is imported rather than re-typed so the mount below and this variable name one
+			// path -- two literals is how they drift with both suites green.
+			sessionFile: prepared.session ? CONTAINER_SESSION_FILE : undefined,
+			authFromPi, // source the provider key from pi's auth.json when the env has none
+		});
+
+		const args = buildDockerRunArgs({
+			// Same split as packagePaths above: the per-job value off `job`, the deployment value off the closure,
+			// so a trigger can name its own toolchain (INT-TRIGGERS-FILE-CONTRACT). Resolved through the SAME
+			// function the pre-spend preflight uses (image-preflight.mjs), so the tag that was checked is the tag
+			// that runs -- one answer by construction, not two call sites that happen to agree.
+			image: resolveJobImage(job, image),
+			env,
+			jobDir: prepared.jobDir,
+			workspace: prepared.workspace,
+			outboxDir: prepared.outboxDir, // undefined for github jobs -> docker-run's guard skips the /outbox mount
+			// The job's OWN copy, under jobDir -- never the shared store. Undefined when the trigger did not
+			// arm run.resume or no key resolved, and docker-run's guard then skips the mount entirely.
+			sessionDir: prepared.session?.hostDir,
+			globalPiDir, // undefined/null -> docker-run's guard skips the /opt/pi-global mount
+			name,
+		});
+
+		// Host-side per-job log sink, teed off `onOutput`. `name` is `pi-job-<jobId>`; the sink
+		// sanitizes internally. No container mount, no env var -- the sink lives on this side only.
+		const sink = openJobLog(name);
+
+		return await new Promise((resolve, reject) => {
+			const child = spawnFn("docker", args, { stdio: ["ignore", "pipe", "pipe"] });
+			// A throwing sink.write is swallowed so a misbehaving sink cannot break the tee or hang the run.
+			const tee = (chunk) => {
+				onOutput(chunk);
+				try {
+					sink.write(chunk);
+				} catch {}
+			};
+			child.stdout?.on("data", tee);
+			child.stderr?.on("data", tee);
+			// docker not found / daemon down -- a transient infra fault, so tag it retryable
+			// (CONST-RETRY-INFRA-ONLY). `reason` also cues the processor to release the budget slot,
+			// since a container that never started spent nothing.
+			child.on("error", (err) => {
+				sink.close().catch(() => {}); // best-effort teardown; a rejecting close cannot leak an unhandled rejection
+				reject(new InfraRetry("container-never-started", { cause: err, reason: "container-never-started" }));
+			});
+			child.on("close", async (code) => {
+				const aborted = signal?.aborted === true; // capture BEFORE the await
+				// A rejecting sink.close is swallowed so a misbehaving sink cannot hang the run; turns/tokens/session/usage fall back to null.
+				let turns = null;
+				let tokens = null;
+				let session = null;
+				let usage = null;
+				try {
+					({ turns, tokens, session, usage } = await sink.close());
+				} catch {
+					turns = null;
+					tokens = null;
+					session = null;
+					usage = null;
+				}
+				resolve(aborted ? { code: code ?? 137, aborted: true, turns, tokens, session, usage } : { code: code ?? 1, aborted: false, turns, tokens, session, usage });
+			});
+		});
+	};
+}