toolroll 0.9.103 → 0.9.105

package/dist/invoke.js

@@ -1,21 +1,3 @@
-/**
- * The invocation gateway: the only door to any provider binary (§5).
- *
- * "Never let an LLM poll" is only enforceable if there is exactly one place
- * that can start an LLM, and this is it. Every call verifies an open run
- * record WHOSE RECORDED PROVIDER MATCHES the one about to spawn (a repair
- * resumed on the wrong harness is a meaningless session id and a silent
- * fresh spend — refused here, structurally), stamps `provider_started_at`
- * the instant before the process spawns, and parses usage off the envelope
- * of EVERY completed process — nonzero exits included, because a failed
- * turn still spent money and a cost report that skips failures is a
- * smaller number, not a truer one.
- *
- * The architecture test asserts the boundary by imports, not by string
- * scan: only this module imports the registry's spawning surface
- * (`adapterFor`), and only builder, planner, reviewer, and scout import
- * `invokeAgent`.
- */
 import { takeEvalDispatch } from "./eval-gate.js";
 import { adapterFor, auditOf, claudePluginEnv, isolationUnsupported, ALL_CREDENTIAL_ENV } from "./provider.js";
 import { readProviderKey, readAuthModeStrict, PROVIDER_KEY_ENV, OWN_KEY_ENV } from "./keys.js";
@@ -54,11 +36,7 @@ import { proxyEnv, providerOnlyNetwork, repositoryEcosystems, resolveNetwork, st
 import { claudeConfigDir, claudeDefaults, codexDefaults, codexHomeDir, isolatedCodexHome } from "./provider-home.js";
 import { billingOf, claudeBillingFrom, seenBilling } from "./spend.js";
 import { primaryResultEvent, topLevelEvent } from "./stream-scope.js";
-/** "Within seconds": how soon a silent failed run must end for its stderr to
- * be read for the sign-in signal. */
 const AUTH_EARLY_EXIT_MS = 30_000;
-// Fixed names only: neither setting values nor arbitrary JSON keys belong in
-// diagnostics. The CLI's existing login stays where it is; no config is copied.
 const CLAUDE_AUTH_ENV = [
     "ANTHROPIC_API_KEY", "ANTHROPIC_BASE_URL", "ANTHROPIC_AUTH_TOKEN",
     "CLAUDE_CODE_USE_BEDROCK", "CLAUDE_CODE_SKIP_BEDROCK_AUTH", "ANTHROPIC_BEDROCK_BASE_URL",
@@ -67,7 +45,6 @@ const CLAUDE_AUTH_ENV = [
     "CLAUDE_CODE_USE_VERTEX", "CLAUDE_CODE_SKIP_VERTEX_AUTH", "ANTHROPIC_VERTEX_BASE_URL",
     "ANTHROPIC_VERTEX_PROJECT_ID", "CLOUD_ML_REGION", "GOOGLE_APPLICATION_CREDENTIALS", "GOOGLE_CLOUD_PROJECT",
 ];
-/** A value-only preflight: a settings-dependent login cannot survive empty setting sources. */
 function claudeSettingsAuthProblem(configDir) {
     let text;
     try {
@@ -76,8 +53,6 @@ function claudeSettingsAuthProblem(configDir) {
     catch (error) {
         if (error.code === "ENOENT")
             return null;
-        // A sandbox around the plane (a project check's fence, say) may hide the file while the CLI still signs in from its
-        // keychain. Isolated builds never load it, and a login that needed it fails within seconds and is reported as one.
         const code = error.code;
         if (code === "EPERM" || code === "EACCES")
             return null;
@@ -102,20 +77,9 @@ function claudeSettingsAuthProblem(configDir) {
     return keys.length === 0 ? null
         : `Your Claude settings.json defines sign-in settings: ${keys.join(", ")}. Isolated builds do not load that file. Use a Claude login that works without these settings, or select another build provider in Settings. Toolroll has not changed your login or copied these values.`;
 }
-/**
- * A provider can run the repository's own CLI. In a self-hosting build that
- * must never mean "open the database that launched me": a migration from the
- * candidate checkout would change the live schema underneath the older
- * supervisor, and even a read can contend with its watch transaction. Every
- * provider process therefore sees a unique disposable Toolroll
- * database while retaining its normal HOME/XDG environment for subscriptions
- * and unrelated developer tools.
- */
 function isolatedAgentDatabase(runId) {
     return isolatedChildDatabase(`agent-${runId}`);
 }
-/** Defend the durable registry even when a test or alternate transport calls
- * the callback directly instead of passing through an in-tree JSONL runner. */
 function transportSessionId(id) {
     if (typeof id !== "string")
         return null;
@@ -134,11 +98,6 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
     if (run.provider !== spec.provider) {
         throw new Error(`run ${runId} was opened for ${run.provider} but ${spec.provider} is about to spawn — a session resumed across harnesses is not a session`);
     }
-    // Session selection is durable authority, not an argv-only hint. A resumed
-    // turn must name exactly the canonical identity already recorded on THIS
-    // run before anything awaits or spawns. That makes a wrong child-row id a
-    // caller bug in the same class as a wrong provider, and prevents COALESCE's
-    // first-write rule from leaving row A while the process actually resumes B.
     const recordedSessionId = transportSessionId(run.sessionId);
     if (run.sessionId !== null && recordedSessionId === null) {
         throw new Error(`run ${runId} carries an empty durable session identity — nothing resumes an identity the registry cannot name`);
@@ -162,16 +121,11 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
     if (recordedSessionId !== null && requestedResumeSessionId === null && startSessionId !== recordedSessionId) {
         throw new Error(`run ${runId} already records session ${recordedSessionId} but this invocation neither resumes nor starts under it`);
     }
-    // An eval world (eval-gate.ts, docs/plans/evals-nightly.md part C): every dispatch takes one of the attempt's slots,
-    // named for this run so the runner can match it to the run's record; past the case's limit nothing spawns. Outside
-    // an eval world this changes nothing.
     const evalSlot = takeEvalDispatch(`run:${runId}`);
     if (evalSlot.active && !evalSlot.ok)
         return { kind: "refused", reason: "containment", providerVersion: null, diagnostic: evalSlot.why };
     const adapter = adapterFor(spec.provider);
     const { startSessionId: _untrustedStartSessionId, streamInput: _untrustedStreamInput, ...invocationWithoutStart } = invocation;
-    // Live input (live-input.ts): only Claude's builds, only through a transport that keeps stdin open. The brief is
-    // the session's first stdin message and never rides the argv; every other road keeps its prompt where it was.
     const liveInput = spec.provider === "claude" && invocation.phase === "build" && options.liveInput !== undefined && streamsInput(options.runner ?? adapter.defaultRunner)
         ? options.liveInput
         : null;
@@ -184,19 +138,11 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
     };
     const argv = adapter.argv(resolvedInvocation);
     const stdin = adapter.stdin?.(resolvedInvocation);
-    // Long-running phases pass idleTimeoutMs: the process has no absolute
-    // deadline and is stopped only after a full no-output interval. Bounded
-    // callers (notably repair) keep timeoutMs and its hard wall clock. A
-    // legacy caller that names neither retains the historic bounded default.
     const hardTimeoutMs = options.timeoutMs === undefined ? undefined : adapter.clampTimeout(invocation.phase, options.timeoutMs);
     const idleTimeoutMs = options.idleTimeoutMs === undefined ? undefined : adapter.clampTimeout(invocation.phase, options.idleTimeoutMs);
     const defaultTimeoutMs = hardTimeoutMs === undefined && idleTimeoutMs === undefined
         ? adapter.clampTimeout(invocation.phase, 30 * 60_000)
         : undefined;
-    // Tier-2 attestation (A2/B3): the authoritative check, immediately
-    // before the spawn it authorizes. Tier-1 providers return null here and
-    // keep their road byte-identical.
-    // An ACP agent is admitted by its own record (acp-attest.ts), read below; the version ranges are for the others.
     const attested = isAcpProvider(spec.provider) ? null : await attestProvider(spec.provider, adapter.binary, options.versionProbe);
     if (attested !== null && !attested.ok) {
         if (attested.version !== null)
@@ -208,18 +154,11 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
             diagnostic: attested.problem,
         };
     }
-    // AN ACP AGENT'S ADMISSION (docs/plans/acp-adapter.md § Admission): a passed conformance check of the exact binary
-    // on this runner, or nothing runs — absence is denial. It builds and repairs only, on a model it offered when it was
-    // checked, and no dollar cap rides it (it can't hold one; the scheduler refuses capped work first, this is the belt).
-    // An ACP spawn is admitted by its agent's attestation on this runner — or, for the conformance check alone, by the
-    // check request that will create it (acpCheck: set only by the check job). The two never stand in for each other.
     const acpCheckAsk = options.acpCheck ?? null;
     const acpAttestation = isAcpProvider(spec.provider) && acpCheckAsk === null ? store.acpAttestationFor(spec.provider, run.runner) : null;
     const acpCheckRequest = isAcpProvider(spec.provider) && acpCheckAsk !== null ? store.acpCheckAdmitting(acpCheckAsk.requestId, acpCheckAsk.step, runId, clock()) : null;
     const acpCheckLaunch = acpCheckRequest?.launchJson == null ? null : launchFromJson(acpCheckRequest.launchJson);
-    /** The plane's own isolation reading for a check's first step (below, before spawn); null when none was asked. */
     let acpIsolation = null;
-    /** What starts the agent, and who the handshake must say it is (unknown, for a check: the check learns it). */
     const acpLaunch = acpAttestation !== null ? acpAttestation.launch : acpCheckLaunch;
     if (!isAcpProvider(spec.provider) && acpCheckAsk !== null)
         throw new Error("only an ACP agent is checked");
@@ -245,29 +184,15 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
         }
         if (invocation.maxBudgetUsd !== undefined)
             return refuse(`${name} can't hold a dollar cap, so it doesn't run capped work (budget-unenforceable)`);
-        // The billing the run was admitted under must be for the model about to be chosen.
         const stamp = store.acpBillingOfRun(runId);
         if (stamp !== null && stamp.model !== spec.model)
             return refuse(`this run was admitted to bill ${stamp.model}, not ${spec.model}`);
-        // And the money moment holds it to the hard monthly budgets as stamped — immutable since admission, so a
-        // declaration changed between a gate and this spawn changes nothing: metered work a budget holds never starts.
         const billed = stamp?.kind === "plan" ? "subscription" : "api-key";
         const held = store.budgetGate(clock())({ ...store.budgetSubject(run.taskRef), agents: [{ provider: spec.provider, billing: billed }] });
         if (held.over !== null)
             return refuse(`a monthly budget holds metered work, and ${name} on ${spec.model ?? "this model"} is metered here (budget)`);
     }
-    // Auth mode decides how the credential reaches the process (the operator
-    // keeps BOTH and prefers the subscription): in "api-key" mode the
-    // managed file wins, the ambient env is a real fallback (explicit
-    // re-supply survives resolveChildEnv's chat-key strip); in
-    // "subscription" mode the key is STRIPPED from the child so the CLI's
-    // own login is used — its key is retained, just not handed over.
     const { runner, clock: _clock, versionProbe: _probe, keyHome, timeoutMs: _hardTimeout, idleTimeoutMs: _idleTimeout, stdin: _callerStdin, accumulateUsage: _accumulateUsage, liveInput: _liveInput, acpCheck: _acpCheck, network: launchNetwork, writes: launchWrites, sandbox: launchSandbox, ...runOptions } = options;
-    // The live setting is read STRICTLY (atomic authority closure): a
-    // present mode file that says neither word is a value-shaped refusal
-    // before any stamp or process — never the subscription default a
-    // lenient read would coerce it to, which would spend on a credential
-    // the seal never proved. The same reader gates filing and the seal.
     const strict = readAuthModeStrict(spec.provider, keyHome);
     if (!strict.ok) {
         return {
@@ -277,7 +202,6 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
             diagnostic: strict.problem,
         };
     }
-    // A run on an approved chain spends under the auth mode that entry was pinned to, never the provider's current setting.
     const pinned = invocation.phase === "review" ? null : pinnedEntryOf(store, runId);
     if (pinned !== null && "problem" in pinned) {
         return { kind: "refused", reason: "route-authority", providerVersion: attested === null ? null : attested.version, diagnostic: `the fallback agent's authority lapsed before spawn — ${pinned.problem}` };
@@ -288,24 +212,17 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
         if (problem !== null)
             return { kind: "refused", reason: "auth-mode", providerVersion: attested?.version ?? null, diagnostic: problem };
     }
-    // An ACP agent has no key Toolroll holds or injects: its own and everyone else's are shed (adapter.extraOmitEnv).
     const keyed = isKeyedProvider(spec.provider) ? spec.provider : null;
     const ownKeyEnv = keyed === null ? [] : OWN_KEY_ENV[keyed];
     const keyEnvName = keyed === null ? null : PROVIDER_KEY_ENV[keyed];
     const managedKey = authMode === "api-key" && keyed !== null && keyEnvName !== null
         ? readProviderKey(keyed, keyHome) ?? (process.env[keyEnvName] || null)
         : null;
-    // A pinned API key that isn't there never falls through to some other credential.
     if (pinned !== null && authMode === "api-key" && managedKey === null) {
         return { kind: "refused", reason: "auth-mode", providerVersion: attested === null ? null : attested.version, diagnostic: `this fallback agent is approved on an API key, and ${spec.provider} has none here` };
     }
-    // What decides the child's credential, computed once: the environment it starts from and every variable it sheds. The
-    // live plan proof below reads with exactly these, and the child launches with exactly these (childOmitEnv).
     const childAuth = childAuthEnv({ provider: spec.provider, phase: invocation.phase, authMode, keyEnvName, ownKeyEnv,
         extraOmitEnv: adapter.extraOmitEnv, runEnv: runOptions.env, runOmitEnv: runOptions.omitEnv });
-    // A fallback agent approved on its plan runs only on a login its CLI proves, live, is that plan: read with the run's
-    // own environment, before anything is started for it (no proxy, tools or homes to leave behind). A provider with no
-    // live proof never gets here (filing refuses it); if one does, it's refused too. A key is never read as paid.
     if (pinned !== null && pinned.index > 0 && authMode === "subscription") {
         const live = PLAN_LOGIN_PROVABLE.has(spec.provider)
             ? await livePlanLogin(spec.provider, attested !== null ? attested.executable : adapter.binary, childAuth.omitEnv, childAuth.env)
@@ -316,55 +233,26 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
                 diagnostic: `this fallback agent is approved on its plan, and ${spec.provider} isn't signed in to one here${live === "api-key" ? " (it's signed in another way)" : ""}` };
         }
     }
-    // Resume XOR mint, enforced at the GATEWAY (Codex gemini verify round 2,
-    // finding 3): a resume and a minted start id are mutually exclusive —
-    // geminiArgv silently prefers --resume, so a minted id that rides
-    // alongside a resume would be stamped and later enforced against an
-    // envelope that never carried it, a paid protocol refusal. When resuming,
-    // the minted id is dropped here, before it is ever stamped.
-    // The minted session identity (A5): stamped durably BEFORE the start
-    // stamp — intent precedes the process, and the envelope must later
-    // MATCH this id or the run fails typed.
     if (startSessionId !== undefined) {
         store.stampRun(runId, { sessionId: startSessionId });
     }
     const spawn = witnessedRunner(store, runId, clock, runner ?? adapter.defaultRunner);
     let transportAnnouncedSessionId = null;
     let transportSessionConflict = false;
-    // B3: the attested executable IS the spawned executable — one resolution.
-    // A MANAGED key reaches exactly its own provider's child environment
-    // (keys.ts): the foreign-credential strip already shed everybody
-    // else's, and the plane's own env never needed to carry it. A key
-    // already ambient in the environment keeps working; the managed file,
-    // being deliberate, wins.
     const isolatedDb = isolatedAgentDatabase(runId);
-    // Where the build runs: Claude reads the repository's CLAUDE.md from here.
     const workspace = invocation.phase === "review" ? null : runOptions.cwd ?? run.worktree ?? null;
-    // How a tool server the broker starts is fenced: as its agent is, once that fence is fixed below.
     let serverFence = null;
-    // The run's containment, fixed before any tool is prepared: this platform and the OS fence its run gets (a build
-    // has one wherever the plane has a database to fence). It decides which tools may hold secrets in a process the
-    // build could otherwise read; nothing the launch or the checkout writes feeds it.
     const containment = { platform: process.platform, fence: invocation.phase === "review" ? "none" : fenceMethod(spec.provider, store.databaseFile() !== null) };
-    // The project's tools (v80): exactly its MCP servers, and none of the
-    // operator's global or a repository's own, served by this launch's broker
-    // (tool-broker.ts), which alone holds their secrets. A review keeps its isolation.
-    // Set once the fence is known: a fenced build's servers never start outside a fence.
     let serverMustBeFenced = false;
-    // Pinned for the attempt (sandbox parity C11): whether an instance operator allowed unconfined agents, read once now.
-    // A tool server the agent starts late gets the decision this attempt launched with, never one changed meanwhile.
     const unconfinedAtLaunch = store.unfencedAgentsAllowed();
-    // What the build writes (its checkout, its project's caches): a tool server never runs from there, nor reads it at all.
     const serverUntrusted = workspace === null ? [] : toolUntrusted(store, workspace, keyHome);
     const launchTools = invocation.phase === "review" ? null : await runTools(store, runId, spec, options.keyHome, clock, invocation.readOnlyTools, invocation.researchWithheld, containment, {
         env: { ...process.env, ...(runOptions.env ?? {}) },
         omitEnv: [...(runOptions.omitEnv ?? []), ...ALL_CREDENTIAL_ENV],
         pass: childDatabaseEnv(isolatedDb.file),
-        // A tool server starts in a folder the build can't write, and never runs the build's own bytes (arc 2).
         cwd: keyHome ?? homedir(),
         untrusted: serverUntrusted,
         wrap: () => serverFence,
-        // A fenced build's tool servers start only in a fence too, unless an instance operator allowed unconfined agents.
         unwrapped: () => serverMustBeFenced && !unconfinedAtLaunch
             ? "This machine can't confine the tool's server (no macOS sandbox, no working bubblewrap), so it was not started." : null,
     });
@@ -374,7 +262,6 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
     }
     const tools = launchTools;
     const codexHarness = spec.provider === "codex" || spec.provider === "openrouter";
-    // A Codex build's own CODEX_HOME (provider-home.ts): the operator's sign-in and sessions, linked, and nothing else.
     let codexHome = null;
     if (codexHarness && invocation.phase !== "review") {
         try {
@@ -386,13 +273,6 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
             return { kind: "refused", reason: "containment", providerVersion: attested?.version ?? null, diagnostic: "The build's private Codex home could not be created; check access to its sign-in and sessions folders, then retry." };
         }
     }
-    // The agent fence: Toolroll's own secrets, database and other runs'
-    // evidence stay out of reach, whatever the permission mode. A review is
-    // already confined to its sealed files.
-    // A build's fence also holds its task boundary: home configuration and
-    // the repositories beside its own, fresh and resumed alike. Codex starts
-    // tool servers outside its command sandbox, so its own launch folder is
-    // fenced too; Claude reads its config from there, inside the sandbox.
     const ownTools = tools?.privateDir === undefined ? null : realpathSync(tools.privateDir);
     const fenceOf = invocation.phase === "review" ? { fence: [], fileTools: [], grants: NO_GRANTS, gitPaths: [], cache: undefined, problem: undefined } : await runFence(store, runId, spec.provider, options.keyHome, codexHarness ? null : ownTools, launchWrites ?? WRITES_DEFAULT, launchSandbox ?? LEGACY_SANDBOX);
     if (fenceOf.problem !== undefined) {
@@ -403,10 +283,7 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
     }
     const fence = [...fenceOf.fence, ...(fenceOf.fence.length > 0 && codexHarness ? [ownTools, codexHome === null ? null : realpathSync(codexHome.dir)].filter((path) => path !== null) : [])];
     const grants = { ...fenceOf.grants };
-    // The run's network (egress.ts): sealed by its approval, or the provider's hosts alone, or the caller's own proxy.
     const network = launchNetwork ?? { policy: providerOnlyNetwork(spec.provider) };
-    // Codex's command sandbox has no proxy (its argv is fixed just below): its commands are online only for a sealed
-    // open network, and offline otherwise.
     if (fence.length > 0 && codexHarness) {
         grants.network = "policy" in network && network.policy.mode === "open" ? { mode: "open" }
             : { mode: "allowlist", proxyPort: 0, brokerPorts: [], loopback: "proxy-only", socketRoots: [] };
@@ -415,38 +292,26 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
     const buildInvocation = { ...resolvedInvocation, ...(tools === null ? {} : { toolArgv: tools.argv, fence, fenceGrants: grants, fileToolFence: fenceOf.fileTools }), ...(workspace === null ? {} : { workspace }), ...(inherited === undefined ? {} : { inherited }) };
     const launchArgv = tools === null ? argv : adapter.argv(buildInvocation);
     const fenced = fenceLaunch(spec.provider, fence);
-    // An ACP agent runs only inside the OS fence: nothing else holds it (it may run commands without asking).
     if (isAcpProvider(spec.provider) && fenced.method !== "macos-sandbox" && fenced.method !== "linux-bubblewrap") {
         tools?.cleanup();
         codexHome?.cleanup();
         removeAgentDatabase(isolatedDb.dir);
         return { kind: "refused", reason: "containment", providerVersion: acpAttestation?.agent.version ?? null, diagnostic: `${ACP_AGENTS[spec.provider].name} runs only inside the OS fence (the macOS sandbox or bubblewrap), and this launch has neither (fence-unavailable)` };
     }
-    // The tools were chosen for the fence decided above: a launch that got any other starts nothing.
-    // Only a prepared project-tool broker depends on the earlier decision. Empty Claude configs also have a privateDir.
     if (tools?.serverPids !== undefined && fenced.method !== containment.fence) {
         tools.cleanup();
         codexHome?.cleanup();
         removeAgentDatabase(isolatedDb.dir);
         return { kind: "refused", reason: "containment", providerVersion: attested?.version ?? null, diagnostic: "The build's fence changed while its tools were prepared. Nothing was started; retry the task." };
     }
-    // A tool server the broker starts is fenced by what this platform supports, whatever the provider: Codex's own
-    // profile fences only its agent's commands, and the broker starts servers outside it.
     if (fence.length > 0) {
-        // A tool server keeps its own reach (it holds its tool's secrets, not the agent's code): never the agent's network,
-        // nor its write allowlist (a server keeps its own state where it always has).
         const serverGrants = () => serverGrantsOf(grants);
-        // Nor read what the build wrote: however its arguments are spelled, no byte of the checkout or caches can load.
         const serverDenies = [...fence, ...serverUntrusted.filter(path => existsSync(path)).map(path => realpathSync(path))];
-        // Pinned: the server fence this attempt launched with, a copy, whatever changes later (C11).
         const pinned = structuredClone(serverGrants());
         if (macosFenceAvailable() || linuxFenceAvailable())
             serverFence = (file, args, cwd) => sandboxedSpawn(file, args, serverDenies, pinned, cwd);
         serverMustBeFenced = true;
     }
-    // No silent fallback (arc 1): a build this machine can't confine at the OS — Claude reduced to its own file-tool
-    // rules, Gemini to nothing — doesn't start unless the instance operator allowed unconfined agents here. An injected
-    // runner (tests) starts no real agent.
     const unconfined = fence.length > 0 && (fenced.method === "claude-rules" || fenced.method === "none");
     if (unconfined && runner === undefined && !store.unfencedAgentsAllowed()) {
         tools?.cleanup();
@@ -460,8 +325,6 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
     const confinedOs = fenced.method === "macos-sandbox" || fenced.method === "linux-bubblewrap";
     if (fence.length > 0 && !codexHarness && confinedOs) {
         const brokerPorts = tools?.brokerPort === undefined ? [] : [tools.brokerPort];
-        // Unix sockets only under this run's own folders: its checkout, and a temp folder of its own inside its private
-        // launch folder (the system temp folder holds other programs' sockets — editors, agents, password managers).
         if (ownTools !== null) {
             runTemp = join(ownTools, "tmp");
             mkdirSync(runTemp, { recursive: true, mode: 0o700 });
@@ -479,9 +342,6 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
                 egress = await startEgressProxy({ hosts: network.policy.hosts });
                 grants.network = { mode: "allowlist", proxyPort: egress.port, brokerPorts, loopback: network.policy.loopback, socketRoots, token: egress.secret };
             }
-            // On Linux the build has a network of its own, and the sandbox runtime relays only two ports into it: the
-            // proxy's (3128) and a second (1080), which carries this run's tool broker. Claude's tool list names it there.
-            // (An injected runner, in tests, runs outside every sandbox and keeps the broker's own address.)
             if (fenced.method === "linux-bubblewrap" && grants.network.mode === "allowlist" && runner === undefined && tools?.brokerPort !== undefined && tools.privateDir !== undefined) {
                 const list = join(tools.privateDir, "mcp.json");
                 if (existsSync(list))
@@ -497,14 +357,10 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
                 diagnostic: `The build's network could not be set up, so nothing was started: ${error instanceof Error ? error.message : String(error)}` };
         }
     }
-    // The attempt's pinned fence, stamped on the run (C11): its method, policy version, the digest of exactly what it was
-    // given, and the sandbox engine and version it runs in.
     if (invocation.phase !== "review")
         store.recordRunFence(runId, { method: fenced.method, paths: fence.length, policy: (launchSandbox ?? LEGACY_SANDBOX).policy,
             digest: fenceDigest(fence, grants), engine: sandboxRuntimeWords() }, clock());
     const billingSeen = { keySource: null, model: null, planWindows: false, answered: false };
-    // v105: a Codex run on its sign-in bills as Codex says it's signed in (a ChatGPT plan, or a saved key, or Bedrock),
-    // read right before it runs. Never with an injected runner: tests don't start a real Codex.
     const codexLogin = spec.provider === "codex" && authMode === "subscription" && runner === undefined
         ? await codexLoginBilling(attested !== null ? attested.executable : adapter.binary, [...(runOptions.omitEnv ?? []), ...adapter.extraOmitEnv, ...ownKeyEnv])
         : null;
@@ -512,30 +368,20 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
         ...(runOptions.env ?? {}),
         ...(adapter.env?.(buildInvocation) ?? {}),
         ...(tools?.env ?? {}),
-        // A fenced build's git never expires a reflog, so gc never rewrites another task's (agent-fence.ts).
         ...(fence.length > 0 ? fencedGitEnv({ ...process.env, ...(runOptions.env ?? {}) }) : {}),
         ...(codexHome === null ? {} : { CODEX_HOME: codexHome.dir }),
         ...(managedKey === null || keyEnvName === null ? {} : { [keyEnvName]: managedKey }),
-        // The run's own proxy, in every spelling a program reads (egress.ts): after every other setting, so no caller's
-        // environment points the build around it. A program that ignores them is refused by the OS fence instead.
         ...(egress === null || !("policy" in network) ? {} : proxyEnv(egress, network.policy.loopback)),
-        // Its own temp folder, where its tools' sockets may live (the only one its fence admits besides its checkout).
         ...(runTemp === null ? {} : { TMPDIR: runTemp, TMP: runTemp, TEMP: runTemp }),
-        // Claude's own working folder goes there too (it is otherwise the shared /tmp/claude-<uid>).
         ...(runTemp === null || spec.provider !== "claude" ? {} : { CLAUDE_CODE_TMPDIR: runTemp }),
-        // A workspace build's package managers keep their caches in its project's own folder (arc 2).
         ...(fenceOf.cache === undefined || grants.writes === undefined ? {} : buildCacheEnv(fenceOf.cache)),
-        // This key is deliberately last: no caller may point an agent back at
-        // the live control database through a generic RunOptions override.
         ...childDatabaseEnv(isolatedDb.file),
     };
-    // The one omit list (childAuthEnv): the live plan proof read with this same list.
     const childOmitEnv = childAuth.omitEnv;
     const launchOptions = {
         ...(fenced.wrap.length === 0 ? {} : { fence: fenced.wrap, fenceGrants: grants, confinement: "required" }),
         ...runOptions,
         ...(workspace === null ? {} : { cwd: workspace }),
-        // v105: how the CLI really billed this turn (its key source, its plan's windows), read off its own stream.
         onStreamEvent: event => {
             observeClaudeBilling(billingSeen, event);
             runOptions.onStreamEvent?.(event);
@@ -549,20 +395,13 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
         },
         ...(stdin === undefined ? {} : { stdin }),
         ...(liveInput === null ? {} : { liveInput }),
-        // One ACP conversation: the brief, the sealed model, and who the check says the agent is.
         ...(acpLaunch === null || spec.model === null ? {} : { acp: { prompt: buildInvocation.brief, model: spec.model, expect: acpAttestation?.agent ?? null, ...(runOptions.acp?.onControl === undefined ? {} : { onControl: runOptions.acp.onControl }), ...(runOptions.acp?.handshakeMs === undefined ? {} : { handshakeMs: runOptions.acp.handshakeMs }) } }),
         ...(hardTimeoutMs === undefined ? {} : { timeoutMs: hardTimeoutMs }),
         ...(idleTimeoutMs === undefined ? {} : { idleTimeoutMs }),
         ...(defaultTimeoutMs === undefined ? {} : { timeoutMs: defaultTimeoutMs }),
         env: childEnv,
         omitEnv: childOmitEnv,
-        // Providers run in their own process group (M6.12): the harness spawns
-        // shells and tools of its own, and both the timeout and the watch's
-        // hard stop must end the whole tree, not orphan the grandchildren.
         processGroup: true,
-        // The session registry's crash guarantee (M6.9): the id is stamped the
-        // moment the stream announces it, first write wins — a daemon that
-        // dies mid-turn still knows which session to offer the successor.
         onSessionId: id => {
             const normalized = transportSessionId(id);
             if (normalized === null)
@@ -583,7 +422,6 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
             const probeOptions = {
                 cwd: workspace, env: checkoutGitEnv({ ...inheritedEnv, ...childEnv }), omitEnv: childOmitEnv, envAllowlist: [],
             };
-            // A broken checkout is not evidence of a broken fence. No provider is invoked by either check.
             const gitArgs = [...HARDENED_GIT_ARGS, "rev-parse", "HEAD"];
             const control = await runCommand("git", gitArgs, probeOptions);
             if (control.code === 0) {
@@ -602,11 +440,7 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
                 }
             }
         }
-        // THE CHECK'S ISOLATION, PROVEN BY THE PLANE (docs/plans/acp-adapter.md § Layer E): inside the exact fence and
-        // child environment the agent is about to get, a canary file in the fenced state must be unreadable and a canary
-        // key in the launching environment must be absent. No agent takes part, so no agent can fake it.
         if (acpCheckAsk?.isolation !== undefined && launchOptions.fence !== undefined && workspace !== null) {
-            // processGroup: run() applies the fence only on the process-group road (a plain execFile carries none).
             const probe = { cwd: workspace, env: childEnv, omitEnv: childOmitEnv, fence: launchOptions.fence, confinement: "required", ...(launchOptions.fenceGrants === undefined ? {} : { fenceGrants: launchOptions.fenceGrants }), timeoutMs: 15_000, processGroup: true };
             const read = await runCommand("/bin/cat", [acpCheckAsk.isolation.file], probe);
             const env = await runCommand("/usr/bin/env", [], probe);
@@ -615,22 +449,6 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
                 envClear: env.code === 0 && !env.stdout.includes(acpCheckAsk.isolation.envValue),
             };
         }
-        // The stamp precedes the spawn, so a crash between the two leaves a run
-        // that claims spend which never happened — the honest direction. A spawn
-        // before the stamp would leave spend no record claims, which is the lie
-        // the invariant exists to rule out. For attested providers the probed
-        // version rides the SAME durable write (B2).
-        // The spawn leg of the runner gate (MCP spec v6, review finding 4):
-        // the tuple re-proven against LIVE rows AFTER every awaited step, in
-        // the same breath as the stamp — a takeover during the attestation
-        // await can no longer slip a stale process through.
-        // THE PLANNER'S ROUTE, RE-PROVED AT THE SPAWN (final authority closure):
-        // the provenance the planner was admitted under is held to the authority
-        // its task holds RIGHT NOW — the strict working projection of a filed
-        // scope (exact terms, resolved profile, route parity, digest,
-        // live auth mode), or the bare word `legacy` on a task with no scope. A
-        // scope rewritten, corrupted, or unresolved between the claim and this
-        // instant invokes no provider: a value-shaped refusal, no spend.
         if (run.role === "planner") {
             const proved = store.proveRouteForSpawn(runId, clock());
             if (!proved.ok) {
@@ -650,10 +468,6 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
                 diagnostic: "the run's runner custody lapsed before spawn — the lease, the runner, or its repo binding no longer stands",
             };
         }
-        // THE STOP FENCE at the spawn (v52): a stop recorded against this run
-        // — or the attempt it runs under — before this instant spawns nothing.
-        // A value-shaped refusal, no stamp, no process, no spend; the road's
-        // settlement seals the attempt as interrupted.
         const stopBeforeSpawn = store.applicableStopFor(runId);
         if (stopBeforeSpawn !== null) {
             return {
@@ -663,10 +477,6 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
                 diagnostic: `stopped by ${stopBeforeSpawn.requestedBy} (run #${stopBeforeSpawn.run}) before the provider spawned — nothing was spent`,
             };
         }
-        // THE CONTAINMENT FENCE at the spawn (OS containment plan): a required
-        // native policy this runner cannot meet — macOS, an undelegated cgroup,
-        // a missing helper — spawns nothing. A value-shaped refusal in the
-        // policy's own words, no stamp, no process, no spend.
         const containment = currentContainment();
         if (containment.refusal !== null) {
             return {
@@ -676,9 +486,7 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
                 diagnostic: containment.refusal,
             };
         }
-        // The ACP launch re-proved HERE, after every await: each bound file is still the one that passed its check.
         if (acpCheckAsk !== null && acpCheckRequest !== null && acpCheckLaunch !== null) {
-            // The check request is read again here, after every await: still running, unexpired, owned, this step's run.
             const still = store.acpCheckAdmitting(acpCheckAsk.requestId, acpCheckAsk.step, runId, clock());
             if (still === null || still.launchJson !== acpCheckRequest.launchJson) {
                 return { kind: "refused", reason: "provider-unattested", providerVersion: null, diagnostic: "the check stopped admitting this run while it was being set up — nothing was started" };
@@ -688,7 +496,6 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
                 return { kind: "refused", reason: "provider-unattested", providerVersion: null, diagnostic: verified.problem };
         }
         if (acpAttestation !== null) {
-            // The record is read again here, after every await: a check revoked or replaced during setup starts nothing.
             const live = store.acpAttestationFor(spec.provider, run.runner);
             if (live === null || live.id !== acpAttestation.id) {
                 return { kind: "refused", reason: "provider-unattested", providerVersion: acpAttestation.agent.version, diagnostic: `${ACP_AGENTS[spec.provider].name}'s check was revoked or replaced while this run was being set up — nothing was started` };
@@ -698,8 +505,6 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
                 return { kind: "refused", reason: "provider-unattested", providerVersion: acpAttestation.agent.version, diagnostic: verified.problem };
             }
         }
-        // THE CHAIN'S LAST LOOK (fallback.ts): the walk's place, the approval, and for a paid entry the live grant, read in
-        // the one transaction that stamps the spend, after every await.
         const chainRefusal = store.transact(() => {
             const custody = invocation.phase === "review" ? null : chainCustodyProblem(store, runId);
             if (custody !== null)
@@ -715,14 +520,8 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
         if (chainRefusal !== null) {
             return { kind: "refused", reason: "route-authority", providerVersion: attested === null ? null : attested.version, diagnostic: `the fallback chain's authority lapsed before spawn — ${chainRefusal}` };
         }
-        // The brief is queued only once the checkout has passed the fence check.
         liveInput?.begin(invocation.brief);
         spawnedAt = Date.now();
-        // Under the stop watch (v52): the run's stop row is re-read while the
-        // provider runs, and a stop kills THIS run's process group through the
-        // handle registered under its owner tag — the exact-attempt road,
-        // never the global sweep. Settlement then reads the same row.
-        // An ACP agent starts through its attested launch (the pinned interpreter for a script), never a PATH lookup.
         result = await underStopWatch(store, runId, () => acpLaunch !== null
             ? spawn(acpLaunch.file, [...acpLaunch.prefix, ...launchArgv], launchOptions)
             : spawn(attested !== null ? attested.executable : adapter.binary, launchArgv, launchOptions));
@@ -731,8 +530,6 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
         removeAgentDatabase(isolatedDb.dir);
         tools?.cleanup();
         codexHome?.cleanup();
-        // What the run's proxy saw (shown on its result): connections it made and refused. A connection the OS refused
-        // outright never reached it, and isn't counted.
         if (invocation.phase !== "review" && grants.network !== undefined) {
             store.recordRunNetwork(runId, {
                 mode: grants.network.mode, phase: "agent",
@@ -742,44 +539,25 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
         }
         await egress?.close();
     }
-    // v105: the run's billing, fixed from evidence before its usage is priced: a key it was given is a key; otherwise
-    // what the CLI said (Claude's stream) or was last seen doing (Codex's account), and the setting only when neither.
     const evidence = spec.provider === "claude" ? claudeBillingFrom(billingSeen)
-        // Codex signed in with ChatGPT is its plan, unless its plan is itself billed by use (seen by the console's probe).
         : codexLogin === "subscription" ? seenBilling(store.handle, "codex") ?? "subscription" : codexLogin;
-    // What this computer's Claude does with no key from us (subagents and drafts bill the same way): learnt only from a
-    // run we gave no key that got as far as an answer.
     if (spec.provider === "claude" && managedKey === null && authMode === "subscription" && billingSeen.answered && evidence !== null) {
         store.recordProviderBilling("claude", evidence, new Date());
     }
-    // An ACP run bills as its admission stamp says (store.acpBillingOfRun): its agent's own plan, or metered.
     const acpBilling = isAcpProvider(spec.provider) ? (store.acpBillingOfRun(runId)?.kind === "plan" ? "subscription" : "api-key") : null;
     store.fixRunBilling(runId, acpBilling ?? (authMode === "api-key" ? "api-key" : evidence ?? billingOf(spec.provider, store.handle)), new Date());
-    // v141: whether that billing is this run's own evidence or this computer's default (a guess: unknown money).
     recordRunBillingBasis(store, runId, acpBilling !== null || authMode === "api-key" || evidence !== null ? "evidence" : "default");
     const envelope = adapter.parse(result.stdout);
     store.stampAgentReportedUsage(runId, envelope.agentReportedUsage ?? null);
-    // An installed CLI too old for a build's own setup refuses its flags
-    // before it starts: nothing ran, and the run says what to update.
     const unsupported = result.code !== 0 && envelope.initObserved !== true && invocation.phase !== "review" ? isolationUnsupported(spec.provider, result.stderr) : null;
     if (unsupported !== null) {
-        // The CLI refused its flags before any model turn: the run never started, whatever the stamp said.
         store.withdrawProviderStart(runId);
         return { kind: "refused", reason: "provider-unattested", providerVersion: attested === null ? null : attested.version, diagnostic: unsupported };
     }
-    // The callback is the crash-safe early stamp; the parsed envelope is the
-    // authoritative completed-stream account. Stamp it as a fallback for an
-    // alternate transport. On fresh runs COALESCE makes callback/parser
-    // disagreement visible in the durable row; resumed runs need the separate
-    // callback latch because their row deliberately carries the input session.
     if (envelope.sessionId !== null) {
         store.stampRun(runId, { sessionId: envelope.sessionId });
     }
     const durableSessionId = store.getRun(runId)?.sessionId ?? null;
-    // The durable id, callback id, and retained envelope must all resolve to
-    // ONE identity. This deliberately includes resumed turns: a provider that
-    // returns a fork has not proved the same-session repair/warm-resume
-    // contract, and COALESCE must not disguise row A / process B as success.
     const sessionIdentityProblem = transportSessionConflict
         ? "the provider transport announced conflicting session ids"
         : transportAnnouncedSessionId !== null && transportAnnouncedSessionId !== envelope.sessionId
@@ -791,8 +569,6 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
                         ? "the provider returned a session id different from the exact identity recorded for resume"
                         : "the provider session id was different from the identity durably recorded when the stream initialized"
                 : null;
-    // A run whose cost could not be read may still have spent up to its cap: it is charged the cap, never nothing, so
-    // the next run's remaining budget stays honest. With no cap it is unmeasured, as a Codex run is, and says so.
     const unknownCost = envelope.costUnknown === true;
     const cap = typeof invocation.maxBudgetUsd === "number" && Number.isFinite(invocation.maxBudgetUsd) && invocation.maxBudgetUsd > 0 ? invocation.maxBudgetUsd : null;
     const costUsd = unknownCost ? cap : envelope.costUsd;
@@ -804,47 +580,29 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
         ...(envelope.tokensOut === null ? {} : { tokensOut: envelope.tokensOut + (options.accumulateUsage ? run.tokensOut ?? 0 : 0) }),
         ...(costUsd === null ? {} : { costUsd: costUsd + (options.accumulateUsage ? run.costUsd ?? 0 : 0) }),
         ...(usageJson === null ? {} : { usageJson }),
-        // How many agent turns it took, where the provider reports it (docs/plans/run-efficiency.md); unknown stays NULL.
         ...(envelope.ending?.turns == null ? {} : { agentTurns: envelope.ending.turns + (options.accumulateUsage ? run.agentTurns ?? 0 : 0) }),
     });
-    // v141: a turn whose cost wasn't reported leaves the run's money unknown for good (a sticky column, never the note).
     recordRunCostUnknown(store, runId, envelope.costUnknown === true);
-    // v140: the exact model the provider's own events named (null: not reported); a resumed turn adds its own to the run's.
     recordRunModelReported(store, runId, envelope.modelReported ?? null, options.accumulateUsage === true);
-    // How the attempt ended, classified HERE where the structural terminal
-    // still exists; a sign-in that no longer works pauses its provider.
-    // A run that failed within seconds having produced nothing is read for
-    // the sign-in signal too: a CLI that is not logged in often says so on
-    // stderr before its structured stream starts.
     const quietEarlyExit = result.code !== 0 && !result.timedOut && !result.notFound &&
         Date.now() - spawnedAt <= AUTH_EARLY_EXIT_MS &&
         envelope.promptConsumed !== true && (envelope.tokensOut ?? 0) === 0;
-    // Claude has no attested range (attest.ts), so a terminal that reads as a plan limit asks the installed CLI its version.
     const limitVersion = !terminalMatchesLimit(spec.provider, authMode, envelope.structuralTerminal) ? null
         : attested !== null ? attested.version : await reportedVersion(adapter.binary, options.versionProbe);
     const terminalClass = classifyTerminal({
         terminal: envelope.structuralTerminal,
         run: { provider: spec.provider, authMode, version: limitVersion },
-        // stderr and plain stdout only: a JSON event line can carry the agent's
-        // own command output (codex aggregated_output), never its sign-in.
         earlyExit: quietEarlyExit ? `${result.stderr.slice(-4096)}\n${plainLines(result.stdout).slice(-4096)}` : null,
     });
-    // A plan limit counts only from a run whose protocol and identity hold (fallback.ts moves work on it): a terminal from a
-    // conflicting session, a minted id it didn't echo, or a failure on exit 0 is refused below and is never exhaustion.
     const protocolClean = envelope.protocolError === null
         && !(startSessionId !== undefined && envelope.initObserved === true && envelope.sessionId !== startSessionId)
         && sessionIdentityProblem === null
         && !(result.code === 0 && envelope.structuralTerminal?.failed === true);
     store.stampTerminalClass(runId, authMode, terminalClass === "usage-exhausted" && !protocolClean ? "not-exhausted" : terminalClass);
-    // What the provider said on its way out, saved for a person (provider-capture.ts). Nothing routes on it.
     if (terminalClass !== "auth-expired" && !result.timedOut && !result.notFound && (result.code !== 0 || envelope.structuralTerminal?.failed === true)) {
         captureProviderFailure(store, { run: runId, provider: spec.provider, model: spec.model ?? null, authMode, exitCode: result.code, code: envelope.structuralTerminal?.code ?? null,
             texts: [envelope.structuralTerminal?.text, envelope.finalMessage?.slice(-1_000), result.stderr.slice(-2_000), plainLines(result.stdout).slice(-1_000)] }, new Date());
     }
-    // Contradictory structural identity is a provider protocol failure, not
-    // a session selection problem. Usage above remains recorded because the
-    // process ran and spent, but no downstream handoff or repair may trust
-    // either id from this envelope.
     if (envelope.protocolError !== null) {
         return {
             kind: "refused",
@@ -855,10 +613,6 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
             ...(envelope.acp === undefined ? {} : { acp: { ...envelope.acp, ...(acpIsolation === null ? {} : { isolation: acpIsolation }) } }),
         };
     }
-    // The minted-identity proof (A5): once the harness initialized, the id
-    // it announced must be the id the plane minted — anything else means
-    // the session on disk is not the session on record, and repair must
-    // never resume it. Usage above is already recorded: the spend happened.
     if (startSessionId !== undefined &&
         envelope.initObserved === true &&
         envelope.sessionId !== startSessionId) {
@@ -873,10 +627,6 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
             ...(envelope.acp === undefined ? {} : { acp: { ...envelope.acp, ...(acpIsolation === null ? {} : { isolation: acpIsolation }) } }),
         };
     }
-    // An early transport announcement, a pre-existing resume identity, and
-    // the completed retained envelope must resolve to one canonical id. If
-    // either side is missing or different, no handoff or warm resume may use
-    // this run even though its spend remains on the record.
     if (sessionIdentityProblem !== null) {
         return {
             kind: "refused",
@@ -887,9 +637,6 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
             ...(envelope.acp === undefined ? {} : { acp: { ...envelope.acp, ...(acpIsolation === null ? {} : { isolation: acpIsolation }) } }),
         };
     }
-    // A provider's explicit failure terminal always wins over its process exit
-    // status. Exit 0 only proves the wrapper closed cleanly; it cannot turn a
-    // failed model turn into a successful build.
     if (result.code === 0 && envelope.structuralTerminal?.failed === true) {
         return {
             kind: "refused",
@@ -900,11 +647,6 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
             ...(envelope.acp === undefined ? {} : { acp: { ...envelope.acp, ...(acpIsolation === null ? {} : { isolation: acpIsolation }) } }),
         };
     }
-    // The terminal contract (A4): when the audit requires it, a zero exit is
-    // believed ONLY with initialization observed and the structural success
-    // terminal present. A missing, truncated, or error-status terminal on
-    // exit 0 is the harness breaking its own protocol — never a completed
-    // build, and the handoff is never ingested.
     if (auditOf(spec.provider).terminalContract === "required" &&
         result.code === 0 &&
         !(envelope.initObserved === true && envelope.promptConsumed === true)) {
@@ -920,13 +662,11 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
             ...(envelope.acp === undefined ? {} : { acp: { ...envelope.acp, ...(acpIsolation === null ? {} : { isolation: acpIsolation }) } }),
         };
     }
-    // A run that worked proves its provider's sign-in works: a sign-in pause
-    // on it lifts, and its waiting tasks may start again.
     if (result.code === 0 && envelope.structuralTerminal === null && envelope.promptConsumed !== false) {
         try {
             liftAuthPause(store, spec.provider, "run", `run #${runId}`, clock(), new Date(spawnedAt));
         }
-        catch { /* the pause stays until the next proof */ }
+        catch { }
     }
     return {
         kind: "ran",
@@ -946,14 +686,6 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
                 tokensOut: envelope.tokensOut,
                 costUsd,
             },
-            // Gated on the run having NOTHING to show (Codex M5-M8 audit, C-8),
-            // where "nothing to show" is STRUCTURAL when the transport can say so
-            // (arc 1 finding 15): a retained error result carries diagnostic text
-            // in finalMessage, and that prose must not read as an agent's attempt.
-            // Transports without the consumption signal keep the historical
-            // no-final-message rule. A nonzero exit WITH a consumed prompt is a
-            // failed agent turn — the agent ran, spoke, and failed — and must be
-            // classified as that, never as the harness failing to come up.
             initFailed: envelope.initObserved === false &&
                 (envelope.promptConsumed === null
                     ? envelope.finalMessage === null
@@ -963,7 +695,6 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
         },
     };
 }
-/** The reported usage, when its kept text is whole JSON, to sit beside a cost note. */
 function usageOf(raw) {
     if (raw === null)
         return {};
@@ -974,17 +705,12 @@ function usageOf(raw) {
         return {};
     }
 }
-/** What the plane recorded of a checkout's setup: its project and the setup stamped on it (null: none recorded). */
 function linkedFor(store, worktree) {
     const row = worktree === null ? null : store.getWorktree(worktree);
     return row === null ? null : { repo: row.repo, setupDigest: row.setupDigest ?? null };
 }
-/** The paths this run's agent may not reach: the state folder around the live database (but not its own worktree),
- * ~/.toolroll (or its older name), its task boundary and other launches' private folders; what the fence gives back
- * (FenceGrants); and what only Claude's file tools refuse. */
 async function runFence(store, runId, provider, keyHome, ownTools, writes = WRITES_DEFAULT, sandbox = LEGACY_SANDBOX) {
     try {
-        // A plane always has a database file; an in-memory store (a test) has nothing to fence.
         const databaseFile = store.databaseFile();
         if (databaseFile === null)
             return { fence: [], fileTools: [], grants: NO_GRANTS };
@@ -995,54 +721,34 @@ async function runFence(store, runId, provider, keyHome, ownTools, writes = WRIT
             throw new CheckoutBindingError("The checkout's Git pointer was changed or its trusted binding could not be verified.");
         const poolRoots = [join(dirname(databaseFile), "worktrees"), ...store.listWorktrees().map(record => poolRootOf(record.path, record.repo))];
         const binding = worktree === null || row === null ? null : trustedWorktreeBinding(row.repo, worktree, poolRoots);
-        // The storage check, awaited off this thread (protected-storage.ts): a privacy prompt holds up only its child.
         const storage = await prepareProtectedStorage(keyHome ?? homedir());
         const boundary = worktree === null ? null : taskBoundary({ worktree, provider, ...home, binding, policy: sandbox.policy, storage });
         const folders = runFolders(ownTools);
-        // A build with a checkout writes only its workspace unless its approval said anywhere (arc 2): its checkout and
-        // Git data, its launch folder, its project's caches and the provider state its CLI must write.
         const allowed = worktree === null || row === null || writes !== "workspace" ? null
             : writeAllowlist({ provider, home: keyHome ?? homedir(), worktree, binding, launchFolder: ownTools, cache: buildCacheFolder(row.repo, keyHome ?? homedir()) });
-        // The shared install is granted only as the plane linked it: this checkout's project and stamped setup.
-        // Every plane checkout pool is denied around this one: the plane's own beside the database, and the one this
-        // checkout was recorded in (a --pool elsewhere), so another project's worktree, present at launch, is out of reach. Native wrappers also cover later creations.
         const launch = fenceFor(provider === "command" ? "command" : "build", { databaseFile, worktree, ...home, boundary, binding, runFolders: folders, poolRoots, storage,
             extra: allowed?.deny ?? [], linked: linkedFor(store, worktree), writes: allowed === null ? null : { writes: allowed.writes, readOnly: allowed.readOnly }, policy: sandbox.policy, provider,
-            // This launch's code map file: exactly that file, read-only, inside the denied state folder. Commands don't get it.
             ...(provider === "command" ? {} : { exactFile: deliveredFile(store, runId) }),
-            // The sealed read denies, and whatever the project lists now too (adding a deny only narrows).
             readDeny: [...new Set([...sandbox.readDeny, ...(row === null ? [] : store.projectSandbox(row.repo).readDeny)])].map(one => readDenyPath(one, keyHome ?? homedir())), machLookup: sandbox.machLookup });
         return {
             fence: launch.fence,
             fileTools: boundary?.fileTools ?? [],
             grants: launch.fenceGrants,
-            // The checkout's own Git data (a sign-ins check's network keeps it reachable).
             gitPaths: binding === null ? [] : [binding.gitdir, join(binding.main, ".git")],
             ...(allowed === null || row === null ? {} : { cache: buildCacheFolder(row.repo, keyHome ?? homedir()) }),
         };
     }
     catch (error) {
-        // The storage check's own words: what didn't finish, and which program macOS may need to allow.
         const refused = storageRefusalOf(error);
         if (refused !== null)
             return { fence: [], fileTools: [], grants: NO_GRANTS, problem: refused.message, storageRefused: true };
         return { fence: [], fileTools: [], grants: NO_GRANTS, problem: error instanceof CheckoutBindingError ? error.message : "The build fence could not be prepared." };
     }
 }
-/**
- * A build's setup and check commands, run in its fence (arc 2): the same denies as its agent's (Toolroll's state,
- * credentials, other projects and runs), its write allowlist when its approval sealed one (its checkout and Git data,
- * its project's caches, and a temp folder of the command's own), and its package managers pointed at those caches.
- * Their network stays as it was. A machine without an OS fence runs them as before; a fence that can't be prepared
- * (a checkout whose binding no longer proves) runs nothing.
- */
 export function fencedCommands(store, runId, writes, inner, available = () => macosFenceAvailable() || linuxFenceAvailable(), access = CHECK_ACCESS_DEFAULT, network, sandbox = LEGACY_SANDBOX) {
-    // An injected runner (tests) starts no real command, as an injected agent starts no real agent (invokeAgent).
     if (inner !== runCommand)
         return inner;
     return async (file, args, options) => {
-        // As a build itself: where nothing can confine them, they run only when an instance operator allowed unconfined agents
-        // (and the run says so: its checks ran without a sandbox, whatever was sealed).
         if (!available()) {
             if (store.unfencedAgentsAllowed()) {
                 store.stampRunCheckAccess(runId, "unsandboxed");
@@ -1055,8 +761,6 @@ export function fencedCommands(store, runId, writes, inner, available = () => ma
         try {
             const temp = join(own, "tmp");
             mkdirSync(temp, { mode: 0o700 });
-            // Not sandboxed (check-access.ts): the project's checks are trusted by the whole instance, as before 0.9.66. Never
-            // while local mode is on (easy-start C5): then they run in the fence, sandboxed.
             if (access === "unsandboxed" && !localModeOn(store)) {
                 stampLaunch(store, [runId], unfencedStamp());
                 return await inner(file, args, { ...options, env: { ...(options?.env ?? {}), TMPDIR: temp, TMP: temp, TEMP: temp } });
@@ -1068,7 +772,6 @@ export function fencedCommands(store, runId, writes, inner, available = () => ma
                 stampLaunch(store, [runId], unfencedStamp());
                 return inner(file, args, options);
             }
-            // A self-hosted check's own database (child-database.ts) is the command's to write too.
             const database = options?.env?.["TOOLROLL_DB"];
             const checkData = database === undefined || fenced.grants.writes === undefined ? null : grantFolder(dirname(database), false);
             const grants = checkData === null ? fenced.grants : { ...fenced.grants, writes: { ...fenced.grants.writes, subpaths: [...fenced.grants.writes.subpaths, checkData] } };
@@ -1079,8 +782,6 @@ export function fencedCommands(store, runId, writes, inner, available = () => ma
             if (signIns !== null && "problem" in signIns)
                 return { code: 1, stdout: "", stderr: `${signIns.problem}\n`, timedOut: false, notFound: false };
             try {
-                // Each sign-in file looked at again right before the launch: one no longer itself isn't granted.
-                // Never the keychain: the sign-ins kept there come in the environment, read outside (keychainSignIns).
                 const given = signIns === null ? grants : { ...grants, signIns: { ...signIns.grants, read: signIns.grants.read.filter(path => signInIsItself(realpathSync(homedir()), path)) }, network: signIns.network };
                 stampLaunch(store, [runId], fencedStamp(signIns === null ? "sandboxed" : "sign-ins", fenced.fence, given, signIns === null ? undefined : network));
                 return await inner(file, args, {
@@ -1101,12 +802,6 @@ export function fencedCommands(store, runId, writes, inner, available = () => ma
         }
     };
 }
-/**
- * A project's checks run in a checkout of a result's commit made for them (result-follow-ups.ts, batch-checks.ts), in
- * the same fence as a build's commands: Toolroll's state, credentials, other projects and runs denied; under the
- * project's writes setting, only that checkout, its Git data, its own temp folder, the project's caches and its check
- * database writable. Where nothing can confine them, they run only when an instance operator allowed unconfined agents.
- */
 export function fencedCheckoutCommands(store, repo, checkout, inner, available = () => macosFenceAvailable() || linuxFenceAvailable(), access = CHECK_ACCESS_DEFAULT, network, sandbox = LEGACY_SANDBOX, stampRuns = []) {
     if (inner !== runCommand)
         return inner;
@@ -1127,8 +822,6 @@ export function fencedCheckoutCommands(store, repo, checkout, inner, available =
         try {
             const temp = join(own, "tmp");
             mkdirSync(temp, { mode: 0o700 });
-            // Not sandboxed (check-access.ts): the project's checks are trusted by the whole instance, as before 0.9.66. Never
-            // while local mode is on (easy-start C5): then they run in the fence, sandboxed.
             if (access === "unsandboxed" && !localModeOn(store)) {
                 stampLaunch(store, stampRuns, unfencedStamp());
                 return await inner(file, args, { ...options, env: { ...(options?.env ?? {}), TMPDIR: temp, TMP: temp, TEMP: temp } });
@@ -1158,15 +851,11 @@ export function fencedCheckoutCommands(store, repo, checkout, inner, available =
                 readDeny: sandbox.readDeny.map(one => readDenyPath(one, homedir())), machLookup: sandbox.machLookup, policy: sandbox.policy,
                 writes: allowed === null ? null : { writes: { ...allowed.writes, subpaths: [...allowed.writes.subpaths, ...(checkData === null ? [] : [checkData])] }, readOnly: allowed.readOnly } });
             const grants = launch.fenceGrants;
-            // With sign-ins, under the network its caller proved for it (the narrowest of its results' sealed check networks and
-            // the project's current one): none given, nothing runs.
             const signIns = access !== "sign-ins" ? null : network === undefined ? { problem: "A check with sign-ins has no network sealed for it, so nothing ran." }
                 : await signInsLaunch(store, own, temp, checkout, network, [binding.gitdir, join(binding.main, ".git")]);
             if (signIns !== null && "problem" in signIns)
                 return { code: 1, stdout: "", stderr: `${signIns.problem}\n`, timedOut: false, notFound: false };
             try {
-                // Each sign-in file looked at again right before the launch: one no longer itself isn't granted.
-                // Never the keychain: the sign-ins kept there come in the environment, read outside (keychainSignIns).
                 const given = signIns === null ? grants : { ...grants, signIns: { ...signIns.grants, read: signIns.grants.read.filter(path => signInIsItself(realpathSync(homedir()), path)) }, network: signIns.network };
                 stampLaunch(store, stampRuns, fencedStamp(signIns === null ? "sandboxed" : "sign-ins", launch.fence, given, signIns === null ? undefined : network));
                 return await inner(file, args, {
@@ -1187,13 +876,10 @@ export function fencedCheckoutCommands(store, repo, checkout, inner, available =
         }
     };
 }
-/** What a build writes that a tool server must never run from: its checkout and its project's caches. A checkout with
- * no record never gets this far: its fence refuses the launch (runFence) before any tool server can start. */
 function toolUntrusted(store, workspace, keyHome) {
     const row = store.getWorktree(workspace);
     return [workspace, ...(row === null ? [] : [buildCacheFolder(row.repo, keyHome ?? homedir())])];
 }
-/** The operator's own model choices a build routed with no model keeps (provider-home.ts). */
 function inheritedDefaults(provider, env, home) {
     if (provider === "claude")
         return claudeDefaults(claudeConfigDir(env, home));
@@ -1201,15 +887,10 @@ function inheritedDefaults(provider, env, home) {
         return codexDefaults(codexHomeDir(env, home));
     return undefined;
 }
-/** How the fence reaches a provider: Codex through its own sandbox profile
- * (already in its argv; wrapping it would nest sandboxes), Claude and
- * Gemini inside the macOS sandbox the spawn road applies (`wrap`), Claude
- * elsewhere through its own file-tool rules only. */
 function fenceLaunch(provider, fence) {
     const method = fenceMethod(provider, fence.length > 0);
     return { wrap: method === "macos-sandbox" || method === "linux-bubblewrap" ? fence : [], method };
 }
-/** The fence a launch gets, from its provider, whether it has anything to fence, and what this platform supports. */
 function fenceMethod(provider, fenced) {
     if (!fenced)
         return "none";
@@ -1221,39 +902,20 @@ function fenceMethod(provider, fenced) {
         return "linux-bubblewrap";
     return provider === "claude" ? "claude-rules" : "none";
 }
-/** One launch's tools, or — when they cannot be prepared — the same isolation with none, never the operator's global servers. */
 async function runTools(store, runId, spec, keyHome, clock, readOnly, withheld, containment, broker) {
     try {
         return await prepareRunTools(store, runId, spec.provider, { ...(keyHome === undefined ? {} : { home: keyHome }), now: clock(), containment, ...(readOnly === undefined ? {} : { readOnly }), ...(withheld === undefined ? {} : { withheld }), broker });
     }
     catch (error) {
-        // Sign-ins made for this run couldn't all be kept (and were revoked): it doesn't start.
         if (error instanceof RunSignInError)
             return { refused: error.message };
         return noToolsArgs(spec.provider);
     }
 }
-/** The lines of a harness's stdout that are not JSON events. */
 function plainLines(stdout) {
     return stdout.split("\n").filter(line => !line.trimStart().startsWith("{")).join("\n");
 }
-/** What a `sign-ins` check never inherits: a caller's choice of Claude's config folder (Claude's keychain sign-in is
- * keyed to its default one; check-access.ts). gh's and Codex's are set to the granted ones instead. */
 const SIGN_INS_OMITTED_ENV = ["CLAUDE_CONFIG_DIR"];
-/**
- * A `sign-ins` check's launch (check-access.ts, sandbox parity C10): its exact sign-in files, read by the check itself
- * through its sandbox (agent-fence.ts signInGrants: nothing privileged reads or copies one), its own transcript folder
- * and Codex's session and log folders; Codex, gh and XDG pointed at the real folders; and the network the check runs
- * under: open, or its allowlist through a proxy of its own (on Linux, relayed in by the sandbox runtime). Nothing about it is
- * started unless all of it is.
- */
-/**
- * macOS: the sign-ins a check with sign-ins needs that live in the keychain, not in files: Claude Code's
- * ("Claude Code-credentials", its current access token as CLAUDE_CODE_OAUTH_TOKEN) and gh's ("gh:github.com", as
- * GH_TOKEN). Read here, by Toolroll, outside the sandbox, and handed to the check in its environment, so the check never
- * reaches securityd (sandbox-runtime.ts SEATBELT_NO_KEYCHAIN) and nothing else in the keychain. The check can't renew
- * Claude's token: one that has expired fails its sign-in. A value that isn't a plain token is left out.
- */
 export const KEYCHAIN_SIGN_INS = [
     { service: "Claude Code-credentials", env: "CLAUDE_CODE_OAUTH_TOKEN", token: secret => {
             try {
@@ -1264,18 +926,13 @@ export const KEYCHAIN_SIGN_INS = [
                 return null;
             }
         } },
-    // go-keyring (gh's) may keep it base64-encoded behind a prefix.
     { service: "gh:github.com", env: "GH_TOKEN", token: secret => secret.startsWith("go-keyring-base64:") ? Buffer.from(secret.slice("go-keyring-base64:".length), "base64").toString("utf8") : secret },
 ];
 const PLAIN_TOKEN = /^[A-Za-z0-9._~+/=-]{8,4096}$/;
-/** One keychain item's secret by its service, read with the system's `security` (null: none, or it can't be read). A
- * keychain file may be named (tests: a throwaway one); never the item's value in an argument. */
 export function readKeychainSecret(service, keychain) {
     const read = spawnSync("/usr/bin/security", ["find-generic-password", "-s", service, "-w", ...keychain === undefined ? [] : [keychain]], { encoding: "utf8", timeout: 10_000, env: { PATH: "/usr/bin:/bin", HOME: homedir() }, stdio: ["ignore", "pipe", "ignore"] });
     return read.status === 0 && typeof read.stdout === "string" ? read.stdout.replace(/\n$/, "") : null;
 }
-/** The keychain's sign-ins as a check's environment (macOS only; elsewhere, for anything missing, and where Toolroll
- * keeps nothing in the keychain (TOOLROLL_SECRET_STORE=files: the test suite), nothing). */
 export function keychainSignIns(platform = process.platform, read) {
     if (platform !== "darwin")
         return {};
@@ -1302,8 +959,6 @@ export async function signInsLaunch(store, own, temp, checkout, policy, gitPaths
         const env = { CODEX_HOME: join(home, ".codex"), GH_CONFIG_DIR: join(home, ".config", "gh"), XDG_CONFIG_HOME: join(home, ".config"), ...keychain() };
         if (policy.mode === "open")
             return { grants, network: { mode: "open" }, env, close };
-        // Exactly the project's network: the services the sign-ins are for are reached only if the operator allowed their
-        // hosts (check-access.ts signInHostsMissing says which are missing; never added here).
         egress = await startEgressProxy({ hosts: policy.hosts });
         const network = { mode: "allowlist", proxyPort: egress.port, brokerPorts: [], loopback: policy.loopback, socketRoots: [temp, realpathSync(checkout)], token: egress.secret };
         return { grants, network, env: { ...env, ...proxyEnv(egress, policy.loopback) }, close };
@@ -1313,21 +968,11 @@ export async function signInsLaunch(store, own, temp, checkout, policy, gitPaths
         return { problem: `The check's network could not be set up, so nothing ran: ${error instanceof Error ? error.message : String(error)}` };
     }
 }
-/** How a check at `access` actually runs here: unsandboxed where no OS fence exists (and an operator allowed that), else
- * as asked. Recorded on every check's receipt, so a check that ran without a sandbox is never shown as sandboxed. */
 export function actualCheckAccess(store, access) {
     return macosFenceAvailable() || linuxFenceAvailable() || !store.unfencedAgentsAllowed() ? access : "unsandboxed";
 }
-/**
- * A check of saved results, in their own checkout (batch-checks.ts, result-follow-ups.ts), worked out right before each
- * command: never wider than any of those results' own checks ran, nor than the project allows now; under sign-ins, the
- * narrowest of their sealed check networks and the project's current one. A result with no sealed network runs it
- * sandboxed.
- */
 export function checkoutLaunchOf(store, repo, runIds, platform = process.platform) {
-    // As checks can get it: sign-ins (off for now; a stamp or setting from before, or another database) run sandboxed.
     const asked = checkAccessHere(narrowestAccess([store.projectCheckAccess(repo), ...runIds.map(id => store.runCheckAccess(id))]), platform);
-    // Easy-start C5: while local mode is on, never unsandboxed (re-read here, at launch).
     const access = localModeOn(store) ? localModeCap(asked) : asked;
     if (access !== "sign-ins")
         return { access, network: undefined };
@@ -1337,13 +982,9 @@ export function checkoutLaunchOf(store, repo, runIds, platform = process.platfor
     const live = resolveNetwork("command", store.projectNetwork(repo), repositoryEcosystems(repo));
     return { access, network: sealed.reduce((low, one) => narrowestNetwork(low, one), live) };
 }
-/** The widest level a check's commands actually ran at (what its receipt says). */
 export const widestRan = (levels) => levels.includes("unsandboxed") ? "unsandboxed" : levels.includes("sign-ins") ? "sign-ins" : CHECK_ACCESS_DEFAULT;
-/** A check log's line for how its commands ran, when wider than sandboxed (shown with the log). */
 export const ranAtLine = (level) => level === "sandboxed" ? null
     : `=== Check access ===\n${level === "unsandboxed" ? "These commands ran without a sandbox." : "These commands ran sandboxed, with model and GitHub sign-ins."}`;
-/** A saved result's check command runner (batch-checks.ts, result-follow-ups.ts): its level and network worked out right
- * now (checkoutLaunchOf), and how it actually runs told to `ran`. */
 export function checkoutRunner(store, repo, checkout, inner, runIds, ran, platform = process.platform) {
     return (file, args, options) => {
         const launch = checkoutLaunchOf(store, repo, runIds, platform);
@@ -1351,12 +992,6 @@ export function checkoutRunner(store, repo, checkout, inner, runIds, ran, platfo
         return fencedCheckoutCommands(store, repo, checkout, inner, undefined, launch.access, launch.network, checkoutSandboxOf(store, repo, runIds), runIds)(file, args, options);
     };
 }
-/**
- * A saved result's checks' sandbox terms (sandbox parity C9), never wider than any of those results' own approvals nor
- * the project now: v2 only when every result's approval sealed v2; every read deny any of them sealed or the project
- * lists now; mach services only those all of them sealed and the project still lists. A result with
- * no readable approval counts as v1 with nothing listed.
- */
 export function checkoutSandboxOf(store, repo, runIds) {
     const sealed = runIds.map(id => {
         const taskRef = store.getRun(id)?.taskRef;
@@ -1372,8 +1007,6 @@ export function checkoutSandboxOf(store, repo, runIds) {
         machLookup: common(one => one.machLookup, live.machLookup),
     };
 }
-/** A fenced launch's stamp: the level it runs at and exactly what it was given (check-stamp.ts), read from the grants the
- * launch itself takes, never from what was asked for. */
 export function fencedStamp(level, fence, grants, network) {
     const writes = grants.writes;
     return {
@@ -1388,15 +1021,9 @@ function stampLaunch(store, runs, stamp) {
     for (const runId of runs)
         recordCheckStamp(store, runId, stamp, now);
 }
-/** The digest of a launch's whole fence (its denied paths and grants, canonical), as stamped on its run (C11). */
 export function fenceDigest(fence, grants) {
     return createHash("sha256").update(`toolroll:fence:${canonicalJson({ fence: [...fence], grants: grants })}`).digest("hex").slice(0, 32);
 }
-/**
- * One stream event's billing observation: the key source and model from the session's own init, plan windows from a
- * rate-limit event, and whether the main query answered. The session's own events only (stream-scope.ts): a
- * subagent's init, rate-limit event or result says nothing about this turn's billing.
- */
 export function observeClaudeBilling(seen, event) {
     if (event["type"] === "system" && event["subtype"] === "init" && topLevelEvent(event)) {
         if (typeof event["apiKeySource"] === "string")
@@ -1411,12 +1038,6 @@ export function observeClaudeBilling(seen, event) {
         seen.answered = true;
     }
 }
-/**
- * What decides a child's credential: the environment it starts from (the plane's, then the caller's) and every variable
- * it sheds. Subscription: this provider's own keys too, so an ambient key can't force API billing over the login.
- * API key: every other own-key alias, so a stray one can't override the one key injected. Foreign keys and (for a
- * Claude build) plugin variables always. The live plan proof and the launch both use this one answer.
- */
 export function childAuthEnv(args) {
     const env = { ...process.env, ...(args.runEnv ?? {}) };
     return {
@@ -1424,7 +1045,6 @@ export function childAuthEnv(args) {
         omitEnv: [
             ...(args.runOmitEnv ?? []),
             ...args.extraOmitEnv,
-            // A Claude build loads no plugin, from settings or the environment (a review's safe mode already loads none).
             ...(args.provider === "claude" && args.phase !== "review" ? claudePluginEnv(env) : []),
             ...(args.authMode === "subscription" ? args.ownKeyEnv : args.ownKeyEnv.filter(name => name !== args.keyEnvName)),
         ],