toolroll 0.9.104 → 0.9.105

package/dist/exec.js

@@ -1,11 +1,3 @@
-/**
- * Running external commands.
- *
- * Two rules define this module. Arguments are passed as an array and never
- * through a shell, so a directory named `; rm -rf ~` is a string and not a
- * command. And nothing here rejects: a failed command is a value. Discovery
- * walks repos it has never seen, and one broken repo must not end the scan.
- */
 import { ACP_LINE_CAP, createAcpConversation } from "./acp-client.js";
 import { linuxFenceAvailable, macosFenceAvailable, sandboxedSpawn } from "./agent-fence.js";
 import { withoutProtectedEnv } from "./protected-storage.js";
@@ -17,15 +9,9 @@ import { createContainer, currentContainment } from "./containment.js";
 import { claudeLimitsOf, noteLimits } from "./provider-limits.js";
 import { sleep as defaultSleep } from "./sleep.js";
 import { primaryResultEvent, topLevelEvent } from "./stream-scope.js";
-/** Shell convention for "could not be executed": the refusal before any target ran. */
 export const CONTAINMENT_REFUSED_CODE = 126;
-/** Live provider children, for the deterministic stop. Registered only when `processGroup` was set. */
 const liveProviders = new Set();
-/** Children this process's own hard stop ended: their results say so (`stoppedByPlane`). */
 const hardStopped = new WeakSet();
-/** Live children by owner tag (v52): the exact-attempt stop's handle. A
- * child is registered here beside liveProviders when its options named an
- * owner, and dropped the moment it closes. */
 const ownedChildren = new Map();
 function registerOwned(owner, child) {
     if (owner === undefined)
@@ -45,22 +31,12 @@ function registerOwned(owner, child) {
             ownedChildren.delete(owner);
     });
 }
-/** The native OS object behind a live child, when it has one. */
 const containers = new WeakMap();
-/** Thrown BEFORE any spawn when required containment cannot be had. */
 export class ContainmentRefusal extends Error {
     name = "ContainmentRefusal";
 }
-/**
- * The command as it runs inside the agent fence (Anthropic's sandbox-runtime wrapping it: agent-fence.ts
- * sandboxedSpawn), with the environment that needs beside the caller's, or as it is when it has no fence. A spawn whose
- * confinement is required and that no sandbox here can wrap is refused (ContainmentRefusal): nothing runs, and nothing
- * falls back to running it unwrapped.
- */
 export function confined(file, args, bag) {
     const fence = bag.fence ?? [];
-    // A fence is only ever made by fenceFor (agent-fence.ts), which marks it required: one without the mark was put
-    // together some other way, and would run bare wherever no OS fence applies. Nothing runs.
     if (fence.length > 0 && bag.confinement !== "required")
         throw new ContainmentRefusal("This process was given a fence that isn't marked required, so it was not started.");
     if (fence.length > 0 && (macosFenceAvailable() || linuxFenceAvailable())) {
@@ -78,15 +54,11 @@ export function confined(file, args, bag) {
     }
     return { file, args: [...args], env: {} };
 }
-/** A spawn's environment with what its sandbox needs added (nothing added: the caller's, as it was). */
 export function withSandboxEnv(env, added, fenced = false) {
-    // A fenced launch never gets a chat or vault variable (protected-storage.ts), whoever made its environment.
     if (fenced)
         return withoutProtectedEnv({ ...(env ?? process.env), ...added });
     return Object.keys(added).length === 0 ? env : { ...(env ?? process.env), ...added };
 }
-/** A spawn callback refused custody AFTER the child existed: the caller
- * must reap exactly this child before answering. */
 class SpawnCustodyFailure extends Error {
     child;
     reason;
@@ -97,37 +69,22 @@ class SpawnCustodyFailure extends Error {
         this.reason = reason;
     }
 }
-/** The child a failed spawn road left behind, if any. */
 function rejectedChild(error, child) {
     return error instanceof SpawnCustodyFailure ? error.child : child;
 }
-/**
- * The ONE spawn road for containable children (buffered and streaming
- * transports): consult the pinned policy, make this spawn's OS
- * object, spawn the target INSIDE it, and register the object beside the
- * handle. Under observed containment this is exactly the old spawn. A
- * required policy that cannot be met throws ContainmentRefusal here —
- * nothing has been spawned, so the caller's reap is a no-op and its
- * result says `refused` in the policy's words.
- */
 function spawnContained(file, args, spawnOptions, label, bag, contain = true) {
-    // The agent fence wraps the target itself (sandbox-exec then execs it, same pid).
     const sandboxed = confined(file, args, { ...bag, cwd: spawnOptions.cwd, temp: spawnOptions.env?.["TMPDIR"] });
     ({ file, args } = sandboxed);
     spawnOptions = { ...spawnOptions, env: withSandboxEnv(spawnOptions.env, sandboxed.env, (bag.fence?.length ?? 0) > 0) };
-    // The policy refusal comes first: nothing is reserved, recorded or
-    // spawned for a spawn that cannot be contained as required.
     const effective = contain ? currentContainment() : null;
     if (effective !== null && effective.refusal !== null)
         throw new ContainmentRefusal(effective.refusal);
     if (bag.beforeSpawn?.() === false)
         throw new Error("the attempt stopped before this process could spawn");
-    // From here a witness may be reserved: every road that makes no process
-    // says so through onSpawnFailed before it returns or throws.
     const neverStarted = () => { try {
         bag.onSpawnFailed?.();
     }
-    catch { /* the reservation stays unproven */ } };
+    catch { } };
     let made;
     try {
         made = effective === null ? { container: null } : createContainer(effective, label);
@@ -171,7 +128,6 @@ function spawnContained(file, args, spawnOptions, label, bag, contain = true) {
         });
     }
     catch (error) {
-        // The OS spawn itself threw: this invocation made no target process.
         try {
             if (container !== null)
                 bag.onContainerEmpty?.();
@@ -183,8 +139,6 @@ function spawnContained(file, args, spawnOptions, label, bag, contain = true) {
     }
     if (container !== null) {
         containers.set(child, container);
-        // A descendant may keep stdout/stderr open after the root exits. Begin
-        // cleanup at root exit; waiting for `close` would wait for that descendant.
         child.once("exit", () => {
             void settleContainer(container, bag).then(empty => {
                 if (!empty) {
@@ -200,9 +154,6 @@ function spawnContained(file, args, spawnOptions, label, bag, contain = true) {
             bag.onSpawn?.(child.pid);
         }
         else if (container === null) {
-            // No pid: the OS refused the spawn (ENOENT, EACCES) and only an
-            // 'error' event follows. A contained spawn settles once its object is
-            // proven empty, and its transport's return finishes the witness.
             neverStarted();
         }
     }
@@ -212,13 +163,6 @@ function spawnContained(file, args, spawnOptions, label, bag, contain = true) {
     const attached = launch === null || child.pid === undefined ? Promise.resolve({ ok: true }) : launch.attach(child);
     return { child, container, attached };
 }
-/**
- * The settlement every containable transport runs at the root's exit:
- * members that outlived the root (a setsid'd helper, a double fork) are
- * killed and the OS asked for its empty state, bounded. The answer is
- * the proof the custody record keeps — `false` leaves the record
- * unproven and every stop/resume fence closed.
- */
 const containerSettlements = new WeakMap();
 function settleContainer(container, bag, timeoutMs = 5_000) {
     const existing = containerSettlements.get(container);
@@ -244,16 +188,14 @@ async function finishContainer(container, bag, timeoutMs) {
             bag.onUnknown?.();
     }
     catch {
-        // Custody that cannot be written stays unproven; the fences hold.
         empty = false;
     }
     try {
         container.release();
     }
-    catch { /* proof already determines the result */ }
+    catch { }
     return empty;
 }
-/** The result's containment field for a spawn that ran inside an object. */
 function containmentOf(container, empty, attachFailure) {
     if (attachFailure !== null)
         return { containment: { refused: attachFailure } };
@@ -261,11 +203,9 @@ function containmentOf(container, empty, attachFailure) {
         return {};
     return { containment: { backend: container.backend, id: container.id, empty } };
 }
-/** The streaming transports' spawn: contained when the spawn is a provider (process group), plain otherwise. */
 function spawnStream(file, args, options, stdio, childEnv) {
     return spawnContained(file, args, { cwd: options.cwd, env: childEnv, stdio, detached: options.processGroup === true && process.platform !== "win32" }, options.owner ?? "stream", { beforeSpawn: options.beforeSpawn, onSpawn: options.onSpawn, onSpawnFailed: options.onSpawnFailed, onContainer: options.onContainer, onContainerEmpty: options.onContainerEmpty, onUnknown: options.onUnknown, fence: options.fence, fenceGrants: options.fenceGrants, confinement: options.confinement }, options.processGroup === true);
 }
-/** The refusal-before-spawn shape shared by every containable transport. */
 function refusedResult(error) {
     if (error instanceof ContainmentRefusal) {
         return { code: CONTAINMENT_REFUSED_CODE, stdout: "", stderr: error.message, timedOut: false, notFound: false, containment: { refused: error.message } };
@@ -274,8 +214,6 @@ function refusedResult(error) {
 }
 const databaseOwners = new WeakMap();
 let memoryDatabaseOwner = 0;
-/** Run IDs are local to a database. Connections to the same file share
- * custody; separate files and separate in-memory databases never do. */
 export function runOwnerTag(store, runId) {
     let owner = databaseOwners.get(store.handle);
     if (owner === undefined) {
@@ -286,19 +224,9 @@ export function runOwnerTag(store, runId) {
     }
     return JSON.stringify([owner, runId]);
 }
-/** How many live children this process still tracks under an owner tag. */
-// Zero is local to this process registry. Recovery must also inspect durable
-// witnesses and its authenticated OS census; this count is not an absence proof.
 export function ownedProcessCount(owner) {
     return ownedChildren.get(owner)?.size ?? 0;
 }
-/**
- * The exact-attempt stop (v52): SIGKILL the process group of every live
- * child registered under the owner tag — and only those. Returns how many
- * were signalled. Idempotent: a child already gone was dropped at close,
- * and a tag nobody registered kills nothing. This is the ONLY kill road a
- * task action may take; the global sweep below is the watch's shutdown.
- */
 export function terminateOwnedProcesses(owner) {
     const owned = ownedChildren.get(owner);
     if (owned === undefined)
@@ -312,22 +240,15 @@ export function terminateOwnedProcesses(owner) {
     }
     return terminated;
 }
-/** SIGKILL the child's whole process group; fall back to the child alone. */
 function killGroup(child) {
     const container = containers.get(child);
     if (container !== undefined) {
-        // The OS object reaches every member at once — detached helpers
-        // included — and its empty state is awaited by the transport's
-        // settlement, never assumed here.
         void container.kill().catch(() => { });
-        // The Windows helper is the job's owner and reporter: it terminates the
-        // job on the order above and answers "empty"; killing it instead would
-        // close the handle (kill-on-close still ends the job) but lose the proof.
         if (container.backend !== "job-object") {
             try {
                 child.kill("SIGKILL");
             }
-            catch { /* already gone */ }
+            catch { }
         }
         return;
     }
@@ -335,15 +256,10 @@ function killGroup(child) {
         return;
     const pid = child.pid;
     if (pid !== undefined && process.platform === "win32") {
-        // Windows has no process groups to signal (Codex M5-M8 audit, IV-6):
-        // taskkill /T walks the tree, so a harness's shell grandchildren die
-        // with it instead of writing to the worktree after "stopped". Untested
-        // on physical Windows, like the daemon — stated, not hidden.
         try {
             spawn("taskkill", ["/PID", String(pid), "/T", "/F"], { stdio: "ignore", windowsHide: true }).on("error", () => { });
         }
         catch {
-            // taskkill missing or refused — the direct kill below still runs.
         }
     }
     if (pid !== undefined && process.platform !== "win32") {
@@ -352,23 +268,14 @@ function killGroup(child) {
             return;
         }
         catch {
-            // No group of ours (not detached, or already gone) — fall through.
         }
     }
     try {
         child.kill("SIGKILL");
     }
     catch {
-        // Already gone.
     }
 }
-/**
- * The hard stop (M6.12): SIGKILL every live provider's process group.
- * Called by the watch when its stop grace expires — never on the first
- * signal, which stays graceful. Late output cannot commit or publish:
- * the killed process exits nonzero, the build finalizes as the failure
- * it is, and every commit sits behind fences the corpse cannot pass.
- */
 export function terminateLiveProviders() {
     let terminated = 0;
     for (const child of liveProviders) {
@@ -378,16 +285,6 @@ export function terminateLiveProviders() {
     }
     return terminated;
 }
-/** The one place a child's environment is decided (audit IV-5). */
-/**
- * Chat credentials never reach a child process (Codex chat v3 review,
- * change 10): ANTHROPIC_API_KEY is the chat key AND would silently flip
- * the claude harness from subscription auth to API billing if inherited.
- * A caller that genuinely needs it re-supplies it via `env` explicitly.
- * (OPENROUTER_API_KEY is not listed: the openrouter BUILD adapter reads
- * it from the child env by design, and the agent-facing shell excludes
- * it separately via the provider's own config.)
- */
 const CHAT_KEYS_NEVER_INHERITED = ["ANTHROPIC_API_KEY"];
 function resolveChildEnv(options) {
     const { env, omitEnv, envAllowlist } = options;
@@ -416,13 +313,8 @@ function resolveChildEnv(options) {
     }
     return merged;
 }
-/** Conventions from the shell and from coreutils `timeout(1)`. */
 export const NOT_FOUND_CODE = 127;
 export const TIMEOUT_CODE = 124;
-/** Output too large to hold. Not a timeout, and must not be reported as one. */
-/** A spawn callback records custody after the child exists. If that write
- * fails, stop and reap the owned child before reporting failure; otherwise
- * an unrecorded provider could keep writing after its caller retries. */
 function reapRejectedSpawn(child, group) {
     if (child === undefined)
         return Promise.resolve();
@@ -446,24 +338,14 @@ function reapRejectedSpawn(child, group) {
             try {
                 child.kill("SIGKILL");
             }
-            catch { /* The child must still exit before failure is returned. */ }
+            catch { }
         }
     });
 }
 export const OVERFLOW_CODE = 125;
 export const DEFAULT_TIMEOUT_MS = 15_000;
 export const DEFAULT_MAX_BUFFER = 8 * 1024 * 1024;
-/**
- * A streaming process may run for hours while it is making observable
- * progress. This controller keeps the ordinary hard timeout available for
- * bounded work, while allowing provider callers to choose an activity-based
- * watchdog with no wall-clock deadline. Both roads share the same kill and
- * settlement semantics.
- */
-function streamWatchdog(options, onTimeout, 
-/** The idle limit was reached: true when the caller ended the wait its own way (a paused live session closes
- * stdin), so the same limit runs again for the process to exit before it is killed. */
-onIdle) {
+function streamWatchdog(options, onTimeout, onIdle) {
     const hardMs = options.timeoutMs ?? (options.idleTimeoutMs === undefined ? DEFAULT_TIMEOUT_MS : undefined);
     const idleMs = options.idleTimeoutMs;
     let fired = false;
@@ -512,25 +394,11 @@ onIdle) {
     };
 }
 const MAX_BUFFER_ERROR = "ERR_CHILD_PROCESS_STDIO_MAXBUFFER";
-/**
- * A spawn the OS refused for the moment — no free process slot or file
- * descriptor (a loaded machine, a fork storm from a parallel test suite) —
- * is not the command failing: the command never ran. Left as an exit 1, a
- * `git symbolic-ref` that never started reads as "no branch checked out"
- * and an unattended pass refuses on a lie. So the two buffered transports
- * retry EXACTLY this class, bounded, before answering.
- */
 const TRANSIENT_SPAWN_CODES = new Set(["EAGAIN", "EMFILE", "ENFILE"]);
 export const SPAWN_RETRY_DELAYS_MS = [50, 100, 200, 400, 800];
 export function isTransientSpawnFailure(error) {
     return error !== null && error !== undefined && typeof error.code === "string" && TRANSIENT_SPAWN_CODES.has(error.code);
 }
-/**
- * Retry `attempt` while it reports a transient spawn failure, sleeping the
- * given delays between tries; the last answer stands when they run out.
- * A non-transient answer — success, a real exit code, not found, timeout —
- * is returned at once: only the never-started case is retried.
- */
 export async function retryTransientSpawn(attempt, delays = SPAWN_RETRY_DELAYS_MS, sleep = defaultSleep) {
     let last = await attempt();
     for (const delay of delays) {
@@ -544,8 +412,6 @@ export async function retryTransientSpawn(attempt, delays = SPAWN_RETRY_DELAYS_M
 export function run(file, args, options = {}) {
     const { cwd, timeoutMs = DEFAULT_TIMEOUT_MS, maxBuffer = DEFAULT_MAX_BUFFER } = options;
     const childEnv = resolveChildEnv(options);
-    // A provider run needs its own process group; execFile cannot give one,
-    // so the buffered path detours through spawn with identical semantics.
     if (options.processGroup === true) {
         return retryTransientSpawn(() => runBufferedGroup(file, args, {
             timeoutMs,
@@ -572,8 +438,6 @@ export function run(file, args, options = {}) {
             ...(options.onContainerEmpty === undefined ? {} : { onContainerEmpty: options.onContainerEmpty }),
         }));
     }
-    // The plain road wraps exactly as the process-group road does: a fence given here is never dropped, and a spawn
-    // whose confinement is required and can't be wrapped refuses before anything runs.
     let wrapped;
     try {
         wrapped = confined(file, args, { ...options, cwd, temp: childEnv?.["TMPDIR"] });
@@ -584,8 +448,6 @@ export function run(file, args, options = {}) {
         return Promise.resolve({ code: CONTAINMENT_REFUSED_CODE, stdout: "", stderr: error.message, timedOut: false, notFound: false, containment: { refused: error.message } });
     }
     return retryTransientSpawn(() => new Promise(resolve => {
-        // execFile's timeout sends SIGTERM and nothing more: a process that survives it (one that ignores or blocks
-        // it) never exits, and its caller would wait forever. SIGKILL follows a short grace later.
         let hardKill;
         const child = execFile(wrapped.file, wrapped.args, {
             cwd,
@@ -611,19 +473,12 @@ export function run(file, args, options = {}) {
             hardKill = setTimeout(() => { try {
                 child.kill("SIGKILL");
             }
-            catch { /* gone */ } }, timeoutMs + TERM_GRACE_MS);
+            catch { } }, timeoutMs + TERM_GRACE_MS);
             hardKill.unref?.();
         }
     }));
 }
-/** How long a timed-out plain command has to exit after SIGTERM before it is killed outright. */
 export const TERM_GRACE_MS = 2_000;
-/**
- * The buffered transport for process-group providers (claude): spawn
- * detached so the harness and everything it launches share one killable
- * group, collect output up to the same maxBuffer contract as execFile,
- * and register as a live provider for the watch's hard stop.
- */
 function runBufferedGroup(file, args, bag) {
     return new Promise(resolve => {
         let child;
@@ -662,7 +517,6 @@ function runBufferedGroup(file, args, bag) {
             timedOut = true;
             killGroup(child);
         }, bag.timeoutMs);
-        // The caller's deadline, when it owns one: the same group kill as the timer.
         const aborted = () => {
             timedOut = true;
             killGroup(child);
@@ -681,7 +535,7 @@ function runBufferedGroup(file, args, bag) {
             try {
                 bag.onStdout?.(chunk);
             }
-            catch { /* a listener never breaks the run */ }
+            catch { }
         });
         child.stderr?.setEncoding("utf8");
         child.stderr?.on("data", (chunk) => {
@@ -690,7 +544,7 @@ function runBufferedGroup(file, args, bag) {
             try {
                 bag.onStderr?.(chunk);
             }
-            catch { /* a listener never breaks the run */ }
+            catch { }
         });
         let settled = false;
         let transient = false;
@@ -702,8 +556,6 @@ function runBufferedGroup(file, args, bag) {
             clearTimeout(timer);
             bag.signal?.removeEventListener("abort", aborted);
             liveProviders.delete(child);
-            // The OS object is settled BEFORE the answer: a root that exited is
-            // not an empty container until the OS says so.
             const settlement = container === null ? Promise.resolve(null) : settleContainer(container, bag);
             void settlement.then(empty => {
                 resolve({
@@ -711,7 +563,6 @@ function runBufferedGroup(file, args, bag) {
                         code: notFound ? NOT_FOUND_CODE : overflowed ? OVERFLOW_CODE : timedOut ? TIMEOUT_CODE : inputFailed ? 1 : attachFailure !== null || empty === false ? CONTAINMENT_REFUSED_CODE : (code ?? 1),
                         stdout,
                         stderr: empty === false ? `${stderr}\nNative process containment could not prove all descendants exited.`.trim() : attachFailure !== null && stderr === "" ? attachFailure : stderr,
-                        // Overflow also killed the child; it is not a timeout and must not read as one.
                         timedOut: timedOut && !overflowed,
                         notFound,
                         ...containmentOf(container, empty, attachFailure),
@@ -740,11 +591,6 @@ function runBufferedGroup(file, args, bag) {
         }
     });
 }
-/**
- * Turn an execFile error into a result. The order matters: a maxBuffer overflow
- * also arrives with `killed: true`, so it has to be recognised before the
- * timeout check or a truncated `git log` reads as a hung one.
- */
 function describeFailure(error, stdout, stderr) {
     const notFound = error.code === "ENOENT";
     const overflowed = error.code === MAX_BUFFER_ERROR;
@@ -768,57 +614,22 @@ function resolveCode(error, flags) {
         return TIMEOUT_CODE;
     return 1;
 }
-/**
- * The streaming transport for JSONL-emitting providers.
- *
- * A long agent session can write far more event stream than any fixed
- * buffer should hold, and the lines that matter — the session identity,
- * the terminal usage — arrive LAST. Buffering-and-overflowing would kill
- * the process at 8 MiB and lose exactly the facts a paid run must not
- * lose (Codex provider review, high finding 2). So stdout is consumed
- * incrementally and only the load-bearing lines are retained:
- *
- *   - a bounded identity witness for `thread.started` (first usable id,
- *     first conflicting id, and last event), plus the LAST `turn.completed`
- *     and `turn.failed` line
- *   - the LAST `item.completed` line carrying an agent_message
- *
- * each capped per line; everything else is counted and dropped. The
- * result's stdout is the retained lines joined — a synthetic, bounded
- * envelope the parser reads exactly like test fixtures.
- */
 const JSONL_LINE_CAP = 64 * 1024;
 const JSONL_STDERR_CAP = 64 * 1024;
-/** Canonical identity at the transport boundary. Never persist or expose
- * provider framing whitespace as part of a resumable session id. */
 function transportSessionId(value) {
     if (typeof value !== "string")
         return null;
     const id = value.trim();
     return id === "" ? null : id;
 }
-/**
- * Provider replies are nested inside their JSONL envelope. A 64 KiB reply
- * therefore needs appreciably more than 64 KiB on the wire once quotes,
- * backslashes, and control characters are escaped. 512 KiB carries that
- * worst useful case while remaining a hard, per-event memory boundary.
- */
 export const JSONL_EVENT_HARD_CAP = 512 * 1024;
 const JSONL_OVERFLOW_PREFIX_CAP = 4 * 1024;
-/**
- * Split a byte stream into JSONL records without ever accumulating an
- * unbounded partial line. The callback is synchronous so the same fixed
- * storage can be reused for the next record. Counting the original bytes
- * (rather than JavaScript characters) makes the overflow receipt exact.
- */
 function boundedJsonlFramer(cap, onLine, inspectDiscriminants = false, tailCap = 0) {
     const retained = Buffer.allocUnsafe(cap);
     let retainedBytes = 0;
     let originalBytes = 0;
     let nonWhitespace = false;
     let discriminants = inspectDiscriminants ? jsonlDiscriminants() : null;
-    // An oversized line's last tailCap bytes, kept only once the line passes the cap (Claude's result carries its cost
-    // after the words that made it too large). Seeded from the retained prefix's end, so it is always the line's true end.
     const tailSize = Math.max(0, Math.min(tailCap, cap));
     const tail = tailSize === 0 ? null : Buffer.allocUnsafe(tailSize);
     let tailBytes = 0;
@@ -853,7 +664,6 @@ function boundedJsonlFramer(cap, onLine, inspectDiscriminants = false, tailCap =
         if (retainedBytes < cap) {
             retainedBytes += part.copy(retained, retainedBytes, 0, cap - retainedBytes);
         }
-        // The bytes up to the cap are in the prefix; only what runs past it moves the tail.
         if (tail !== null && originalBytes > cap)
             keepTail(before >= cap ? part : part.subarray(cap - before));
     };
@@ -887,8 +697,6 @@ function boundedJsonlFramer(cap, onLine, inspectDiscriminants = false, tailCap =
             }
         },
         finish() {
-            // Match the old `partial.trim() !== ""` rule: a final unterminated
-            // whitespace-only record is not an event and needs no receipt.
             if (originalBytes > 0 && nonWhitespace)
                 emit();
         },
@@ -904,8 +712,6 @@ function overflowReceiptText(transport, line) {
         hardCapBytes: JSONL_EVENT_HARD_CAP,
         prefixBytes: rawPrefix.length,
         prefix: rawPrefix.toString("utf8"),
-        // The readable prefix can end halfway through a UTF-8 character. This
-        // companion is the exact retained byte prefix for forensic evidence.
         prefixBase64: rawPrefix.toString("base64"),
     });
 }
@@ -961,17 +767,10 @@ function geminiMalformedLine(line) {
         error: { message: malformedReceiptText("gemini", line) },
     });
 }
-/**
- * Read only the leading, top-level `type` discriminant from an incomplete
- * JSON object. Provider JSONL dialects put `type` first. Anchoring the match
- * means content later in an oversized event can never spoof classification.
- */
 function leadingJsonObjectType(prefix) {
     const match = /^\s*\{\s*"type"\s*:\s*"([A-Za-z0-9._-]+)"/.exec(prefix.toString("utf8", 0, Math.min(prefix.length, 256)));
     return match?.[1] ?? null;
 }
-/** Codex emits `item` immediately after the outer type. Only an agent
- * message is load-bearing; completed command/tool telemetry is droppable. */
 function leadingCodexCompletedItemType(prefix) {
     const match = /^\s*\{\s*"type"\s*:\s*"item\.completed"\s*,\s*"item"\s*:\s*\{\s*"type"\s*:\s*"([A-Za-z0-9._-]+)"/.exec(prefix.toString("utf8", 0, Math.min(prefix.length, 512)));
     return match?.[1] ?? null;
@@ -980,9 +779,7 @@ function leadingClaudeSystemSubtype(prefix) {
     const match = /^\s*\{\s*"type"\s*:\s*"system"\s*,\s*"subtype"\s*:\s*"([A-Za-z0-9._-]+)"/.exec(prefix.toString("utf8", 0, Math.min(prefix.length, 512)));
     return match?.[1] ?? null;
 }
-/** How much of an oversized Claude result's end is kept to read its cost and usage (they follow the words). */
 const CLAUDE_RESULT_TAIL_CAP = 64 * 1024;
-/** Marks a Claude result whose session cost could not be read: the gateway charges the run's dollar cap instead. */
 export const CLAUDE_COST_UNKNOWN = "standing_orders_cost_unknown";
 function malformedCodexEventIsLoadBearing(prefix) {
     const type = leadingJsonObjectType(prefix);
@@ -995,9 +792,6 @@ function malformedCodexEventIsLoadBearing(prefix) {
 }
 function malformedGeminiEventIsLoadBearing(prefix) {
     const type = leadingJsonObjectType(prefix);
-    // These two records authorize the session and the successful terminal.
-    // Malformed messages remain diagnostics only; startup prose, tool traffic,
-    // and warnings retain the transport's established noise tolerance.
     return type === "init" || type === "result";
 }
 export function runStreamJsonl(file, args, options = {}) {
@@ -1037,9 +831,6 @@ export function runStreamJsonl(file, args, options = {}) {
         let inputFailed = false;
         const keep = (framed) => {
             if (framed.overflowed) {
-                // Inspect structural keys across the complete byte stream, including
-                // keys AFTER discarded command output. Quoted or nested types cannot
-                // spoof these discriminants, and malformed/ambiguous input stays red.
                 const type = framed.discriminants?.type ?? null;
                 if (type !== null && !["thread.started", "turn.completed", "turn.failed", "item.completed"].includes(type)) {
                     return;
@@ -1049,9 +840,6 @@ export function runStreamJsonl(file, args, options = {}) {
                     if (itemType !== undefined && itemType !== null && ["command_execution", "mcp_tool_call", "web_search", "file_change", "todo_list"].includes(itemType))
                         return;
                 }
-                // A load-bearing or unclassifiable hard-cap breach is independently
-                // retained as failure. Once those bytes were discarded, a later
-                // ordinary message must never turn the run green.
                 if (overflowLine === null)
                     overflowLine = codexOverflowLine(framed);
                 return;
@@ -1061,13 +849,9 @@ export function runStreamJsonl(file, args, options = {}) {
                 const event = JSON.parse(line);
                 const type = String(event["type"] ?? "");
                 if (type === "thread.started") {
-                    // Keep the last init for the existing transport contract and a
-                    // bounded pair of earlier witnesses so a conflict cannot hide.
                     startedLine = line;
                     const id = transportSessionId(event["thread_id"]);
                     if (id !== null) {
-                        // Retain only enough events to prove the identity contract:
-                        // one usable id when the first init was blank, and one conflict.
                         if (startedSessionId === null) {
                             startedSessionId = id;
                             startedIdentityLine = line;
@@ -1080,7 +864,6 @@ export function runStreamJsonl(file, args, options = {}) {
                                 options.onSessionId(id);
                             }
                             catch {
-                                // A registry that cannot be written must not kill the turn.
                             }
                         }
                     }
@@ -1089,8 +872,6 @@ export function runStreamJsonl(file, args, options = {}) {
                     completedLine = line;
                 }
                 else if (type === "turn.failed") {
-                    // Retain failure independently from completion: seeing either at
-                    // any point is load-bearing, while one slot per kind stays bounded.
                     failedLine = line;
                 }
                 else if (type === "item.completed") {
@@ -1104,14 +885,10 @@ export function runStreamJsonl(file, args, options = {}) {
                         options.onStreamEvent(event);
                     }
                     catch {
-                        // Observational only: a broken listener never touches the run.
                     }
                 }
             }
             catch {
-                // Startup prose and ordinary malformed telemetry remain ignorable.
-                // Once initialization is proven, however, a recognizable control or
-                // answer record cannot disappear merely because its JSON was cut.
                 if (startedLine !== null &&
                     malformedLine === null &&
                     malformedCodexEventIsLoadBearing(framed.prefix)) {
@@ -1167,8 +944,6 @@ export function runStreamJsonl(file, args, options = {}) {
                 ...containmentOf(container, empty, attachFailure),
             }));
         };
-        // A failed spawn fires 'error' and may never fire 'close' — both routes
-        // settle, exactly once.
         child.on("error", error => {
             notFound = error.code === "ENOENT";
             if (stderr === "")
@@ -1177,8 +952,6 @@ export function runStreamJsonl(file, args, options = {}) {
         });
         child.on("close", code => finish(code));
         if (options.stdin !== undefined && child.stdin !== null) {
-            // Even an exit-0 child cannot prove a review if prompt delivery failed.
-            // Handle EPIPE without crashing the supervisor, then wait for close.
             child.stdin.on("error", error => {
                 inputFailed = true;
                 stderr = `review prompt input failed: ${String(error)}`.slice(0, JSONL_STDERR_CAP);
@@ -1191,27 +964,6 @@ export function runStreamJsonl(file, args, options = {}) {
         }
     });
 }
-/**
- * The streaming transport for gemini's stream-json dialect (Phase 3 D1/A7).
- *
- * Retention: a bounded `init` identity witness (the first init signal, first
- * usable session id, and first conflicting id), the FIRST
- * `severity:"error"` error event (diagnostics),
- * the LAST `result` event (tokens + structural status), and the assistant's
- * text — which gemini emits only as many `message` delta lines — ASSEMBLED
- * into one line of a dedicated internal schema the real CLI cannot emit:
- *
- *   {"type":"synthetic_message","content":"...","truncated":true?}
- *
- * Assembly rules (round-3 f9): only `role:"assistant"` events with
- * `delta === true` concatenate; a non-delta assistant message REPLACES the
- * buffer (full-message semantics); non-string content is dropped; the cap
- * is enforced on the SERIALIZED UTF-8 BYTES of the complete synthetic line
- * (marker included), so it can never violate the runner's own line
- * discipline. Everything else — user echoes, tool_use, tool_result,
- * warnings — is dropped. Timeout, process-group, kill, and spawn
- * semantics match `runStreamJsonl`.
- */
 export function runGeminiStreamJsonl(file, args, options = {}) {
     const childEnv = resolveChildEnv(options);
     return new Promise(resolve => {
@@ -1250,9 +1002,6 @@ export function runGeminiStreamJsonl(file, args, options = {}) {
         const keep = (framed) => {
             if (framed.overflowed) {
                 const type = leadingJsonObjectType(framed.prefix);
-                // Tool plumbing is never a terminal or answer. All load-bearing and
-                // unknown oversized events latch a terminal protocol failure so a
-                // later small success cannot hide discarded provider bytes.
                 if (type !== "tool_use" && type !== "tool_result") {
                     if (overflowLine === null)
                         overflowLine = geminiOverflowLine(framed);
@@ -1270,7 +1019,7 @@ export function runGeminiStreamJsonl(file, args, options = {}) {
                     malformedGeminiEventIsLoadBearing(framed.prefix)) {
                     malformedLine = geminiMalformedLine(framed);
                 }
-                return; // startup prose and non-load-bearing malformed noise are dropped
+                return;
             }
             if (event === null || typeof event !== "object")
                 return;
@@ -1295,13 +1044,12 @@ export function runGeminiStreamJsonl(file, args, options = {}) {
                             options.onSessionId(id);
                         }
                         catch {
-                            // A registry that cannot be written must not kill the turn.
                         }
                     }
                 }
             }
             else if (type === "result") {
-                resultLine = line; // last one wins
+                resultLine = line;
             }
             else if (type === "error") {
                 if (errorLine === null && String(event["severity"] ?? "") === "error")
@@ -1310,7 +1058,7 @@ export function runGeminiStreamJsonl(file, args, options = {}) {
             else if (type === "message" && String(event["role"] ?? "") === "assistant") {
                 const content = event["content"];
                 if (typeof content !== "string")
-                    return; // non-string content: dropped
+                    return;
                 if (event["delta"] === true) {
                     if (!messageTruncated) {
                         message += content;
@@ -1319,7 +1067,6 @@ export function runGeminiStreamJsonl(file, args, options = {}) {
                     }
                 }
                 else {
-                    // A full (non-delta) assistant message replaces the buffer.
                     message = content;
                     messageTruncated = Buffer.byteLength(message, "utf8") > JSONL_LINE_CAP;
                 }
@@ -1329,7 +1076,6 @@ export function runGeminiStreamJsonl(file, args, options = {}) {
                     options.onStreamEvent(event);
                 }
                 catch {
-                    // Observational only: a broken listener never touches the run.
                 }
             }
         };
@@ -1368,12 +1114,8 @@ export function runGeminiStreamJsonl(file, args, options = {}) {
                 lines.push(syntheticMessageLine(message, messageTruncated));
             if (resultLine !== null)
                 lines.push(resultLine);
-            // Keep the overflow last: gemini's contract is last-result-wins, and
-            // no later small event may erase evidence that a record was discarded.
             if (overflowLine !== null)
                 lines.push(overflowLine);
-            // A recognizable, malformed terminal is just as conclusive as an
-            // oversized one. Keep it last so last-result-wins cannot erase it.
             if (malformedLine !== null)
                 lines.push(malformedLine);
             const settlement = container === null ? Promise.resolve(null) : settleContainer(container, options);
@@ -1395,7 +1137,6 @@ export function runGeminiStreamJsonl(file, args, options = {}) {
         child.on("close", code => finish(code));
     });
 }
-/** One process listing: ids, group, state and command name only (never arguments — they can carry a brief). */
 function processRows() {
     try {
         return execFileSync("/bin/ps", ["-axo", "pid=,ppid=,pgid=,stat=,comm="], { encoding: "utf8", timeout: 2_000, maxBuffer: 8 * 1024 * 1024 })
@@ -1408,11 +1149,6 @@ function processRows() {
         return null;
     }
 }
-/**
- * What the agent started and is still running: from `root` (the spawned process — the agent itself, or a fence
- * wrapper around it), down to the agent's own process (the first whose command is the agent's launch, `names`), then
- * every live, non-zombie process beneath it, with its group. The agent itself and any wrapper are never counted.
- */
 function liveUnderAgent(root, names, rootIsWrapper = false) {
     const rows = processRows();
     if (rows === null)
@@ -1422,8 +1158,6 @@ function liveUnderAgent(root, names, rootIsWrapper = false) {
         children.set(row.parent, [...(children.get(row.parent) ?? []), row]);
     const self = rows.find(row => row.pid === root);
     const named = (row) => agentNamed(row, names);
-    // The agent: the root when it is the agent (macOS sandbox-exec execs in place), else the first named descendant.
-    // On Linux the root is the sandbox launch helper (sandbox-launch.ts, itself node): never taken for the agent.
     let agent = !rootIsWrapper && self !== undefined && named(self) ? root : null;
     const pending = [...(children.get(root) ?? [])];
     while (agent === null && pending.length > 0) {
@@ -1445,7 +1179,6 @@ function liveUnderAgent(root, names, rootIsWrapper = false) {
     }
     return found;
 }
-/** The program a Linux process runs (its /proc exe), or null: elsewhere, or unreadable. */
 function linuxProgramOf(pid) {
     if (process.platform !== "linux")
         return null;
@@ -1456,23 +1189,15 @@ function linuxProgramOf(pid) {
         return null;
     }
 }
-/**
- * Whether a listed process is the agent's launch (`names`): by its listed name, or on Linux by the program it runs,
- * since a listing there shows the main thread's name, which Node 24 sets to "MainThread".
- */
 export function agentNamed(row, names, programOf = linuxProgramOf) {
     if (names.some(name => row.name === name || row.name.endsWith(`/${name}`)))
         return true;
     const program = programOf(row.pid);
     return program !== null && names.includes(program);
 }
-/** How long each shutdown step waits: session/close's answer, then exit after stdin closes, then exit after SIGTERM. */
 export const ACP_SHUTDOWN_MS = { close: 2_000, eof: 5_000, term: 5_000 };
-/** How long each handshake step (initialize, session/new, choosing the model) may take before the agent is stopped. */
 export const ACP_HANDSHAKE_MS = 30_000;
-/** After the agent itself has exited, how long its pipes may stay open (a descendant holding them) before they are closed. */
 const ACP_PIPES_AFTER_EXIT_MS = 5_000;
-/** SIGTERM the child's process group (POSIX) or the child alone; a container's own stop is the forced one, later. */
 function termGroup(child) {
     const pid = child.pid;
     try {
@@ -1482,20 +1207,8 @@ function termGroup(child) {
             child.kill("SIGTERM");
     }
     catch {
-        // Already gone.
     }
 }
-/**
- * One ACP build conversation over the agent's stdio (docs/plans/acp-adapter.md § Gateway, runner, custody). The
- * conversation itself is acp-client.ts; this owns the process: the same contained spawn, ownership, descendant
- * observation, container settlement and watchdog every other runner uses, with both clocks at once.
- *
- * After the prompt is answered it shuts the agent down in bounded steps — session/close (when offered), stdin EOF,
- * SIGTERM to the group, then the forced kill — and returns only when the process has settled, so the gateway's
- * witness records the real exit. A protocol failure kills at once. A stop, from the gateway's stop watch, kills at
- * any step. The result's stdout is the conversation's retained record, never the agent's stream; its code is 0 only
- * when the prompt was answered end_turn and the agent then exited cleanly or on our own signal.
- */
 export function runAcpSession(file, args, options = {}) {
     const acp = options.acp;
     if (acp === undefined)
@@ -1522,18 +1235,14 @@ export function runAcpSession(file, args, options = {}) {
         if (options.processGroup === true && container === null)
             observeProcessTree(child, options);
         const conversation = createAcpConversation({ cwd: options.cwd ?? process.cwd(), prompt: acp.prompt, model: acp.model, expect: acp.expect });
-        // The agent's own process, as a listing names it: the launched file, or the script a pinned interpreter runs.
         const agentNames = [...new Set([file, ...args.slice(0, 2)].filter(one => one.startsWith("/")).map(one => one.split("/").pop()).filter(one => one !== ""))];
         let stderr = "";
         let timedOut = false;
         let notFound = false;
         let settled = false;
         let shuttingDown = false;
-        /** The signals the plane itself sent after the prompt was answered, by its own shutdown ladder: an exit by one of
-         * those is clean. A stop or a timeout kills through other roads and never sets these. */
         let termAfterTerminal = false;
         let killAfterTerminal = false;
-        /** How the process came to end, for the record: on its own (before or after stdin closed), or by our signal. */
         let endedBy = "self";
         let announced = null;
         const timers = [];
@@ -1545,7 +1254,7 @@ export function runAcpSession(file, args, options = {}) {
                 try {
                     child.stdin.write(`${one}\n`);
                 }
-                catch { /* the agent closed its stdin: its exit decides */ }
+                catch { }
             }
         };
         const forceKill = () => {
@@ -1555,7 +1264,6 @@ export function runAcpSession(file, args, options = {}) {
             else
                 child.kill("SIGKILL");
         };
-        /** Each handshake step has its own deadline, beside the run's clocks. */
         let handshakePhase = null;
         const armHandshake = () => {
             const phase = conversation.phase();
@@ -1585,7 +1293,7 @@ export function runAcpSession(file, args, options = {}) {
                 try {
                     child.stdin?.end();
                 }
-                catch { /* gone */ }
+                catch { }
                 endedBy = "eof";
                 later(ACP_SHUTDOWN_MS.eof, () => {
                     if (exited())
@@ -1630,13 +1338,13 @@ export function runAcpSession(file, args, options = {}) {
                 try {
                     options.onSessionId?.(id);
                 }
-                catch { /* a registry that cannot be written must not kill the turn */ }
+                catch { }
             }
             for (const update of reaction.live) {
                 try {
                     options.onStreamEvent?.({ acp: update });
                 }
-                catch { /* observational only */ }
+                catch { }
             }
             const phase = conversation.phase();
             if (phase === "failed" || phase === "ended")
@@ -1677,10 +1385,7 @@ export function runAcpSession(file, args, options = {}) {
                 liveDescendants: () => process.platform === "win32" ? null : exited() || child.pid === undefined ? [] : liveUnderAgent(child.pid, agentNames, child.spawnargs.some(arg => arg.endsWith("sandbox-launch.js"))),
             });
         }
-        catch { /* the caller's own failure */ }
-        // The moment the agent itself exits, what it left in its own group ends with it — not at "close", which a
-        // descendant holding the agent's pipes can postpone forever; and if those pipes are still open shortly after, they
-        // are closed, so settlement never waits on a stray. Escaped groups are the custody observer's, as for every runner.
+        catch { }
         let leftover = false;
         child.on("exit", () => {
             if (options.processGroup === true && container === null && child.pid !== undefined && process.platform !== "win32") {
@@ -1694,7 +1399,7 @@ export function runAcpSession(file, args, options = {}) {
                 try {
                     process.kill(-child.pid, "SIGKILL");
                 }
-                catch { /* none left */ }
+                catch { }
             }
             later(ACP_PIPES_AFTER_EXIT_MS, () => {
                 if (settled)
@@ -1703,32 +1408,26 @@ export function runAcpSession(file, args, options = {}) {
                     try {
                         pipe?.destroy();
                     }
-                    catch { /* gone */ }
+                    catch { }
                 }
             });
         });
         const finish = (code, signal) => {
             if (settled)
                 return;
-            // The last record, even one with no newline after it, is read before anything is decided.
             framing.finish();
             settled = true;
             for (const timer of timers)
                 clearTimeout(timer);
             watchdog.stop();
             liveProviders.delete(child);
-            // Whatever the agent started in its own group and left running ends with it (a group id can't be reused while any
-            // member lives, so this reaches only what it left). Escaped groups are the custody observer's, as for every runner.
             const terminal = conversation.terminal();
             const answered = terminal !== null && "stopReason" in terminal && terminal.stopReason === "end_turn" && conversation.failure() === null;
-            // A clean exit after the answer, or an exit by the plane's own post-answer signal (its shutdown ladder's SIGTERM,
-            // then SIGKILL), is success; anything else — a stop, a timeout, another signal — is its code.
             const ownSignal = (termAfterTerminal && (signal === "SIGTERM" || code === 143)) || (killAfterTerminal && (signal === "SIGKILL" || code === 137));
             const exitCode = answered && !timedOut && (code === 0 || ownSignal) ? 0 : (code ?? 1);
             const settlement = container === null ? Promise.resolve(null) : settleContainer(container, options);
             void settlement.then(empty => resolve({
                 code: notFound ? NOT_FOUND_CODE : timedOut ? TIMEOUT_CODE : attachFailure !== null || empty === false ? CONTAINMENT_REFUSED_CODE : exitCode,
-                // The runner's own account of the ending rides last: a type no agent can emit.
                 stdout: `${conversation.retained()}${JSON.stringify({ type: "acp.exit", how: endedBy, leftover: leftover || empty === false, timedOut })}\n`,
                 stderr: empty === false ? `${stderr}\nNative process containment could not prove all descendants exited.`.trim() : attachFailure !== null && stderr === "" ? attachFailure : stderr,
                 timedOut,
@@ -1747,12 +1446,6 @@ export function runAcpSession(file, args, options = {}) {
     });
 }
 const TRUNCATION_MARKER = "…[truncated]";
-/**
- * One serialized synthetic line, guaranteed ≤ JSONL_LINE_CAP in UTF-8
- * bytes — the trim loop measures the COMPLETE serialized line (escaping
- * and marker included), so pathological escaping cannot smuggle it past
- * the cap (round-3 f9).
- */
 function syntheticMessageLine(content, truncated) {
     let body = content;
     let marked = truncated;
@@ -1764,42 +1457,11 @@ function syntheticMessageLine(content, truncated) {
         if (over <= 0)
             return line;
         marked = true;
-        // Cut at least the overage in UTF-16 units; the loop re-measures.
         const cut = Math.max(1, over);
         body = body.slice(0, Math.max(0, body.length - cut));
     }
 }
-/**
- * The streaming transport for claude's stream-json dialect (arc 1).
- *
- * Same rationale as `runStreamJsonl`: a long agent session writes far more
- * event stream than any fixed buffer should hold, and the line that matters
- * — the terminal result carrying session, usage, and dollars — arrives
- * LAST. The 8 MiB buffered kill would destroy exactly that accounting
- * envelope, so stdout is consumed incrementally and only the load-bearing
- * lines are retained:
- *
- *   - a bounded identity witness for `system`/`init`: the first init signal,
- *     the first usable session id, and one conflicting id
- *   - the FIRST primary `result` event, selected STRUCTURALLY (finding 10;
- *     stream-scope.ts `primaryResultEvent`): top-level, and origin absent or
- *     `origin.kind === "human"` — an allowlist, so a subagent's or background
- *     task's result (or any future origin kind) can never be mistaken for the
- *     main query's accounting. Later results are dropped. A subagent's init
- *     never enters the identity witness.
- *
- * The result's stdout is the retained lines joined — a synthetic, bounded
- * envelope `claudeParse` reads exactly like test fixtures. Timeout,
- * process-group, kill, and spawn semantics match `runStreamJsonl`.
- */
-/** The usage fields Claude reports per message (not per session): a live session's account adds them up. */
 const LIVE_SUMMED_USAGE = ["input_tokens", "output_tokens", "cache_creation_input_tokens", "cache_read_input_tokens"];
-/**
- * A live session's account so far (one main result per turn, checked on Claude Code 2.1.290): the latest result's
- * session, ending, words and cost — `total_cost_usd` is already the session's running total — with the usage token
- * fields and `num_turns`, which count only their own message, added up across every main result. A field that is not
- * a non-negative number adds nothing.
- */
 export function cumulativeLiveResult(previous, latest) {
     const count = (value) => typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : null;
     const usageOf = (event) => event["usage"] !== null && typeof event["usage"] === "object" && !Array.isArray(event["usage"]) ? event["usage"] : null;
@@ -1817,9 +1479,7 @@ export function cumulativeLiveResult(previous, latest) {
         ...(turnsBefore === null && turnsNow === null ? {} : { num_turns: (turnsBefore ?? 0) + (turnsNow ?? 0) }),
     };
 }
-/** This transport can keep stdin open for a live session (RunOptions.liveInput). */
 export const STREAM_INPUT = Symbol.for("toolroll.streamInput");
-/** Whether a runner declares it keeps stdin open for a live session; an injected runner opts in by carrying the mark. */
 export const streamsInput = (runner) => typeof runner === "function" && runner[STREAM_INPUT] === true;
 export function runClaudeStreamJsonl(file, args, options = {}) {
     const childEnv = resolveChildEnv(options);
@@ -1847,17 +1507,12 @@ export function runClaudeStreamJsonl(file, args, options = {}) {
         let initLine = null;
         let initIdentityLine = null;
         let conflictingInitLine = null;
-        /** v140: the first init's model, and the first top-level init naming another (the parser reads them as a conflict:
-         * unknown, never one of them). Kept even within one session id. */
         let initModel = null;
         let initModelLine = null;
         let modelConflictLine = null;
         let initSessionId = null;
         let resultLine = null;
         let resultOverflowed = false;
-        // The run's account: the first main result, or for a live session every main result added up (each oversized
-        // one's scanned cost and usage too). Its cost is the highest running total seen; costUnknown when the latest main
-        // result's cost could not be read (an oversized one), which only a later readable result can clear.
         let account = null;
         let costUnknown = false;
         let overflowLine = null;
@@ -1865,8 +1520,6 @@ export function runClaudeStreamJsonl(file, args, options = {}) {
         let stderr = "";
         let timedOut = false;
         let notFound = false;
-        // Latch BEFORE invoking (finding 13): a throwing listener has already
-        // consumed its one firing, and the stream goes on unharmed.
         const fireReceipt = () => {
             if (receiptFired || options.onReceipt === undefined) {
                 receiptFired = true;
@@ -1877,8 +1530,6 @@ export function runClaudeStreamJsonl(file, args, options = {}) {
                 options.onReceipt();
             }
             catch {
-                // A receipt that cannot be recorded must not alter the run; the
-                // note stays honestly unreceipted and re-attaches later.
             }
         };
         const tally = (event, line) => {
@@ -1886,7 +1537,6 @@ export function runClaudeStreamJsonl(file, args, options = {}) {
             account = account === null || live === null ? event : { ...(line === null ? account : {}), ...cumulativeLiveResult(account, event) };
             const cost = event["total_cost_usd"];
             const readable = typeof cost === "number" && Number.isFinite(cost) && cost >= 0;
-            // The running total only grows: an earlier, higher total stands (a session's cost is never given back).
             const prior = before?.["total_cost_usd"];
             if (readable && typeof prior === "number" && prior > cost)
                 account = { ...account, total_cost_usd: prior };
@@ -1903,12 +1553,6 @@ export function runClaudeStreamJsonl(file, args, options = {}) {
         };
         const keep = (framed) => {
             if (framed.overflowed) {
-                // An oversized result is the first primary candidate and therefore
-                // closes the slot fail-closed; an oversized non-result is merely a
-                // fallback that a later parseable primary result can supersede.
-                // Claude's parser trusts the first primary result. When a line is
-                // too large to classify, reserve that first slot fail-closed rather
-                // than let a later small result hide emitted bytes we discarded.
                 const type = leadingJsonObjectType(framed.prefix);
                 if (type !== null && type !== "result") {
                     if (type !== "system")
@@ -1916,18 +1560,10 @@ export function runClaudeStreamJsonl(file, args, options = {}) {
                     const subtype = leadingClaudeSystemSubtype(framed.prefix);
                     if (subtype !== null && subtype !== "init")
                         return;
-                    // An init too large to inspect may conceal a conflicting session
-                    // identity. Latch it independently from the primary result so the
-                    // same event set fails regardless of whether it arrived before or
-                    // after the terminal, while a normal terminal can still account
-                    // for the turn's usage.
                     if (overflowLine === null)
                         overflowLine = claudeOverflowLine(framed);
                     return;
                 }
-                // Nothing inside an oversized result is trusted: the agent shapes its bytes (tool inputs in permission_denials
-                // are real JSON objects), so a planted total_cost_usd or origin could read as genuine. It counts as the main
-                // result with an unknown cost, charged at the run's cap, and a live session's input closes.
                 const scanned = { primary: true, account: {} };
                 if (live !== null || resultLine === null)
                     tally(scanned.account, null);
@@ -1937,8 +1573,6 @@ export function runClaudeStreamJsonl(file, args, options = {}) {
                 }
                 else if (overflowLine === null)
                     overflowLine = claudeOverflowLine(framed);
-                // A live session whose main result was too large to read cannot be steered safely: close its input, so the
-                // process ends instead of running further turns nobody can account for.
                 if (live !== null && scanned.primary)
                     live.close("settled");
                 return;
@@ -1949,14 +1583,11 @@ export function runClaudeStreamJsonl(file, args, options = {}) {
                 event = JSON.parse(line);
             }
             catch {
-                return; // not JSON: not an event; dropped
+                return;
             }
             if (event === null || typeof event !== "object")
                 return;
             const type = String(event["type"] ?? "");
-            // A subagent's init, words and result are not the session's (stream-scope.ts): they never witness its identity,
-            // name its session, fire its receipt or stand as its result. They still reach the observers below, which filter
-            // for themselves.
             if (type === "system" && String(event["subtype"] ?? "") === "init" && topLevelEvent(event)) {
                 if (initLine === null)
                     initLine = line;
@@ -1986,30 +1617,19 @@ export function runClaudeStreamJsonl(file, args, options = {}) {
                             options.onSessionId(id);
                         }
                         catch {
-                            // A registry that cannot be written must not kill the turn.
                         }
                     }
                 }
             }
             else if (type === "assistant") {
-                // Top-level only (finding 11): assistant events carry no origin;
-                // parent_tool_use_id is the correlation field, and a subagent's
-                // words prove nothing about the main prompt.
                 if (topLevelEvent(event))
                     fireReceipt();
             }
             else if (type === "rate_limit_event") {
-                // v105: the plan's usage windows, as Claude says them each turn (the Tasks page's limits).
                 noteLimits(claudeLimitsOf(event));
             }
             else if (type === "result" && (resultLine === null || live !== null) && primaryResultEvent(event)) {
-                // A live session ends a turn with a result each time: the run's account is the last one, with every main
-                // result's usage and turns added up (account). After an oversized main result the retained result stays the
-                // fail-closed overflow, but later results still count toward its cost.
                 tally(event, line);
-                // Fallback receipt (finding 11): a SUCCESSFUL main-query completion
-                // entails the prompt ran even if the stream elided assistant
-                // events. Error results never fire — startup death is not delivery.
                 if (event["is_error"] !== true && String(event["subtype"] ?? "") === "success")
                     fireReceipt();
             }
@@ -2018,15 +1638,11 @@ export function runClaudeStreamJsonl(file, args, options = {}) {
                     options.onStreamEvent(event);
                 }
                 catch {
-                    // Observational only: a broken listener never touches the run.
                 }
             }
-            // After the run's own bookkeeping: the session may close stdin on this event.
             if (live !== null)
                 live.observe(event);
         };
-        // The retained main result as the run's account: an oversized one stays the fail-closed overflow but carries the
-        // cost and usage read from it and from later results; a cost that could not be read says so (CLAUDE_COST_UNKNOWN).
         const accountedResultLine = () => {
             if (resultLine === null || (!resultOverflowed && !costUnknown))
                 return resultLine;
@@ -2088,7 +1704,6 @@ export function runClaudeStreamJsonl(file, args, options = {}) {
         child.on("close", code => finish(code));
         if (live !== null && child.stdin !== null) {
             const input = child.stdin;
-            // A pipe the child closed (it exited) ends live input; the run settles on the process, as always.
             input.on("error", () => live.detach("input-failed"));
             live.attach({ write: line => { input.write(line, "utf8"); }, end: () => { input.end(); } });
         }