@edgehero/pi-dispatch 1.9.0 → 1.10.0

package/src/config.mjs

@@ -8,6 +8,7 @@
 import { existsSync } from "node:fs";
 import { hostname } from "node:os";
 import { delimiter } from "node:path";
+import { DEFAULT_BACKEND, backendRefusals, parseBackendFloor, parseBackendList } from "./backends.mjs";
 import { DEFAULT_EGRESS_PROXY, egressArmed } from "./egress.mjs";
 import { MINTED_TOKEN_VARS } from "./forges.mjs";
 import { parseSecretProfiles } from "./secret-profiles.mjs";
@@ -158,6 +159,47 @@ function egressEnabled(env) {
 	}
 }
 
+/**
+ * PI_BACKENDS and PI_BACKEND_FLOOR (issue #227). Both parse in `backends.mjs` for `egressEnabled`'s reason
+ * directly above: `doctor` reads the environment itself, and three copies of one grammar is two chances to
+ * disagree about what an operator's floor says. Here they gain the `piDispatchConfig` tag only.
+ *
+ * ENV-ONLY, never the overlay and never the deployment pointer, on `secretResolverRoots`' rule: a bound
+ * that can be widened from the surface it bounds is not a bound. The pointer needs no edit to enforce it --
+ * `POINTER_ENV_ALLOWLIST` is an ALLOWLIST (of the path and URL variables `resolvePaths` reads), so a
+ * name absent from it is refused by omission, and a capability grant is never added to it.
+ */
+function backendSet(env) {
+	try {
+		return parseBackendList(env.PI_BACKENDS);
+	} catch (error) {
+		throw configError(error.message);
+	}
+}
+
+function backendFloorOf(env) {
+	try {
+		return parseBackendFloor(env.PI_BACKEND_FLOOR);
+	} catch (error) {
+		throw configError(error.message);
+	}
+}
+
+/**
+ * THE BOOT REFUSAL. A deployment whose configuration needs something its backends cannot provide is refused
+ * here, named backend by named property, rather than discovering it per job.
+ *
+ * The RULES live in `backends.mjs` as a pure function over an explicit backend list; this only re-tags them
+ * so the CLI prints them cleanly, which is `egressEnabled`'s arrangement. That split is not tidiness: a
+ * rule reachable only through `loadConfig` can only be exercised with backend names `parseBackendList`
+ * accepts, and there is exactly one today, so three of these rules survived a mutation pass unprotected
+ * while living here.
+ */
+function refuseBackendShortfall(config) {
+	const [first] = backendRefusals(config);
+	if (first) throw configError(first);
+}
+
 // The operator's global pi overlay dir (REQ-GLOBAL-PI-OVERLAY). Unset/empty = feature off. When set it
 // must EXIST at boot -- a typo pointing at nothing would silently drop the operator's whole setup on
 // every job, so fail loud like every other config error rather than degrade to nothing.
@@ -211,7 +253,12 @@ export function globalExtensionsEnabled(env) {
  */
 export function loadConfig(env = process.env, { fileExists = existsSync } = {}) {
 	const model = env.PI_MODEL ?? "claude-sonnet-4-5-20250929"; // dated snapshot; deterministic per CONST-PI-VERSION-PINNED
-	return {
+	// #227. Hoisted above the object because `defaultBackend` INDEXES `backends`, and a property cannot read
+	// a sibling of the literal it is in. (Calling the parser twice would be harmless -- `egressEnabled` is
+	// called twice a few properties down for the same reason -- so this is about the index, not the throw.)
+	const backends = backendSet(env);
+	const backendFloor = backendFloorOf(env);
+	const config = {
 		valkeyUrl: env.VALKEY_URL ?? "redis://127.0.0.1:6379",
 		// Issue #57. What this machine calls itself: the key of its registry row, the `host` on every log
 		// line and run record, and the BullMQ worker name. Always populated -- a deployment that declares
@@ -238,6 +285,15 @@ export function loadConfig(env = process.env, { fileExists = existsSync } = {})
 		// per-job network is built around. Read BEFORE forwardEnv below, because the forward list's refusal
 		// of the proxy variables is conditional on it.
 		egress: egressEnabled(env),
+		// #227. The blessed set and the minimum every member of it must declare. The default set is the one
+		// name every existing deployment is already running, so an operator who has never heard of either
+		// variable gets exactly what they had.
+		backends,
+		backendFloor,
+		// The FIRST blessed name, which is what a deployment means by "the one my jobs run on unless a
+		// trigger says otherwise". `parseBackendList` never returns empty, so the fallback is belt-and-braces
+		// against a future edit rather than a reachable branch today.
+		defaultBackend: backends[0] ?? DEFAULT_BACKEND,
 		egressProxy: env.PI_EGRESS_PROXY || DEFAULT_EGRESS_PROXY, // || (not ??) so an empty string falls back
 		forwardEnv: forwardEnvList(env.PI_FORWARD_ENV, egressEnabled(env)), // extra host var NAMES to forward (e.g. a custom provider's key); explicit allowlist, GitHub token names refused
 		authFromPi: env.PI_AUTH_FROM_PI !== "0", // ON by default: use the key in ~/.pi/agent/auth.json when the env has none (api-key only). PI_AUTH_FROM_PI=0 forces env-only.
@@ -344,6 +400,12 @@ export function loadConfig(env = process.env, { fileExists = existsSync } = {})
 		forgejo: loadForgejoAuth(env),
 		azure: loadAzureAuth(env),
 	};
+
+	// #227, and it runs AFTER the object is built rather than inside it: the refusal reads `egress` as well
+	// as the two backend fields, and a check woven between properties would depend on key order.
+	refuseBackendShortfall(config);
+
+	return config;
 }
 
 /**

package/src/container-spec.mjs

@@ -0,0 +1,226 @@
+/**
+ * WHAT the box is, with no Docker vocabulary in it (issue #227).
+ *
+ * This module is the half of `INT-CONTAINER-RUNTIME-CONTRACT` that is not about Docker: the container-side
+ * paths a job always sees, and the value that describes one container before any runtime spells it. The
+ * other half -- `ISOLATION_FLAGS`, `dockerArgsFromSpec` -- stays in `docker-run.mjs`, which re-exports
+ * everything below so no call site moved. Two modules import from here directly: `docker-run.mjs` for the
+ * spec builder, and `packages.mjs` for `CONTAINER_GLOBAL_PI_DIR`. The second one is the one to keep in mind
+ * when editing this file, because it is the reason the leaf property below is load-bearing.
+ *
+ * WHY IT IS ITS OWN FILE NOW AND WAS NOT BEFORE. Issue #261 split the spec from the argv but deliberately
+ * kept both in one file, and said exactly what would change that:
+ *
+ *   "Rejected: a separate `container-spec.mjs`, which would have ... added an import edge before a second
+ *    consumer exists; the split here is by function, and the move to its own module belongs to the PR that
+ *    adds one."
+ *
+ * This is that PR. The second consumer is the backend seam: a backend that is not the local Docker daemon
+ * consumes a spec and never produces a Docker argv, so the description of a container has to be reachable
+ * without reaching the argv builder. Nothing about the value changed in the move -- same fields, same
+ * order, same guards -- because a byte-identical local deployment is #227's first constraint.
+ *
+ * It imports NOTHING, which is the property `packages.mjs` depends on when it derives the staged-packages
+ * root from `CONTAINER_GLOBAL_PI_DIR` rather than re-typing the path.
+ */
+
+/**
+ * Where the operator's global pi overlay lands INSIDE the container (REQ-GLOBAL-PI-OVERLAY). Exported
+ * because packages.mjs derives the staged-packages root from it: the mount and that root are ONE fact on
+ * one side of the boundary, and two literals in two modules could drift apart with both test suites still
+ * green. A Linux container path, so it is always built with "/" -- never `path.join`, which yields
+ * backslashes when the worker itself runs on Windows.
+ */
+export const CONTAINER_GLOBAL_PI_DIR = "/opt/pi-global";
+
+/**
+ * The session mount and the file inside it, exported together and used by both the argv builder in
+ * docker-run.mjs and the env builder in env-allowlist.mjs. Two literals in two modules is how a mount and
+ * the variable naming a path inside it drift apart with both suites green -- the runner would then look for
+ * a transcript at a path nothing mounted, find none, and cold-start every job without saying so.
+ *
+ * Nothing key-derived crosses the boundary: the container always sees the same constant path, so no
+ * repository name, no branch name and no host layout is legible from inside a job.
+ */
+export const CONTAINER_SESSION_DIR = "/session";
+export const CONTAINER_SESSION_FILE = `${CONTAINER_SESSION_DIR}/current.jsonl`;
+
+/**
+ * WHAT the box is, with no Docker vocabulary in it.
+ *
+ * Split from the argv builder so the description of a container exists as a VALUE before it becomes one
+ * runtime's flags. `buildDockerRunArgs` is unchanged in name, signature and output -- it is
+ * `dockerArgsFromSpec(containerSpec(opts))` -- so every caller and every assertion is untouched, and the
+ * only thing that is new is that the middle of that sentence can be read on its own.
+ *
+ * Mounts are structured (`{host, container, readOnly}`) rather than pre-flattened `host:container:ro`
+ * strings, because the flattening IS the Docker part: a runtime that does not bind-mount has to be able to
+ * see which host path becomes which container path, and what may be written.
+ *
+ * `dockerExtra` is named for what it is. It carries raw Docker flags (`-i -t --entrypoint bash`, a
+ * Linux-only `--user`), so it is the one field a non-Docker consumer must refuse rather than translate.
+ * Calling it `extraFlags` at the boundary would have hidden that.
+ *
+ * @param image      pinned job image tag/digest
+ * @param env        the closed env map from buildContainerEnv -- passed as explicit -e NAME=VALUE
+ * @param jobDir     host path to the /job inputs dir (contains prompt.md and pi/); mounted /job:ro
+ * @param workspace  host path to the fresh clone / local folder (mounted /workspace:rw)
+ * @param outboxDir  host path to the /outbox chain-request dir (local jobs only); mounted /outbox:rw
+ * @param sessionDir host path to this job's OWN copy of its session transcript (REQ-RESUMABLE-SESSION);
+ *                   mounted /session:rw. Per-job, like jobDir -- never the shared store.
+ * @param globalPiDir host path to the operator's global pi overlay (REQ-GLOBAL-PI-OVERLAY); mounted /opt/pi-global:ro
+ * @param name       container name (for `docker stop` at the timeout)
+ * @param memory     e.g. "4g"; cpus e.g. "2"
+ * @param network    the per-job egress network this container joins (REQ-EGRESS-ALLOWLIST); null = the
+ *                   docker default bridge, which is what every job did before that requirement existed
+ * @param extraFlags escape hatch for a Linux-only --user uid:gid on a bind-mounted local folder
+ */
+export function containerSpec({
+	image,
+	env,
+	jobDir,
+	workspace,
+	outboxDir,
+	sessionDir,
+	globalPiDir,
+	name,
+	memory = "4g",
+	cpus = "2",
+	network = null,
+	extraFlags = [],
+}) {
+	if (!image) throw new Error("docker run: image is required");
+	if (!name) throw new Error("docker run: container name is required");
+	if (!workspace) throw new Error("docker run: workspace mount is required");
+
+	const mounts = [];
+	// The WHOLE /job dir is read-only (INT-CONTAINER-JOB-INPUTS): it holds prompt.md and pi/, and
+	// the agent cannot rewrite any of it. /workspace is the only writable mount.
+	if (jobDir) mounts.push({ host: jobDir, container: "/job", readOnly: true });
+	mounts.push({ host: workspace, container: "/workspace", readOnly: false });
+	// Local jobs get a writable /outbox host bind, the same host-bind mechanism as /workspace
+	// (DES-WORKER-ON-HOST). github jobs pass no outboxDir, so the request channel does not exist for
+	// them -- an untrusted issue author cannot chain (INT-OUTBOX-CONTRACT).
+	if (outboxDir) mounts.push({ host: outboxDir, container: "/outbox", readOnly: false });
+
+	// This job's OWN copy of its session transcript (REQ-RESUMABLE-SESSION, INT-SESSION-STORE-CONTRACT).
+	// Writable, because pi appends to it as the agent works -- and per-job, exactly like jobDir, which is
+	// the whole reason CONST-ISOLATION-CONTAINER-PER-JOB's "none host-wide" clause still reads true. The
+	// shared store under PI_SESSIONS_DIR is NEVER bind-mounted: one job here would otherwise be able to
+	// read and rewrite every other branch's and every other repository's transcripts, which is not a
+	// weakening of that constraint but its inversion. Absent unless the trigger armed run.resume AND a key
+	// resolved, so an unarmed job's argv is byte-identical to one built before this feature existed.
+	if (sessionDir) mounts.push({ host: sessionDir, container: CONTAINER_SESSION_DIR, readOnly: false });
+
+	// The operator's global pi overlay (REQ-GLOBAL-PI-OVERLAY): custom models, global skills, a global
+	// persona, layered UNDER each repo's own .pi/. Read-only -- it is operator-authored deploy-time config,
+	// the same trust class as the baked floor, but the agent still must not rewrite it. Both job kinds.
+	if (globalPiDir) mounts.push({ host: globalPiDir, container: CONTAINER_GLOBAL_PI_DIR, readOnly: true });
+
+	return {
+		image,
+		name,
+		memory,
+		cpus,
+		network,
+		// UNCONDITIONALLY true, and there is deliberately no parameter that can unset it. The boundary is
+		// not a thing a caller opts into -- CONST-ISOLATION-CONTAINER-PER-JOB is why every other flag here
+		// exists -- so the spec is simply unable to describe an unisolated container, and the builder in
+		// docker-run.mjs refuses one it is handed. A field that could be false would be a way to ask for less.
+		isolated: true,
+		mounts,
+		env,
+		dockerExtra: extraFlags,
+	};
+}
+
+/**
+ * The mounts of a spec, rendered as TRANSFERS for a runtime that cannot bind-mount (issue #227).
+ *
+ * A bind mount is not a file copy, and the whole value of this function is that it refuses to pretend
+ * otherwise. `DES-JOB-FILES-VIA-VOLUME-SUBPATH` already recorded the specific loss: `docker cp` "cannot
+ * give `/job` a kernel-enforced read-only mount, which `INT-CONTAINER-JOB-INPUTS` depends on" -- and every
+ * vendor upload API is `docker cp`-shaped. So `binds` says which kind of runtime is asking: a binding one
+ * gets `readOnlyEnforcedBy: "kernel"`, a copying one gets `"convention"`, and the second is a DECLARED
+ * DOWNGRADE rather than a neutral translation. That word is what a conformance suite reads, and what stops
+ * "we upload the files" being mistaken for "the agent cannot rewrite its own instructions".
+ *
+ * `0444` file modes are the second and weaker line, named here so nobody mistakes them for the first: they
+ * bind an agent that respects them and nothing else, whereas the kernel binds one that does not.
+ *
+ * DIRECTION FOLLOWS WRITABILITY, not a list of paths. An earlier draft hardcoded `/workspace` as the only
+ * mount coming back, and that was wrong in a way that would have been silent: `/outbox` and `/session` are
+ * writable too, and the HOST reads both after the container exits -- `collectChain` reads `jobDir/outbox`
+ * for the chain requests the agent wrote (`INT-OUTBOX-CONTRACT`), and `promoteSession` reads
+ * `jobDir/session` for the transcript pi appended to (`REQ-RESUMABLE-SESSION`). An adapter that brought
+ * back only `/workspace` would never enqueue a chained child and would cold-start every resume, both
+ * reporting success. So a mount the container may write is a mount the host may need back, and the rule is
+ * exactly that.
+ *
+ * THE NESTING IS MODELLED, because it is the trap. `session/` nests inside `jobDir` for every job kind, and
+ * `workspace/` and `outbox/` nest for their own kinds, so an adapter that uploads each mount independently
+ * produces a container where `/job/workspace` also exists with a stale copy of the tree -- path-equivalent
+ * to nothing the local backend ever produces, and silently divergent rather than broken. `contains` names,
+ * for each entry, the other container paths whose host path lies inside this one, so an adapter can exclude
+ * them from the upload instead of discovering the overlap in review.
+ *
+ * @param binds  true when the runtime bind-mounts (the local backend); false when it copies.
+ */
+export function transfersFromSpec(spec, { binds = true } = {}) {
+	const mounts = spec?.mounts ?? [];
+	return mounts.map((m) => ({
+		host: m.host,
+		container: m.container,
+		readOnly: m.readOnly === true,
+		// The distinction this function exists for. A bind is enforced by the kernel; a copy is enforced by
+		// whatever the agent chooses to respect, which is not enforcement. `null` where nothing is claimed.
+		readOnlyEnforcedBy: m.readOnly === true ? (binds ? "kernel" : "convention") : null,
+		// Writable means the container may change it, which means the host may need it back. See the header:
+		// `/outbox` and `/session` are both read after the run, and hardcoding `/workspace` missed them.
+		direction: m.readOnly === true ? "in" : "in-out",
+		// Other mounts whose HOST path is nested inside this one, by container path. Uploading this entry
+		// without excluding these duplicates their trees under it.
+		contains: mounts.filter((o) => isInside(m.host, o.host)).map((o) => o.container),
+	}));
+}
+
+/**
+ * Is `inner` a host path strictly beneath `outer`?
+ *
+ * SEPARATOR-AGNOSTIC, because host paths are built with `path.join` (`join(jobDir, "workspace")`) and this
+ * worker runs on Windows -- where those are backslash-separated while an earlier draft compared against a
+ * hardcoded `/`. That draft reported NO nesting at all on Windows, which is precisely the platform where a
+ * silently divergent upload would be hardest to spot. The container paths above are always `/`-built and
+ * are not the ones compared here.
+ *
+ * A trailing separator on either side is ignored, and equality is not containment.
+ */
+function isInside(outer, inner) {
+	const strip = (v) => String(v ?? "").replace(/[\\/]+$/, "");
+	const a = strip(outer);
+	const b = strip(inner);
+	if (a === "" || a === b) return false;
+	const next = b.charAt(a.length);
+	return b.startsWith(a) && (next === "/" || next === "\\");
+}
+
+/**
+ * What an adapter LOSES by copying instead of bind-mounting, as `[{ container, was, becomes }]`.
+ *
+ * Empty for a runtime that binds. Non-empty is not a failure: it is the list an adapter must declare, and
+ * the reason `readOnlyJobInputs` is a property in the backend table at all rather than an assumption. An
+ * adapter that returns entries here and still declares `readOnlyJobInputs: enforced` is making exactly the
+ * claim `CONST-EGRESS-POLICY-IN-THE-ARGV` calls worse than no claim.
+ *
+ * `backend-conformance.mjs` is the consumer, and it is what makes this a control rather than a contract: a
+ * backend declaring `binds: false` and `readOnlyJobInputs: enforced` FAILS on the strength of this list.
+ * A backend that declares no `binds` at all makes the harness abstain rather than pass, because a bundle
+ * that has not said how it moves files has not earned the word.
+ */
+export function copyDowngrades(spec) {
+	const bound = transfersFromSpec(spec, { binds: true });
+	const copied = transfersFromSpec(spec, { binds: false });
+	return bound
+		.map((b, i) => ({ container: b.container, was: b.readOnlyEnforcedBy, becomes: copied[i].readOnlyEnforcedBy }))
+		.filter((d) => d.was !== null && d.was !== d.becomes);
+}

package/src/docker-run.mjs

@@ -6,28 +6,21 @@
  * array (never a shell string): no interpolation, no injection, and the env allowlist is passed
  * with explicit `-e NAME` where the value is read from the argv env map, never `--env-file` and
  * never a host pass-through.
- */
-
-/**
- * Where the operator's global pi overlay lands INSIDE the container (REQ-GLOBAL-PI-OVERLAY). Exported
- * because packages.mjs derives the staged-packages root from it: the mount and that root are ONE fact on
- * one side of the boundary, and two literals in two modules could drift apart with both test suites still
- * green. A Linux container path, so it is always built with "/" -- never `path.join`, which yields
- * backslashes when the worker itself runs on Windows.
- */
-export const CONTAINER_GLOBAL_PI_DIR = "/opt/pi-global";
-
-/**
- * The session mount and the file inside it, exported together and used by both the argv builder here and
- * the env builder in env-allowlist.mjs. Two literals in two modules is how a mount and the variable
- * naming a path inside it drift apart with both suites green -- the runner would then look for a
- * transcript at a path nothing mounted, find none, and cold-start every job without saying so.
  *
- * Nothing key-derived crosses the boundary: the container always sees the same constant path, so no
- * repository name, no branch name and no host layout is legible from inside a job.
+ * HOW Docker spells a container. WHAT a container IS moved to `container-spec.mjs` (issue #227), which is
+ * the move #261 deferred to "the PR that adds a second consumer" -- the backend seam is that consumer, since
+ * a backend that is not the local Docker daemon consumes a spec and never produces an argv. The constants
+ * and `containerSpec` are RE-EXPORTED below, so every existing import of this module still resolves and
+ * every assertion in the suite is untouched. This file is now the LOCAL backend's half of that contract.
  */
-export const CONTAINER_SESSION_DIR = "/session";
-export const CONTAINER_SESSION_FILE = `${CONTAINER_SESSION_DIR}/current.jsonl`;
+
+// The portable half. Re-exported rather than moved out of reach: `run-container.mjs` reads
+// CONTAINER_SESSION_FILE beside `buildDockerRunArgs` and is Docker-bound anyway, and `containerSpec` is
+// imported from this module by the suite. `CONST-EGRESS-POLICY-IN-THE-ARGV`'s Code evidence names
+// `buildDockerRunArgs`, which never moved; the entry that names `containerSpec` is design.md's 2026-08-31
+// row, and this move is recorded in its own row rather than by leaving that pointer to rot.
+export { containerSpec, CONTAINER_GLOBAL_PI_DIR, CONTAINER_SESSION_DIR, CONTAINER_SESSION_FILE } from "./container-spec.mjs";
+import { containerSpec } from "./container-spec.mjs";
 
 /** The fixed isolation flags. Not configurable -- these ARE the boundary. */
 export const ISOLATION_FLAGS = [
@@ -50,103 +43,104 @@ export const ISOLATION_FLAGS = [
 ];
 
 /**
- * WHAT the box is, with no Docker vocabulary in it.
- *
- * Split from the argv builder below so the description of a container exists as a VALUE before it becomes
- * one runtime's flags. `buildDockerRunArgs` is unchanged in name, signature and output -- it is now
- * `dockerArgsFromSpec(containerSpec(opts))` -- so every caller and every assertion is untouched, and the
- * only thing that is new is that the middle of that sentence can be read on its own.
+ * HOW Docker spells it. The only consumer of a spec today, and the local backend's translation step:
+ * a second backend implements this function's job against its own runtime and shares everything above it.
+ */
+/**
+ * Flags a `dockerExtra` may not carry, because docker resolves a repeated option LAST-WINS and this array
+ * is appended AFTER `ISOLATION_FLAGS`. `--privileged` supersedes `--cap-drop=ALL`; `--network` supersedes
+ * the per-job one; `--pull` supersedes `--pull=never`; `--rm=false` supersedes `--rm` (verified against
+ * docker 27.4.0, not assumed); a second `-v` adds a mount the spec never declared; a second `--name` wins
+ * and leaves a container outside both reapers' filter and beyond `docker stop`.
  *
- * Mounts are structured (`{host, container, readOnly}`) rather than pre-flattened `host:container:ro`
- * strings, because the flattening IS the Docker part: a runtime that does not bind-mount has to be able to
- * see which host path becomes which container path, and what may be written.
+ * The list covers every member of `ISOLATION_FLAGS`, the container name, and the near-synonyms that reach
+ * the same effect without repeating a listed flag (`--volumes-from` for a mount, `--memory-swap` for the
+ * memory bound). It is a DENY-list and therefore only as good as its coverage: docker's surface is large
+ * and a release can add another way in. So it NARROWS the gap rather than closing it, and the backend
+ * table's `isolation` and `ephemeral` words rest on this plus the single production caller passing fixed
+ * literals, never on this alone.
  *
- * `dockerExtra` is named for what it is. It carries raw Docker flags (`-i -t --entrypoint bash`, a
- * Linux-only `--user`), so it is the one field a non-Docker consumer must refuse rather than translate.
- * Calling it `extraFlags` at the boundary would have hidden that.
+ * Without this the two standing assertions that "every member of ISOLATION_FLAGS reaches the argv" would
+ * still pass on an argv with no boundary left, because membership is not effectiveness. Nothing passes any
+ * of these today -- `sandbox.mjs` sends `-i -t --entrypoint bash` plus loopback-bound `-p` flags, all of
+ * which stay allowed -- so this closes a hole rather than changing a behaviour, and it makes "the builder
+ * CANNOT DECLINE the boundary" true of the whole argv instead of of one boolean field.
  *
- * @param image      pinned job image tag/digest
- * @param env        the closed env map from buildContainerEnv -- passed as explicit -e NAME=VALUE
- * @param jobDir     host path to the /job inputs dir (contains prompt.md and pi/); mounted /job:ro
- * @param workspace  host path to the fresh clone / local folder (mounted /workspace:rw)
- * @param outboxDir  host path to the /outbox chain-request dir (local jobs only); mounted /outbox:rw
- * @param sessionDir host path to this job's OWN copy of its session transcript (REQ-RESUMABLE-SESSION);
- *                   mounted /session:rw. Per-job, like jobDir -- never the shared store.
- * @param globalPiDir host path to the operator's global pi overlay (REQ-GLOBAL-PI-OVERLAY); mounted /opt/pi-global:ro
- * @param name       container name (for `docker stop` at the timeout)
- * @param memory     e.g. "4g"; cpus e.g. "2"
- * @param network    the per-job egress network this container joins (REQ-EGRESS-ALLOWLIST); null = the
- *                   docker default bridge, which is what every job did before that requirement existed
- * @param extraFlags escape hatch for a Linux-only --user uid:gid on a bind-mounted local folder
+ * `--user` is DELIBERATELY NOT HERE, and it is the one that looks like it belongs. It is a documented,
+ * tested feature -- the Linux-only `uid:gid` on a bind-mounted local folder, so files the agent writes into
+ * an operator's own directory come back owned by the operator rather than by root. It also does not touch
+ * this boundary: it changes which uid runs, not what that uid may do, and `--cap-drop=ALL` plus
+ * `no-new-privileges` hold either way. What it does bear on is `nonRoot`, which the backend table already
+ * declares `asserted` for the separate reason that the image's `USER pi` is what provides it. Denying it
+ * here would break local-folder jobs to make a word honest that is already honest.
  */
-export function containerSpec({
-	image,
-	env,
-	jobDir,
-	workspace,
-	outboxDir,
-	sessionDir,
-	globalPiDir,
-	name,
-	memory = "4g",
-	cpus = "2",
-	network = null,
-	extraFlags = [],
-}) {
-	if (!image) throw new Error("docker run: image is required");
-	if (!name) throw new Error("docker run: container name is required");
-	if (!workspace) throw new Error("docker run: workspace mount is required");
-
-	const mounts = [];
-	// The WHOLE /job dir is read-only (INT-CONTAINER-JOB-INPUTS): it holds prompt.md and pi/, and
-	// the agent cannot rewrite any of it. /workspace is the only writable mount.
-	if (jobDir) mounts.push({ host: jobDir, container: "/job", readOnly: true });
-	mounts.push({ host: workspace, container: "/workspace", readOnly: false });
-	// Local jobs get a writable /outbox host bind, the same host-bind mechanism as /workspace
-	// (DES-WORKER-ON-HOST). github jobs pass no outboxDir, so the request channel does not exist for
-	// them -- an untrusted issue author cannot chain (INT-OUTBOX-CONTRACT).
-	if (outboxDir) mounts.push({ host: outboxDir, container: "/outbox", readOnly: false });
-
-	// This job's OWN copy of its session transcript (REQ-RESUMABLE-SESSION, INT-SESSION-STORE-CONTRACT).
-	// Writable, because pi appends to it as the agent works -- and per-job, exactly like jobDir, which is
-	// the whole reason CONST-ISOLATION-CONTAINER-PER-JOB's "none host-wide" clause still reads true. The
-	// shared store under PI_SESSIONS_DIR is NEVER bind-mounted: one job here would otherwise be able to
-	// read and rewrite every other branch's and every other repository's transcripts, which is not a
-	// weakening of that constraint but its inversion. Absent unless the trigger armed run.resume AND a key
-	// resolved, so an unarmed job's argv is byte-identical to one built before this feature existed.
-	if (sessionDir) mounts.push({ host: sessionDir, container: CONTAINER_SESSION_DIR, readOnly: false });
-
-	// The operator's global pi overlay (REQ-GLOBAL-PI-OVERLAY): custom models, global skills, a global
-	// persona, layered UNDER each repo's own .pi/. Read-only -- it is operator-authored deploy-time config,
-	// the same trust class as the baked floor, but the agent still must not rewrite it. Both job kinds.
-	if (globalPiDir) mounts.push({ host: globalPiDir, container: CONTAINER_GLOBAL_PI_DIR, readOnly: true });
-
-	return {
-		image,
-		name,
-		memory,
-		cpus,
-		network,
-		// UNCONDITIONALLY true, and there is deliberately no parameter that can unset it. The boundary is
-		// not a thing a caller opts into -- CONST-ISOLATION-CONTAINER-PER-JOB is why every other flag here
-		// exists -- so the spec is simply unable to describe an unisolated container, and the builder below
-		// refuses one it is handed. A field that could be false would be a way to ask for less.
-		isolated: true,
-		mounts,
-		env,
-		dockerExtra: extraFlags,
-	};
-}
+export const DOCKER_EXTRA_FORBIDDEN = [
+	// Each of the seven logical flags in ISOLATION_FLAGS, and the argv member beside them that the worker's
+	// own machinery reads back. A flag missing from here is a flag the array cannot defend.
+	"--rm", // `--rm=false` leaves the container behind; verified against docker 27.4.0. `ephemeral` rests on it.
+	"--init",
+	"--shm-size",
+	// The container NAME is not an isolation flag and is the sharpest entry on this list: both boot reapers
+	// match `pi-job-` as a substring and the abort path is `docker stop <name>`, so a second `--name` wins
+	// last and leaves a container no sweep finds and no timeout can stop. `ephemeral` and `abortable` both
+	// rest on it.
+	"--name",
+	"--privileged",
+	"--cap-add",
+	"--security-opt",
+	"--pids-limit",
+	"--memory",
+	"-m",
+	"--cpus",
+	"--network",
+	"--net",
+	"--pull",
+	// Add a mount, which is what `-v`/`--volume`/`--mount` are blocked for; `mountSet` rests on all five.
+	"--volumes-from",
+	"--tmpfs",
+	// Relax the memory bound without repeating `--memory`.
+	"--memory-swap",
+	"--oom-kill-disable",
+	// Widen what the process may do without repeating a flag already listed.
+	"--ulimit",
+	"--sysctl",
+	"--group-add",
+	"--cgroup-parent",
+	"--device-cgroup-rule",
+	"--gpus",
+	"--runtime",
+	"-v",
+	"--volume",
+	"--mount",
+	"--device",
+	"--pid",
+	"--ipc",
+	"--uts",
+	"--userns",
+	"--cgroupns",
+];
 
-/**
- * HOW Docker spells it. The only consumer of a spec today.
- */
 export function dockerArgsFromSpec(spec) {
 	// The builder CANNOT DECLINE the boundary. `containerSpec` cannot produce anything but `true`, so this
 	// only ever fires on a hand-built spec -- and a hand-built spec that forgot the field is exactly the
 	// case that must fail loudly rather than quietly emit a container with no isolation flags at all.
 	if (spec?.isolated !== true) throw new Error("docker run: refusing to build an argv for a spec that is not isolated");
 
+	// Same refusal, one level down. `dockerExtra` is raw Docker flags by design, and it lands after the
+	// boundary where a repeat supersedes it -- so the escape hatch is bounded by what it may not say.
+	// Split on `=` so `--network=foo` is caught alongside `--network foo`.
+	for (const flag of spec.dockerExtra ?? []) {
+		// REFUSED, not skipped. Skipping a non-string still PUSHED it into the argv below, so
+		// `new String("--privileged")` and `{ toString: () => "--privileged" }` walked past the check and
+		// then reached docker as the flag they stringify to.
+		if (typeof flag !== "string") {
+			throw new Error(`docker run: dockerExtra must contain only strings; got ${typeof flag}`);
+		}
+		if (DOCKER_EXTRA_FORBIDDEN.includes(flag.split("=", 1)[0])) {
+			throw new Error(`docker run: refusing a dockerExtra flag that would supersede the isolation boundary: ${flag}`);
+		}
+	}
+
 	// `--network` sits HERE, beside --memory and --cpus, and deliberately NOT inside ISOLATION_FLAGS.
 	// That array is the LITERAL, value-free, unconditional set, and two separate places assert every member
 	// of it reaches the sandbox argv *against the imported array, not a copy* (CONST-ISOLATION-CONTAINER-PER-JOB