Phase 2: docker run argv construction, verified launching the real image

INT-CONTAINER-RUNTIME-CONTRACT / CONST-ISOLATION-CONTAINER-PER-JOB. buildDockerRunArgs
constructs the `docker run` argv as an explicit array -- never a shell string, so no
interpolation and no injection. Every isolation flag is fixed and load-bearing: --rm --init
--cap-drop=ALL --security-opt no-new-privileges --pids-limit=512 --shm-size=1g, plus
--memory/--cpus. --ipc=host and --privileged are asserted ABSENT.

The env is an explicit -e NAME=VALUE allowlist built from buildContainerEnv's closed map:
no bare `-e NAME` (which would inherit the host value), no --env-file, undefined values
skipped rather than passed empty. /job/pi is mounted :ro (the agent cannot rewrite its
instructions), /workspace is the only writable mount.

Verified end to end: the constructed argv launched the real pi-job image with all flags and
the runner ran to its config check (exit 2 on the missing /job/prompt.md), proving the argv
is correct against a real container, not just asserted in a unit test.

Five worker modules now built and each verified against real infrastructure (real git with
hostile objects, real Valkey, the real image): exit-code, env-allowlist, materialize,
budget, docker-run. The BullMQ Worker wrapper + 30-min timeout, GitHub token minting, and
branch-protection precondition follow -- the first needs the wiring research in flight, the
latter two need a GitHub App to verify rather than guess.

Author: edgehero

worker/src/docker-run.mjs

@@ -0,0 +1,64 @@
+/**
+ * INT-CONTAINER-RUNTIME-CONTRACT. Construct the `docker run` argv for one job container.
+ *
+ * Every flag here is the enforcement surface of CONST-ISOLATION-CONTAINER-PER-JOB -- pi has no
+ * permission system, so the container is the only real control. The argv is built as an explicit
+ * 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.
+ */
+
+/** The fixed isolation flags. Not configurable -- these ARE the boundary. */
+export const ISOLATION_FLAGS = [
+	"--rm", // ephemeral: gone after the run
+	"--init", // reap zombies (Chromium spawns many); node is PID 1 and does not reap
+	"--cap-drop=ALL", // pi would otherwise inherit the launching user's capabilities
+	"--security-opt",
+	"no-new-privileges",
+	"--pids-limit=512", // bound a fork bomb (UNVERIFIED figure; measured headroom ~4.5x, see spec)
+	"--shm-size=1g", // Chromium OOMs on the default 64MB /dev/shm; NOT --ipc=host (shares host ns)
+];
+
+/**
+ * Build the full `docker run` argv (excluding the leading "docker").
+ *
+ * @param image      pinned job image tag/digest
+ * @param env        the closed env map from buildContainerEnv -- passed as explicit -e NAME=VALUE
+ * @param jobPiDir   host path to the materialised .pi/ (mounted /job/pi:ro)
+ * @param workspace  host path to the fresh clone / local folder (mounted /workspace:rw)
+ * @param name       container name (for `docker stop` at the timeout)
+ * @param memory     e.g. "4g"; cpus e.g. "2"
+ * @param extraFlags escape hatch for a Linux-only --user uid:gid on a bind-mounted local folder
+ */
+export function buildDockerRunArgs({
+	image,
+	env,
+	jobPiDir,
+	workspace,
+	name,
+	memory = "4g",
+	cpus = "2",
+	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 args = ["run", `--name=${name}`, ...ISOLATION_FLAGS, `--memory=${memory}`, `--cpus=${cpus}`, ...extraFlags];
+
+	// Explicit env allowlist. Each entry is `-e NAME=VALUE`, built from the closed map -- so a
+	// stray host variable cannot ride along (no bare `-e NAME` inheriting from the host, no
+	// --env-file). Undefined values are skipped, never passed as an empty string.
+	for (const [k, v] of Object.entries(env ?? {})) {
+		if (v === undefined || v === null) continue;
+		args.push("-e", `${k}=${v}`);
+	}
+
+	// /job is read-only (INT-CONTAINER-JOB-INPUTS): the agent cannot rewrite its own instructions.
+	// /workspace is the only writable mount.
+	if (jobPiDir) args.push("-v", `${jobPiDir}:/job/pi:ro`);
+	args.push("-v", `${workspace}:/workspace`);
+
+	args.push(image);
+	return args;
+}

worker/test/docker-run.test.mjs

@@ -0,0 +1,68 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { buildDockerRunArgs, ISOLATION_FLAGS } from "../src/docker-run.mjs";
+
+const base = {
+	image: "pi-job:pinned",
+	env: { PI_PROVIDER: "anthropic", ANTHROPIC_API_KEY: "sk-real" },
+	jobPiDir: "/srv/jobs/abc/pi",
+	workspace: "/srv/jobs/abc/workspace",
+	name: "pi-job-abc",
+};
+
+test("carries every isolation flag -- these ARE the boundary", () => {
+	const args = buildDockerRunArgs(base);
+	const s = args.join(" ");
+	for (const flag of ["--rm", "--init", "--cap-drop=ALL", "no-new-privileges", "--pids-limit=512", "--shm-size=1g"]) {
+		assert.ok(args.includes(flag) || s.includes(flag), `missing isolation flag: ${flag}`);
+	}
+	// The dangerous one we must NEVER add.
+	assert.ok(!s.includes("--ipc=host"), "--ipc=host shares the host IPC namespace with adversarial code");
+	assert.ok(!s.includes("--privileged"), "--privileged");
+});
+
+test("/job is read-only, /workspace is writable", () => {
+	const args = buildDockerRunArgs(base);
+	assert.ok(args.includes("/srv/jobs/abc/pi:/job/pi:ro"), "/job/pi must be :ro");
+	assert.ok(args.includes("/srv/jobs/abc/workspace:/workspace"), "/workspace must be writable");
+	assert.ok(!args.some((a) => a.includes("/workspace:ro")), "/workspace must not be read-only");
+});
+
+test("env is an explicit -e NAME=VALUE allowlist, never a pass-through or --env-file", () => {
+	const args = buildDockerRunArgs(base);
+	assert.ok(args.includes("-e") && args.includes("ANTHROPIC_API_KEY=sk-real"));
+	assert.ok(!args.includes("--env-file"), "must never use --env-file");
+	// No bare `-e NAME` (which would inherit the host value) -- every -e is followed by NAME=VALUE.
+	for (let i = 0; i < args.length; i++) {
+		if (args[i] === "-e") assert.match(args[i + 1], /=/, `bare -e ${args[i + 1]} would inherit from host`);
+	}
+});
+
+test("an undefined env value is skipped, not passed as empty", () => {
+	const args = buildDockerRunArgs({ ...base, env: { PI_MODEL: "m", GITHUB_TOKEN: undefined } });
+	assert.ok(!args.some((a) => a.startsWith("GITHUB_TOKEN")), "absent token must not appear at all");
+});
+
+test("a local-folder job can add a Linux-only --user via extraFlags", () => {
+	const args = buildDockerRunArgs({ ...base, extraFlags: ["--user", "1000:1000"] });
+	assert.ok(args.includes("--user") && args.includes("1000:1000"));
+});
+
+test("refuses to build without image / name / workspace", () => {
+	assert.throws(() => buildDockerRunArgs({ ...base, image: undefined }), /image/);
+	assert.throws(() => buildDockerRunArgs({ ...base, name: undefined }), /name/);
+	assert.throws(() => buildDockerRunArgs({ ...base, workspace: undefined }), /workspace/);
+});
+
+test("ISOLATION_FLAGS is frozen intent -- the exact set the spec pins", () => {
+	// A change here is a change to the security boundary and must be deliberate.
+	assert.deepEqual(ISOLATION_FLAGS, [
+		"--rm",
+		"--init",
+		"--cap-drop=ALL",
+		"--security-opt",
+		"no-new-privileges",
+		"--pids-limit=512",
+		"--shm-size=1g",
+	]);
+});