@edgehero/pi-dispatch 0.1.0

package/src/runtime-settings.mjs

@@ -0,0 +1,188 @@
+import * as nodeFs from "node:fs";
+import { dirname } from "node:path";
+import { defaultSettingsFile } from "./config.mjs";
+
+/**
+ * Runtime-settings overlay: the shared, durable truth between the admin extension and the worker
+ * (INT-CONFIG-OVERLAY-CONTRACT, DES-RUNTIME-SETTINGS-FILE-OVERLAY). A flat `settings.json` with ten
+ * optional keys -- `model`, `provider` (non-empty strings), `maxTurns`, `dailyCap`, `weeklyCap`,
+ * `monthlyCap`, `maxTokens`, `dailyTokenCap` (int >= 1), `concurrency` (int 1-10), `softHoldPct`
+ * (int 1-99) -- read by the worker at each job start and written atomically by the admin extension
+ * (tmp + rename). `maxTokens`/`dailyTokenCap` are the optional token controls (issue #25).
+ *
+ * `readOverlay` NEVER throws: a bad settings file returns a discriminated `{ invalid }` rather than an
+ * exception, so the processor RETURNS a policy refusal (`settings-overlay-invalid`) instead of letting
+ * its catch classify the file as retryable infra and pay to retry a job that can never succeed
+ * (CONST-RETRY-INFRA-ONLY). A present-but-unreadable file fails closed -- it never degrades to an empty
+ * overlay that would silently restore env's higher `dailyCap` (DES-RUNTIME-SETTINGS-FILE-OVERLAY).
+ *
+ * Precedence resolved here is overlay > env > default only; `config` already encodes env > default. The
+ * `job.data` precedence layer belongs to the processor, not here.
+ *
+ * Invalid reasons name the offending KEY and its constraint, never the value: settings values may echo
+ * operator input, so only key names are safe to surface in logs and refusals (no-pii-in-logs).
+ *
+ * Custom: overlay validated inline per config.mjs precedent; zod not in deps
+ */
+
+export const KNOWN_KEYS = ["model", "provider", "maxTurns", "dailyCap", "weeklyCap", "monthlyCap", "maxTokens", "dailyTokenCap", "concurrency", "softHoldPct"];
+
+function isNonEmptyString(value) {
+	return typeof value === "string" && value.trim() !== "";
+}
+
+function isIntAtLeast(value, min) {
+	return Number.isInteger(value) && value >= min;
+}
+
+function isIntInRange(value, min, max) {
+	return Number.isInteger(value) && value >= min && value <= max;
+}
+
+/**
+ * The absolute path of the settings overlay. Mirrors config.mjs: `PI_SETTINGS_FILE` wins, an unset or
+ * empty value falls back to the shared default so the admin extension and the worker resolve the same
+ * path without either coupling to the other.
+ */
+export function settingsFilePath(env = process.env) {
+	return env.PI_SETTINGS_FILE || defaultSettingsFile();
+}
+
+/**
+ * Validate a parsed overlay against the key contract, returning the sanitized overlay (known keys only)
+ * or `{ invalid }`. Shared by `readOverlay` (post-parse) and `writeOverlay` (pre-write) so a single
+ * definition governs both directions. Unknown keys are dropped and logged, leaving the overlay valid;
+ * any invalid known key fails the WHOLE object.
+ */
+function validateOverlay(candidate, log) {
+	if (candidate === null || typeof candidate !== "object" || Array.isArray(candidate)) {
+		return { invalid: "root must be a JSON object" };
+	}
+	const overlay = {};
+	for (const key of Object.keys(candidate)) {
+		const value = candidate[key];
+		switch (key) {
+			case "model":
+			case "provider":
+				if (!isNonEmptyString(value)) return { invalid: `${key} must be a non-empty string` };
+				overlay[key] = value;
+				break;
+			case "maxTurns":
+			case "dailyCap":
+			case "weeklyCap":
+			case "monthlyCap":
+			case "maxTokens":
+			case "dailyTokenCap":
+				// Overlay caps are positive ints. A window/cap is DISABLED by absence, not by a 0 -- `unset weeklyCap`
+				// drops the key so it falls through to env, which unset means the window is off (config.mjs). The
+				// token knobs (maxTokens, dailyTokenCap) follow the same "absent = disabled" shape (issue #25).
+				if (!isIntAtLeast(value, 1)) return { invalid: `${key} must be an integer >= 1` };
+				overlay[key] = value;
+				break;
+			case "concurrency":
+				// Range-checked here, not via config's positiveInt: that helper has no upper bound and parses
+				// env strings, so it cannot enforce the 1-10 ceiling this key carries over a JSON number.
+				if (!isIntInRange(value, 1, 10)) return { invalid: "concurrency must be an integer 1-10" };
+				overlay[key] = value;
+				break;
+			case "softHoldPct":
+				// A percentage of each active cap; 100 would equal the hard wall (no band) and 0 has no meaning,
+				// so the enforced band is 1-99. Absence disables the soft-hold entirely.
+				if (!isIntInRange(value, 1, 99)) return { invalid: "softHoldPct must be an integer 1-99" };
+				overlay[key] = value;
+				break;
+			default:
+				log("settings_overlay_unknown_key", { key });
+		}
+	}
+	return { overlay };
+}
+
+/**
+ * Read the overlay at `path`. Returns `{ overlay }` (known keys only) on success, or `{ invalid }` with
+ * a key-only reason on failure. NEVER throws.
+ *
+ * A missing file (ENOENT) is the normal empty overlay `{ overlay: {} }`. Any OTHER read error
+ * (EACCES, EISDIR, ...) is `{ invalid }`: a present-but-unreadable file must fail closed, not silently
+ * become an empty overlay that restores env's higher `dailyCap`. Unparseable JSON, a non-object root,
+ * or an invalid known key is `{ invalid }`.
+ */
+export function readOverlay(path, { fs = nodeFs, log = () => {} } = {}) {
+	let text;
+	try {
+		text = fs.readFileSync(path, "utf8");
+	} catch (err) {
+		if (err?.code === "ENOENT") return { overlay: {} }; // missing file is a normal empty overlay
+		return { invalid: `settings file unreadable (${err?.code ?? "read-error"})` };
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(text);
+	} catch {
+		return { invalid: "settings file is not valid JSON" };
+	}
+	return validateOverlay(parsed, log);
+}
+
+/**
+ * Resolve the ten effective settings from `config` and a validated `overlay`: overlay value where the
+ * overlay sets it, else the config value. Precedence is overlay > env > default only -- `config`
+ * already carries env > default. `weeklyCap`/`monthlyCap`/`maxTokens`/`dailyTokenCap`/`softHoldPct` may
+ * resolve to `null` (their config value when unset), meaning that window / cap / band is disabled.
+ * `job.data` is NOT merged here; that layer is the processor's.
+ */
+export function effectiveSettings(config, overlay) {
+	const o = overlay ?? {};
+	return {
+		provider: o.provider ?? config.provider,
+		model: o.model ?? config.model,
+		maxTurns: o.maxTurns ?? config.maxTurns,
+		dailyCap: o.dailyCap ?? config.dailyCap,
+		weeklyCap: o.weeklyCap ?? config.weeklyCap,
+		monthlyCap: o.monthlyCap ?? config.monthlyCap,
+		maxTokens: o.maxTokens ?? config.maxTokens,
+		dailyTokenCap: o.dailyTokenCap ?? config.dailyTokenCap,
+		concurrency: o.concurrency ?? config.concurrency,
+		softHoldPct: o.softHoldPct ?? config.softHoldPct,
+	};
+}
+
+/**
+ * Write `candidate` to `path` atomically. Validates with the same rules as `readOverlay` (an invalid
+ * candidate returns `{ invalid }` and touches no file; an empty `{}` candidate is valid), serialises
+ * the validated overlay with 2-space indent and a trailing newline, writes a same-directory
+ * `<path>.tmp`, then renames it over `path`. NEVER throws.
+ *
+ * The rename is retried once on EPERM to ride out a Windows AV/indexer briefly locking the destination;
+ * a second failure surfaces as `{ invalid }`, never a throw. Returns `{ ok: true }` on success.
+ */
+export function writeOverlay(path, candidate, { fs = nodeFs, log = () => {} } = {}) {
+	const result = validateOverlay(candidate, log);
+	if (result.invalid) return { invalid: result.invalid };
+
+	try {
+		fs.mkdirSync(dirname(path), { recursive: true });
+	} catch (err) {
+		return { invalid: `settings dir unwritable (${err?.code ?? "mkdir-error"})` };
+	}
+
+	const tmp = `${path}.tmp`;
+	const data = `${JSON.stringify(result.overlay, null, 2)}\n`;
+	try {
+		fs.writeFileSync(tmp, data);
+	} catch (err) {
+		return { invalid: `settings write failed (${err?.code ?? "write-error"})` };
+	}
+
+	try {
+		fs.renameSync(tmp, path);
+	} catch (err) {
+		if (err?.code !== "EPERM") return { invalid: `settings rename failed (${err?.code ?? "rename-error"})` };
+		try {
+			fs.renameSync(tmp, path); // single retry: Windows AV/indexer lock is transient
+		} catch (retryErr) {
+			return { invalid: `settings rename failed (${retryErr?.code ?? "rename-error"})` };
+		}
+	}
+	return { ok: true };
+}

package/src/sandbox-cli.mjs

@@ -0,0 +1,156 @@
+import { parseArgs } from "node:util";
+import { loadConfig } from "./config.mjs";
+import { sanitizeJobId } from "./run-history.mjs";
+import { buildSandboxRunArgs, launchSandbox, listRunningSandboxes, parsePublish, resolveSandbox, sandboxContainerName } from "./sandbox.mjs";
+import { listSandboxes, pinSandbox } from "./sandbox-store.mjs";
+
+/**
+ * `pi-dispatch sandbox` -- re-open a finished run's sandbox as an interactive shell
+ * (REQ-RESURRECTABLE-SANDBOX).
+ *
+ * A command module beside doctor.mjs and import-pi.mjs, with the same posture: the whole I/O surface is
+ * injected so the decision paths are testable without docker, a terminal, or a disk, and every refusal
+ * names what to do about it rather than only what went wrong.
+ *
+ * The container this launches is NOT a job container. It carries the same isolation flags and the same
+ * mounts, and no credentials at all -- see sandbox.mjs, which owns that shape.
+ */
+export async function runSandbox(argv = [], { env = process.env, deps = {} } = {}) {
+	const {
+		out = (s) => process.stdout.write(s),
+		err = (s) => process.stderr.write(s),
+		isTty = Boolean(process.stdin.isTTY && process.stdout.isTTY),
+		running = listRunningSandboxes,
+		launch = launchSandbox,
+		now = () => Date.now(),
+	} = deps;
+
+	let values;
+	let positionals;
+	try {
+		({ values, positionals } = parseArgs({
+			args: argv,
+			allowPositionals: true,
+			options: {
+				list: { type: "boolean", default: false },
+				publish: { type: "string", multiple: true }, // repeatable; always bound to 127.0.0.1
+				pin: { type: "boolean", default: false },
+			},
+		}));
+	} catch (error) {
+		return fail(err, error.message);
+	}
+
+	const config = loadConfig(env);
+	// A docker that cannot be reached costs a column, never the command: `listRunningSandboxes` throws so
+	// the REAPER can tell "none" from "could not ask", and these callers only draw a marker. Asked only
+	// where it is used, and never before the arguments are known good -- a typo should not shell out.
+	const liveSandboxes = async () => new Set(await running().catch(() => []));
+
+	if (values.list) {
+		return renderList({ config, live: await liveSandboxes(), out, now });
+	}
+
+	const jobId = positionals[0];
+	if (!jobId) return fail(err, "a job id is required — `pi-dispatch sandbox --list` shows what is still re-openable");
+
+	// Refused BEFORE anything else that could half-succeed. `-t` against a pipe fails inside docker with
+	// "the input device is not a TTY", which names neither the cause nor the fix; a sandbox is an operator
+	// session by definition, so the absence of an operator is a refusal rather than a fallback.
+	if (!isTty) {
+		return fail(err, "`pi-dispatch sandbox` needs a terminal — it opens an interactive shell, so it cannot run from a pipe, a script without a TTY, or CI");
+	}
+
+	// `listRunningSandboxes` yields ids, already sanitized, so this compares like with like.
+	if ((await liveSandboxes()).has(sanitizeJobId(jobId))) {
+		return fail(err, `a sandbox for ${jobId} is already running — attach to it with \`docker attach ${sandboxContainerName(jobId)}\`, or exit it first`);
+	}
+
+	let publish;
+	try {
+		publish = parsePublish(values.publish ?? []);
+	} catch (error) {
+		return fail(err, error.message);
+	}
+
+	const resolved = resolveSandbox({
+		jobId,
+		sandboxDir: config.sandboxDir,
+		retentionHours: config.sandboxRetentionHours,
+		publish,
+	});
+	if (resolved.refused) return fail(err, resolved.message);
+
+	// Pin BEFORE the shell, not after: the operator asked to keep this one, and a session that ends in a
+	// crashed terminal or a closed laptop lid must not be the reason the pin never landed.
+	if (values.pin) {
+		const pinned = pinSandbox({ sandboxDir: config.sandboxDir, jobId, pinDays: config.sandboxPinDays, now });
+		if (pinned.pinned) out(`pinned ${jobId} until ${pinned.keepUntil} (${config.sandboxPinDays}d)\n`);
+		else err(`warning: could not pin ${jobId}: ${pinned.reason}\n`);
+	}
+
+	const args = buildSandboxRunArgs({
+		image: resolved.manifest.image,
+		name: resolved.name,
+		workspace: resolved.manifest.workspace,
+		jobDir: resolved.manifest.dir,
+		publish,
+		term: env.TERM,
+		idleSeconds: config.sandboxIdleMinutes * 60,
+	});
+
+	out(`opening ${resolved.name} — image ${resolved.manifest.image}, workspace ${resolved.manifest.workspace}\n`);
+	out("no credentials are set in this container. exit the shell to dispose of it.\n");
+	if (publish.length > 0) out(`published: ${publish.filter((f) => f !== "-p").join(", ")}\n`);
+
+	const { code, error } = await launch({ args });
+	if (error) return fail(err, `could not start docker: ${error.message}`);
+	return code ?? 0;
+}
+
+/**
+ * What is still re-openable, newest first, plus what is running right now.
+ *
+ * The running column is the honest answer to `TMOUT`'s one gap: an idle timeout does not tick while a
+ * foreground command runs, so a sandbox left serving an app stays up. Making it findable is the least
+ * this can do about that.
+ */
+function renderList({ config, live, out, now }) {
+	if (config.sandboxRetentionHours === 0) {
+		out("workspace retention is off (PI_SANDBOX_RETENTION_HOURS=0) — finished runs are deleted as before\n");
+	}
+	const rows = listSandboxes({ sandboxDir: config.sandboxDir });
+	if (rows.length === 0) {
+		out("no retained workspaces\n");
+		return 0;
+	}
+	const width = Math.max(...rows.map((r) => String(r.jobId ?? "").length), 5);
+	for (const row of rows) {
+		const id = String(row.jobId ?? "?").padEnd(width);
+		const kind = String(row.kind ?? "?").padEnd(8);
+		const state = live.has(sanitizeJobId(row.jobId)) ? "RUNNING" : remaining(row, config.sandboxRetentionHours, now());
+		out(`${id}  ${kind}  ${state}\n`);
+	}
+	return 0;
+}
+
+/** How long this one has left, from the manifest's own timestamps -- never from mtime, which a live sandbox moves. */
+function remaining(row, retentionHours, at) {
+	const keepUntil = Date.parse(row.keepUntil ?? "");
+	if (Number.isFinite(keepUntil)) return `pinned, ${humanise(keepUntil - at)} left`;
+	const createdAt = Date.parse(row.createdAt ?? "");
+	if (!Number.isFinite(createdAt)) return "expired";
+	return `${humanise(createdAt + retentionHours * 3600000 - at)} left`;
+}
+
+function humanise(ms) {
+	if (ms <= 0) return "0h";
+	const hours = Math.round(ms / 3600000);
+	if (hours < 48) return `${Math.max(1, hours)}h`;
+	return `${Math.round(hours / 24)}d`;
+}
+
+function fail(err, message) {
+	err(`error: ${message}\n`);
+	return 1;
+}

package/src/sandbox-store.mjs

@@ -0,0 +1,269 @@
+import { lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, relative } from "node:path";
+import { sanitizeJobId } from "./run-history.mjs";
+
+/**
+ * sandbox-store.mjs -- the host side of a resurrectable sandbox (REQ-RESURRECTABLE-SANDBOX,
+ * INT-SANDBOX-CONTRACT).
+ *
+ * A job container is still single-use and still `--rm`s. What survives it, for a bounded window, is the
+ * per-job DIRECTORY: `cleanup` renames it here instead of deleting it, and `pi-dispatch sandbox` later
+ * mounts it into a fresh container. Nothing about the job path changes -- with the window at 0 this
+ * module is never reached and `cleanup` is byte-for-byte the `rm -rf` it always was.
+ *
+ * A SIBLING of makeLogReaper and of session-store's reapSessions rather than a widening of either: that
+ * one's `.log`/`.json` filter and logsDir scope are a documented contract, and these directories have a
+ * different retention policy and a different PII class again. Same never-throws shape, and three
+ * DELIBERATE divergences from makeLogReaper, each of which would be a silent bug if copied from it:
+ *
+ *   - `lstatSync`, never `statSync`. The retained tree is agent-written; a symlink planted in it resolves
+ *     on the HOST when the reaper stats it. session-store.mjs:192-201 records this lesson and
+ *     makeLogReaper is the habit that predates it.
+ *   - Age comes from the manifest's `createdAt`, never from mtime. makeLogReaper calls mtime "the
+ *     authority" and is right about an append-once log file. Here an operator working inside a resurrected
+ *     sandbox writes into the directory, so mtime would keep moving and the window would never close --
+ *     for exactly the directories most likely to be large.
+ *   - A directory whose sandbox container is RUNNING is skipped. The sweep runs at worker boot, an
+ *     operator's shell can outlive a worker restart by design (the container is named outside the
+ *     `pi-job-` reaper's filter), and deleting a live bind mount underneath it is a confusing failure
+ *     with a boring cause.
+ *
+ * NEVER THROWS, on any path. Retention is a convenience layered onto a job that has already finished and
+ * already been paid for; a disk fault here must degrade to "not resurrectable" and never to a failed run.
+ */
+
+/** The manifest filename inside a retained directory. */
+export const SANDBOX_MANIFEST = "manifest.json";
+
+const HOUR_MS = 3600000;
+const DAY_MS = 86400000;
+
+const defaultFs = { lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync };
+
+/**
+ * Retain one finished job's directory, or delete it.
+ *
+ * Called by `makeCleanup` in place of the bare `rm -rf`. Returns the written manifest, or `null` when
+ * nothing was retained -- and on `null` the caller has nothing left to do, because every failure path
+ * here removes `jobDir` itself. Retention must never leave debris behind.
+ *
+ * `prepared.sandbox` is `{ jobId, kind, image }`, stamped by `makePrepareWorkspace`. Absent (a bare
+ * construction, a test, an unwired dispatcher) means no retention, which keeps such a caller on exactly
+ * the pre-feature path.
+ */
+export function retainJobDir(prepared, { sandboxDir, fs = defaultFs, log = () => {}, now = () => Date.now() } = {}) {
+	const jobDir = prepared?.jobDir;
+	const meta = prepared?.sandbox;
+	if (!jobDir) return null;
+	if (!sandboxDir || !meta?.jobId) {
+		discard(jobDir, fs);
+		return null;
+	}
+
+	const dest = join(sandboxDir, sanitizeJobId(meta.jobId));
+	try {
+		// FIRST, and load-bearing rather than hygiene. The per-job transcript copy is the most PII-bearing
+		// artifact this system holds -- tool output, file contents, the agent's own reasoning -- and it
+		// belongs to PI_SESSIONS_DIR's own TTL (INT-SESSION-STORE-CONTRACT). Carrying it into a directory
+		// with a different, operator-extendable lifetime would silently extend that TTL, which is not a
+		// weakening of the session policy so much as an end-run around it.
+		fs.rmSync(join(jobDir, "session"), { recursive: true, force: true });
+
+		fs.mkdirSync(sandboxDir, { recursive: true, mode: 0o700 });
+		// A BullMQ retry reuses the job id, so the previous attempt may already be sitting at `dest`. Last
+		// attempt wins: it is the one whose workspace matches the run the operator just watched.
+		fs.rmSync(dest, { recursive: true, force: true });
+		fs.renameSync(jobDir, dest);
+
+		const manifest = {
+			jobId: meta.jobId,
+			kind: meta.kind ?? null,
+			image: meta.image ?? null,
+			workspace: rebaseWorkspace(prepared.workspace, jobDir, dest),
+			createdAt: new Date(now()).toISOString(),
+			keepUntil: null,
+		};
+		fs.writeFileSync(join(dest, SANDBOX_MANIFEST), `${JSON.stringify(manifest, null, 2)}\n`, { mode: 0o600 });
+		log("sandbox_retained", { jobId: meta.jobId, kind: manifest.kind });
+		return manifest;
+	} catch (err) {
+		// Fall back to the behaviour retention replaced. Both paths are attempted because the rename may
+		// have already moved the tree, in which case `jobDir` no longer exists and `dest` is the debris.
+		log("sandbox_retain_failed", { jobId: meta.jobId, reason: err?.message });
+		discard(jobDir, fs);
+		discard(dest, fs);
+		return null;
+	}
+}
+
+/**
+ * Where the sandbox's `/workspace` lives once the directory has moved.
+ *
+ * A forge job's workspace is a subdirectory of jobDir (prepare-github.mjs), so it travels with the rename
+ * and its recorded path must be rebased. A local job's workspace IS the operator's own folder, outside
+ * jobDir entirely, and must be recorded verbatim -- it was never ours to move.
+ *
+ * Decided by path containment rather than by `kind`, so a preparer that changes where it puts a clone
+ * cannot silently record a path that does not exist.
+ */
+function rebaseWorkspace(workspace, jobDir, dest) {
+	if (!workspace) return null;
+	const rel = relative(jobDir, workspace);
+	if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) return workspace;
+	return join(dest, rel);
+}
+
+/** Best-effort removal. Swallows everything: this is already the failure path. */
+function discard(dir, fs) {
+	try {
+		fs.rmSync(dir, { recursive: true, force: true });
+	} catch {
+		// nothing left to try
+	}
+}
+
+/** One retained run by (raw) job id, or null when absent, unreadable or not JSON. */
+export function readManifest({ sandboxDir, jobId, fs = defaultFs }) {
+	if (!sandboxDir || jobId === undefined || jobId === null) return null;
+	const dir = join(sandboxDir, sanitizeJobId(jobId));
+	try {
+		const manifest = JSON.parse(fs.readFileSync(join(dir, SANDBOX_MANIFEST), "utf8"));
+		return { ...manifest, dir };
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Every retained run, newest first. A filename-keyed scan of one directory, exactly like
+ * makeFindPreviousRun's -- no index, no database, no new query surface (DES-RUN-HISTORY-FLAT-FILES-NO-DB).
+ * An entry with no readable manifest is skipped rather than surfaced: it cannot be resurrected, and the
+ * reaper removes it on the next sweep.
+ */
+export function listSandboxes({ sandboxDir, fs = defaultFs }) {
+	if (!sandboxDir) return [];
+	let names;
+	try {
+		names = fs.readdirSync(sandboxDir);
+	} catch {
+		return [];
+	}
+	const out = [];
+	for (const name of names) {
+		const dir = join(sandboxDir, name);
+		try {
+			const manifest = JSON.parse(fs.readFileSync(join(dir, SANDBOX_MANIFEST), "utf8"));
+			out.push({ ...manifest, dir });
+		} catch {
+			// unreadable or not a retained directory
+		}
+	}
+	return out.sort((a, b) => String(b.createdAt ?? "").localeCompare(String(a.createdAt ?? "")));
+}
+
+/**
+ * Extend one run's retention to `now + pinDays`, and say so on disk.
+ *
+ * Bounded on purpose: `keepUntil` is a timestamp, never a boolean. "Keep this one" that means "forever"
+ * is how a directory holding a full repository clone per run becomes unbounded, and the acceptance this
+ * feature was written against says retention stays swept.
+ */
+export function pinSandbox({ sandboxDir, jobId, pinDays, fs = defaultFs, now = () => Date.now() }) {
+	const manifest = readManifest({ sandboxDir, jobId, fs });
+	if (!manifest) return { pinned: false, reason: "absent" };
+	const keepUntil = new Date(now() + pinDays * DAY_MS).toISOString();
+	const { dir, ...body } = manifest;
+	try {
+		fs.writeFileSync(join(dir, SANDBOX_MANIFEST), `${JSON.stringify({ ...body, keepUntil }, null, 2)}\n`, { mode: 0o600 });
+		return { pinned: true, keepUntil };
+	} catch (err) {
+		return { pinned: false, reason: err?.message ?? "write-failed" };
+	}
+}
+
+/**
+ * The boot sweep. Fault isolation is the contract, mirroring makeLogReaper and makeReaper: `reapSandboxes`
+ * NEVER throws under any input, and one bad entry cannot abort the rest of the sweep.
+ *
+ * There is NO keep-forever sentinel here, unlike PI_LOG_RETENTION_DAYS and PI_SESSIONS_TTL_DAYS.
+ * `retentionHours === 0` is the feature being OFF, and it needs no special case: the cutoff becomes `now`,
+ * so every unpinned directory is already expired and gets swept. Turning retention off therefore also
+ * cleans up what an earlier setting retained, while an explicit `--pin` still runs to its own deadline --
+ * an operator's deliberate act outliving a config change is the behaviour worth having.
+ *
+ * `listRunning` yields the JOB IDS of live sandboxes -- ids, not container names, so this module needs to
+ * know nothing about how a container is named and the two files stay acyclic. It defaults to none, so an
+ * unwired reaper still sweeps; start.mjs injects the docker-backed one.
+ */
+export function makeSandboxReaper({
+	sandboxDir,
+	retentionHours,
+	fs = defaultFs,
+	log = () => {},
+	now = () => Date.now(),
+	listRunning = async () => [],
+}) {
+	return async function reapSandboxes() {
+		if (!sandboxDir) return;
+		let running = new Set();
+		try {
+			running = new Set(await listRunning());
+		} catch (err) {
+			// Could not ask docker. Sweeping blind risks pulling a mount out from under a live shell, so
+			// skip this sweep entirely: a directory kept one boot too long is the cheaper mistake.
+			log("sandbox_reaper_skipped", { reason: err?.message ?? "running-lookup-failed" });
+			return;
+		}
+
+		let names;
+		try {
+			names = fs.readdirSync(sandboxDir);
+		} catch (err) {
+			log("sandbox_reaper_skipped", { reason: err?.message });
+			return;
+		}
+
+		const at = now();
+		const cutoff = at - retentionHours * HOUR_MS;
+		for (const name of names) {
+			const dir = join(sandboxDir, name);
+			try {
+				// lstat: a symlink here resolves on the host, and this tree is agent-written.
+				if (!fs.lstatSync(dir).isDirectory()) {
+					fs.rmSync(dir, { recursive: true, force: true });
+					log("reaped_sandbox", { entry: name, reason: "not-a-directory" });
+					continue;
+				}
+				if (running.has(name)) continue; // an operator is inside it
+				const verdict = expiry(dir, fs, at, cutoff);
+				if (!verdict.expired) continue;
+				fs.rmSync(dir, { recursive: true, force: true });
+				log("reaped_sandbox", { entry: name, reason: verdict.reason });
+			} catch (err) {
+				log("sandbox_reaper_skipped", { entry: name, reason: err?.message });
+			}
+		}
+	};
+}
+
+/**
+ * Whether one retained directory is past its window.
+ *
+ * An unreadable, absent or unparseable manifest is EXPIRED, not skipped: without it the directory names no
+ * image, no workspace and no job, so nothing can resurrect it and keeping it is just disk. A pin wins over
+ * the base window while it lasts, and an unparseable `keepUntil` is treated as no pin rather than as
+ * forever -- the direction that stays bounded.
+ */
+function expiry(dir, fs, at, cutoff) {
+	let manifest;
+	try {
+		manifest = JSON.parse(fs.readFileSync(join(dir, SANDBOX_MANIFEST), "utf8"));
+	} catch {
+		return { expired: true, reason: "no-manifest" };
+	}
+	const keepUntil = Date.parse(manifest?.keepUntil ?? "");
+	if (Number.isFinite(keepUntil)) return keepUntil <= at ? { expired: true, reason: "pin-expired" } : { expired: false };
+	const createdAt = Date.parse(manifest?.createdAt ?? "");
+	if (!Number.isFinite(createdAt)) return { expired: true, reason: "no-created-at" };
+	return createdAt < cutoff ? { expired: true, reason: "window" } : { expired: false };
+}