@tangle-network/agent-runtime 0.105.0 → 0.106.0

package/dist/supervisor-DTKhF-RV.js

@@ -0,0 +1,3826 @@
+import { c as RuntimeRunStateError, u as ValidationError } from "./errors-DEAvWQPy.js";
+import { f as zeroTokenUsage, t as addTokenUsage } from "./util-MVgdwuIS.js";
+import { a as contentAddress, c as replaySpawnTree, o as materializeTreeView, s as pendingWaits } from "./spawn-journal-CwPvKUTa.js";
+import { estimateCost, isModelPriced } from "@tangle-network/agent-eval";
+import { createHash, randomUUID } from "node:crypto";
+import { applyWorkspacePlan, materializeProfile } from "@tangle-network/agent-profile-materialize";
+import { access, chmod, copyFile, mkdir, mkdtemp, open, readFile, realpath, rm, symlink, writeFile } from "node:fs/promises";
+import { constants, createReadStream } from "node:fs";
+import { basename, delimiter, dirname, isAbsolute, join, resolve, sep, win32 } from "node:path";
+import { spawn } from "node:child_process";
+import { homedir, tmpdir } from "node:os";
+import { stripVTControlCharacters } from "node:util";
+//#region src/mcp/codex-diagnostics.ts
+/** Thrown when reproducible Codex exits without one valid terminal usage event. */
+var CodexExecutionDiagnosticError = class extends Error {
+	reason;
+	diagnostic;
+	code = "CODEX_EXECUTION_DIAGNOSTIC";
+	constructor(reason, diagnostic, cause) {
+		super(`runLocalHarness: reproducible Codex execution failed: ${reason}; diagnostic=${JSON.stringify(diagnostic)}`, { cause });
+		this.reason = reason;
+		this.diagnostic = diagnostic;
+		this.name = "CodexExecutionDiagnosticError";
+	}
+};
+const CODEX_FAILURE_STREAM_MAX_CHARS = 4096;
+const CODEX_AUTH_MAX_BYTES = 1024 * 1024;
+const CODEX_REDACTED = "<REDACTED_CREDENTIAL>";
+const codexSensitiveEnvironmentName = /(TOKEN|KEY|SECRET|PASSWORD|CREDENTIAL|AUTH|COOKIE)/i;
+function createCodexExecutionDiagnosticError(opts) {
+	const redact = (value) => redactCodexDiagnostic(value, opts.codexHome, opts.redactionValues);
+	const boundedStdout = boundCodexDiagnostic(redact(opts.stdout));
+	const boundedStderr = boundCodexDiagnostic(redact(opts.stderr));
+	const diagnostic = {
+		exitCode: opts.exitCode,
+		killedBySignal: opts.killedBySignal,
+		timedOut: opts.timedOut,
+		...opts.aborted !== void 0 ? { aborted: opts.aborted } : {},
+		durationMs: opts.durationMs,
+		stdout: boundedStdout.value,
+		stderr: boundedStderr.value,
+		stdoutTruncated: boundedStdout.truncated,
+		stderrTruncated: boundedStderr.truncated
+	};
+	const safeReason = boundCodexDiagnostic(redact(opts.reason), 1024).value;
+	return new CodexExecutionDiagnosticError(safeReason, diagnostic, redactCodexErrorCause(opts.cause, safeReason, redact));
+}
+function redactCodexHome(value, codexHome) {
+	return codexHome ? value.replaceAll(codexHome, "<ISOLATED_CODEX_HOME>") : value;
+}
+function collectCodexDiagnosticRedactionValues(env, authText) {
+	const values = Object.entries(env).filter(([name, value]) => codexSensitiveEnvironmentName.test(name) && typeof value === "string").map(([, value]) => value);
+	try {
+		collectStringLeaves(JSON.parse(authText), values);
+	} catch {}
+	const encoded = values.filter((value) => value.length >= 8).flatMap((value) => [
+		Buffer.from(value, "utf8").toString("base64"),
+		Buffer.from(value, "utf8").toString("base64url"),
+		encodeURIComponent(value),
+		JSON.stringify(value).slice(1, -1)
+	]);
+	return [.../* @__PURE__ */ new Set([...values, ...encoded])];
+}
+async function readCodexAuthRedactionText(path) {
+	const handle = await open(path, constants.O_RDONLY | constants.O_NONBLOCK);
+	try {
+		const stats = await handle.stat();
+		if (!stats.isFile() || !Number.isSafeInteger(stats.size) || stats.size > CODEX_AUTH_MAX_BYTES) throw new Error("Codex auth.json must be a regular file no larger than 1 MiB");
+		const buffer = Buffer.alloc(stats.size);
+		let offset = 0;
+		while (offset < buffer.length) {
+			const { bytesRead } = await handle.read(buffer, offset, buffer.length - offset, offset);
+			if (bytesRead === 0) break;
+			offset += bytesRead;
+		}
+		return buffer.subarray(0, offset).toString("utf8");
+	} finally {
+		await handle.close();
+	}
+}
+function boundCodexDiagnostic(value, maxChars = CODEX_FAILURE_STREAM_MAX_CHARS) {
+	if (value.length <= maxChars) return {
+		value,
+		truncated: false
+	};
+	const marker = "\n<... OUTPUT TRUNCATED ...>\n";
+	const contentChars = maxChars - 28;
+	const headChars = Math.floor(contentChars / 2);
+	const tailChars = contentChars - headChars;
+	return {
+		value: `${value.slice(0, headChars)}${marker}${value.slice(-tailChars)}`,
+		truncated: true
+	};
+}
+function redactCodexDiagnostic(value, codexHome, protectedValues) {
+	let redacted = redactCodexHome(stripVTControlCharacters(value), codexHome);
+	const exactValues = [...new Set(protectedValues.filter((item) => item.length >= 6))].sort((a, b) => b.length - a.length);
+	for (const secret of exactValues) redacted = redacted.replaceAll(secret, CODEX_REDACTED);
+	redacted = redacted.replace(/(\bBearer\s+)[A-Za-z0-9._~+/=-]{6,}/gi, `$1${CODEX_REDACTED}`).replace(/\b(?:sk|rk|pk)-[A-Za-z0-9._-]{8,}\b/g, CODEX_REDACTED).replace(/\beyJ[A-Za-z0-9_-]{6,}\.[A-Za-z0-9_-]{6,}\.[A-Za-z0-9_-]{6,}\b/g, CODEX_REDACTED).replace(/((?:["']?(?:api[-_]?key|access[-_]?token|refresh[-_]?token|id[-_]?token|client[-_]?secret|private[-_]?key|session[-_]?(?:id|token)|secret|password|passwd|authorization|credential|cookie)["']?)\s*[:=]\s*)(["'])[^"'\r\n]*\2/gi, `$1$2${CODEX_REDACTED}$2`).replace(/((?:["']?(?:api[-_]?key|access[-_]?token|refresh[-_]?token|id[-_]?token|client[-_]?secret|private[-_]?key|session[-_]?(?:id|token)|secret|password|passwd|authorization|credential|cookie)["']?)\s*[:=]\s*)([^\s,;}]+)/gi, `$1${CODEX_REDACTED}`);
+	for (const secret of exactValues) redacted = redacted.replaceAll(secret, CODEX_REDACTED);
+	return redacted;
+}
+function redactCodexErrorCause(cause, safeReason, redact) {
+	if (!(cause instanceof Error)) return void 0;
+	const safeCause = new Error(safeReason);
+	safeCause.name = cause.name;
+	if (cause.stack) safeCause.stack = boundCodexDiagnostic(redact(cause.stack)).value;
+	return safeCause;
+}
+function collectStringLeaves(value, output) {
+	if (typeof value === "string") {
+		output.push(value);
+		return;
+	}
+	if (Array.isArray(value)) {
+		for (const item of value) collectStringLeaves(item, output);
+		return;
+	}
+	if (value !== null && typeof value === "object") for (const item of Object.values(value)) collectStringLeaves(item, output);
+}
+//#endregion
+//#region src/mcp/local-harness.ts
+/**
+*
+* Subprocess wrappers for the local coding-harness CLIs installed in the
+* sandbox image (claude-code, codex, opencode). Used by the in-process
+* delegation executor (`createInProcessExecutor`) so a delegated coding task
+* spawns a real harness on a real git worktree instead of provisioning a
+* sibling sandbox.
+*
+* All harness invocations:
+*   - run with `cwd` set to the worktree
+*   - inherit env from the parent (the MCP server inside the sandbox has
+*     the harness's auth already)
+*   - capture stdout/stderr
+*   - support cancellation via AbortSignal
+*   - enforce a wall-clock timeout
+*
+* @experimental
+*/
+const codexReasoningEffort = {
+	none: "none",
+	minimal: "minimal",
+	low: "low",
+	medium: "medium",
+	high: "high",
+	xhigh: "xhigh",
+	ultracode: "xhigh"
+};
+function codexReasoningArgs(reasoningEffort) {
+	const mapped = codexReasoningEffort[reasoningEffort];
+	if (mapped === void 0) throw new Error(`harnessInvocation: unsupported Codex reasoning effort ${String(reasoningEffort)}`);
+	return ["-c", `model_reasoning_effort="${mapped}"`];
+}
+/**
+* Default per-harness command + arg shape. `buildArgs` takes ONLY the task prompt and
+* emits the prompt-only invocation (no model, no system prompt) — the safe default shape
+* the in-process executor's `streamPrompt` drives. `modelArgs` maps a resolved model to
+* the harness's selector flag (every supported harness takes `-m <model>`). The §1.5
+* profile-aware mapper `harnessInvocation` composes these to thread the full
+* supervisor-authored profile (systemPrompt + model) into argv.
+*/
+const HARNESS_INVOCATIONS = {
+	claude: {
+		command: "claude",
+		buildArgs: (taskPrompt) => ["-p", taskPrompt],
+		modelArgs: (model) => ["-m", model]
+	},
+	codex: {
+		command: "codex",
+		buildArgs: (taskPrompt) => ["exec", taskPrompt],
+		modelArgs: (model) => ["-m", model],
+		reasoningArgs: codexReasoningArgs
+	},
+	opencode: {
+		command: "opencode",
+		buildArgs: (taskPrompt) => ["run", taskPrompt],
+		modelArgs: (model) => ["-m", model]
+	}
+};
+const CODEX_REPRODUCIBLE_ARGS = [
+	"--ephemeral",
+	"--ignore-rules",
+	"--json",
+	"-c",
+	"approval_policy=\"never\"",
+	"-c",
+	"web_search=\"disabled\"",
+	"-c",
+	"project_doc_max_bytes=0",
+	"-c",
+	"skills.include_instructions=false",
+	"-c",
+	"include_apps_instructions=false",
+	"--disable",
+	"tool_suggest",
+	"-c",
+	"features.multi_agent_v2.root_agent_usage_hint_text=\"\"",
+	"-c",
+	"features.multi_agent_v2.subagent_usage_hint_text=\"\"",
+	"-c",
+	"features.multi_agent_v2.multi_agent_mode_hint_text=\"\"",
+	"--strict-config"
+];
+function buildHarnessArgs(harness, taskPrompt, options = {}) {
+	const args = HARNESS_INVOCATIONS[harness].buildArgs(taskPrompt);
+	if (harness === "claude" && options.dangerouslySkipPermissions) args.push("--dangerously-skip-permissions");
+	if (options.codexReproducible) {
+		if (harness !== "codex") throw new Error("harnessInvocation: codexReproducible requires the Codex harness");
+		args.push(...CODEX_REPRODUCIBLE_ARGS);
+	}
+	return args;
+}
+/**
+* Map a supervisor-authored `AgentProfile` + the per-task prompt onto a concrete harness
+* `command` + `args` (the §1.5 fix). UNLIKE the prompt-only `HARNESS_INVOCATIONS.buildArgs`
+* — which drops both the authored model and the system prompt — this threads the FULL
+* profile payload into argv:
+*
+*  - `profile.prompt.systemPrompt` → the PROMPT channel: a portable, harness-agnostic
+*    default that prepends the system prompt above the task prompt (`<system>\n\n<task>`),
+*    so the authored standing instructions reach EVERY harness (none of the three CLIs
+*    expose a portable replace-system-prompt flag for a one-shot non-interactive run).
+*  - `profile.prompt.instructions[]` → appended prompt sections in authored order.
+*  - `profile.model.default` → the harness's `-m <model>` selector.
+*
+* The task prompt alone is the floor; an empty/absent profile yields exactly the legacy
+* `buildArgs(taskPrompt)` shape so existing callers are byte-identical.
+*/
+function harnessInvocation(harness, profile, taskPrompt, options = {}) {
+	const invocation = HARNESS_INVOCATIONS[harness];
+	if (!invocation) throw new Error(`harnessInvocation: unknown harness ${String(harness)}`);
+	if (options.codexReproducible) {
+		const model = profile.model?.default;
+		if (typeof model !== "string" || model.trim().length === 0) throw new Error("harnessInvocation: codexReproducible requires profile.model.default");
+		if (profile.model?.reasoningEffort === void 0) throw new Error("harnessInvocation: codexReproducible requires profile.model.reasoningEffort");
+	}
+	const systemPrompt = profile.prompt?.systemPrompt;
+	const instructions = profile.prompt?.instructions;
+	if (instructions !== void 0 && (!Array.isArray(instructions) || instructions.some((instruction) => typeof instruction !== "string"))) throw new Error("harnessInvocation: profile.prompt.instructions must be an array of strings");
+	const composedPrompt = [
+		...typeof systemPrompt === "string" && systemPrompt.trim().length > 0 ? [systemPrompt] : [],
+		...instructions?.filter((instruction) => instruction.trim().length > 0) ?? [],
+		taskPrompt
+	].join("\n\n");
+	const args = buildHarnessArgs(harness, composedPrompt, options);
+	const model = profile.model?.default;
+	if (typeof model === "string" && model.length > 0) args.push(...invocation.modelArgs(model));
+	const reasoningEffort = profile.model?.reasoningEffort;
+	if (reasoningEffort !== void 0 && invocation.reasoningArgs) args.push(...invocation.reasoningArgs(reasoningEffort));
+	return {
+		command: invocation.command,
+		args,
+		prompt: composedPrompt
+	};
+}
+const DEFAULT_TIMEOUT_MS = 300 * 1e3;
+const DEFAULT_MAX_OUTPUT_BYTES = 64 * 1024 * 1024;
+const processKillGraceMs = 250;
+const processGroupExitConfirmMs = 1e3;
+const processGroupExitPollMs = 10;
+var RollingByteCapture = class {
+	maxBytes;
+	chunks = [];
+	bytes = 0;
+	constructor(maxBytes) {
+		this.maxBytes = maxBytes;
+	}
+	append(chunk) {
+		if (this.maxBytes === 0) return;
+		const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+		this.chunks.push(buffer);
+		this.bytes += buffer.length;
+		let excess = this.bytes - this.maxBytes;
+		while (excess > 0 && this.chunks.length > 0) {
+			const first = this.chunks[0];
+			if (first.length <= excess) {
+				this.chunks.shift();
+				this.bytes -= first.length;
+				excess -= first.length;
+			} else {
+				this.chunks[0] = first.subarray(excess);
+				this.bytes -= excess;
+				excess = 0;
+			}
+		}
+	}
+	text() {
+		return Buffer.concat(this.chunks, this.bytes).toString("utf8");
+	}
+};
+/**
+* Spawn a local coding harness CLI as a subprocess + collect its output.
+*
+* NOT responsible for parsing the harness's output or extracting a diff —
+* the in-process executor's `streamPrompt` orchestrates `git diff` against
+* the worktree after this resolves. This function is intentionally narrow:
+* spawn, wait, capture, return.
+*
+* Fails loud — throws when:
+*   - `cwd` doesn't exist (subprocess emits ENOENT; surfaced as Error)
+*   - the harness binary is not on PATH (ENOENT)
+*   - the caller signal was already aborted before process launch
+*
+* Does NOT throw when:
+*   - the subprocess exits non-zero (`result.exitCode` carries the code)
+*   - a non-reproducible subprocess is aborted / timed out (`result.aborted` /
+*     `result.timedOut` carries the reason even when a TERM-aware child exits zero)
+*
+* Reproducible Codex additionally requires a terminal usage event. If cancellation
+* prevents that event, this rejects with `CodexExecutionDiagnosticError` instead of
+* returning an incomplete reproducibility receipt.
+*
+* @experimental
+*/
+async function runLocalHarness(options) {
+	const { harness, cwd, taskPrompt } = options;
+	if (options.codexReproducible && harness !== "codex") throw new Error("runLocalHarness: codexReproducible requires the Codex harness");
+	if (options.codexReproducible && process.platform !== "linux") throw new Error("runLocalHarness: codexReproducible currently requires Linux");
+	if (options.codexReadDeniedPaths !== void 0 && !options.codexReproducible) throw new Error("runLocalHarness: codexReadDeniedPaths requires codexReproducible");
+	const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	const maxOutputBytes = options.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
+	if (!Number.isSafeInteger(maxOutputBytes) || maxOutputBytes < 0) throw new Error("runLocalHarness: maxOutputBytes must be a non-negative safe integer");
+	const spawnImpl = options.spawn ?? spawn;
+	const invocation = HARNESS_INVOCATIONS[harness];
+	if (!invocation) throw new Error(`runLocalHarness: unknown harness ${String(harness)}`);
+	const startedAt = Date.now();
+	const requestedCommand = options.invocation?.command ?? invocation.command;
+	const args = options.invocation ? [...options.invocation.args] : buildHarnessArgs(harness, taskPrompt, options);
+	if (options.codexReproducible) assertCodexReproducibleInvocation(requestedCommand, args);
+	options.signal?.throwIfAborted();
+	const baseEnv = {
+		...options.env ?? process.env,
+		PWD: cwd
+	};
+	const isolated = options.codexReproducible ? await isolateCodexHome({
+		baseEnv,
+		cwd,
+		command: requestedCommand,
+		readDeniedPaths: options.codexReadDeniedPaths ?? [],
+		resolveExecutable: options.resolveCodexExecutable ?? resolveCodexNativeExecutable
+	}) : {
+		env: baseEnv,
+		command: requestedCommand,
+		cleanup: async () => void 0,
+		controlledConfigSha256: "",
+		executableSha256: "",
+		readDeniedPathsSha256: "",
+		readDeniedPathCount: 0,
+		readDeniedPaths: [],
+		diagnosticRedactionValues: [],
+		ambientAuth: "",
+		isolatedAuth: "",
+		writeProbe: "",
+		stagedWriteProbe: "",
+		deniedProbePaths: []
+	};
+	const env = isolated.env;
+	const command = isolated.command;
+	if (options.codexReproducible) assertCodexReproducibleInvocation(command, args);
+	try {
+		const evidence = options.codexReproducible ? await collectCodexExecutionEvidence({
+			command,
+			args,
+			cwd,
+			env,
+			spawn: spawnImpl,
+			controlledConfigSha256: isolated.controlledConfigSha256,
+			executableSha256: isolated.executableSha256,
+			readDeniedPathsSha256: isolated.readDeniedPathsSha256,
+			readDeniedPathCount: isolated.readDeniedPathCount,
+			readDeniedPaths: isolated.readDeniedPaths,
+			ambientAuth: isolated.ambientAuth,
+			isolatedAuth: isolated.isolatedAuth,
+			writeProbe: isolated.writeProbe,
+			stagedWriteProbe: isolated.stagedWriteProbe,
+			deniedProbePaths: isolated.deniedProbePaths,
+			...options.signal ? { signal: options.signal } : {}
+		}) : void 0;
+		return await new Promise((resolve, reject) => {
+			let child;
+			try {
+				options.signal?.throwIfAborted();
+				child = spawnImpl(command, args, {
+					cwd,
+					env,
+					stdio: "pipe",
+					detached: process.platform !== "win32"
+				});
+			} catch (err) {
+				reject(err instanceof Error ? err : new Error(String(err)));
+				return;
+			}
+			child.stdin?.end();
+			const stdoutCapture = new RollingByteCapture(maxOutputBytes);
+			const stderrCapture = new RollingByteCapture(maxOutputBytes);
+			let timedOut = false;
+			let aborted = false;
+			let settled = false;
+			let leaderClosed = false;
+			let timer = null;
+			let termination = null;
+			const clearLifecycle = () => {
+				if (timer) clearTimeout(timer);
+				options.signal?.removeEventListener("abort", onAbort);
+			};
+			const rejectOnce = (err) => {
+				if (settled) return;
+				settled = true;
+				clearLifecycle();
+				reject(err instanceof Error ? err : new Error(String(err)));
+			};
+			const terminate = () => {
+				if (!termination) {
+					termination = terminateProcessTreeAndConfirm(child, () => leaderClosed);
+					termination.catch(rejectOnce);
+				}
+				return termination;
+			};
+			timer = timeoutMs > 0 ? setTimeout(() => {
+				timedOut = true;
+				terminate();
+			}, timeoutMs) : null;
+			if (timer && typeof timer.unref === "function") timer.unref();
+			const onAbort = () => {
+				aborted = true;
+				terminate();
+			};
+			if (options.signal) if (options.signal.aborted) onAbort();
+			else options.signal.addEventListener("abort", onAbort, { once: true });
+			child.stdout?.on("data", (chunk) => {
+				stdoutCapture.append(chunk);
+			});
+			child.stderr?.on("data", (chunk) => {
+				stderrCapture.append(chunk);
+			});
+			const finalize = (result) => {
+				if (settled) return;
+				settled = true;
+				clearLifecycle();
+				resolve(result);
+			};
+			child.on("error", (err) => {
+				leaderClosed = true;
+				if (timer) clearTimeout(timer);
+				(async () => {
+					try {
+						if (termination) await termination;
+						rejectOnce(err);
+					} catch (terminationError) {
+						rejectOnce(terminationError);
+					}
+				})();
+			});
+			child.on("close", (code, signal) => {
+				leaderClosed = true;
+				if (timer) clearTimeout(timer);
+				(async () => {
+					const stdout = stdoutCapture.text();
+					const stderr = stderrCapture.text();
+					try {
+						if (!termination && process.platform !== "win32" && typeof child.pid === "number" && processGroupExists(child.pid)) await terminate();
+						if (termination) await termination;
+						const durationMs = Date.now() - startedAt;
+						const usage = options.codexReproducible ? parseCodexTokenUsage(stdout) : void 0;
+						finalize({
+							exitCode: code,
+							stdout,
+							stderr: redactCodexHome(stderr, env.CODEX_HOME),
+							killedBySignal: signal,
+							durationMs,
+							timedOut,
+							aborted,
+							...usage ? { usage } : {},
+							...evidence ? { evidence } : {}
+						});
+					} catch (err) {
+						if (settled) return;
+						settled = true;
+						clearLifecycle();
+						const durationMs = Date.now() - startedAt;
+						const reason = err instanceof Error ? err.message : String(err);
+						reject(options.codexReproducible ? createCodexExecutionDiagnosticError({
+							reason,
+							exitCode: code,
+							killedBySignal: signal,
+							timedOut,
+							aborted,
+							durationMs,
+							stdout,
+							stderr,
+							codexHome: env.CODEX_HOME,
+							redactionValues: isolated.diagnosticRedactionValues,
+							cause: err
+						}) : err instanceof Error ? err : new Error(reason));
+					}
+				})();
+			});
+		});
+	} finally {
+		await isolated.cleanup();
+	}
+}
+const CODEX_EXECUTION_POLICY = {
+	sessionPersistence: "ephemeral",
+	userConfig: false,
+	rules: false,
+	projectInstructions: false,
+	skillInstructions: false,
+	appInstructions: false,
+	toolSuggestions: false,
+	multiAgentInstructions: false,
+	sandbox: "workspace-write",
+	permissionProfile: "agent_runtime_reproducible",
+	approvalPolicy: "never",
+	shellNetwork: false,
+	webSearch: false,
+	serviceTier: "default",
+	shellEnvironment: "core-filtered",
+	loginShell: false,
+	credentialsReadable: false,
+	hostHomeReadable: false,
+	procEnvironment: "private-sanitized",
+	sensitiveEnvironmentNamesVisible: false,
+	parentRepoRead: false,
+	gitMetadata: false,
+	temporaryDirectory: "workspace-private",
+	stagedExecutable: "static-elf-read-only",
+	callerReadDeniedPaths: "enforced",
+	containerSockets: false
+};
+const FORBIDDEN_CODEX_PROMPT_MARKERS = [
+	"<skills_instructions>",
+	"# AGENTS.md instructions",
+	"<apps_instructions>",
+	"<recommended_plugins>",
+	"<multi_agent_mode>",
+	"You are `/root`, the primary agent"
+];
+async function collectCodexExecutionEvidence(opts) {
+	assertCodexReproducibleInvocation(opts.command, opts.args);
+	const prompt = opts.args[1];
+	if (opts.args[0] !== "exec" || typeof prompt !== "string" || prompt.length === 0) throw new Error("runLocalHarness: reproducible Codex invocation must be codex exec <prompt>");
+	const cliVersion = (await runCodexProbe(opts, ["--version"])).stdout.trim();
+	if (!/^codex-cli \d+\.\d+\.\d+(?:[-+].+)?$/.test(cliVersion)) throw new Error(`runLocalHarness: unexpected Codex CLI version output ${JSON.stringify(cliVersion)}`);
+	const sandboxProof = [
+		[
+			"CODEX_HOME",
+			"CODEX_ACCESS_TOKEN",
+			"CODEX_API_KEY",
+			"OPENAI_API_KEY"
+		].map((name) => `test -z "\${${name}:-}"`).join(" && "),
+		"test -r .",
+		"! test -r .git",
+		"touch \"$1\"",
+		"rm \"$1\"",
+		"staged_dir=$(dirname \"$2\")",
+		"test -x \"$staged_dir/codex\"",
+		"! chmod 700 \"$staged_dir\" 2>/dev/null",
+		"! rm \"$staged_dir/codex\" 2>/dev/null",
+		"! touch \"$2\" 2>/dev/null",
+		"shift 2",
+		"for path in \"$@\"; do ! test -r \"$path\" || exit 1; done",
+		"touch \"$TMPDIR/.agent-runtime-tmp-proof\"",
+		"rm \"$TMPDIR/.agent-runtime-tmp-proof\""
+	].join(" && ");
+	await runCodexProbe(opts, [
+		"sandbox",
+		"-P",
+		CODEX_PERMISSION_PROFILE,
+		"-C",
+		opts.cwd,
+		"sh",
+		"-c",
+		sandboxProof,
+		"sh",
+		opts.writeProbe,
+		opts.stagedWriteProbe,
+		...opts.deniedProbePaths
+	]);
+	await runCodexProbe(opts, [
+		"sandbox",
+		"-P",
+		CODEX_PERMISSION_PROFILE,
+		"-C",
+		opts.cwd,
+		"python3",
+		"-c",
+		`import os,re
+pattern=re.compile(br'(TOKEN|KEY|SECRET|PASSWORD|CREDENTIAL|AUTH|COOKIE|CODEX_HOME)', re.I)
+paths=('/proc/1/environ', '/proc/self/environ', f'/proc/{os.getppid()}/environ')
+for path in dict.fromkeys(paths):
+ data=open(path,'rb').read().split(b'\\0')
+ names=(item.split(b'=',1)[0] for item in data if b'=' in item)
+ assert not any(pattern.search(name) for name in names), path`
+	]);
+	await runCodexProbe(opts, [
+		"sandbox",
+		"-P",
+		CODEX_PERMISSION_PROFILE,
+		"-C",
+		opts.cwd,
+		"python3",
+		"-c",
+		"import socket,sys\nfor path in sys.argv[1:]:\n s=socket.socket(socket.AF_UNIX)\n try: s.connect(path)\n except OSError: continue\n raise SystemExit(1)",
+		"/var/run/docker.sock",
+		"/run/docker.sock",
+		"/var/run/containerd/containerd.sock",
+		"/run/containerd/containerd.sock"
+	]);
+	const renderedPrompt = (await runCodexProbe(opts, codexPromptDebugArgs(opts.args, prompt))).stdout;
+	let parsedPrompt;
+	try {
+		parsedPrompt = JSON.parse(renderedPrompt);
+	} catch {
+		throw new Error("runLocalHarness: codex debug prompt-input returned invalid JSON");
+	}
+	const promptEvidenceText = normalizeCodexDebugPromptNewlines(prompt);
+	if (!Array.isArray(parsedPrompt) || !jsonTextContains(parsedPrompt, promptEvidenceText)) throw new Error("runLocalHarness: Codex prompt evidence did not contain the exact task prompt");
+	const promptContextWithoutTask = JSON.stringify(redactJsonText(parsedPrompt, promptEvidenceText));
+	for (const marker of FORBIDDEN_CODEX_PROMPT_MARKERS) if (promptContextWithoutTask.includes(marker)) throw new Error(`runLocalHarness: Codex prompt evidence contains forbidden marker ${marker}`);
+	for (const marker of ["<permissions instructions>", "<environment_context>"]) if (!renderedPrompt.includes(marker)) throw new Error(`runLocalHarness: Codex prompt evidence is missing required marker ${marker}`);
+	const nonPromptArgs = ["codex", ...opts.args.map((arg, index) => index === 1 ? "<PROMPT>" : arg)];
+	return {
+		cliVersion,
+		executableSha256: opts.executableSha256,
+		requestedPromptSha256: sha256(prompt),
+		effectivePromptSha256: sha256(renderedPrompt),
+		nonPromptArgsSha256: sha256(JSON.stringify(nonPromptArgs)),
+		controlledConfigSha256: opts.controlledConfigSha256,
+		readDeniedPathsSha256: opts.readDeniedPathsSha256,
+		readDeniedPathCount: opts.readDeniedPathCount,
+		readDeniedPaths: [...opts.readDeniedPaths],
+		policy: { ...CODEX_EXECUTION_POLICY }
+	};
+}
+function assertCodexReproducibleInvocation(command, args) {
+	const executable = basename(command);
+	if (executable !== "codex" && executable !== "codex.exe") throw new Error("runLocalHarness: reproducible Codex invocation must use the Codex executable");
+	const expectedPrefix = [
+		"exec",
+		args[1],
+		...CODEX_REPRODUCIBLE_ARGS
+	];
+	const hasExactPrefix = expectedPrefix.every((arg, index) => args[index] === arg);
+	const tail = args.slice(expectedPrefix.length);
+	const validModel = tail[0] === "-m" && typeof tail[1] === "string" && tail[1].length > 0 && !tail[1].startsWith("-");
+	const validReasoning = tail[2] === "-c" && typeof tail[3] === "string" && /^model_reasoning_effort="(?:none|minimal|low|medium|high|xhigh)"$/.test(tail[3]);
+	if (!hasExactPrefix || tail.length !== 4 || !validModel || !validReasoning) throw new Error("runLocalHarness: reproducible Codex invocation does not match the required isolated argv");
+}
+function codexPromptDebugArgs(execArgs, prompt) {
+	const debugArgs = ["debug", "prompt-input"];
+	for (let index = 2; index < execArgs.length; index += 1) {
+		const arg = execArgs[index];
+		const value = execArgs[index + 1];
+		if (arg === "-c" && value !== void 0) {
+			debugArgs.push("-c", value);
+			index += 1;
+		} else if (arg === "--disable" && value !== void 0) {
+			debugArgs.push("--disable", value);
+			index += 1;
+		} else if (arg === "-m" && value !== void 0) {
+			debugArgs.push("-c", `model=${JSON.stringify(value)}`);
+			index += 1;
+		} else if (arg === "-s" && value !== void 0) {
+			debugArgs.push("-c", `sandbox_mode=${JSON.stringify(value)}`);
+			index += 1;
+		}
+	}
+	debugArgs.push(prompt);
+	return debugArgs;
+}
+function runCodexProbe(opts, args) {
+	return new Promise((resolve, reject) => {
+		let child;
+		try {
+			child = opts.spawn(opts.command, args, {
+				cwd: opts.cwd,
+				env: opts.env,
+				stdio: "pipe",
+				detached: process.platform !== "win32"
+			});
+		} catch (err) {
+			reject(err instanceof Error ? err : new Error(String(err)));
+			return;
+		}
+		child.stdin?.end();
+		let stdout = "";
+		let stderr = "";
+		let settled = false;
+		let leaderClosed = false;
+		let termination = null;
+		let terminationReason = null;
+		const clearLifecycle = () => {
+			clearTimeout(timer);
+			opts.signal?.removeEventListener("abort", onAbort);
+		};
+		const rejectOnce = (err) => {
+			if (settled) return;
+			settled = true;
+			clearLifecycle();
+			reject(err instanceof Error ? err : new Error(String(err)));
+		};
+		const terminate = (reason) => {
+			if (reason) terminationReason ??= reason;
+			if (!termination) {
+				termination = terminateProcessTreeAndConfirm(child, () => leaderClosed);
+				termination.catch(rejectOnce);
+			}
+			return termination;
+		};
+		const timer = setTimeout(() => {
+			terminate("timed out");
+		}, 1e4);
+		timer.unref?.();
+		const onAbort = () => {
+			terminate("aborted");
+		};
+		if (opts.signal) if (opts.signal.aborted) onAbort();
+		else opts.signal.addEventListener("abort", onAbort, { once: true });
+		child.stdout?.on("data", (chunk) => {
+			stdout += String(chunk);
+		});
+		child.stderr?.on("data", (chunk) => {
+			stderr += String(chunk);
+		});
+		child.on("error", (err) => {
+			leaderClosed = true;
+			clearTimeout(timer);
+			(async () => {
+				try {
+					if (termination) await termination;
+					rejectOnce(err);
+				} catch (terminationError) {
+					rejectOnce(terminationError);
+				}
+			})();
+		});
+		child.on("close", (code, signal) => {
+			leaderClosed = true;
+			clearTimeout(timer);
+			(async () => {
+				try {
+					if (!termination && process.platform !== "win32" && typeof child.pid === "number" && processGroupExists(child.pid)) await terminate();
+					if (termination) await termination;
+					if (settled) return;
+					settled = true;
+					clearLifecycle();
+					if (code !== 0 || terminationReason) {
+						const safeStderr = redactCodexHome(stderr, opts.env.CODEX_HOME);
+						reject(/* @__PURE__ */ new Error(`runLocalHarness: Codex evidence probe ${terminationReason ?? "failed"} (exit ${String(code)}, signal ${String(signal)}): ${safeStderr.trim()}`));
+						return;
+					}
+					resolve({
+						stdout,
+						stderr
+					});
+				} catch (err) {
+					rejectOnce(err);
+				}
+			})();
+		});
+	});
+}
+function sha256(value) {
+	return createHash("sha256").update(value).digest("hex");
+}
+/** Codex's debug renderer converts CRLF pairs to LF. No other whitespace is equivalent. */
+function normalizeCodexDebugPromptNewlines(value) {
+	return value.replaceAll("\r\n", "\n");
+}
+function jsonTextContains(value, needle) {
+	if (typeof value === "string") return value.includes(needle);
+	if (Array.isArray(value)) return value.some((item) => jsonTextContains(item, needle));
+	if (isRecord(value)) return Object.values(value).some((item) => jsonTextContains(item, needle));
+	return false;
+}
+function redactJsonText(value, text) {
+	if (typeof value === "string") return value.replaceAll(text, "");
+	if (Array.isArray(value)) return value.map((item) => redactJsonText(item, text));
+	if (isRecord(value)) return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, redactJsonText(item, text)]));
+	return value;
+}
+const CODEX_AUTH_ENV = [
+	"CODEX_ACCESS_TOKEN",
+	"CODEX_API_KEY",
+	"OPENAI_API_KEY"
+];
+const CODEX_PERMISSION_PROFILE = "agent_runtime_reproducible";
+async function isolateCodexHome(opts) {
+	const isolatedHome = await mkdtemp(join(tmpdir(), "agent-runtime-codex-"));
+	await chmod(isolatedHome, 448);
+	let workspaceTemp = "";
+	let stagedExecutableDir = "";
+	let ownsStagedExecutableDir = false;
+	let writeProbe = "";
+	const cleanup = async () => {
+		if (ownsStagedExecutableDir) await chmod(stagedExecutableDir, 448).catch(() => void 0);
+		await Promise.all([
+			...writeProbe ? [rm(writeProbe, { force: true })] : [],
+			...workspaceTemp ? [rm(workspaceTemp, {
+				recursive: true,
+				force: true
+			})] : [],
+			...ownsStagedExecutableDir ? [rm(stagedExecutableDir, {
+				recursive: true,
+				force: true
+			})] : [],
+			rm(isolatedHome, {
+				recursive: true,
+				force: true
+			})
+		]);
+	};
+	try {
+		const readDeniedPaths = await normalizeReadDeniedPaths(opts.readDeniedPaths);
+		const candidateRoot = await realpath(opts.cwd);
+		writeProbe = join(candidateRoot, `.agent-runtime-write-proof-${randomUUID()}`);
+		const stagedPath = join(candidateRoot, ".agent-runtime-bin");
+		if (readDeniedPaths.some((path) => isSameOrDescendant(candidateRoot, path) || isSameOrDescendant(stagedPath, path) || isSameOrDescendant(path, stagedPath))) throw new Error("runLocalHarness: codexReadDeniedPaths cannot contain the candidate root or staged executable");
+		const nativeExecutable = await opts.resolveExecutable(opts.command, opts.baseEnv);
+		if (!await isStaticElfExecutable(nativeExecutable)) throw new Error("runLocalHarness: reproducible Codex mode requires a statically linked Linux Codex ELF");
+		const sourceExecutableSha256 = await sha256File(nativeExecutable);
+		stagedExecutableDir = stagedPath;
+		try {
+			await mkdir(stagedExecutableDir, { mode: 448 });
+			ownsStagedExecutableDir = true;
+		} catch (err) {
+			throw new Error(`runLocalHarness: candidate-private .agent-runtime-bin must not already exist: ${String(err.code ?? err)}`);
+		}
+		const stagedExecutable = join(stagedExecutableDir, "codex");
+		await copyFile(nativeExecutable, stagedExecutable, constants.COPYFILE_FICLONE);
+		await chmod(stagedExecutable, 320);
+		const executableSha256 = await sha256File(stagedExecutable);
+		if (executableSha256 !== sourceExecutableSha256 || !await isStaticElfExecutable(stagedExecutable)) throw new Error("runLocalHarness: staged Codex executable digest mismatch");
+		await chmod(stagedExecutableDir, 320);
+		workspaceTemp = await mkdtemp(join(candidateRoot, ".agent-runtime-tmp-"));
+		await chmod(workspaceTemp, 448);
+		const ambientHome = resolve(opts.baseEnv.CODEX_HOME?.trim() || join(homedir(), ".codex"));
+		const ambientAuth = join(ambientHome, "auth.json");
+		const isolatedAuth = join(isolatedHome, "auth.json");
+		let authText = "";
+		try {
+			await access(ambientAuth, constants.R_OK);
+			authText = await readCodexAuthRedactionText(ambientAuth);
+			await symlink(ambientAuth, isolatedAuth);
+		} catch (err) {
+			throw new Error(`runLocalHarness: reproducible Codex mode requires readable auth.json: ${String(err.code ?? err)}`);
+		}
+		const deniedHostRoots = [
+			homedir(),
+			opts.baseEnv.HOME?.trim(),
+			ambientHome
+		].filter((path) => Boolean(path)).map((path) => resolve(path)).filter((path, index, paths) => paths.indexOf(path) === index);
+		const controlledConfig = codexControlledConfig({
+			ambientTmp: opts.baseEnv.TMPDIR?.trim() || tmpdir(),
+			deniedHostRoots,
+			workspaceTemp,
+			stagedExecutableDir,
+			readDeniedPaths
+		});
+		await writeFile(join(isolatedHome, "config.toml"), controlledConfig, { mode: 384 });
+		const env = { ...opts.baseEnv };
+		for (const name of Object.keys(env)) if (codexSensitiveEnvironmentName.test(name) || CODEX_AUTH_ENV.some((authName) => authName === name)) delete env[name];
+		env.CODEX_HOME = isolatedHome;
+		const home = homedir();
+		const deniedProbePaths = [
+			...deniedHostRoots,
+			ambientAuth,
+			isolatedAuth,
+			join(home, ".claude", ".credentials.json"),
+			join(home, ".claude.json"),
+			join(home, ".local", "share", "opencode", "auth.json"),
+			join(home, ".agents"),
+			join(home, "Documents"),
+			join(home, "Downloads"),
+			join(home, ".npm"),
+			join(home, "code"),
+			...readDeniedPaths
+		].filter((path, index, paths) => paths.indexOf(path) === index);
+		return {
+			env,
+			command: stagedExecutable,
+			cleanup,
+			controlledConfigSha256: sha256(controlledConfig),
+			executableSha256,
+			readDeniedPaths,
+			readDeniedPathsSha256: sha256(JSON.stringify(readDeniedPaths)),
+			readDeniedPathCount: readDeniedPaths.length,
+			diagnosticRedactionValues: collectCodexDiagnosticRedactionValues(opts.baseEnv, authText),
+			ambientAuth,
+			isolatedAuth,
+			writeProbe,
+			stagedWriteProbe: join(stagedExecutableDir, "write-proof"),
+			deniedProbePaths
+		};
+	} catch (err) {
+		await cleanup();
+		throw err;
+	}
+}
+function codexControlledConfig(opts) {
+	const rules = /* @__PURE__ */ new Map();
+	const broadDeniedPaths = minimalPathRoots([
+		...opts.deniedHostRoots.map((path) => resolve(path)),
+		tmpdir(),
+		opts.ambientTmp,
+		"/proc",
+		"/run/docker",
+		"/run/containerd"
+	]);
+	for (const path of broadDeniedPaths) rules.set(path, "deny");
+	const workspaceRoot = dirname(opts.workspaceTemp);
+	for (const path of opts.readDeniedPaths) if (!broadDeniedPaths.some((root) => isSameOrDescendant(path, root)) || isSameOrDescendant(path, workspaceRoot)) rules.set(path, "deny");
+	if (!rules.has(opts.workspaceTemp)) rules.set(opts.workspaceTemp, "write");
+	if (!rules.has(opts.stagedExecutableDir)) rules.set(opts.stagedExecutableDir, "read");
+	const filesystemRules = [...rules].sort(([a], [b]) => a.localeCompare(b)).map(([path, access]) => `${JSON.stringify(path)} = ${JSON.stringify(access)}`).join("\n");
+	return `default_permissions = "${CODEX_PERMISSION_PROFILE}"
+approval_policy = "never"
+allow_login_shell = false
+service_tier = "default"
+
+[shell_environment_policy]
+inherit = "core"
+ignore_default_excludes = false
+exclude = ["^CODEX_HOME$", "(?i).*TOKEN.*", "(?i).*KEY.*", "(?i).*SECRET.*", "(?i).*PASSWORD.*", "(?i).*CREDENTIAL.*", "(?i).*AUTH.*", "(?i).*COOKIE.*"]
+set = { TMPDIR = ${JSON.stringify(opts.workspaceTemp)} }
+
+[permissions.${CODEX_PERMISSION_PROFILE}.filesystem]
+":minimal" = "read"
+${filesystemRules}
+":slash_tmp" = "deny"
+
+[permissions.${CODEX_PERMISSION_PROFILE}.filesystem.":workspace_roots"]
+"." = "write"
+".git" = "deny"
+
+[permissions.${CODEX_PERMISSION_PROFILE}.network]
+enabled = false
+
+[permissions.${CODEX_PERMISSION_PROFILE}.network.unix_sockets]
+"/var/run/docker.sock" = "deny"
+"/run/docker.sock" = "deny"
+"/var/run/containerd/containerd.sock" = "deny"
+"/run/containerd/containerd.sock" = "deny"
+`;
+}
+function isSameOrDescendant(path, root) {
+	const normalizedPath = resolve(path);
+	const normalizedRoot = resolve(root);
+	return normalizedPath === normalizedRoot || normalizedPath.startsWith(`${normalizedRoot}${sep}`);
+}
+function minimalPathRoots(paths) {
+	const ordered = [...new Set(paths.map((path) => resolve(path)))].sort((a, b) => a.length - b.length || a.localeCompare(b));
+	return ordered.filter((path, index) => !ordered.slice(0, index).some((root) => isSameOrDescendant(path, root)));
+}
+async function normalizeReadDeniedPaths(paths) {
+	if (!Array.isArray(paths)) throw new Error("runLocalHarness: codexReadDeniedPaths must be an array of absolute paths");
+	const normalized = /* @__PURE__ */ new Set();
+	for (const path of paths) {
+		if (typeof path !== "string" || path.length === 0 || path.includes("\0") || !isAbsolute(path)) throw new Error("runLocalHarness: codexReadDeniedPaths must contain absolute paths");
+		const absolute = resolve(path);
+		normalized.add(absolute);
+		try {
+			normalized.add(await realpath(absolute));
+		} catch (err) {
+			if (err.code !== "ENOENT") throw err;
+		}
+	}
+	return [...normalized].sort();
+}
+async function resolveCodexNativeExecutable(command, env) {
+	const candidates = command.includes(sep) || isAbsolute(command) ? [resolve(command)] : (env.PATH ?? "").split(delimiter).filter(Boolean).map((entry) => join(entry, command));
+	const seen = /* @__PURE__ */ new Set();
+	for (const candidate of candidates) {
+		let resolved;
+		try {
+			await access(candidate, constants.X_OK);
+			resolved = await realpath(candidate);
+		} catch {
+			continue;
+		}
+		if (seen.has(resolved)) continue;
+		seen.add(resolved);
+		if (await isStaticElfExecutable(resolved)) return resolved;
+		const packageRoot = await findCodexPackageRoot(resolved);
+		if (!packageRoot) continue;
+		const bundled = await findBundledCodexExecutable(packageRoot);
+		if (bundled) return bundled;
+	}
+	throw new Error("runLocalHarness: could not resolve the native Codex executable from the requested command");
+}
+async function findCodexPackageRoot(file) {
+	let cursor = dirname(file);
+	while (true) {
+		try {
+			if (JSON.parse(await readFile(join(cursor, "package.json"), "utf8")).name === "@openai/codex") return cursor;
+		} catch {}
+		const parent = dirname(cursor);
+		if (parent === cursor) return void 0;
+		cursor = parent;
+	}
+}
+async function findBundledCodexExecutable(packageRoot) {
+	const target = linuxCodexTarget();
+	const candidates = [join(packageRoot, "node_modules", "@openai", target.packageName, "vendor", target.triple, "bin", "codex"), join(packageRoot, "vendor", target.triple, "bin", "codex")];
+	for (const executable of candidates) if (await isStaticElfExecutable(executable)) return executable;
+}
+function linuxCodexTarget() {
+	if (process.platform !== "linux") throw new Error("runLocalHarness: reproducible Codex mode requires Linux");
+	if (process.arch === "x64") return {
+		packageName: "codex-linux-x64",
+		triple: "x86_64-unknown-linux-musl"
+	};
+	if (process.arch === "arm64") return {
+		packageName: "codex-linux-arm64",
+		triple: "aarch64-unknown-linux-musl"
+	};
+	throw new Error(`runLocalHarness: unsupported Linux architecture ${process.arch}`);
+}
+async function isStaticElfExecutable(path) {
+	let handle;
+	try {
+		await access(path, constants.X_OK);
+		handle = await open(path, "r");
+		const header = Buffer.alloc(64);
+		const { bytesRead } = await handle.read(header, 0, header.length, 0);
+		if (bytesRead !== header.length || !header.subarray(0, 4).equals(Buffer.from([
+			127,
+			69,
+			76,
+			70
+		])) || header[4] !== 2 || header[5] !== 1) return false;
+		const programHeaderOffset = Number(header.readBigUInt64LE(32));
+		const programHeaderSize = header.readUInt16LE(54);
+		const programHeaderCount = header.readUInt16LE(56);
+		const expectedMachine = process.arch === "x64" ? 62 : process.arch === "arm64" ? 183 : -1;
+		if (![2, 3].includes(header.readUInt16LE(16)) || header.readUInt16LE(18) !== expectedMachine || !Number.isSafeInteger(programHeaderOffset) || programHeaderOffset < 64 || programHeaderSize < 56 || programHeaderSize > 1024 || programHeaderCount === 0 || programHeaderCount > 1024) return false;
+		const tableSize = programHeaderSize * programHeaderCount;
+		const table = Buffer.alloc(tableSize);
+		if ((await handle.read(table, 0, tableSize, programHeaderOffset)).bytesRead !== tableSize) return false;
+		for (let index = 0; index < programHeaderCount; index += 1) if (table.readUInt32LE(index * programHeaderSize) === 3) return false;
+		return true;
+	} catch {
+		return false;
+	} finally {
+		await handle?.close();
+	}
+}
+function sha256File(path) {
+	return new Promise((resolveDigest, reject) => {
+		const hash = createHash("sha256");
+		const stream = createReadStream(path);
+		stream.on("error", reject);
+		stream.on("data", (chunk) => hash.update(chunk));
+		stream.on("end", () => resolveDigest(hash.digest("hex")));
+	});
+}
+function signalProcessTree(child, signal) {
+	if (process.platform !== "win32" && typeof child.pid === "number") try {
+		process.kill(-child.pid, signal);
+		return;
+	} catch (err) {
+		if (err.code === "ESRCH") return;
+	}
+	try {
+		child.kill(signal);
+	} catch {}
+}
+async function terminateProcessTreeAndConfirm(child, leaderClosed, context = "runLocalHarness") {
+	signalProcessTree(child, "SIGTERM");
+	if (process.platform === "win32" || typeof child.pid !== "number") {
+		const graceDeadline = Date.now() + processKillGraceMs;
+		while (!leaderClosed() && Date.now() < graceDeadline) await delayUntilNextProcessCheck(graceDeadline);
+		if (!leaderClosed()) signalProcessTree(child, "SIGKILL");
+		return;
+	}
+	const processGroupId = child.pid;
+	if (await waitForProcessGroupExit(processGroupId, Date.now() + processKillGraceMs)) return;
+	signalProcessTree(child, "SIGKILL");
+	if (await waitForProcessGroupExit(processGroupId, Date.now() + processGroupExitConfirmMs)) return;
+	throw new Error(`${context}: process group ${processGroupId} survived SIGKILL`);
+}
+async function waitForProcessGroupExit(processGroupId, deadline) {
+	while (processGroupExists(processGroupId)) {
+		if (Date.now() >= deadline) return false;
+		await delayUntilNextProcessCheck(deadline);
+	}
+	return true;
+}
+async function delayUntilNextProcessCheck(deadline) {
+	const delayMs = Math.min(processGroupExitPollMs, Math.max(0, deadline - Date.now()));
+	if (delayMs > 0) await new Promise((resolve) => setTimeout(resolve, delayMs));
+}
+function processGroupExists(processGroupId) {
+	try {
+		process.kill(-processGroupId, 0);
+		return true;
+	} catch (err) {
+		if (err.code === "ESRCH") return false;
+		return true;
+	}
+}
+/** Parse and validate the one terminal usage event emitted by `codex exec --json`. */
+function parseCodexTokenUsage(stdout) {
+	const completed = [];
+	for (const [index, line] of stdout.split(/\r?\n/).entries()) {
+		if (line.trim().length === 0) continue;
+		let event;
+		try {
+			event = JSON.parse(line);
+		} catch {
+			throw new Error(`runLocalHarness: Codex JSONL line ${index + 1} is not valid JSON`);
+		}
+		if (isRecord(event) && event.type === "turn.completed") completed.push(event);
+	}
+	if (completed.length !== 1) throw new Error(`runLocalHarness: expected exactly one Codex turn.completed usage event, received ${completed.length}`);
+	const event = completed[0];
+	if (!isRecord(event) || !isRecord(event.usage)) throw new Error("runLocalHarness: Codex turn.completed event is missing usage");
+	const usage = event.usage;
+	const inputTokens = naturalNumber(usage.input_tokens, "input_tokens");
+	const cachedInputTokens = naturalNumber(usage.cached_input_tokens, "cached_input_tokens");
+	const outputTokens = naturalNumber(usage.output_tokens, "output_tokens");
+	const reasoningOutputTokens = naturalNumber(usage.reasoning_output_tokens, "reasoning_output_tokens");
+	if (cachedInputTokens > inputTokens) throw new Error("runLocalHarness: Codex cached_input_tokens exceeds input_tokens");
+	if (reasoningOutputTokens > outputTokens) throw new Error("runLocalHarness: Codex reasoning_output_tokens exceeds output_tokens");
+	return {
+		inputTokens,
+		cachedInputTokens,
+		outputTokens,
+		reasoningOutputTokens
+	};
+}
+function isRecord(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function naturalNumber(value, field) {
+	if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) throw new Error(`runLocalHarness: Codex usage.${field} must be a non-negative safe integer`);
+	return value;
+}
+//#endregion
+//#region src/mcp/worktree.ts
+/**
+*
+* Git worktree helpers for the in-process delegation executor. Each
+* delegation runs in its own worktree so multiple parallel harness
+* subprocesses (claude / codex / opencode in a 3-way fanout) don't clobber
+* each other's edits on the shared workspace.
+*
+* Worktrees live under `<repoRoot>/.agent-worktrees/<runId>/`. After the
+* harness exits + the diff is captured, the worktree is removed.
+*
+* All operations spawn `git` via `child_process.spawn` synchronously
+* (via a `runGit` helper). Stays narrow on purpose: no commits, no rebases.
+* Diff capture stages all changes (`git add -A`) into the ephemeral worktree's
+* index so created (untracked) files appear in the `--cached` diff.
+*
+* @experimental
+*/
+async function runGitAsync(args, cwd, runner) {
+	if (runner) return runner(args, { cwd });
+	return new Promise((resolve, reject) => {
+		const proc = spawn("git", args, {
+			cwd,
+			stdio: "pipe"
+		});
+		let stdout = "";
+		let stderr = "";
+		proc.stdout?.on("data", (c) => {
+			stdout += String(c);
+		});
+		proc.stderr?.on("data", (c) => {
+			stderr += String(c);
+		});
+		proc.on("error", reject);
+		proc.on("close", (code) => resolve({
+			stdout,
+			stderr,
+			exitCode: code ?? -1
+		}));
+	});
+}
+function ensureGitOk(step, result) {
+	if (result.exitCode !== 0) throw gitFailure(step, result);
+}
+function gitFailure(step, result) {
+	return /* @__PURE__ */ new Error(`worktree: git ${step} failed (exit ${result.exitCode}): ${result.stderr.slice(0, 400)}`);
+}
+/** Checkout a fresh git worktree for a delegation run on a new branch under `variantsDir`. @experimental */
+async function createWorktree(options) {
+	const variants = options.variantsDir ?? ".agent-worktrees";
+	const baseRef = options.baseRef ?? "HEAD";
+	const branch = `delegate/${options.runId}`;
+	const path = `${options.repoRoot.replace(/\/+$/, "")}/${variants}/${options.runId}`;
+	const headSha = await runGitAsync(["rev-parse", baseRef], options.repoRoot, options.runGit);
+	ensureGitOk(`rev-parse ${baseRef}`, headSha);
+	const add = await runGitAsync([
+		"worktree",
+		"add",
+		"-b",
+		branch,
+		path,
+		baseRef
+	], options.repoRoot, options.runGit);
+	ensureGitOk(`worktree add ${path}`, add);
+	return {
+		path,
+		baseSha: headSha.stdout.trim(),
+		branch
+	};
+}
+/** Stage worker changes and return the diff + shortstat, excluding declared input paths. @experimental */
+async function captureWorktreeDiff(options) {
+	const baseRef = options.baseRef ?? options.worktree.baseSha;
+	const pathspecs = worktreeDiffPathspecs(options.excludePaths ?? []);
+	ensureGitOk("add -A", await runGitAsync([
+		"add",
+		"-A",
+		...pathspecs.length > 0 ? [
+			"--",
+			".",
+			...pathspecs
+		] : []
+	], options.worktree.path, options.runGit));
+	const patch = await runGitAsync([
+		"diff",
+		"--cached",
+		baseRef,
+		...pathspecs.length > 0 ? [
+			"--",
+			".",
+			...pathspecs
+		] : []
+	], options.worktree.path, options.runGit);
+	ensureGitOk(`diff --cached ${baseRef}`, patch);
+	const shortstat = await runGitAsync([
+		"diff",
+		"--cached",
+		"--shortstat",
+		baseRef,
+		...pathspecs.length > 0 ? [
+			"--",
+			".",
+			...pathspecs
+		] : []
+	], options.worktree.path, options.runGit);
+	ensureGitOk(`diff --cached --shortstat ${baseRef}`, shortstat);
+	const stats = parseShortstat(shortstat.stdout);
+	return {
+		patch: patch.stdout,
+		stats
+	};
+}
+function worktreeDiffPathspecs(paths) {
+	const normalized = /* @__PURE__ */ new Set();
+	for (const path of paths) {
+		if (typeof path !== "string" || path.length === 0 || path.includes("\\") || hasControlCharacter(path) || isAbsolute(path) || win32.isAbsolute(path)) throw new Error(`worktree: excluded path must be a canonical repository-relative path: ${path}`);
+		if (path.split("/").some((segment) => segment.length === 0 || segment === "." || segment === "..")) throw new Error(`worktree: excluded path must be a canonical repository-relative path: ${path}`);
+		normalized.add(path);
+	}
+	return [...normalized].sort((left, right) => left.localeCompare(right)).map((path) => `:(top,exclude,literal)${path}`);
+}
+function hasControlCharacter(value) {
+	for (let index = 0; index < value.length; index += 1) {
+		const code = value.charCodeAt(index);
+		if (code < 32 || code === 127) return true;
+	}
+	return false;
+}
+function parseShortstat(text) {
+	const out = {
+		filesChanged: 0,
+		insertions: 0,
+		deletions: 0
+	};
+	const filesMatch = text.match(/(\d+)\s+files?\s+changed/);
+	if (filesMatch?.[1]) out.filesChanged = Number(filesMatch[1]);
+	const insertMatch = text.match(/(\d+)\s+insertions?/);
+	if (insertMatch?.[1]) out.insertions = Number(insertMatch[1]);
+	const deleteMatch = text.match(/(\d+)\s+deletions?/);
+	if (deleteMatch?.[1]) out.deletions = Number(deleteMatch[1]);
+	return out;
+}
+/**
+* Remove a git worktree and delete its branch. Already-removed paths are harmless; every other
+* Git failure rejects so callers cannot report a worktree as destroyed when cleanup failed.
+* @experimental
+*/
+async function removeWorktree(options) {
+	const force = options.force ?? true;
+	const args = ["worktree", "remove"];
+	if (force) args.push("--force");
+	args.push(options.worktree.path);
+	const removal = await runGitAsync(args, options.repoRoot, options.runGit);
+	const removalError = removal.exitCode !== 0 && !/not a working tree/iu.test(removal.stderr) ? gitFailure(`worktree remove ${options.worktree.path}`, removal) : void 0;
+	const branchRemoval = await runGitAsync([
+		"branch",
+		"-D",
+		options.worktree.branch
+	], options.repoRoot, options.runGit);
+	const branchError = branchRemoval.exitCode !== 0 && !/branch .+ not found/iu.test(branchRemoval.stderr) ? gitFailure(`branch -D ${options.worktree.branch}`, branchRemoval) : void 0;
+	if (removalError && branchError) throw new AggregateError([removalError, branchError], "worktree: failed to remove worktree and branch");
+	if (removalError) throw removalError;
+	if (branchError) throw branchError;
+}
+//#endregion
+//#region src/mcp/worktree-harness.ts
+/**
+*
+* The ONE worktree-harness execution core. The physical act — run a supervisor-authored
+* `AgentProfile` on a local coding-harness CLI (claude / codex / opencode) against a fresh git
+* worktree off `repoRoot`, capture the diff, derive the test/typecheck PASS signals, then clean
+* up — lives here ONCE. Two executors adapt it to two ports without re-implementing it:
+*   - `createWorktreeCliExecutor` — the `Scope`/`Supervisor` leaf `Executor`.
+*   - `createInProcessExecutor`   — the `runAgentRounds` `SandboxClient` / coder-delegate path.
+*
+* §1.5 by construction: prompt + model reach the direct invocation, while file-backed resources
+* are lowered by the shared profile materializer and applied before spawn. Resource instructions
+* join the direct prompt because reproducible Codex intentionally disables ambient project docs.
+*
+* Lifecycle: `createWorktree` → materialize profile inputs → `harnessInvocation` +
+* `runLocalHarness` → `captureWorktreeDiff` excluding those inputs (BEFORE checks, so the patch is
+* the harness's output, not polluted by files a test run writes) → configured checks → return the
+* result + caller-owned `cleanup`. A throw cleans up before propagating.
+*
+* @experimental
+*/
+const defaultCheckOutputCap = 16e3;
+function materializerHarness(harness) {
+	return harness === "claude" ? "claude-code" : harness;
+}
+/**
+* Run the one worktree-harness operation. A failed run attempts cleanup before propagating; if
+* cleanup also fails, both errors are preserved. The caller cleans up a successful run.
+*/
+async function runWorktreeHarness(opts) {
+	opts.signal?.throwIfAborted();
+	const runHarness = opts.runHarness ?? runLocalHarness;
+	const runCommand = opts.runCommand ?? defaultRunCommand;
+	const checkTimeoutMs = opts.checkTimeoutMs ?? opts.harnessTimeoutMs ?? 300 * 1e3;
+	const cap = opts.checkOutputCap ?? defaultCheckOutputCap;
+	const worktree = await createWorktree({
+		repoRoot: opts.repoRoot,
+		runId: opts.runId,
+		...opts.baseRef ? { baseRef: opts.baseRef } : {},
+		...opts.runGit ? { runGit: opts.runGit } : {}
+	});
+	const cleanup = () => removeWorktree({
+		worktree,
+		repoRoot: opts.repoRoot,
+		...opts.runGit ? { runGit: opts.runGit } : {}
+	});
+	try {
+		assertSupportedWorktreeProfile(opts.profile, opts.harness);
+		assertSafeProfileResourcePaths(opts.profile);
+		const resourceInstructions = resolveResourceInstructions(opts.profile);
+		const plan = materializeProfile(materializationOnlyProfile(opts.profile), materializerHarness(opts.harness));
+		if (plan.unsupported.length > 0) throw new Error(`runWorktreeHarness: profile cannot be materialized for ${opts.harness}: ${plan.unsupported.map(({ dimension, reason }) => `${dimension}: ${reason}`).join("; ")}`);
+		assertSafeMaterializedPaths(plan);
+		const applied = applyWorkspacePlan(plan, worktree.path, { existingFiles: "reject" });
+		if (applied.unsupported.length > 0) throw new Error("runWorktreeHarness: applied profile unexpectedly retained unsupported rows");
+		const invocationProfile = profileWithResourceInstructions(opts.profile, resourceInstructions);
+		const { command, args } = harnessInvocation(opts.harness, invocationProfile, opts.taskPrompt, {
+			dangerouslySkipPermissions: opts.harness === "claude",
+			...opts.codexReproducible ? { codexReproducible: true } : {}
+		});
+		const harnessResult = await runHarness({
+			harness: opts.harness,
+			cwd: worktree.path,
+			taskPrompt: opts.taskPrompt,
+			invocation: {
+				command,
+				args: [...args, ...applied.flags]
+			},
+			env: {
+				...process.env,
+				...applied.env
+			},
+			...opts.codexReproducible ? { codexReproducible: true } : {},
+			...opts.codexReadDeniedPaths ? { codexReadDeniedPaths: opts.codexReadDeniedPaths } : {},
+			...opts.harnessTimeoutMs !== void 0 ? { timeoutMs: opts.harnessTimeoutMs } : {},
+			...opts.signal ? { signal: opts.signal } : {}
+		});
+		if (harnessResult.aborted || opts.signal?.aborted) throw new Error("runWorktreeHarness: harness was cancelled by the caller", { cause: opts.signal?.reason });
+		opts.signal?.throwIfAborted();
+		const diff = await captureWorktreeDiff({
+			worktree,
+			excludePaths: applied.written,
+			...opts.runGit ? { runGit: opts.runGit } : {}
+		});
+		opts.signal?.throwIfAborted();
+		const checks = await runWorktreeChecks({
+			worktreePath: worktree.path,
+			...opts.testCmd !== void 0 ? { testCmd: opts.testCmd } : {},
+			...opts.typecheckCmd !== void 0 ? { typecheckCmd: opts.typecheckCmd } : {},
+			timeoutMs: checkTimeoutMs,
+			cap,
+			runCommand,
+			...opts.signal ? { signal: opts.signal } : {}
+		});
+		opts.signal?.throwIfAborted();
+		return {
+			worktree,
+			result: {
+				branch: worktree.branch,
+				patch: diff.patch,
+				stats: diff.stats,
+				profileMaterialization: profileMaterializationReceipt(applied, resourceInstructions),
+				harness: {
+					name: opts.harness,
+					exitCode: harnessResult.exitCode,
+					timedOut: harnessResult.timedOut,
+					killedBySignal: harnessResult.killedBySignal,
+					durationMs: harnessResult.durationMs,
+					stdout: harnessResult.stdout,
+					stderr: harnessResult.stderr,
+					...harnessResult.usage ? { usage: harnessResult.usage } : {},
+					...harnessResult.evidence ? {
+						cliVersion: harnessResult.evidence.cliVersion,
+						executableSha256: harnessResult.evidence.executableSha256,
+						requestedPromptSha256: harnessResult.evidence.requestedPromptSha256,
+						effectivePromptSha256: harnessResult.evidence.effectivePromptSha256,
+						nonPromptArgsSha256: harnessResult.evidence.nonPromptArgsSha256,
+						controlledConfigSha256: harnessResult.evidence.controlledConfigSha256,
+						readDeniedPaths: [...harnessResult.evidence.readDeniedPaths],
+						readDeniedPathsSha256: harnessResult.evidence.readDeniedPathsSha256,
+						readDeniedPathCount: harnessResult.evidence.readDeniedPathCount,
+						executionPolicy: harnessResult.evidence.policy
+					} : {}
+				},
+				...checks ? { checks } : {}
+			},
+			cleanup
+		};
+	} catch (err) {
+		try {
+			await cleanup();
+		} catch (cleanupError) {
+			throw new AggregateError([err, cleanupError], "runWorktreeHarness: run failed and worktree cleanup also failed");
+		}
+		throw err;
+	}
+}
+function resolveResourceInstructions(profile) {
+	const instructions = profile.resources?.instructions;
+	if (instructions === void 0) return void 0;
+	if (typeof instructions === "string") return instructions.trim().length > 0 ? instructions : void 0;
+	if (instructions.kind === "inline" && typeof instructions.content === "string") return instructions.content.trim().length > 0 ? instructions.content : void 0;
+	throw new Error("runWorktreeHarness: resources.instructions must be a string or inline resource; remote refs require pre-resolution");
+}
+function profileWithResourceInstructions(profile, resourceInstructions) {
+	let resources;
+	if (profile.resources) {
+		const { instructions: _instructions, ...structuralResources } = profile.resources;
+		resources = structuralResources;
+	}
+	return {
+		...profile,
+		...resources ? { resources } : {},
+		...resourceInstructions === void 0 ? {} : { prompt: {
+			...profile.prompt,
+			instructions: [...profile.prompt?.instructions ?? [], resourceInstructions]
+		} }
+	};
+}
+function materializationOnlyProfile(profile) {
+	const { prompt: _prompt, model: _model, resources: profileResources, ...structuralProfile } = profile;
+	let resources;
+	if (profileResources) {
+		const { instructions: _instructions, ...fileBackedResources } = profileResources;
+		resources = fileBackedResources;
+	}
+	return {
+		...structuralProfile,
+		...resources ? { resources } : {}
+	};
+}
+function assertSupportedWorktreeProfile(profile, harness) {
+	const unsupportedAxes = [
+		hasEntries(profile.tools) ? "tools" : null,
+		hasEntries(profile.permissions) ? "permissions" : null,
+		profile.connections && profile.connections.length > 0 ? "connections" : null,
+		hasEntries(profile.confidential) ? "confidential" : null,
+		hasEntries(profile.modes) ? "modes" : null,
+		hasEntries(profile.extensions) ? "extensions" : null
+	].filter((axis) => axis !== null);
+	if (profile.model?.reasoningEffort !== void 0 && harness !== "codex") unsupportedAxes.push("model.reasoningEffort");
+	for (const [name, server] of Object.entries(profile.mcp ?? {})) {
+		const path = `mcp[${JSON.stringify(name)}]`;
+		if (server.enabled === false && harness !== "opencode") unsupportedAxes.push(`${path}.enabled`);
+		if (hasEntries(server.headers) && harness === "codex") unsupportedAxes.push(`${path}.headers`);
+		if (server.cwd !== void 0 && harness === "opencode") unsupportedAxes.push(`${path}.cwd`);
+	}
+	if (harness === "claude") for (const [event, commands] of Object.entries(profile.hooks ?? {})) for (const [index, command] of commands.entries()) {
+		const path = `hooks[${JSON.stringify(event)}][${index}]`;
+		if (hasEntries(command.env)) unsupportedAxes.push(`${path}.env`);
+		if (command.blocking !== void 0) unsupportedAxes.push(`${path}.blocking`);
+	}
+	for (const [name, subagent] of Object.entries(profile.subagents ?? {})) {
+		const path = `subagents[${JSON.stringify(name)}]`;
+		if (hasEntries(subagent.permissions)) unsupportedAxes.push(`${path}.permissions`);
+		if (subagent.maxSteps !== void 0) unsupportedAxes.push(`${path}.maxSteps`);
+		if (hasEntries(subagent.tools) && harness !== "claude") unsupportedAxes.push(`${path}.tools`);
+	}
+	if (unsupportedAxes.length > 0) throw new Error(`runWorktreeHarness: profile requests unsupported worktree behavior: ${unsupportedAxes.join(", ")}`);
+}
+function hasEntries(value) {
+	return value !== void 0 && Object.keys(value).length > 0;
+}
+function assertSafeMaterializedPaths(plan) {
+	for (const file of plan.files) if (file.relPath.split("/").some(isGitMetadataSegment)) throw new Error(`runWorktreeHarness: profile file cannot target reserved Git metadata: ${file.relPath}`);
+}
+function assertSafeProfileResourcePaths(profile) {
+	for (const file of profile.resources?.files ?? []) if (file.path.split("/").some(isGitMetadataSegment)) throw new Error(`runWorktreeHarness: profile file cannot target reserved Git metadata: ${file.path}`);
+}
+function isGitMetadataSegment(segment) {
+	const windowsCanonical = segment.replace(/[ .]+$/u, "").toLowerCase();
+	return windowsCanonical === ".git" || windowsCanonical.startsWith(".git:");
+}
+function profileMaterializationReceipt(applied, resourceInstructions) {
+	const instructionBytes = resourceInstructions === void 0 ? null : Buffer.from(resourceInstructions, "utf8");
+	return {
+		workspacePlanDigest: applied.workspacePlanDigest,
+		writtenPaths: [...applied.written],
+		unsupported: [...applied.unsupported],
+		environmentNames: Object.keys(applied.env).sort(),
+		flags: [...applied.flags],
+		resourceInstructions: instructionBytes ? {
+			delivery: "invocation-prompt",
+			sha256: `sha256:${createHash("sha256").update(instructionBytes).digest("hex")}`,
+			byteLength: instructionBytes.byteLength
+		} : {
+			delivery: "none",
+			sha256: null,
+			byteLength: 0
+		}
+	};
+}
+/** Run the configured test + typecheck commands in the live worktree, projecting exit codes into
+*  `checks`. Returns `undefined` when neither was configured (so the result omits `checks`). */
+async function runWorktreeChecks(opts) {
+	opts.signal?.throwIfAborted();
+	if (opts.testCmd === void 0 && opts.typecheckCmd === void 0) return void 0;
+	const runCommand = opts.runCommand ?? defaultRunCommand;
+	const run = async (command) => {
+		opts.signal?.throwIfAborted();
+		const res = await runCommand({
+			command,
+			cwd: opts.worktreePath,
+			timeoutMs: opts.timeoutMs,
+			...opts.signal ? { signal: opts.signal } : {}
+		});
+		opts.signal?.throwIfAborted();
+		return {
+			command,
+			passed: res.exitCode === 0,
+			exitCode: res.exitCode,
+			output: res.output.length > opts.cap ? res.output.slice(-opts.cap) : res.output
+		};
+	};
+	const checks = {};
+	if (opts.testCmd !== void 0) checks.tests = await run(opts.testCmd);
+	opts.signal?.throwIfAborted();
+	if (opts.typecheckCmd !== void 0) checks.typecheck = await run(opts.typecheckCmd);
+	opts.signal?.throwIfAborted();
+	return checks;
+}
+/** Internal argv-safe process runner shared by worktree checks and improvement verifiers. */
+async function runSettledCommand(opts) {
+	opts.signal?.throwIfAborted();
+	return new Promise((resolve, reject) => {
+		const child = spawn(opts.command, opts.args ?? [], {
+			cwd: opts.cwd,
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			],
+			detached: process.platform !== "win32"
+		});
+		const stdout = [];
+		const stderr = [];
+		let settled = false;
+		let leaderClosed = false;
+		let timedOut = false;
+		let termination = null;
+		const terminate = () => {
+			termination ??= terminateProcessTreeAndConfirm(child, () => leaderClosed, "defaultRunCommand");
+			return termination;
+		};
+		const timer = setTimeout(() => {
+			timedOut = true;
+			terminate().catch(fail);
+		}, opts.timeoutMs);
+		const onAbort = () => void terminate().catch(fail);
+		if (opts.signal) if (opts.signal.aborted) onAbort();
+		else opts.signal.addEventListener("abort", onAbort, { once: true });
+		child.stdout?.on("data", (d) => stdout.push(String(d)));
+		child.stderr?.on("data", (d) => stderr.push(String(d)));
+		const finish = (fn) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			opts.signal?.removeEventListener("abort", onAbort);
+			fn();
+		};
+		function fail(err) {
+			finish(() => reject(err instanceof Error ? err : new Error(String(err))));
+		}
+		child.on("error", (err) => {
+			leaderClosed = true;
+			(termination ?? Promise.resolve()).then(() => fail(err), fail);
+		});
+		child.on("close", (code, killedBySignal) => {
+			leaderClosed = true;
+			(async () => {
+				try {
+					await (termination ?? terminate());
+					opts.signal?.throwIfAborted();
+					finish(() => resolve({
+						exitCode: code,
+						stdout: stdout.join(""),
+						stderr: stderr.join(""),
+						killedBySignal,
+						timedOut
+					}));
+				} catch (err) {
+					fail(err);
+				}
+			})();
+		});
+	});
+}
+/** Default verification-command runner — `/bin/sh -c <command>` in the worktree, capturing
+*  combined stdout+stderr. Never throws on a non-zero exit (that IS the fail signal); spawn
+*  failures and caller cancellation reject. Timeout terminates and confirms the whole process
+*  group before returning. */
+async function defaultRunCommand(opts) {
+	const result = await runSettledCommand({
+		command: "/bin/sh",
+		args: ["-c", opts.command],
+		cwd: opts.cwd,
+		timeoutMs: opts.timeoutMs,
+		...opts.signal ? { signal: opts.signal } : {}
+	});
+	return {
+		exitCode: result.exitCode,
+		output: result.stdout + result.stderr
+	};
+}
+//#endregion
+//#region src/runtime/tool-loop.ts
+/** ≈ chars/4 over content + any tool-call arguments — a cheap, provider-agnostic size proxy. The
+*  exact constant does not matter: it only has to track GROWTH so the threshold trips as history
+*  accumulates, which a uniform chars/4 does. */
+function estimateConversationTokens(messages) {
+	let chars = 0;
+	for (const m of messages) {
+		const content = m.content;
+		chars += typeof content === "string" ? content.length : safeJsonLength(content);
+		const calls = m.tool_calls;
+		if (calls) for (const c of calls) chars += c.function?.arguments?.length ?? 0;
+	}
+	return Math.ceil(chars / 4);
+}
+function safeJsonLength(value) {
+	if (value === void 0 || value === null) return 0;
+	try {
+		return JSON.stringify(value)?.length ?? 0;
+	} catch {
+		return String(value).length;
+	}
+}
+/** Distill the conversation's accumulated middle into one note and splice it in, IF the estimated
+*  size exceeds the threshold. Returns true when a compaction fired. The preserved head keeps the
+*  system + task verbatim; everything after collapses to a single `user` progress note, so no
+*  assistant `tool_calls` is left without its `tool` replies. */
+async function maybeCompact(messages, c, turn) {
+	const head = c.preserveHead !== void 0 && c.preserveHead > 0 ? c.preserveHead : 2;
+	if (messages.length <= head + 1) return false;
+	const estimate = c.estimateTokens ?? estimateConversationTokens;
+	const before = estimate(messages);
+	if (before <= c.thresholdTokens) return false;
+	const digest = await c.distill([...messages]);
+	messages.splice(head, messages.length - head, {
+		role: "user",
+		content: `[earlier work compacted to save context — progress so far]\n${digest}`
+	});
+	c.onCompact?.({
+		turn,
+		beforeTokens: before,
+		afterTokens: estimate(messages)
+	});
+	return true;
+}
+async function runBrainLoop(opts) {
+	const maxTurns = opts.maxTurns ?? 4;
+	const messages = [...opts.initialMessages];
+	let toolCalls = 0;
+	let lastText = "";
+	const usage = {
+		input: 0,
+		output: 0
+	};
+	const toolTrace = [];
+	for (let turn = 1; turn <= maxTurns; turn += 1) {
+		if (opts.hooks?.stopBefore?.(turn)) break;
+		await opts.hooks?.beforeTurn?.(turn, messages);
+		if (opts.compaction) await maybeCompact(messages, opts.compaction, turn);
+		const r = await opts.chat(messages, opts.tools);
+		if (r.usage) {
+			usage.input += r.usage.input;
+			usage.output += r.usage.output;
+			opts.hooks?.onUsage?.(r.usage);
+		}
+		if (r.content) lastText = r.content;
+		if (r.toolCalls.length === 0) {
+			if (r.content) messages.push({
+				role: "assistant",
+				content: r.content
+			});
+			return {
+				final: lastText,
+				turns: turn,
+				toolCalls,
+				toolTrace,
+				usage,
+				messages
+			};
+		}
+		messages.push({
+			role: "assistant",
+			content: r.content ?? "",
+			tool_calls: r.toolCalls.map((tc) => ({
+				id: tc.id,
+				type: "function",
+				function: {
+					name: tc.name,
+					arguments: tc.arguments
+				}
+			}))
+		});
+		for (const tc of r.toolCalls) {
+			toolCalls += 1;
+			let args = {};
+			try {
+				args = JSON.parse(tc.arguments);
+			} catch {
+				messages.push({
+					role: "tool",
+					tool_call_id: tc.id,
+					content: `error: arguments were not valid JSON: ${tc.arguments.slice(0, 200)}`
+				});
+				continue;
+			}
+			const out = await opts.execute(tc.name, args);
+			messages.push({
+				role: "tool",
+				tool_call_id: tc.id,
+				content: out
+			});
+			toolTrace.push({
+				name: tc.name,
+				args: tc.arguments,
+				result: out
+			});
+		}
+	}
+	return {
+		final: lastText,
+		turns: maxTurns,
+		toolCalls,
+		toolTrace,
+		usage,
+		messages
+	};
+}
+//#endregion
+//#region src/runtime/router-client.ts
+/**
+* The one router chat client: direct OpenAI-compatible completions through the
+* Tangle router — the cheapest dial, no sandbox. Three layers: `routerChatWithUsage`
+* (chat-only), `routerChatWithTools` (one completion with function tools), and
+* `routerToolLoop` (the off-box agentic loop over tool-calling). Shared by the
+* built-in executors and the bench/lab harnesses.
+*
+* Reports REAL token usage so the backend-integrity guard sees a real backend.
+* Returns `undefined` usage when the provider omitted it — never a fabricated 0
+* (a phantom 0 reads as a free call downstream, which the gate would act on).
+*/
+/** One OpenAI-compatible chat completion through the Tangle router, returning text + REAL token usage (`undefined` when the provider omits it — never a fabricated 0). */
+async function routerChatWithUsage(cfg, messages, opts) {
+	const url = `${cfg.routerBaseUrl.replace(/\/$/, "")}/chat/completions`;
+	const headers = {
+		"content-type": "application/json",
+		authorization: `Bearer ${cfg.routerKey}`
+	};
+	let temperature = opts?.temperature ?? .2;
+	const body = () => ({
+		model: cfg.model,
+		messages,
+		temperature,
+		max_tokens: opts?.maxTokens ?? 8192,
+		...opts?.reasoningEffort ? { reasoning_effort: opts.reasoningEffort } : {}
+	});
+	if (cfg.complete) return parseChatResult(await cfg.complete(body()), cfg.model);
+	let lastErr = "";
+	for (let attempt = 0; attempt < 5; attempt += 1) {
+		const res = await fetch(url, {
+			method: "POST",
+			headers,
+			body: JSON.stringify(body()),
+			...opts?.signal ? { signal: opts.signal } : {}
+		});
+		if (res.ok) return parseChatResult(await res.json(), cfg.model);
+		const status = res.status;
+		const text = (await res.text()).slice(0, 200);
+		lastErr = `router ${status}: ${text}`;
+		if (status === 400 && /temperature/i.test(text) && temperature !== 1) {
+			temperature = 1;
+			continue;
+		}
+		if (![
+			408,
+			425,
+			429,
+			500,
+			502,
+			503,
+			504,
+			520,
+			522,
+			524
+		].includes(status)) throw new Error(lastErr);
+		if (attempt < 4) await new Promise((r) => setTimeout(r, 800 * 2 ** attempt));
+	}
+	throw new Error(`${lastErr} (exhausted retries)`);
+}
+function parseChatResult(json, model) {
+	const data = json;
+	const u = data.usage;
+	const usage = u && typeof u.prompt_tokens === "number" && typeof u.completion_tokens === "number" ? {
+		input: u.prompt_tokens,
+		output: u.completion_tokens
+	} : void 0;
+	const costUsd = usage && isModelPriced(model) ? estimateCost(usage.input, usage.output, model) : void 0;
+	const msg = data.choices?.[0]?.message;
+	const { content, reasoning } = splitReasoning(msg?.content ?? "", msg?.reasoning ?? msg?.reasoning_content);
+	return {
+		content,
+		...reasoning ? { reasoning } : {},
+		...usage ? { usage } : {},
+		...costUsd !== void 0 ? { costUsd } : {}
+	};
+}
+/**
+* Normalize the two ways providers surface thinking-model reasoning into one shape:
+* a separate field (OpenRouter: `reasoning`, DeepSeek/Kimi: `reasoning_content`) or a
+* `<think>...</think>` block inlined at the head of `content` (Groq, some local runtimes).
+* An UNCLOSED `<think>` (the model hit max_tokens mid-thought) yields empty content and
+* everything as reasoning — which is honest: no final answer was emitted.
+*/
+function splitReasoning(rawContent, fieldReasoning) {
+	const open = rawContent.indexOf("<think>");
+	if (open !== -1) {
+		const close = rawContent.indexOf("</think>", open);
+		const inline = close !== -1 ? rawContent.slice(open + 7, close) : rawContent.slice(open + 7);
+		const rest = close !== -1 ? rawContent.slice(0, open) + rawContent.slice(close + 8) : rawContent.slice(0, open);
+		const reasoning = [fieldReasoning, inline.trim()].filter(Boolean).join("\n");
+		return {
+			content: rest.trim(),
+			...reasoning ? { reasoning } : {}
+		};
+	}
+	return {
+		content: rawContent,
+		...fieldReasoning ? { reasoning: fieldReasoning } : {}
+	};
+}
+/**
+* A router completion WITH tool-calling — the operator driver's LLM seam. Passes OpenAI-shape
+* `messages` (system/user/assistant-with-tool_calls/tool roles) + function `tools`, and returns the
+* assistant text plus the tool calls the model wants run. Same fail-loud + real-usage discipline as
+* `routerChatWithUsage`. `tool_choice: 'auto'` lets the model decide; the driver loops on the result.
+*/
+async function routerChatWithTools(cfg, messages, tools, opts) {
+	const body = {
+		model: cfg.model,
+		messages,
+		tools,
+		tool_choice: opts?.toolChoice ?? "auto",
+		temperature: opts?.temperature ?? .3,
+		...opts?.maxTokens ? { max_tokens: opts.maxTokens } : {}
+	};
+	const data = cfg.complete ? await cfg.complete(body) : await (async () => {
+		const res = await fetch(`${cfg.routerBaseUrl.replace(/\/$/, "")}/chat/completions`, {
+			method: "POST",
+			headers: {
+				"content-type": "application/json",
+				authorization: `Bearer ${cfg.routerKey}`
+			},
+			body: JSON.stringify(body),
+			...opts?.signal ? { signal: opts.signal } : {}
+		});
+		if (!res.ok) throw new Error(`router ${res.status}: ${(await res.text()).slice(0, 200)}`);
+		return res.json();
+	})();
+	const msg = data.choices?.[0]?.message;
+	const toolCalls = (msg?.tool_calls ?? []).map((tc, i) => ({
+		id: tc.id ?? `call_${i}`,
+		name: tc.function?.name ?? "",
+		arguments: tc.function?.arguments ?? "{}"
+	}));
+	const u = data.usage;
+	const usage = u && typeof u.prompt_tokens === "number" && typeof u.completion_tokens === "number" ? {
+		input: u.prompt_tokens,
+		output: u.completion_tokens
+	} : void 0;
+	const costUsd = usage && isModelPriced(cfg.model) ? estimateCost(usage.input, usage.output, cfg.model) : void 0;
+	return {
+		content: msg?.content ?? null,
+		toolCalls,
+		...usage ? { usage } : {},
+		...costUsd !== void 0 ? { costUsd } : {}
+	};
+}
+/**
+* The tool-using router backend: a real agentic loop OVER the Tangle router (which
+* supports tool-calling), off-box — no sandbox. Each turn is one router completion
+* with `tools`; if the model emits tool_calls, `execute` runs them on the host and
+* their results are folded back as `tool` messages; the loop repeats until the
+* model answers without a tool call or the turn budget is hit. One turn = one
+* inference call, so `maxTurns` is the equal-compute unit against random@k.
+*
+* This is the depth substrate for agentic gates (the worker ACTS, observes the real
+* result, and continues) that the chat-only `routerChatWithUsage` cannot express.
+*/
+async function routerToolLoop(cfg, system, user, tools, execute, opts) {
+	return runBrainLoop({
+		chat: (messages, toolSpecs) => routerChatWithTools(cfg, messages, toolSpecs, {
+			...opts?.temperature !== void 0 ? { temperature: opts.temperature } : {},
+			...opts?.maxTokens ? { maxTokens: opts.maxTokens } : {},
+			...opts?.signal ? { signal: opts.signal } : {}
+		}),
+		tools,
+		execute,
+		initialMessages: opts?.initialMessages ?? [{
+			role: "system",
+			content: system
+		}, {
+			role: "user",
+			content: user
+		}],
+		maxTurns: opts?.maxTurns ?? 4
+	});
+}
+/**
+* The router as a supervisor BRAIN: the canonical `ToolLoopChat` seam backed by the router's
+* tool-calling. The driver's spawn/observe/steer/await/stop turns become real router tool-calls.
+* The turnkey production brain — tests script a mock `ToolLoopChat`; production passes
+* `routerBrain(cfg)`. No message translation: the loop already speaks the router's OpenAI shape.
+*/
+function routerBrain(cfg, opts = {}) {
+	const temperature = opts.temperature ?? .4;
+	return (messages, tools) => routerChatWithTools(cfg, messages, tools, {
+		temperature,
+		toolChoice: "auto"
+	});
+}
+//#endregion
+//#region src/runtime-hooks.ts
+/** Identity helper that types a {@link RuntimeHooks} literal so the fields are inferred. */
+function defineRuntimeHooks(hooks) {
+	return hooks;
+}
+/**
+* Merge several {@link RuntimeHooks} into one. Falsy entries are dropped (so you can
+* pass `flag && hooks`), and every observer's `onEvent`/`onDecisionPoint` fires for each
+* event. Use this to attach N observers to a loop instead of a second event bus.
+*/
+function composeRuntimeHooks(...entries) {
+	const hooks = entries.filter((entry) => !!entry);
+	return {
+		onEvent: hooks.some((hook) => hook.onEvent) ? (event, context) => {
+			const pending = [];
+			for (const hook of hooks) {
+				const result = hook.onEvent?.(event, context);
+				if (isThenable(result)) pending.push(Promise.resolve(result));
+			}
+			if (pending.length > 0) return Promise.all(pending).then(() => void 0);
+		} : void 0,
+		onDecisionPoint: hooks.some((hook) => hook.onDecisionPoint) ? (point, context) => {
+			const pending = [];
+			for (const hook of hooks) {
+				const result = hook.onDecisionPoint?.(point, context);
+				if (isThenable(result)) pending.push(Promise.resolve(result));
+			}
+			if (pending.length > 0) return Promise.all(pending).then(() => void 0);
+		} : void 0,
+		onHookError: hooks.some((hook) => hook.onHookError) ? (error, context) => {
+			const pending = [];
+			for (const hook of hooks) {
+				const result = hook.onHookError?.(error, context);
+				if (isThenable(result)) pending.push(Promise.resolve(result));
+			}
+			if (pending.length > 0) return Promise.all(pending).then(() => void 0);
+		} : void 0
+	};
+}
+/** Fire `hooks.onEvent`, swallowing sync throws and surfacing async failures to `onError`. */
+function notifyRuntimeHookEvent(hooks, event, context = {}) {
+	const onEvent = hooks?.onEvent;
+	if (!onEvent) return;
+	try {
+		const result = onEvent(event, context);
+		if (isThenable(result)) result.catch((error) => {
+			notifyRuntimeHookError(hooks, toError(error), {
+				hook: "onEvent",
+				eventId: event.id,
+				target: event.target,
+				phase: event.phase
+			});
+		});
+	} catch (error) {
+		notifyRuntimeHookError(hooks, toError(error), {
+			hook: "onEvent",
+			eventId: event.id,
+			target: event.target,
+			phase: event.phase
+		});
+	}
+}
+/** Fire `hooks.onDecisionPoint`, swallowing sync throws and surfacing async failures to `onError`. */
+function notifyRuntimeDecisionPoint(hooks, point, context = {}) {
+	const onDecisionPoint = hooks?.onDecisionPoint;
+	if (!onDecisionPoint) return;
+	try {
+		const result = onDecisionPoint(point, context);
+		if (isThenable(result)) result.catch((error) => {
+			notifyRuntimeHookError(hooks, toError(error), {
+				hook: "onDecisionPoint",
+				decisionId: point.id,
+				decisionKind: point.kind
+			});
+		});
+	} catch (error) {
+		notifyRuntimeHookError(hooks, toError(error), {
+			hook: "onDecisionPoint",
+			decisionId: point.id,
+			decisionKind: point.kind
+		});
+	}
+}
+function notifyRuntimeHookError(hooks, error, context) {
+	try {
+		const result = hooks?.onHookError?.(error, context);
+		if (isThenable(result)) result.catch(() => void 0);
+	} catch {}
+}
+function isThenable(value) {
+	return typeof value === "object" && value !== null && "then" in value && typeof value.then === "function";
+}
+function toError(error) {
+	return error instanceof Error ? error : new Error(String(error));
+}
+//#endregion
+//#region src/runtime/supervise/progress.ts
+/** How long a worker may produce no metered activity before a `progress()` read calls it stalled.
+*  Deliberately generous: a coding harness routinely spends minutes inside one tool call, and a
+*  false stall that provokes a steer is worse than a late one. */
+const DEFAULT_STALL_AFTER_MS = 18e4;
+/** Create a bounded activity ring. `limit` caps memory for a worker that runs thousands of tools. */
+function createActivityLog(limit = 12) {
+	const notes = [];
+	const cap = Math.max(1, Math.floor(limit));
+	return {
+		push(note) {
+			notes.push(note);
+			if (notes.length > cap) notes.splice(0, notes.length - cap);
+		},
+		read: () => [...notes],
+		last: () => notes[notes.length - 1],
+		size: () => notes.length
+	};
+}
+/** Fold the scope-derived facts and the executor's optional enrichment into one read. Pure: the
+*  caller supplies `now`, so a test can observe a stall without waiting for one. */
+function readWorkerProgress(scope, executor, now, stallAfterMs = DEFAULT_STALL_AFTER_MS) {
+	const live = scope.status !== "done" && scope.status !== "failed" && scope.status !== "cancelled";
+	const executorActivityAt = executor?.recentActivity?.length ? executor.recentActivity[executor.recentActivity.length - 1].at : 0;
+	const lastActivityAt = Math.max(scope.lastActivityAt, executorActivityAt);
+	const idleMs = Math.max(0, now - lastActivityAt);
+	const note = executor?.note;
+	return {
+		id: scope.id,
+		status: scope.status,
+		live,
+		steerable: scope.steerable,
+		startedAt: scope.startedAt,
+		lastActivityAt,
+		idleMs,
+		stalled: live && idleMs > stallAfterMs,
+		stallAfterMs,
+		turns: executor?.turns ?? scope.turns,
+		tokens: scope.tokens,
+		usd: scope.usd,
+		pendingMessages: executor?.pendingMessages ?? 0,
+		recentActivity: executor?.recentActivity ?? [],
+		...note ? { note } : {}
+	};
+}
+//#endregion
+//#region src/runtime/supervise/wait.ts
+/**
+*
+* WAIT-STATES — a supervision-tree node that waits on wall-clock time or an external condition
+* without holding a worker, an executor, a sandbox, or a single LLM turn.
+*
+* A long-horizon run spends most of its wall-clock NOT computing: waiting for CI to finish,
+* for a nightly job to land, for a human to reply, for a rate-limit window to reopen. Before
+* this, the only way to express that was to keep something alive and re-ask — which spends
+* driver tokens per re-ask and pins a process to the wait.
+*
+* Two node kinds, both first-class:
+*   - `timer` — wake at an ABSOLUTE wall-clock instant (`untilMs`).
+*   - `poll`  — re-run a named predicate every `intervalMs` until it returns true, or until an
+*               absolute `timeoutAtMs` passes (CI status, file existence, an HTTP probe, an
+*               inbox message).
+*
+* ── How this differs from `await_event`'s 15s poll fence (`DEFAULT_AWAIT_EVENT_TIMEOUT_MS`) ──
+*
+* They look similar and are not the same mechanism. `await_event` is an IN-RUN RENDEZVOUS: the
+* driver blocks on the coordination bus for the next event from a live worker, and the 15s fence
+* exists only so a remote MCP request does not exceed the client's timeout — the caller re-polls.
+* Every re-poll is another driver inference turn (real tokens) against a process that must stay
+* up, and nothing about that wait is recorded: kill the process and the wait is simply gone.
+*
+* A wait-state is a NODE, not a call. It has a node id in the tree, a journal record carrying its
+* ABSOLUTE deadline, and it settles through the same `Scope.next()` cursor as any worker. Nobody
+* is blocked on it — the driver can stop reasoning entirely, and the process can die. Cost while
+* waiting: zero LLM calls, zero executor, zero sandbox, zero conserved budget (a wait reserves
+* nothing from the pool). The only in-process residue is one timer entry.
+*
+* ── Why probes are NAMED, not passed as closures ────────────────────────────────────────────
+*
+* A wait must survive a process restart with its original deadline intact, and a closure cannot
+* be journaled. So a `poll` names its predicate (`probe: 'ci-green'`) and the run resolves it
+* through a `WaitProbeRegistry`. A brand-new process re-resolves the SAME name against its own
+* registry and re-arms the wait — which is what makes "kill the box, the wait keeps waiting"
+* true rather than aspirational.
+*
+* Absolute instants for the same reason: `untilMs` / `timeoutAtMs` are epoch ms, not durations,
+* so a resumed wait counts down from the original arm, not from the restart. `timerAt`/`pollFor`
+* build them from a duration when that is what the caller has.
+*
+* @experimental
+*/
+/** Build a `timer` spec from a DURATION. The instant is resolved once, at arm time — a resumed
+*  wait re-uses the journaled instant, never a fresh `now + ms`. */
+function timerAt(ms, now) {
+	return {
+		kind: "timer",
+		untilMs: now + ms
+	};
+}
+/** Build a bounded `poll` spec from a duration. */
+function pollFor(probe, opts, now) {
+	return {
+		kind: "poll",
+		probe,
+		intervalMs: opts.intervalMs,
+		...opts.timeoutMs !== void 0 ? { timeoutAtMs: now + opts.timeoutMs } : {},
+		...opts.args ? { args: opts.args } : {}
+	};
+}
+/** Registry over a plain name→predicate record. */
+function createWaitProbes(entries) {
+	const map = new Map(Object.entries(entries));
+	return { resolve: (name) => map.get(name) };
+}
+/** Narrow a settlement's `out` to a wait outcome — a wait settles on the SAME cursor as workers,
+*  so a driver that mixes them tags them apart with this. */
+function isWaitOutcome(value) {
+	return typeof value === "object" && value !== null && value.waitOutcome === true;
+}
+/** The absolute instant a spec is bounded by, or `undefined` for an unbounded poll. */
+function waitUntil(spec) {
+	return spec.kind === "timer" ? spec.untilMs : spec.timeoutAtMs;
+}
+/** Structural validation, independent of the run. Returns null when the spec is usable. */
+function validateWaitSpec(spec) {
+	if (spec.kind === "timer") return Number.isFinite(spec.untilMs) ? null : "timer.untilMs must be a finite epoch-ms instant";
+	if (typeof spec.probe !== "string" || spec.probe.length === 0) return "poll.probe must be a non-empty probe name";
+	if (!Number.isFinite(spec.intervalMs) || spec.intervalMs <= 0) return "poll.intervalMs must be > 0";
+	if (spec.timeoutAtMs !== void 0 && !Number.isFinite(spec.timeoutAtMs)) return "poll.timeoutAtMs must be a finite epoch-ms instant";
+	return null;
+}
+/**
+* A wait must not silently outlive the run's HARD wall-clock ceiling. When the conserved pool
+* carries an absolute `deadlineMs`, a wait bounded past it — or an unbounded poll — is REFUSED at
+* arm time (`deadline-exceeded`) rather than sleeping through a ceiling the caller already set.
+* The alternative (extending the pool's deadline to cover the wait) would let a wait override a
+* hard budget guard, which is exactly what mechanic D forbids; a run that intends week-long waits
+* either sets a deadline that covers them or sets none.
+*/
+function assertWaitWithinDeadline(spec, deadlineMs) {
+	if (deadlineMs <= 0) return true;
+	const until = waitUntil(spec);
+	if (until === void 0) return false;
+	return until <= deadlineMs;
+}
+/**
+* Drive one wait to its resolution. Spends nothing: a `timer` is one sleep, a `poll` is a sleep
+* between predicate checks. No LLM call, no executor, no box, no budget reservation.
+*/
+async function runWait(args) {
+	const { spec, label, armedAt, resumed, signal, now } = args;
+	const sleep = args.sleep ?? defaultSleep;
+	if (signal.aborted) return {
+		kind: "cancelled",
+		reason: "aborted before arming"
+	};
+	if (spec.kind === "timer") {
+		const remaining = spec.untilMs - now();
+		if (remaining > 0) await sleep(remaining, signal);
+		if (signal.aborted) return {
+			kind: "cancelled",
+			reason: "wait aborted"
+		};
+		return {
+			kind: "woke",
+			outcome: outcome("timer", "fired", label, spec.untilMs, armedAt, now(), 0, 0, resumed)
+		};
+	}
+	const probe = args.probes?.resolve(spec.probe);
+	if (!probe) throw new ValidationError(`wait '${label}': poll probe '${spec.probe}' is not registered in this run's WaitProbeRegistry`);
+	let polls = 0;
+	let probeErrors = 0;
+	for (;;) {
+		if (signal.aborted) return {
+			kind: "cancelled",
+			reason: "wait aborted"
+		};
+		polls += 1;
+		let fired = false;
+		try {
+			fired = await probe(spec.args, signal);
+		} catch {
+			probeErrors += 1;
+		}
+		if (fired) return {
+			kind: "woke",
+			outcome: outcome("poll", "fired", label, spec.timeoutAtMs, armedAt, now(), polls, probeErrors, resumed)
+		};
+		if (spec.timeoutAtMs !== void 0 && now() >= spec.timeoutAtMs) return {
+			kind: "woke",
+			outcome: outcome("poll", "timeout", label, spec.timeoutAtMs, armedAt, now(), polls, probeErrors, resumed)
+		};
+		await sleep(spec.timeoutAtMs === void 0 ? spec.intervalMs : Math.min(spec.intervalMs, Math.max(0, spec.timeoutAtMs - now())), signal);
+	}
+}
+function outcome(kind, settled, label, untilMs, armedAt, wokenAt, polls, probeErrors, resumed) {
+	return {
+		waitOutcome: true,
+		kind,
+		settled,
+		label,
+		...untilMs !== void 0 ? { untilMs } : {},
+		armedAt,
+		wokenAt,
+		polls,
+		probeErrors,
+		resumed
+	};
+}
+/** `setTimeout` that resolves early (and clears) when the scope aborts, so a cancelled wait
+*  releases the event loop immediately instead of holding the process to its deadline. */
+function defaultSleep(ms, signal) {
+	if (ms <= 0 || signal.aborted) return Promise.resolve();
+	return new Promise((resolve) => {
+		const timer = setTimeout(() => {
+			signal.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		function onAbort() {
+			clearTimeout(timer);
+			resolve();
+		}
+		signal.addEventListener("abort", onAbort, { once: true });
+	});
+}
+//#endregion
+//#region src/runtime/supervise/scope.ts
+/**
+*
+* The reactive `Scope` impl (KEYSTONE, build step 4 + the step-8 adapter).
+*
+* An `Agent.act` runs inside a `Scope`. It `spawn`s children dynamically and reacts to
+* them via `next()`. The scope owns ONE in-memory nursery — the authoritative live set —
+* and is the single place that drives a child's lifecycle: reserve budget atomically,
+* resolve a `Executor` through the open registry, run it (one-shot OR streaming),
+* fold its normalized `UsageEvent`s into a conserved `Spend`, reconcile the reservation
+* (refunding the unspent remainder), persist the result blob + journal records, and
+* deliver the `Settled` through the `next()` cursor.
+*
+* Three invariants this impl enforces by construction:
+*  - `next()` is a ray.wait n=1 cursor over THIS scope's live set; it assigns the
+*    monotonic `seq` (the recorded cursor order) at the moment it yields a settlement, so
+*    replay re-delivers in the identical order — `seq` is never wall-clock.
+*  - Budget is reserved at spawn and reconciled at settle through the shared `BudgetPool`,
+*    so `spawn` fails CLOSED on an exhausted pool and total ≡ free + reserved + committed.
+*  - `view` reads the in-memory nursery, never the journal — O(live), synchronous.
+*
+* The settle path is the only writer of journal `settled` events; the spawn path the only
+* writer of `spawned` events. The result blob is `put` BEFORE the journal `settled` record
+* references its `outRef`, so a crash can never leave a journaled ref with no blob.
+*
+* @experimental
+*/
+/**
+* The recursion seam key. A `Scope` seeds a value of this on each child's
+* `ExecutorContext.seams` so a child whose executor is a DRIVER can mount a NESTED `Scope`
+* over the SAME conserved pool at `depth+1`. A leaf executor never reads it. Single-sourced
+* here so the scope and the driver-executor agree on the seam without a circular import.
+*/
+const nestedScopeSeamKey = "nested-scope";
+function makeNestedScopeSeam(args, childNodeId) {
+	return {
+		depth: args.depth,
+		...args.maxDepth !== void 0 ? { maxDepth: args.maxDepth } : {},
+		journalRoot: args.root,
+		mount(nestedRoot, signal) {
+			return createScope({
+				parentId: childNodeId,
+				root: nestedRoot,
+				pool: args.pool,
+				journal: args.journal,
+				blobs: args.blobs,
+				executors: args.executors,
+				seams: args.seams,
+				depth: args.depth + 1,
+				...args.maxDepth !== void 0 ? { maxDepth: args.maxDepth } : {},
+				signal,
+				...args.now ? { now: args.now } : {},
+				...args.hooks ? { hooks: args.hooks } : {}
+			});
+		}
+	};
+}
+/** Create the reactive `Scope` a driver's `Agent.act` runs inside: spawn children on an atomically reserved conserved budget, settle via the `next()` cursor, journal for replay. */
+function createScope(args) {
+	const children = /* @__PURE__ */ new Map();
+	let spawnOrdinal = args.resumeFrom ? args.resumeFrom.maxSpawnOrdinal + 1 : 0;
+	let cursorSeq = args.resumeFrom ? args.resumeFrom.maxCursorSeq + 1 : 0;
+	let waitOrdinal = args.resumeFrom ? args.resumeFrom.maxWaitOrdinal + 1 : 0;
+	let meterSeq = 0;
+	const now = args.now ?? Date.now;
+	const unclaimedWaits = new Map((args.resumeFrom?.waits ?? []).map((w) => [w.label, w]));
+	function spawn(agent, task, opts) {
+		if (args.maxDepth !== void 0 && args.depth >= args.maxDepth) return {
+			ok: false,
+			reason: "depth-exceeded"
+		};
+		const spec = agent.executorSpec;
+		if (!isAgentSpec(spec)) throw new ValidationError(`scope.spawn: agent "${agent.name}" exposes no \`executorSpec\` (AgentSpec) to resolve a Executor`);
+		const resolved = args.executors.resolve(spec);
+		if (!resolved.succeeded) throw new ValidationError(`scope.spawn: ${resolved.error}`);
+		const reservation = args.pool.reserve(opts.budget);
+		if (!reservation.ok) return {
+			ok: false,
+			reason: reservation.reason
+		};
+		try {
+			const ordinal = spawnOrdinal++;
+			const id = `${args.parentId}:s${ordinal}`;
+			const childAbort = new AbortController();
+			const cascadeAbort = () => childAbort.abort();
+			if (args.signal.aborted) childAbort.abort();
+			else args.signal.addEventListener("abort", cascadeAbort, { once: true });
+			const ctx = {
+				signal: childAbort.signal,
+				seams: {
+					...args.seams,
+					[nestedScopeSeamKey]: makeNestedScopeSeam(args, id)
+				}
+			};
+			const executor = resolved.value(spec, ctx);
+			const handle = {
+				id,
+				label: opts.label,
+				get status() {
+					return children.get(id)?.status ?? "cancelled";
+				},
+				abort(reason) {
+					childAbort.abort(reason);
+				}
+			};
+			const live = {
+				id,
+				status: "acquiring",
+				runtime: executor.runtime,
+				budget: opts.budget,
+				label: opts.label,
+				spent: zeroSpend(),
+				settled: void 0,
+				delivered: false,
+				executorDone: false,
+				startedAt: now(),
+				lastActivityAt: now(),
+				...executor.deliver ? { deliver: executor.deliver.bind(executor) } : {},
+				...executor.progress ? { readProgress: executor.progress.bind(executor) } : {},
+				...executor.traceSource ? { readTraceSource: executor.traceSource.bind(executor) } : {}
+			};
+			children.set(id, live);
+			args.journal.appendEvent(args.root, {
+				kind: "spawned",
+				id,
+				parent: args.parentId,
+				label: opts.label,
+				budget: opts.budget,
+				runtime: executor.runtime,
+				seq: ordinal,
+				at: new Date(now()).toISOString()
+			});
+			notifyRuntimeHookEvent(args.hooks, {
+				id: `${id}:spawn`,
+				runId: args.root,
+				target: "agent.spawn",
+				phase: "after",
+				timestamp: now(),
+				stepIndex: ordinal,
+				parentId: args.parentId,
+				payload: {
+					childId: id,
+					label: opts.label,
+					runtime: executor.runtime,
+					budget: opts.budget,
+					depth: args.depth
+				}
+			}, { signal: args.signal });
+			live.settled = runChild(live, executor, childAbort, task, opts, args.pool, reservation.ticket, args.blobs, now).then((s) => {
+				live.resolved = s;
+				return s;
+			}).finally(() => {
+				args.signal.removeEventListener("abort", cascadeAbort);
+			});
+			return {
+				ok: true,
+				handle
+			};
+		} catch (err) {
+			args.pool.reconcile(reservation.ticket, zeroSpend());
+			throw err;
+		}
+	}
+	async function next() {
+		const undelivered = () => [...children.values()].filter((c) => !c.delivered);
+		if (undelivered().length === 0) return null;
+		for (;;) {
+			const pending = undelivered();
+			if (pending.length === 0) return null;
+			const chosen = pending.find((c) => c.resolved !== void 0) ?? await raceFirstSettled(pending);
+			if (chosen.delivered) continue;
+			chosen.delivered = true;
+			const seq = cursorSeq++;
+			const settlement = chosen.resolved;
+			if (!settlement) throw new ValidationError(`scope.next: child '${chosen.id}' won the settle race without a resolved value`);
+			return finalizeSettlement(chosen, settlement, seq, args, now);
+		}
+	}
+	async function nextResolved() {
+		for (;;) {
+			const candidates = [...children.values()].filter((c) => !c.delivered);
+			const pick = candidates.find((c) => c.resolved !== void 0) ?? candidates.find((c) => c.executorDone);
+			if (!pick) return null;
+			const settlement = await pick.settled;
+			if (pick.delivered) continue;
+			pick.delivered = true;
+			return finalizeSettlement(pick, settlement, cursorSeq++, args, now);
+		}
+	}
+	function send(nodeId, msg) {
+		const child = children.get(nodeId);
+		if (!child || child.delivered || !child.deliver) return false;
+		child.deliver(msg);
+		child.lastActivityAt = now();
+		return true;
+	}
+	/**
+	* Arm a wait-state node. Deliberately NOT a `spawn` with a sleeping executor: it resolves no
+	* `AgentSpec`, constructs no `Executor`, and — the point of the whole mechanic — reserves NOTHING
+	* from the conserved pool, so a week-long wait costs zero tokens and zero dollars and cannot
+	* starve a worker of budget.
+	*
+	* Fail-closed admission, mirroring `spawn`'s typed outcome. The deadline check is the one that
+	* matters: a wait may not silently sleep past the pool's hard wall-clock ceiling, and it may not
+	* extend that ceiling either (that would make a wait override a budget guard).
+	*/
+	function wait(spec, opts) {
+		if (validateWaitSpec(spec) !== null) return {
+			ok: false,
+			reason: "invalid-spec"
+		};
+		if (spec.kind === "poll" && args.probes?.resolve(spec.probe) === void 0) return {
+			ok: false,
+			reason: "unknown-probe"
+		};
+		const adopted = unclaimedWaits.get(opts.label);
+		if (adopted) unclaimedWaits.delete(opts.label);
+		const effectiveSpec = adopted?.spec ?? spec;
+		const armedAt = adopted?.armedAt ?? now();
+		if (!assertWaitWithinDeadline(effectiveSpec, args.pool.readout().deadlineMs)) return {
+			ok: false,
+			reason: "deadline-exceeded"
+		};
+		const id = adopted ? adopted.id : `${args.parentId}:w${waitOrdinal}`;
+		const ordinal = adopted ? adopted.ordinal : waitOrdinal;
+		if (!adopted) waitOrdinal += 1;
+		const waitAbort = new AbortController();
+		const cascadeAbort = () => waitAbort.abort();
+		if (args.signal.aborted) waitAbort.abort();
+		else args.signal.addEventListener("abort", cascadeAbort, { once: true });
+		const handle = {
+			id,
+			label: opts.label,
+			get status() {
+				return children.get(id)?.status ?? "cancelled";
+			},
+			abort(reason) {
+				waitAbort.abort(reason);
+			}
+		};
+		const live = {
+			id,
+			status: "waiting",
+			runtime: "wait",
+			budget: {
+				maxIterations: 0,
+				maxTokens: 0
+			},
+			label: opts.label,
+			spent: zeroSpend(),
+			settled: void 0,
+			delivered: false,
+			executorDone: false,
+			startedAt: armedAt,
+			lastActivityAt: now(),
+			wait: {
+				spec: effectiveSpec,
+				armedAt,
+				label: opts.label
+			}
+		};
+		children.set(id, live);
+		if (!adopted) args.journal.appendEvent(args.root, {
+			kind: "waiting",
+			id,
+			parent: args.parentId,
+			label: opts.label,
+			spec: effectiveSpec,
+			armedAt,
+			seq: ordinal,
+			at: new Date(now()).toISOString()
+		});
+		notifyRuntimeHookEvent(args.hooks, {
+			id: `${id}:waiting`,
+			runId: args.root,
+			target: "agent.spawn",
+			phase: "after",
+			timestamp: now(),
+			stepIndex: ordinal,
+			parentId: args.parentId,
+			payload: {
+				childId: id,
+				label: opts.label,
+				runtime: "wait",
+				wait: effectiveSpec,
+				armedAt,
+				resumed: adopted !== void 0
+			}
+		}, { signal: args.signal });
+		live.settled = runWait({
+			spec: effectiveSpec,
+			label: opts.label,
+			armedAt,
+			resumed: adopted !== void 0,
+			signal: waitAbort.signal,
+			...args.probes ? { probes: args.probes } : {},
+			now,
+			...args.waitSleep ? { sleep: args.waitSleep } : {}
+		}).then(async (resolution) => {
+			live.executorDone = true;
+			live.lastActivityAt = now();
+			if (resolution.kind === "cancelled") return {
+				kind: "down",
+				reason: resolution.reason,
+				infra: false,
+				restartCount: 0
+			};
+			const outRef = contentAddress(resolution.outcome);
+			await args.blobs.put(outRef, resolution.outcome);
+			return {
+				kind: "done",
+				out: resolution.outcome,
+				outRef,
+				spent: zeroSpend()
+			};
+		}).catch((err) => {
+			live.executorDone = true;
+			return {
+				kind: "down",
+				reason: errMessage(err),
+				infra: true,
+				restartCount: 0
+			};
+		}).then((s) => {
+			live.resolved = s;
+			return s;
+		}).finally(() => {
+			args.signal.removeEventListener("abort", cascadeAbort);
+		});
+		return {
+			ok: true,
+			handle
+		};
+	}
+	function progress(nodeId, opts = {}) {
+		const child = children.get(nodeId);
+		if (!child) return void 0;
+		let fromExecutor;
+		try {
+			fromExecutor = child.readProgress?.();
+		} catch {
+			fromExecutor = void 0;
+		}
+		return readWorkerProgress({
+			id: child.id,
+			status: child.status,
+			steerable: child.deliver !== void 0 && !child.delivered,
+			startedAt: child.startedAt,
+			lastActivityAt: child.lastActivityAt,
+			turns: child.spent.iterations,
+			tokens: child.spent.tokens,
+			usd: child.spent.usd
+		}, fromExecutor, opts.now ?? now(), opts.stallAfterMs ?? 18e4);
+	}
+	function traceSource(nodeId) {
+		const child = children.get(nodeId);
+		if (!child) return void 0;
+		try {
+			return child.readTraceSource?.();
+		} catch {
+			return;
+		}
+	}
+	async function meter(spend, detail) {
+		const seq = meterSeq++;
+		args.pool.observe(spend);
+		await args.journal.appendEvent(args.root, {
+			kind: "metered",
+			id: args.parentId,
+			spend,
+			seq,
+			at: new Date(now()).toISOString()
+		});
+		notifyRuntimeHookEvent(args.hooks, {
+			id: `${args.parentId}:meter:${seq}`,
+			runId: args.root,
+			target: "agent.turn",
+			phase: "after",
+			timestamp: now(),
+			parentId: args.parentId,
+			payload: {
+				spend,
+				...detail ?? {}
+			}
+		}, { signal: args.signal });
+	}
+	const resume = args.resumeFrom ? {
+		settled: args.resumeFrom.settled,
+		view: args.resumeFrom.view,
+		waits: args.resumeFrom.waits
+	} : void 0;
+	return {
+		spawn,
+		next,
+		nextResolved,
+		send,
+		wait,
+		progress,
+		traceSource,
+		signal: args.signal,
+		meter,
+		...resume ? { resume } : {},
+		get view() {
+			return makeTreeView(args.parentId, children);
+		},
+		get budget() {
+			return args.pool.readout();
+		}
+	};
+}
+/** Await whichever pending child settles first, returning the child (its `resolved` is set
+*  by the time this resolves because `runChild`'s `.then` sets it before the promise
+*  resolves downstream). */
+async function raceFirstSettled(pending) {
+	return Promise.race(pending.map((c) => c.settled.then(() => c)));
+}
+/** Stamp the cursor `seq`, write the `settled` journal record, and project the
+*  `PreSeqSettled` into the frozen `Settled` the driver branches on. */
+async function finalizeSettlement(child, settlement, seq, args, now) {
+	const handle = frozenHandle(child);
+	if (child.wait) return finalizeWait(child, settlement, seq, args, now, handle);
+	if (settlement.kind === "down") {
+		child.status = "failed";
+		await args.journal.appendEvent(args.root, {
+			kind: "settled",
+			id: child.id,
+			status: "down",
+			spent: child.spent,
+			infra: settlement.infra,
+			seq,
+			at: new Date(now()).toISOString()
+		});
+		if (settlement.metered) await args.journal.appendEvent(args.root, {
+			kind: "metered",
+			id: child.id,
+			spend: settlement.metered,
+			seq,
+			at: new Date(now()).toISOString()
+		});
+		notifyRuntimeHookEvent(args.hooks, {
+			id: `${child.id}:settled`,
+			runId: args.root,
+			target: "agent.child",
+			phase: "after",
+			timestamp: now(),
+			stepIndex: seq,
+			parentId: args.parentId,
+			payload: {
+				childId: child.id,
+				status: "down",
+				reason: settlement.reason,
+				infra: settlement.infra,
+				spent: child.spent
+			}
+		}, { signal: args.signal });
+		return {
+			kind: "down",
+			handle,
+			reason: settlement.reason,
+			infra: settlement.infra,
+			restartCount: settlement.restartCount,
+			seq
+		};
+	}
+	child.status = "done";
+	child.outRef = settlement.outRef;
+	child.spent = settlement.spent;
+	await args.journal.appendEvent(args.root, {
+		kind: "settled",
+		id: child.id,
+		status: "done",
+		outRef: settlement.outRef,
+		...settlement.verdict ? { verdict: settlement.verdict } : {},
+		spent: settlement.spent,
+		seq,
+		at: new Date(now()).toISOString()
+	});
+	if (settlement.metered) await args.journal.appendEvent(args.root, {
+		kind: "metered",
+		id: child.id,
+		spend: settlement.metered,
+		seq,
+		at: new Date(now()).toISOString()
+	});
+	notifyRuntimeHookEvent(args.hooks, {
+		id: `${child.id}:settled`,
+		runId: args.root,
+		target: "agent.child",
+		phase: "after",
+		timestamp: now(),
+		stepIndex: seq,
+		parentId: args.parentId,
+		payload: {
+			childId: child.id,
+			status: "done",
+			outRef: settlement.outRef,
+			score: settlement.verdict?.score,
+			valid: settlement.verdict?.valid,
+			spent: settlement.spent
+		}
+	}, { signal: args.signal });
+	return {
+		kind: "done",
+		handle,
+		out: settlement.out,
+		outRef: settlement.outRef,
+		...settlement.verdict ? { verdict: settlement.verdict } : {},
+		spent: settlement.spent,
+		seq
+	};
+}
+/** Journal a wait-state's settlement as a `woken` event and project it onto the same `Settled`
+*  the driver branches on. `by` names WHY it woke — `fired` / `timeout` / `cancelled` — which is
+*  the fact a resumed reader needs and cannot recover from a payload it may never fetch. */
+async function finalizeWait(child, settlement, seq, args, now, handle) {
+	const at = new Date(now()).toISOString();
+	if (settlement.kind === "down") {
+		child.status = "cancelled";
+		await args.journal.appendEvent(args.root, {
+			kind: "woken",
+			id: child.id,
+			by: "cancelled",
+			seq,
+			at
+		});
+		return {
+			kind: "down",
+			handle,
+			reason: settlement.reason,
+			infra: settlement.infra,
+			restartCount: settlement.restartCount,
+			seq
+		};
+	}
+	child.status = "done";
+	child.outRef = settlement.outRef;
+	const out = settlement.out;
+	await args.journal.appendEvent(args.root, {
+		kind: "woken",
+		id: child.id,
+		by: out.settled,
+		outRef: settlement.outRef,
+		seq,
+		at
+	});
+	notifyRuntimeHookEvent(args.hooks, {
+		id: `${child.id}:woken`,
+		runId: args.root,
+		target: "agent.child",
+		phase: "after",
+		timestamp: now(),
+		stepIndex: seq,
+		parentId: args.parentId,
+		payload: {
+			childId: child.id,
+			status: "done",
+			wait: out
+		}
+	}, { signal: args.signal });
+	return {
+		kind: "done",
+		handle,
+		out: settlement.out,
+		outRef: settlement.outRef,
+		spent: settlement.spent,
+		seq
+	};
+}
+/**
+* Drive one child's `Executor` to a terminal `PreSeqSettled`, folding usage into the
+* conserved `Spend`, reconciling the reservation, and persisting the result blob. Both
+* executor shapes are handled here: a one-shot `Promise<ExecutorResult>` and a streaming
+* `AsyncIterable<UsageEvent>` whose terminal artifact is read from `resultArtifact()`.
+*
+* A thrown executor (or a real abort) becomes a TYPED `down` — never re-thrown — so a
+* single failing child cannot reject the `next()` cursor (the M2 typed-result discipline,
+* applied per child). The reservation is reconciled on EVERY path (success, abort, throw)
+* so the conserved pool can never leak a reservation.
+*/
+async function runChild(live, executor, childAbort, task, opts, pool, ticket, blobs, now) {
+	let reconciled = false;
+	const reconcileOnce = (spend) => {
+		if (reconciled) return;
+		reconciled = true;
+		pool.reconcile(ticket, clampSpend(spend, opts.budget));
+	};
+	try {
+		live.status = "running";
+		const ran = executor.execute(task, childAbort.signal);
+		let artifact;
+		if (isAsyncIterable(ran)) {
+			const spend = await foldStream(ran, (running) => {
+				live.spent = running;
+				live.lastActivityAt = now();
+			});
+			live.spent = spend;
+			artifact = executor.resultArtifact();
+			reconcileOnce(spend);
+		} else {
+			const terminal = await ran;
+			live.spent = terminal.spent;
+			artifact = terminal;
+			reconcileOnce(terminal.spent);
+		}
+		live.executorDone = true;
+		const ownMetered = executor.metered?.();
+		if (childAbort.signal.aborted) {
+			await teardownSafe(executor, opts.shutdown ?? "brutalKill");
+			return downRecord("aborted before settle", true, ownMetered);
+		}
+		const outRef = contentAddress(artifact.out);
+		await blobs.put(outRef, artifact.out);
+		await teardownSafe(executor, opts.shutdown ?? "infinity");
+		return {
+			kind: "done",
+			out: artifact.out,
+			outRef,
+			...artifact.verdict ? { verdict: artifact.verdict } : {},
+			spent: live.spent,
+			...ownMetered ? { metered: ownMetered } : {}
+		};
+	} catch (err) {
+		live.executorDone = true;
+		reconcileOnce(live.spent);
+		await teardownSafe(executor, "brutalKill");
+		const aborted = childAbort.signal.aborted || isAbortError(err);
+		return downRecord(errMessage(err), aborted || isInfraError(err), executor.metered?.());
+	}
+}
+/**
+* The step-8 merge-boundary adapter (M4): rehydrate a `Settled.done` into the kernel's
+* `Iteration` shape so `defaultSelectWinner` stays single-sourced — the supervisor selects
+* across settled children with the SAME argmax the loop kernel uses, not a forked copy.
+*
+* `index` is the cursor `seq` (the recorded, replay-stable order); `output`/`verdict`/
+* `tokenUsage`/`costUsd` are read straight off the settlement (already rehydrated from the
+* `outRef` blob by `next()`). Events are empty — a settled child is an opaque leaf result,
+* not a sandbox event stream — and the timing/cost fields project its conserved `Spend`.
+* Fail loud on a `down` settlement: only a `done` child is an iteration.
+*/
+function settledToIteration(settled) {
+	if (settled.kind === "down") throw new ValidationError(`settledToIteration: cannot adapt a 'down' settlement (node '${settled.handle.id}', seq ${settled.seq}) to an Iteration`);
+	return {
+		index: settled.seq,
+		task: void 0,
+		agentRunName: settled.handle.label,
+		output: settled.out,
+		...settled.verdict ? { verdict: settled.verdict } : {},
+		events: [],
+		startedAt: 0,
+		endedAt: settled.spent.ms,
+		costUsd: settled.spent.usd,
+		tokenUsage: {
+			input: settled.spent.tokens.input,
+			output: settled.spent.tokens.output
+		}
+	};
+}
+function makeTreeView(root, children) {
+	const nodes = [...children.values()].map((c) => ({
+		id: c.id,
+		parent: root,
+		label: c.label,
+		status: c.status,
+		runtime: c.runtime,
+		budget: c.budget,
+		spent: c.spent,
+		...c.outRef ? { outRef: c.outRef } : {}
+	}));
+	return {
+		root,
+		nodes,
+		inFlight: nodes.filter((n) => n.status === "running" || n.status === "acquiring").length,
+		waiting: nodes.filter((n) => n.status === "waiting").length
+	};
+}
+function frozenHandle(child) {
+	return {
+		id: child.id,
+		label: child.label,
+		status: child.status,
+		abort() {}
+	};
+}
+/**
+* Fold a streaming executor's normalized usage into the conserved `Spend`, publishing the
+* running total after EVERY event via `onProgress`.
+*
+* The publish is what makes a running worker observable. Before it, `live.spent` was assigned
+* once — after the whole stream drained — so `observe_agent` on a RUNNING worker reported
+* `{tokens:0, iterations:0}` for the entire run and a driver had no way to tell a worker three
+* turns deep from one that had produced nothing. It also means a worker that THROWS mid-stream
+* now reconciles its real partial spend instead of refunding work the provider already billed.
+*/
+async function foldStream(stream, onProgress) {
+	const tokens = {
+		input: 0,
+		output: 0
+	};
+	let usd = 0;
+	let iterations = 0;
+	for await (const ev of stream) {
+		if (ev.kind === "tokens") {
+			tokens.input += ev.input;
+			tokens.output += ev.output;
+		} else if (ev.kind === "cost") usd += ev.usd;
+		else iterations += 1;
+		onProgress?.({
+			iterations,
+			tokens: { ...tokens },
+			usd,
+			ms: 0
+		});
+	}
+	return {
+		iterations,
+		tokens,
+		usd,
+		ms: 0
+	};
+}
+/** Clamp a child's reported spend to its reservation so the pool's fail-loud over-spend
+*  guard never trips on a benign overshoot from an external usage report; the difference
+*  refunds to the pool as if the child stopped at its ceiling. */
+function clampSpend(spend, budget) {
+	const totalTokens = spend.tokens.input + spend.tokens.output;
+	const tokensOk = totalTokens <= budget.maxTokens;
+	const itersOk = spend.iterations <= budget.maxIterations;
+	const usdOk = budget.maxUsd === void 0 || spend.usd <= budget.maxUsd;
+	if (tokensOk && itersOk && usdOk) return spend;
+	const ratio = !tokensOk && totalTokens > 0 ? budget.maxTokens / totalTokens : 1;
+	return {
+		iterations: Math.min(spend.iterations, budget.maxIterations),
+		tokens: ratio < 1 ? {
+			input: Math.floor(spend.tokens.input * ratio),
+			output: Math.floor(spend.tokens.output * ratio)
+		} : spend.tokens,
+		usd: budget.maxUsd === void 0 ? spend.usd : Math.min(spend.usd, budget.maxUsd),
+		...spend.usdKnown === false ? { usdKnown: false } : {},
+		ms: spend.ms
+	};
+}
+async function teardownSafe(executor, grace) {
+	try {
+		await executor.teardown(grace);
+	} catch {}
+}
+function downRecord(reason, infra, metered) {
+	return {
+		kind: "down",
+		reason,
+		infra,
+		restartCount: 0,
+		...metered ? { metered } : {}
+	};
+}
+function zeroSpend() {
+	return {
+		iterations: 0,
+		tokens: {
+			input: 0,
+			output: 0
+		},
+		usd: 0,
+		ms: 0
+	};
+}
+function isAsyncIterable(value) {
+	return typeof value === "object" && value !== null && typeof value[Symbol.asyncIterator] === "function";
+}
+/** An `AgentSpec` is identified structurally — it carries a `profile` and a `harness`
+*  field (`null` or a `BackendType`) and optionally an `executor`. */
+function isAgentSpec(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const v = value;
+	return "profile" in v && "harness" in v;
+}
+function isAbortError(err) {
+	return typeof err === "object" && err !== null && "name" in err && err.name === "AbortError";
+}
+/** External-boundary failures (network/FS/subprocess) are infra — excluded from the merge
+*  `n` and the equal-k assertion. A `ValidationError` from a built-in executor wraps a
+*  config/transport failure, so it counts as infra; other throws are a real bad result. */
+function isInfraError(err) {
+	return err instanceof ValidationError;
+}
+function errMessage(err) {
+	if (err instanceof Error) return err.message;
+	return String(err);
+}
+//#endregion
+//#region src/runtime/supervise/driver-executor.ts
+/**
+*
+* The recursive driver-executor — the seam that lets a SPAWNED child be a DRIVER, so
+* agents drive agents drive agents over the one keystone atom.
+*
+* A spawned child resolves through the open registry to an `Executor`; the built-in
+* executors (router/inline, sandbox, cli) are LEAVES — `execute(task, signal)` runs the
+* work and settles. This executor is the recursive case: on `execute`, it mounts a NESTED
+* `Scope` (the scope hands it the mount via the `nested-scope` seam) over the SAME
+* conserved pool + shared journal/blobs + the same open registry, one `depth` deeper, then
+* runs the wrapped driver `Agent.act(task, nestedScope)`. The driver spawns its own
+* children into that nested scope; each resolves to EITHER a leaf executor (a worker child)
+* OR this same driver-executor (a driver child) — recursively. So a driver spawns a driver
+* spawns a worker, all on one budget-conserving tree.
+*
+* Why this preserves every keystone invariant (the scope owns the sharing; this executor
+* only runs the driver over what the scope mounts):
+*  - Conserved budget: the nested scope reserves from the SAME `BudgetPool` the root owns
+*    (the scope mounts it over `args.pool`), so `Σk` is conserved ACROSS depth by
+*    construction — a deep tree cannot overspend the root ceiling (reserve-on-spawn fails
+*    closed at any depth).
+*  - Journal: the nested scope writes to its OWN tree key (`${journalRoot}/${nodeId}`) so
+*    its cursor `seq`s never collide with the parent's in the per-tree uniqueness guard,
+*    while every nested tree shares the one `SpawnJournal` — the whole recursion is one
+*    journal, queryable tree by tree.
+*  - Settlement bubbling: the driver child settles into its PARENT scope with the conserved
+*    spend summed off its nested tree's settled events, so the parent's pool reconcile +
+*    the supervisor's `spentTotal` see the whole sub-tree's spend rolled up — settlements
+*    bubble to the root.
+*  - Depth ceiling: the nested scope runs at `depth+1`, so the supervisor's `maxDepth`
+*    (paired with the conserved pool per R3) fails a spawn closed once the recursion is too
+*    deep — exactly as it does for a flat tree.
+*
+* Layering: pure keystone composition. It reuses the scope's `NestedScopeSeam` + the shared
+* `SpawnJournal`; it builds NO new budget, journal, or selection logic. The recursion rides
+* the existing atom.
+*
+* @experimental
+*/
+/** The runtime tag the registry maps a driver child to. */
+const driverRuntime = "driver";
+/** The metadata marker on a driver child's spec the recursive registry routes on. */
+const driverRole = "driver";
+/** True when a spec is a driver child (carries the role marker + a driver Agent). */
+function isDriverSpec(spec) {
+	if (spec.profile.metadata?.role !== driverRole) return false;
+	const driver = spec.driver;
+	if (!isAgent(driver)) throw new ValidationError("driverExecutor: a driver-role spec must carry a `driver` Agent to run inside its nested scope");
+	return true;
+}
+/**
+* The recursive driver-executor factory. `withDriverExecutor` routes a child marked
+* `role: 'driver'` here; any other child resolves to a leaf built-in. On `execute`, it
+* reads the `nested-scope` seam the SCOPE seeded, mounts a nested `Scope` one `depth`
+* deeper over the shared pool/journal/blobs/registry, runs the driver
+* `Agent.act(task, nestedScope)`, and reports the conserved spend summed off the nested
+* tree's settled events — so the parent scope's reconcile rolls the whole sub-tree's spend
+* into the conserved total.
+*
+* A `down` from the nested driver (a thrown `act` or an aborted scope) propagates as a
+* thrown executor, which the parent scope types into a `down` settlement — the same
+* fail-loud-into-typed-down discipline a leaf gets.
+*/
+const driverExecutorFactory = (spec, ctx) => {
+	if (!isDriverSpec(spec)) throw new ValidationError("driverExecutorFactory: spec is not a driver child (no role:\"driver\" marker)");
+	const driver = spec.driver;
+	const journal = spec.journal;
+	const seam = readNestedScopeSeam(ctx);
+	let artifact;
+	let meteredSpend;
+	return {
+		runtime: driverRuntime,
+		async execute(task, signal) {
+			const nestedRoot = nestedTreeKey(seam, journal);
+			await journal.beginTree(nestedRoot, (/* @__PURE__ */ new Date(0)).toISOString());
+			const nestedScope = seam.mount(nestedRoot, signal);
+			try {
+				const out = await driver.act(task, nestedScope);
+				const events = await loadTreeEvents(journal, nestedRoot);
+				const settled = events.filter(isSettled);
+				meteredSpend = nonZeroOrUndef(sumMetered(events));
+				const verdict = deriveDeliveryVerdict(settled);
+				artifact = {
+					outRef: `${driverRuntime}:${nestedRoot}`,
+					out,
+					spent: sumSpend(settled),
+					...verdict ? { verdict } : {}
+				};
+				return artifact;
+			} catch (err) {
+				meteredSpend = await safeSumMetered(journal, nestedRoot);
+				throw err;
+			}
+		},
+		metered() {
+			return meteredSpend;
+		},
+		teardown() {
+			return Promise.resolve({ destroyed: true });
+		},
+		resultArtifact() {
+			if (!artifact) throw new ValidationError("driverExecutor: resultArtifact() read before execute()");
+			return artifact;
+		}
+	};
+};
+/**
+* Register the driver-executor so a child marked `role: 'driver'` resolves to it. The base
+* registry resolves by harness alone (it does not read `role`), so a recursive run needs a
+* registry that routes the driver tag here FIRST. Returns a registry decorator: a
+* driver-role spec → the driver-executor; everything else → the base registry's resolution
+* (leaf built-ins + BYO).
+*/
+function withDriverExecutor(base) {
+	return {
+		register: base.register.bind(base),
+		resolve(spec) {
+			if (spec.profile.metadata?.role === driverRole && !spec.executor) return {
+				succeeded: true,
+				value: driverExecutorFactory
+			};
+			return base.resolve(spec);
+		}
+	};
+}
+/** Mint a unique nested-tree key under the parent's journal root. Uses the parent's
+*  `journalRoot` + a per-journal monotonic ordinal so two sibling driver trees never
+*  collide their keys (each driver child mints exactly one nested tree). */
+function nestedTreeKey(seam, journal) {
+	return `${seam.journalRoot}/d${nextNestOrdinal(journal)}`;
+}
+/** Per-journal monotonic nest counter — keyed on the journal instance so a single run's
+*  nested-tree keys are unique without a shared module global. */
+const nestCounters = /* @__PURE__ */ new WeakMap();
+function nextNestOrdinal(journal) {
+	let c = nestCounters.get(journal);
+	if (!c) {
+		c = { n: 0 };
+		nestCounters.set(journal, c);
+	}
+	return c.n++;
+}
+/** The nested tree's full event list — the one evidence the spend, verdict, AND driver-inference
+*  roll-ups read off the same journal the supervisor sums. */
+async function loadTreeEvents(journal, nestedRoot) {
+	const events = await journal.loadTree(nestedRoot);
+	if (events === void 0) throw new ValidationError(`driverExecutor: nested tree '${nestedRoot}' missing from the journal after run (corrupted log)`);
+	return events;
+}
+function isSettled(ev) {
+	return ev.kind === "settled";
+}
+/** Sum the conserved spend over the nested tree's settled events — the honest per-channel
+*  roll-up of the whole sub-tree's child WORK. */
+function sumSpend(settled) {
+	const total = {
+		iterations: 0,
+		tokens: {
+			input: 0,
+			output: 0
+		},
+		usd: 0,
+		ms: 0
+	};
+	for (const ev of settled) {
+		total.iterations += ev.spent.iterations;
+		total.tokens.input += ev.spent.tokens.input;
+		total.tokens.output += ev.spent.tokens.output;
+		total.usd += ev.spent.usd;
+		if (ev.spent.usdKnown === false) total.usdKnown = false;
+		total.ms += ev.spent.ms;
+	}
+	return total;
+}
+/** Sum the nested tree's `metered` events — the sub-tree's whole driver INFERENCE (this driver's
+*  own turns + any sub-driver inference already re-homed into this tree). Re-homed up to the parent
+*  as one `metered` event; never reconciled (already pool-debited live via `observe`). */
+function sumMetered(events) {
+	const total = {
+		iterations: 0,
+		tokens: {
+			input: 0,
+			output: 0
+		},
+		usd: 0,
+		ms: 0
+	};
+	for (const ev of events) {
+		if (ev.kind !== "metered") continue;
+		total.iterations += ev.spend.iterations;
+		total.tokens.input += ev.spend.tokens.input;
+		total.tokens.output += ev.spend.tokens.output;
+		total.usd += ev.spend.usd;
+		if (ev.spend.usdKnown === false) total.usdKnown = false;
+		total.ms += ev.spend.ms;
+	}
+	return total;
+}
+function isNonZeroSpend(s) {
+	return s.iterations > 0 || s.tokens.input > 0 || s.tokens.output > 0 || s.usd > 0 || s.ms > 0;
+}
+/** A spend, or `undefined` when it is all-zero — so `metered()` returns undefined for a driver
+*  whose sub-tree did no inference (and the parent journals no empty `metered` event). */
+function nonZeroOrUndef(s) {
+	return isNonZeroSpend(s) ? s : void 0;
+}
+/** Sum the nested tree's metered events, tolerating a missing tree (a crash before `beginTree`
+*  landed) — never throw here, or it would mask the original `act` error on the crash path. */
+async function safeSumMetered(journal, nestedRoot) {
+	try {
+		return nonZeroOrUndef(sumMetered(await loadTreeEvents(journal, nestedRoot)));
+	} catch {
+		return;
+	}
+}
+/** Derive the driver child's delivery verdict from its DIRECT children's settlements:
+*  `valid` iff any direct child settled `done` AND `valid` (the keep-best finalize's pick);
+*  `score` = the best delivered score. Returns `undefined` when no child settled at all (the
+*  driver itself produced nothing to bubble a verdict from). Fail-closed: a child whose verdict
+*  carried no `valid` counts as not-delivered. */
+function deriveDeliveryVerdict(settled) {
+	let sawChild = false;
+	let anyValid = false;
+	let bestValidScore;
+	let bestDoneScore;
+	for (const ev of settled) {
+		sawChild = true;
+		if (ev.status !== "done") continue;
+		const score = ev.verdict?.score;
+		if (score !== void 0 && (bestDoneScore === void 0 || score > bestDoneScore)) bestDoneScore = score;
+		if (ev.verdict?.valid === true) {
+			anyValid = true;
+			if (score !== void 0 && (bestValidScore === void 0 || score > bestValidScore)) bestValidScore = score;
+		}
+	}
+	if (!sawChild) return void 0;
+	return {
+		valid: anyValid,
+		score: anyValid ? bestValidScore ?? 1 : bestDoneScore ?? 0
+	};
+}
+function readNestedScopeSeam(ctx) {
+	const seam = ctx.seams[nestedScopeSeamKey];
+	if (!seam || typeof seam.mount !== "function") throw new ValidationError(`driverExecutor: missing required seam "${nestedScopeSeamKey}" — a driver child must be spawned through a Scope that seeds it (the keystone scope does)`);
+	return seam;
+}
+function isAgent(value) {
+	return typeof value === "object" && value !== null && typeof value.act === "function" && typeof value.name === "string";
+}
+//#endregion
+//#region src/runtime/supervise/budget.ts
+/**
+*
+* The conserved budget reservation pool — the invariant the whole instrument
+* rests on (critique M5/B3). One root `Budget` becomes a conserved pool of three
+* quantities (tokens, usd, iterations) plus an absolute deadline. Children reserve
+* atomically at spawn and reconcile at settle:
+*
+*   total ≡ free + reserved + committed          (invariant, always)
+*
+* `reserve` moves a child's whole ceiling from `free` → `reserved` and fails closed
+* when `free` can't cover it (never read-then-spawn overcommit, so `Σk(treatment) ≡
+* Σk(blind)` by construction). `reconcile` releases the reservation, commits ACTUAL
+* spend, and refunds the unspent remainder to `free`. Tokens and usd are separate
+* channels (`LoopTokenUsage` has no `usd`); iterations are conserved alongside them.
+*
+* Pure and deterministic: `now()` is injected, there is no I/O, and no wall-clock or
+* RNG read. A `reserve`/`reconcile` ticket is single-use (fail-loud on double or
+* unknown reconcile) so a child can never refund twice.
+*
+* @experimental
+*/
+/** Fold a normalized `UsageEvent` array into a `Spend`. Tokens and usd are separate
+*  channels; iterations come from `'iteration'` events. Pure; `ms` stays zero (the
+*  pool does not read wall-clock). */
+function spendFromUsageEvents(events) {
+	const tokens = zeroTokenUsage();
+	let usd = 0;
+	let iterations = 0;
+	for (const ev of events) if (ev.kind === "tokens") addTokenUsage(tokens, {
+		input: ev.input,
+		output: ev.output
+	});
+	else if (ev.kind === "cost") usd += ev.usd;
+	else iterations += 1;
+	return {
+		iterations,
+		tokens,
+		usd,
+		ms: 0
+	};
+}
+async function foldUsage(events) {
+	if (Array.isArray(events)) return spendFromUsageEvents(events);
+	const tokens = zeroTokenUsage();
+	let usd = 0;
+	let iterations = 0;
+	for await (const ev of events) if (ev.kind === "tokens") addTokenUsage(tokens, {
+		input: ev.input,
+		output: ev.output
+	});
+	else if (ev.kind === "cost") usd += ev.usd;
+	else iterations += 1;
+	return {
+		iterations,
+		tokens,
+		usd,
+		ms: 0
+	};
+}
+function totalTokens(usage) {
+	return usage.input + usage.output;
+}
+/**
+* Create a conserved reservation pool from a root `Budget`. `now()` is injected so the
+* deadline readout is deterministic; defaults to `Date.now` for non-test callers. The
+* absolute deadline is fixed at construction (`now() + budget.deadlineMs`) so the
+* readout's `deadlineMs` is a stable wall-clock instant, not a shrinking remainder.
+*/
+function createBudgetPool(root, now = Date.now) {
+	let freeTokens = root.maxTokens;
+	let reservedTokens = 0;
+	let committedTokens = 0;
+	const usdCapped = root.maxUsd !== void 0;
+	let freeUsd = root.maxUsd ?? 0;
+	let reservedUsd = 0;
+	let committedUsd = 0;
+	let freeIterations = root.maxIterations;
+	let reservedIterations = 0;
+	let committedIterations = 0;
+	const absoluteDeadlineMs = root.deadlineMs !== void 0 ? now() + root.deadlineMs : 0;
+	let nextTicketId = 0;
+	const open = /* @__PURE__ */ new Set();
+	function reserve(b) {
+		const wantTokens = b.maxTokens;
+		const wantUsd = b.maxUsd ?? 0;
+		const wantIterations = b.maxIterations;
+		if (wantTokens > freeTokens) return {
+			ok: false,
+			reason: "budget-exhausted"
+		};
+		if (wantIterations > freeIterations) return {
+			ok: false,
+			reason: "budget-exhausted"
+		};
+		if (wantUsd > 0 && (!usdCapped || wantUsd > freeUsd)) return {
+			ok: false,
+			reason: "budget-exhausted"
+		};
+		freeTokens -= wantTokens;
+		reservedTokens += wantTokens;
+		freeIterations -= wantIterations;
+		reservedIterations += wantIterations;
+		if (wantUsd > 0) {
+			freeUsd -= wantUsd;
+			reservedUsd += wantUsd;
+		}
+		const id = nextTicketId++;
+		open.add(id);
+		return {
+			ok: true,
+			ticket: {
+				id,
+				reserved: {
+					tokens: wantTokens,
+					usd: wantUsd,
+					iterations: wantIterations
+				}
+			}
+		};
+	}
+	function reconcile(ticket, spent) {
+		if (!open.has(ticket.id)) throw new Error(`budget pool: reconcile of unknown or already-settled ticket ${ticket.id}`);
+		open.delete(ticket.id);
+		const { tokens: rTokens, usd: rUsd, iterations: rIterations } = ticket.reserved;
+		if (usdCapped && spent.usdKnown === false) throw new Error(`budget pool: ticket ${ticket.id} reported unknown dollar cost under a dollar-capped budget`);
+		const spentTokens = totalTokens(spent.tokens);
+		if (spentTokens > rTokens) throw new Error(`budget pool: ticket ${ticket.id} spent ${spentTokens} tokens > reserved ${rTokens}`);
+		if (spent.iterations > rIterations) throw new Error(`budget pool: ticket ${ticket.id} spent ${spent.iterations} iterations > reserved ${rIterations}`);
+		if (usdCapped && spent.usd > rUsd) throw new Error(`budget pool: ticket ${ticket.id} spent $${spent.usd} > reserved $${rUsd}`);
+		reservedTokens -= rTokens;
+		committedTokens += spentTokens;
+		freeTokens += rTokens - spentTokens;
+		reservedIterations -= rIterations;
+		committedIterations += spent.iterations;
+		freeIterations += rIterations - spent.iterations;
+		if (usdCapped && rUsd > 0) {
+			reservedUsd -= rUsd;
+			committedUsd += spent.usd;
+			freeUsd += rUsd - spent.usd;
+		} else committedUsd += spent.usd;
+	}
+	function observe(spend) {
+		if (usdCapped && spend.usdKnown === false) throw new Error("budget pool: cannot observe unknown dollar cost under a dollar-capped budget");
+		const tokens = totalTokens(spend.tokens);
+		freeTokens -= tokens;
+		committedTokens += tokens;
+		freeIterations -= spend.iterations;
+		committedIterations += spend.iterations;
+		committedUsd += spend.usd;
+		if (usdCapped) freeUsd -= spend.usd;
+	}
+	function readout() {
+		return {
+			tokensLeft: freeTokens,
+			usdLeft: usdCapped ? freeUsd : 0,
+			usdCapped,
+			deadlineMs: absoluteDeadlineMs,
+			reservedTokens
+		};
+	}
+	function assertNoOpenTickets() {
+		if (open.size > 0) throw new Error(`budget pool: ${open.size} reservation(s) still open at join barrier (leaked ticket ids: ${[...open].join(", ")}) — conserved-pool invariant violated`);
+	}
+	return {
+		reserve,
+		reconcile,
+		spendFrom: foldUsage,
+		readout,
+		observe,
+		assertNoOpenTickets
+	};
+}
+//#endregion
+//#region src/runtime/supervise/supervisor.ts
+/**
+*
+* The `Supervisor` impl (KEYSTONE, build step 5).
+*
+* Owns the four things a free-running recursive `act` cannot own itself: the GLOBAL
+* conserved budget pool, the event-sourced spawn log, the abort cascade over the whole
+* live tree, and the OTP intensity breaker. `run` builds the root `Scope` over those,
+* runs the root `Agent.act`, and returns a TYPED `SupervisedResult` — a no-winner is
+* never coerced into a best-effort `Out`.
+*
+* Three lifecycle invariants this impl enforces by construction:
+*  - Join barrier: when `act()` settles (resolve OR reject), every still-live child is
+*    torn down before `run` returns — the generalization of the kernel's
+*    `finally{ Promise.allSettled(destroy) }` barrier (run-loop.ts) from boxes to the
+*    whole sub-tree. A teardown failure is `allSettled`'d and journaled as a
+*    `cancelled` event; it NEVER masks act()'s own outcome. act()'s rejection is the
+*    PRIMARY error (the kernel's firstError precedence), so a teardown throw during the
+*    barrier can never overwrite the real failure.
+*  - Abort cascade: a root abort (caller signal, `RootHandle.abort`, a tripped breaker,
+*    or pool exhaustion) aborts ONE internal controller whose signal is the root scope's
+*    signal. The scope cascades that into every live child's executor abort — which, for
+*    an `acquiring` child, chains into the `acquireSandbox` signal and reaps the
+*    find-by-name orphan box (M1). The supervisor never reaps children directly.
+*  - The supervisor NEVER re-enters a child (m3): the kernel/`acquireSandbox` already
+*    retried at the leaf, and a driver re-spawns through `scope.spawn`. The breaker only
+*    COUNTS `down` settlements within the intensity window and trips to a typed
+*    no-winner; it does not restart anything.
+*
+* Selection lives in the driver, not here (selector≠judge): `act` returns the synthesized
+* winner `Out`. The supervisor content-addresses that `Out` for its replay `outRef`, reads
+* `spentTotal` off the journal (`settled` child work + `metered` driver inference), and wraps
+* it as a typed `winner` — it does not re-rank children behind the driver's back.
+*
+* @experimental
+*/
+/** Highest `seq` among events matching `pred`, or `-1` when none match (so a resumed scope's
+*  first new ordinal/seq is 0 — the same start a fresh scope uses). */
+function maxSeqOf(events, pred) {
+	let max = -1;
+	for (const ev of events) if (pred(ev) && ev.seq > max) max = ev.seq;
+	return max;
+}
+/** The default runtime recursion-depth ceiling, paired with the conserved pool so a
+*  runaway recursion hits budget-exhaustion first and depth-exceeded second (R3). */
+const defaultMaxDepth = 4;
+/** Create a supervisor that owns one recursive agent execution tree. */
+function createSupervisor() {
+	let attached;
+	async function run(root, task, opts) {
+		const now = opts.now ?? Date.now;
+		const pool = createBudgetPool(opts.budget, now);
+		const prior = opts.resume === true ? await opts.journal.loadTree(opts.runId) : void 0;
+		const resuming = prior !== void 0 && prior.length > 0;
+		let resumeFrom;
+		if (resuming) resumeFrom = {
+			settled: await replaySpawnTree(opts.journal, opts.blobs, opts.runId),
+			view: materializeTreeView(prior),
+			maxSpawnOrdinal: maxSeqOf(prior, (ev) => ev.kind === "spawned"),
+			maxCursorSeq: maxSeqOf(prior, (ev) => ev.kind === "settled" || ev.kind === "cancelled" || ev.kind === "woken"),
+			maxWaitOrdinal: maxSeqOf(prior, (ev) => ev.kind === "waiting"),
+			waits: pendingWaits(prior)
+		};
+		else {
+			await opts.journal.beginTree(opts.runId, new Date(now()).toISOString());
+			await opts.journal.appendEvent(opts.runId, {
+				kind: "spawned",
+				id: opts.runId,
+				label: "root",
+				budget: opts.budget,
+				runtime: "inline",
+				seq: 0,
+				at: new Date(now()).toISOString()
+			});
+		}
+		const controller = new AbortController();
+		const cascadeAbort = (reason) => {
+			if (controller.signal.aborted) return;
+			controller.abort(reason);
+		};
+		const onCallerAbort = () => cascadeAbort("caller signal aborted");
+		if (opts.signal) if (opts.signal.aborted) cascadeAbort("caller signal aborted");
+		else opts.signal.addEventListener("abort", onCallerAbort, { once: true });
+		const breaker = createIntensityBreaker(opts, () => cascadeAbort("intensity breaker tripped"));
+		const journal = wrapJournalForBreaker(opts.journal, breaker);
+		const scope = createScope({
+			parentId: opts.runId,
+			root: opts.runId,
+			pool,
+			journal,
+			blobs: opts.blobs,
+			executors: opts.executors,
+			seams: {},
+			depth: 0,
+			maxDepth: opts.maxDepth ?? defaultMaxDepth,
+			signal: controller.signal,
+			now,
+			hooks: opts.hooks,
+			...opts.probes ? { probes: opts.probes } : {},
+			...resumeFrom ? { resumeFrom } : {}
+		});
+		const openScope = scope;
+		if (attached) attached.bind({
+			scope: openScope,
+			cascadeAbort,
+			signal: pushRootSignal(cascadeAbort)
+		});
+		let actOutcome;
+		try {
+			actOutcome = {
+				ok: true,
+				out: await root.act(task, scope)
+			};
+		} catch (error) {
+			actOutcome = {
+				ok: false,
+				error
+			};
+		} finally {
+			await drainLiveChildren(openScope, controller);
+			if (opts.signal) opts.signal.removeEventListener("abort", onCallerAbort);
+			if (attached) attached.unbind();
+		}
+		const tree = scope.view;
+		if (actOutcome.ok) {
+			pool.assertNoOpenTickets();
+			const out = actOutcome.out;
+			if (out !== void 0) {
+				const outRef = contentAddress(out);
+				await opts.blobs.put(outRef, out);
+				const { childWork, driverInference } = await spentFromJournal(journal, opts.runId);
+				return {
+					kind: "winner",
+					out,
+					outRef,
+					tree,
+					spentTotal: addSpend(childWork, driverInference),
+					...isNonEmptySpend(driverInference) ? { spentBreakdown: {
+						driverInference,
+						childWork
+					} } : {}
+				};
+			}
+			return noWinner();
+		}
+		return noWinner();
+		async function noWinner() {
+			const { childWork, driverInference } = await spentFromJournal(journal, opts.runId);
+			return {
+				kind: "no-winner",
+				reason: classifyNoWinner(controller, pool, opts, breaker),
+				tree,
+				downCount: breaker.downCount(),
+				spentTotal: addSpend(childWork, driverInference)
+			};
+		}
+	}
+	function attach(h) {
+		const control = rootControls.get(h);
+		if (!control) throw new RuntimeRunStateError("supervisor.attach: handle was not minted by createRootHandle (no control channel)");
+		attached = control;
+	}
+	return {
+		run,
+		attach
+	};
+}
+/** Module-private channel from a minted `RootHandle` to its `RootControl`, so `attach`
+*  can prove a handle is ours and reach its binding without leaking the control onto the
+*  frozen `RootHandle` shape. */
+const rootControls = /* @__PURE__ */ new WeakMap();
+/** A `RootSignal` sink: `cancel` cascades an abort; pause/resume/ask are observability
+*  signals the substrate accepts but does not act on here (the chat/pi-viz client owns
+*  pause semantics — building them now would be mechanism ahead of the gate). */
+function pushRootSignal(cascadeAbort) {
+	return (msg) => {
+		if (msg.kind === "cancel") cascadeAbort(msg.reason ?? "root signal: cancel");
+	};
+}
+function createIntensityBreaker(opts, trip) {
+	const max = opts.maxRestarts;
+	const within = opts.withinMs;
+	const armed = max !== void 0 && within !== void 0;
+	const recent = [];
+	let total = 0;
+	let isTripped = false;
+	return {
+		recordDown(at) {
+			total += 1;
+			if (!armed || isTripped) return;
+			recent.push(at);
+			const cutoff = at - within;
+			while (recent.length > 0 && recent[0] < cutoff) recent.shift();
+			if (recent.length > max) {
+				isTripped = true;
+				trip();
+			}
+		},
+		tripped() {
+			return isTripped;
+		},
+		downCount() {
+			return total;
+		}
+	};
+}
+/** Decorate the journal so the breaker observes every `settled`-`down` event the scope
+*  appends, without the supervisor intercepting `scope.next()`. The decorator is
+*  transparent — it forwards every method verbatim and only reads the down events. */
+function wrapJournalForBreaker(journal, breaker) {
+	return {
+		loadTree: (root) => journal.loadTree(root),
+		beginTree: (root, at) => journal.beginTree(root, at),
+		appendEvent: (root, ev) => {
+			if (ev.kind === "settled" && ev.status === "down") breaker.recordDown(Date.parse(ev.at));
+			return journal.appendEvent(root, ev);
+		}
+	};
+}
+/**
+* Drain the root scope's live set so every still-running/acquiring child is torn down
+* before `run` returns — the join barrier. Abort the cascade controller first (so each
+* child's executor stops cleanly), then pull `next()` to completion so every aborted
+* child's teardown + reconcile runs and its `settled` event is journaled by the scope.
+* A child's own teardown failure is already swallowed inside `runChild`, and the cursor
+* itself never rejects (a failing child is typed into a `down`), so the whole barrier is
+* `allSettled`'d — a stray throw here is NOT the primary error (firstError precedence).
+*/
+async function drainLiveChildren(scope, controller) {
+	const view = scope.view;
+	if (!(view.inFlight > 0 || view.waiting > 0)) return;
+	if (!controller.signal.aborted) controller.abort();
+	await Promise.allSettled([drainCursor(scope)]);
+}
+async function drainCursor(scope) {
+	for (;;) if (await scope.next() === null) return;
+}
+function classifyNoWinner(controller, pool, opts, breaker) {
+	if (breaker.tripped()) return "all-children-down";
+	if (controller.signal.aborted) return "aborted";
+	if (poolExhausted(pool, opts)) return "budget-exhausted";
+	return "all-children-down";
+}
+function poolExhausted(pool, opts) {
+	const r = pool.readout();
+	if (r.tokensLeft <= 0) return true;
+	if (opts.budget.maxUsd !== void 0 && r.usdLeft <= 0) return true;
+	if (opts.budget.deadlineMs !== void 0 && r.deadlineMs > 0 && (opts.now ?? Date.now)() >= r.deadlineMs) return true;
+	return false;
+}
+/**
+* Sum the conserved spend over every journaled `settled` event — the honest per-channel
+* total (input/output/usd/iterations all preserved), read off the same evidence replay
+* reads. Computed AFTER the join barrier so every child's settlement is recorded. Fails
+* loud if the tree was never journaled (the supervisor always `beginTree`s, so a missing
+* tree is a corrupted journal, not a normal path).
+*/
+async function spentFromJournal(journal, root) {
+	const events = await journal.loadTree(root);
+	if (events === void 0) throw new RuntimeRunStateError(`supervisor: spawn tree '${root}' is missing from the journal after run (corrupted log)`);
+	const childWork = {
+		iterations: 0,
+		tokens: {
+			input: 0,
+			output: 0
+		},
+		usd: 0,
+		ms: 0
+	};
+	const driverInference = {
+		iterations: 0,
+		tokens: {
+			input: 0,
+			output: 0
+		},
+		usd: 0,
+		ms: 0
+	};
+	for (const ev of events) if (ev.kind === "settled") accumulate(childWork, ev.spent);
+	else if (ev.kind === "metered") accumulate(driverInference, ev.spend);
+	return {
+		childWork,
+		driverInference
+	};
+}
+/** Add `b` into `a` in place, per channel. */
+function accumulate(a, b) {
+	a.iterations += b.iterations;
+	a.tokens.input += b.tokens.input;
+	a.tokens.output += b.tokens.output;
+	a.usd += b.usd;
+	if (b.usdKnown === false) a.usdKnown = false;
+	a.ms += b.ms;
+}
+/** Sum two conserved-spend tallies per channel — the child-work journal sum + the drivers' own
+*  metered inference, so `spentTotal` is the true cost of the run. */
+function addSpend(a, b) {
+	return {
+		iterations: a.iterations + b.iterations,
+		tokens: {
+			input: a.tokens.input + b.tokens.input,
+			output: a.tokens.output + b.tokens.output
+		},
+		usd: a.usd + b.usd,
+		...a.usdKnown === false || b.usdKnown === false ? { usdKnown: false } : {},
+		ms: a.ms + b.ms
+	};
+}
+/** True when any driver metered inference this run (so the winner carries a `spentBreakdown`).
+*  Checks every channel `addSpend` sums — including `ms` — so the gate stays consistent with the
+*  total even though the coordination driver currently stamps `ms: 0`. */
+function isNonEmptySpend(s) {
+	return s.iterations > 0 || s.tokens.input > 0 || s.tokens.output > 0 || s.usd > 0 || s.ms > 0;
+}
+//#endregion
+export { removeWorktree as A, routerToolLoop as C, runWorktreeHarness as D, runWorktreeChecks as E, parseCodexTokenUsage as M, runLocalHarness as N, captureWorktreeDiff as O, CodexExecutionDiagnosticError as P, routerChatWithUsage as S, runSettledCommand as T, defineRuntimeHooks as _, createScope as a, routerBrain as b, isWaitOutcome as c, validateWaitSpec as d, waitUntil as f, composeRuntimeHooks as g, readWorkerProgress as h, withDriverExecutor as i, harnessInvocation as j, createWorktree as k, pollFor as l, createActivityLog as m, createBudgetPool as n, settledToIteration as o, DEFAULT_STALL_AFTER_MS as p, spendFromUsageEvents as r, createWaitProbes as s, createSupervisor as t, timerAt as u, notifyRuntimeDecisionPoint as v, runBrainLoop as w, routerChatWithTools as x, notifyRuntimeHookEvent as y };
+
+//# sourceMappingURL=supervisor-DTKhF-RV.js.map