tumwater 0.2.0 → 0.4.0

package/dist/src/agent/run-agent.js

@@ -1,27 +1,32 @@
-// vocabulary: plain
 /** The backend-neutral agent runner (plans/agent-backends.md \"The seam\"): everything a run
  * needs regardless of which agent it drives — the spawn, the `tumwater_run` raw-log marker,
- * the watchdog wiring, abort, the group kill and marker sweep, stderr capture, and result
- * assembly. The backend (src/agent/agent-backend.ts, with pi in src/pi/pi-backend.ts) supplies
- * the argv/stdin/env, the native-to-canonical stdout translator, the stderr warning matcher,
- * and the exit classification. `runPi` (src/pi/pi.ts) is the thin alias the existing call sites
- * use, so a caller and its fakes are untouched by this split. */
+ * the watchdog wiring, abort, and stderr capture. The backend (src/agent/agent-backend.ts, with
+ * pi in src/pi/pi-backend.ts) provides the argv/stdin/env, the native-to-canonical stdout
+ * translator, the stderr warning
+ * matcher, and the exit classification. This file keeps the live lifecycle — pre-spawn setup,
+ * `prepare`, spawn, decoders, the stream pipeline, the watchdogs and the feed — and delegates
+ * the post-run settlement (spawn-error result, exit orphan sweep, close-time reconcile and
+ * classify) to src/agent/run-settle.ts. `runPi` (src/pi/pi.ts) is the thin alias the existing
+ * call sites use, so a caller and its fakes are untouched by this split. */
 import { spawn } from "node:child_process";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { StringDecoder } from "node:string_decoder";
-import { ensureDir, ensureParentDir, rotateIfLarge } from "../files/files.js";
-import { agentBinConfigKey, agentBinSourceLabel } from "../pi/pi-bin.js";
+import { ensureDir, ensureParentDir, removeTree, rotateIfLarge } from "../files/files.js";
 import { runOnAbort, terminateChild } from "../process/process.js";
-import { makeRunMarker, sweepRunMarker } from "../process/run-marker.js";
+import { makeRunMarker } from "../process/run-marker.js";
 import { PiStreamParser } from "../pi/pi-stream.js";
 import { startPiWatchdogs } from "../pi/pi-watchdogs.js";
-import { DEFAULT_AGENT, agentBackend, registerAgentBackend } from "./agent-backend.js";
+import { DEFAULT_BACKEND, backendById, registerAgentBackend } from "./agent-backend.js";
 import { recordSession } from "./session-ledger.js";
+import { errorMessage } from "../text/text.js";
+import { warnEventBestEffort, TUMWATER_SOURCE } from "../events/events.js";
 import { piBackend } from "../pi/pi-backend.js";
 import { claudeBackend } from "./claude/claude-backend.js";
+import { codexBackend } from "./codex/codex-backend.js";
 import { opencodeBackend } from "./opencode/opencode-backend.js";
+import { setupFailureResult, settleClose, settleError, settleExit } from "./run-settle.js";
 import { seamImageInput } from "./image-input.js";
 import { ensureNotesShim } from "./notes-shim.js";
 import { nearestTumwaterRoot } from "../paths.js";
@@ -34,7 +39,7 @@ const STDERR_MATCH_TAIL = 512;
  * object; a line this long is already at the default whole-log cap (`logMaxBytes`, 16 MiB), so
  * continuing to buffer it can only be a malformed stream. Past it `feedCanonical` drops the
  * buffered line and skips input to the next newline, so a backend that streams bytes with no
- * newline — each byte resetting the quiet watchdog — cannot grow the buffer until the tick
+ * newline — each byte resetting the quiet watchdog — cannot grow the buffer until the run
  * timeout (4 h by default) exhausts the harness's memory. */
 export const MAX_NATIVE_LINE_CHARS = 16 * 1024 * 1024;
 // The seam's adapters. Registering here — where the lookup happens — keeps the registration
@@ -42,20 +47,7 @@ export const MAX_NATIVE_LINE_CHARS = 16 * 1024 * 1024;
 registerAgentBackend(piBackend);
 registerAgentBackend(claudeBackend);
 registerAgentBackend(opencodeBackend);
-/** Prefix of PiRunResult.errorMessage when the agent process never started (no session file
- * is created for such a run). The resolved binary follows it, so a configured agentBin
- * reads "failed to spawn <bin>" rather than blaming an ambient "pi". */
-const SPAWN_ERROR_PREFIX = "failed to spawn";
-/** The spawn-error message for a resolved binary: the default source keeps today's text
- * ("failed to spawn pi: …"); a configured source names the binary and where it came from —
- * the backend's own env var and config key (agentBinConfigKey) — so a wrong
- * `backends.claude.bin` does not read as pi's legacy `agentBin`. */
-function spawnErrorMessage(resolved, errMessage, backend) {
-    const source = resolved.source === "default"
-        ? ""
-        : ` (resolved from ${agentBinSourceLabel(resolved.source, backend.binEnv, agentBinConfigKey(backend.id))})`;
-    return `${SPAWN_ERROR_PREFIX} ${resolved.bin}${source}: ${errMessage}`;
-}
+registerAgentBackend(codexBackend);
 function openAppendLog(file, maxBytes) {
     ensureParentDir(file);
     rotateIfLarge(file, maxBytes);
@@ -66,449 +58,474 @@ function openAppendLog(file, maxBytes) {
     return log;
 }
 /** Run the configured agent backend non-interactively in a worktree and distill the result.
- * Never throws. */
+ * Never throws: a setup failure (session dir, log file, scratch dir) resolves as a failed run
+ * whose errorMessage names it. */
 export function runAgent(opts) {
-    return new Promise((resolve) => {
+    // An async executor so a backend's `prepare` step (the codex write guard resolving its trust
+    // by spawning app-server) can be awaited before the synchronous invocation is built. A
+    // `prepare` throw is caught and warned, never rejecting the run; a synchronous throw in the
+    // build-and-spawn stage below (e.g. claude's invocation rejecting a run with no model)
+    // rejects the run, matching what the Promise constructor did for a throw from a synchronous
+    // executor.
+    return new Promise(async (resolve, reject) => {
         // The `agent` selector is optional: default to pi, the historical backend. An unregistered
-        // id also falls back to pi rather than rejecting the tick.
-        const backend = agentBackend(opts.config.agent ?? DEFAULT_AGENT) ?? piBackend;
-        ensureDir(opts.sessionDir);
-        // A broken raw log (EACCES, ENOSPC) must not crash the process on an unhandled 'error'
-        // nor hang the tick: openAppendLog marks it so finish() resolves without waiting for a
-        // 'finish' that will never come — a lost transcript is acceptable, a stuck loop is not.
-        const rawLog = openAppendLog(opts.rawLogFile, opts.config.logMaxBytes);
-        // The backend-native stdout, kept beside the canonical raw log for debugging: every
-        // complete native line is written before it is translated, so the two logs line up. A
-        // broken native log degrades to a lost debug log, never a stuck or failed tick.
-        const nativeLog = openAppendLog(opts.nativeLogFile, opts.config.logMaxBytes);
-        // The marker precedes this run's first event in file order — written to the same stream
-        // stdout lines flow through, before spawn, so ordering is exact by construction; on a
-        // failed spawn finish() still ends the stream and flushes it. Exactly one per run: the
-        // kind and agent are always there, the label only when the caller set one.
-        {
-            const marker = {
-                type: "tumwater_run",
-                kind: opts.kind,
-                agent: backend.id,
-            };
-            if (opts.label)
-                marker.label = opts.label;
-            rawLog.stream.write(JSON.stringify(marker) + "\n");
+        // id also falls back to pi rather than rejecting the run.
+        const backend = backendById(opts.config.agent ?? DEFAULT_BACKEND) ?? piBackend;
+        let rawLog;
+        let nativeLog;
+        let runTmp;
+        try {
+            ensureDir(opts.sessionDir);
+            // A broken raw log (EACCES, ENOSPC) must not crash the process on an unhandled 'error'
+            // nor hang the run: openAppendLog marks it so finish() resolves without waiting for a
+            // 'finish' that will never come — a lost transcript is acceptable, a stuck runner is not.
+            rawLog = openAppendLog(opts.rawLogFile, opts.config.logMaxBytes);
+            // The backend-native stdout, kept beside the canonical raw log for debugging: every
+            // complete native line is written before it is translated, so the two logs line up. A
+            // broken native log degrades to a lost debug log, never a stuck or failed run.
+            nativeLog = openAppendLog(opts.nativeLogFile, opts.config.logMaxBytes);
+            // A private TMPDIR per run: concurrent agents default to literal /tmp names, and a shared
+            // per-user TMPDIR would still collide. Removed when the run settles.
+            runTmp = fs.mkdtempSync(path.join(os.tmpdir(), "tumwater-run-"));
+        }
+        catch (err) {
+            // Nothing is spawned yet: close what opened and fail the run instead of rejecting it.
+            rawLog?.stream.end();
+            nativeLog?.stream.end();
+            resolve(setupFailureResult(backend.id, `could not prepare the agent run: ${errorMessage(err)}`));
+            return;
         }
-        // The first blind image read an authoring run made (plans/image-input.md "Detecting a
-        // blind read"): the path, plus an indirection to the child so the parser's parse-time
-        // callback (which fires during feed, after spawn) can kill it. Unset for a gate run,
-        // which only records the read. Declared before the parser so its onBlindRead closure
-        // (which assigns them at parse time, after spawn) can reference them.
+        // The pre-spawn setup below may throw synchronously (a broken marker write, parser
+        // construction, backend.resolveBin). An async executor's own rejection is swallowed by the
+        // Promise constructor, so a throw here would otherwise leave the run's promise pending
+        // forever and emit an unhandled rejection — a synchronous executor used to reject directly.
+        // The try/catch below restores that rejection. A known-recoverable failure (the notes
+        // shim) warns and goes on inside its own guard, so it is deliberately not covered here.
         let blindRead;
         let terminateRun;
-        const parser = new PiStreamParser(opts.onToolCallStart, {
-            // The seam's effective image input (src/agent/image-input.ts): a text-only seam makes
-            // every image read blind even when pi adds no note — a claim its doctor probe proved
-            // false — which the parser checks against its own note rule.
-            imageInput: seamImageInput(opts.config, readPiProviders(piModelsPath())),
-            onBlindRead: (path) => {
-                // Kill an authoring run at once, before the agent goes on working from a picture it
-                // never saw (terminateChild is what the watchdogs use). Gate runs (reviewer,
-                // resolver) only record the read and keep going.
-                if (opts.kind === "author") {
-                    blindRead = path;
-                    terminateRun?.();
-                }
-            },
-        });
-        // The run's cross-group attribution mark, minted before the spawn so the environment can
-        // carry it and the exit sweep can name it.
-        const runMarker = makeRunMarker();
-        const resolved = backend.resolveBin(opts.config);
-        // Install the notes shim under the team root's `.tumwater/bin` so every backend's run finds
-        // `tumwater-notes` first on PATH (notes-shim.ts). A failure to write it logs one warning and
-        // the run goes on without it — notes would then be unwritable by the command, but the run
-        // itself is not blocked.
+        let parser;
+        let runMarker;
+        let resolved;
         let binDir;
+        let runSpec;
         try {
-            // Install the shim only under a real team root — the nearest ancestor holding a
-            // `.tumwater`. A session dir with no such ancestor (a lab script, a smoke run, a
-            // prompt-lab replay) must never mint one: nearestTumwaterRoot is undefined then, and the
-            // run goes on without the shim, exactly as if the install had failed — writing
-            // `<fallback>/.tumwater` from a run created a phantom harness root in a shared directory
-            // and broke every other suite on the host (BUGS.md 2026-10-18).
-            const root = nearestTumwaterRoot(opts.sessionDir);
-            if (root !== undefined)
-                binDir = ensureNotesShim(root);
+            // The marker precedes this run's first event in file order — written to the same stream
+            // stdout lines flow through, before spawn, so ordering is exact by construction; on a
+            // failed spawn finish() still ends the stream and flushes it. Exactly one per run: the
+            // kind, agent and start time are always there, the label only when the caller set one
+            // (`history <role> <n> --transcript` selects a run's segments by this ts).
+            {
+                const marker = {
+                    type: "tumwater_run",
+                    kind: opts.kind,
+                    agent: backend.id,
+                    ts: Date.now(),
+                };
+                if (opts.label)
+                    marker.label = opts.label;
+                rawLog.stream.write(JSON.stringify(marker) + "\n");
+            }
+            // The first blind image read an authoring run made (plans/image-input.md "Detecting a
+            // blind read"): the path, plus an indirection to the child so the parser's parse-time
+            // callback (which fires during feed, after spawn) can kill it. Unset for a gate run,
+            // which only records the read. Declared before the parser so its onBlindRead closure
+            // (which assigns them at parse time, after spawn) can reference them.
+            parser = new PiStreamParser(opts.onToolCallStart, {
+                // The seam's effective image input (src/agent/image-input.ts): a text-only seam makes
+                // every image read blind even when pi adds no note — a claim its doctor probe proved
+                // false — which the parser checks against its own note rule.
+                imageInput: seamImageInput(opts.config, readPiProviders(piModelsPath())),
+                onBlindRead: (path) => {
+                    // Kill an authoring run at once, before the agent goes on working from a picture it
+                    // never saw (terminateChild is what the watchdogs use). Gate runs (reviewer,
+                    // resolver) only record the read and keep going.
+                    if (opts.kind === "author") {
+                        blindRead = path;
+                        terminateRun?.();
+                    }
+                },
+            });
+            // The run's cross-group attribution mark, minted before the spawn so the environment can
+            // carry it and the exit sweep can name it.
+            runMarker = makeRunMarker();
+            resolved = backend.resolveBin(opts.config);
+            // Install the notes shim under the team root's `.tumwater/bin` so every backend's run
+            // finds `tumwater-notes` first on PATH (notes-shim.ts). A failure to write it logs one
+            // warning and the run goes on without it — notes would then be unwritable by the command,
+            // but the run itself is not blocked.
+            try {
+                // Install the shim only under a real team root — the nearest ancestor holding a
+                // `.tumwater`. A session dir with no such ancestor (a lab script, a smoke run, a
+                // prompt-lab replay) must never mint one: nearestTumwaterRoot is undefined then, and
+                // the run goes on without the shim, exactly as if the install had failed — writing
+                // `<fallback>/.tumwater` from a run created a phantom harness root in a shared
+                // directory and broke every other suite on the host (BUGS.md 2026-10-18).
+                const root = nearestTumwaterRoot(opts.sessionDir);
+                if (root !== undefined)
+                    binDir = ensureNotesShim(root);
+            }
+            catch {
+                opts.onAgentWarning?.("could not install the tumwater-notes shim; this run will not find tumwater-notes on PATH");
+            }
+            runSpec = {
+                cwd: opts.cwd,
+                prompt: opts.prompt,
+                config: opts.config,
+                sessionDir: opts.sessionDir,
+                sessionName: opts.sessionName,
+                continueSession: opts.continueSession,
+                kind: opts.kind,
+                agentBin: resolved.bin,
+                runMarker,
+                notesPath: opts.notesPath,
+                ...(binDir !== undefined ? { binDir } : {}),
+                ...(opts.maxBudgetUsd !== undefined ? { maxBudgetUsd: opts.maxBudgetUsd } : {}),
+            };
         }
-        catch {
-            opts.onAgentWarning?.("could not install the tumwater-notes shim; this run will not find tumwater-notes on PATH");
+        catch (err) {
+            // A synchronous throw in the run's pre-spawn setup (marker, parser construction,
+            // resolveBin) rejects the run, restoring the rejection a synchronous executor's throw
+            // used to get from the Promise constructor.
+            reject(err instanceof Error ? err : new Error(`runAgent: ${String(err)}`));
+            return;
         }
-        const runSpec = {
-            cwd: opts.cwd,
-            prompt: opts.prompt,
-            config: opts.config,
-            sessionDir: opts.sessionDir,
-            sessionName: opts.sessionName,
-            continueSession: opts.continueSession,
-            kind: opts.kind,
-            agentBin: resolved.bin,
-            runMarker,
-            notesPath: opts.notesPath,
-            ...(binDir !== undefined ? { binDir } : {}),
-            ...(opts.maxBudgetUsd !== undefined ? { maxBudgetUsd: opts.maxBudgetUsd } : {}),
-        };
-        const invocation = backend.invocation(runSpec);
-        // Record the run in the session ledger before its spawn, so a later resume can pick the
-        // newest session of its own kind instead of whatever file is newest in the dir. The id is
-        // the backend's own when it mints one ahead of the run (claude's UUID, or the resumed
-        // record's id); pi mints none and keeps the session name.
-        recordSession(opts.sessionDir, {
-            agent: backend.id,
-            id: invocation.sessionId ?? opts.sessionName,
-            kind: opts.kind,
-            name: opts.sessionName,
-            cwd: opts.cwd,
-            ...(opts.config.model !== undefined ? { model: opts.config.model } : {}),
-            at: Date.now(),
-        });
-        const translator = backend.translator();
-        // Decode stdout incrementally instead of per chunk: a raw Buffer.toString("utf8")
-        // replaces any multi-byte character whose bytes straddle two 'data' events with U+FFFD,
-        // corrupting that line's text (commit subjects, summaries, transcripts). StringDecoder
-        // holds back the incomplete trailing bytes until the next chunk completes them.
-        const decoder = new StringDecoder("utf8");
-        // stderr gets its own incremental decoder for the same reason: the failure message and
-        // the stderr-keyed matchers (crash, stream-severed, config) read this buffer, so a
-        // character whose bytes straddle two 'data' events must not become U+FFFD.
-        const stderrDecoder = new StringDecoder("utf8");
-        let stderr = "";
-        // The fallback-clone warning arrives at the START of a run, while `stderr` keeps only the
-        // last 64 KiB; match each chunk (with a short carried tail for a straddle) so a chatty run
-        // that pushes the warning out of that window still surfaces the mispriced id.
-        let fallbackClone;
-        let stderrTail = "";
-        let settled = false;
-        // The translator's native line buffer: feed the decoder's text through it and only complete
-        // lines reach the translator, whose canonical output feeds the parser (and the raw log).
-        // `nativeOverflow` marks a buffered line that passed MAX_NATIVE_LINE_CHARS without a newline:
-        // its remainder is skipped to the next newline so it can never be mistaken for an event.
-        let nativeTail = "";
-        let nativeOverflow = false;
-        // A private TMPDIR per run: concurrent agents default to literal /tmp names, and a shared
-        // per-user TMPDIR would still collide. Removed when the run settles.
-        const runTmp = fs.mkdtempSync(path.join(os.tmpdir(), "tumwater-run-"));
-        const child = spawn(resolved.bin, invocation.args, {
-            cwd: opts.cwd,
-            // A backend that feeds the prompt on stdin (every registered one) gets a pipe the runner
-            // writes and ends below; one that returns no stdin keeps stdio[0] "ignore".
-            stdio: [invocation.stdin !== undefined ? "pipe" : "ignore", "pipe", "pipe"],
-            // pi sets its process title at startup, and so does every npm its tool calls run: on
-            // macOS each would register with LaunchServices and leak a launchservicesd port.
-            // Detached so pi leads its own process group: terminateChild signals the group, so a
-            // run's tool-call grandchildren — killed or finished — die with it instead of leaking
-            // to launchd.
-            detached: true,
-            // The run's mark, inherited by every tool call and its descendants: pi 0.87.1's bash
-            // tool spawns each command detached in its OWN group, so the group sweep below cannot
-            // reach what a tool call backgrounds (BUGS.md 2026-09-30) — the mark is the only
-            // attribution that follows a reparented orphan. Appended to any inherited mark so a
-            // nested harness under test keeps the outer run's.
-            env: { ...invocation.env, TMPDIR: runTmp },
-        });
-        if (invocation.stdin !== undefined) {
-            // A backend that dies before draining its stdin — an immediately-failing startup such as
-            // an unknown flag, an unresumable session, or a not-logged-in exit — leaves this write
-            // nothing to feed. Once the prompt exceeds the OS pipe buffer the write then fails EPIPE,
-            // and an unhandled 'error' event on the stdin stream is thrown from the event loop and
-            // takes the whole process (the whole team) down. The child's own exit status and stderr
-            // already report why the run died, so swallowing the failed write adds no silence the
-            // caller needs to break; git.ts's patchId carries the same guard for a patch-id that
-            // dies before reading its input.
-            child.stdin?.on("error", () => { });
-            child.stdin?.end(invocation.stdin);
+        // A backend's asynchronous pre-run work (the codex write guard resolving its trust by
+        // spawning `app-server`, plans/codex-write-guard.md "Trust (parts 4–5)"): awaited just
+        // before the synchronous invocation, so trust is settled before invocation reads it. It
+        // never throws a run away — a throw is a warm-up failure, warned about on the run's own
+        // root (skipped with no root) and the run goes on; a codex trust lookup failure already
+        // records `off` and warns from prepare itself, so this catch is the guard for a backend
+        // whose prepare throws unexpectedly. The call itself is also guarded: a synchronous
+        // `prepare` throw would otherwise escape the async executor (leaving the run's promise
+        // pending and emitting an unhandled rejection), so it is warned-and-continued like an
+        // async rejection.
+        const warnRoot = nearestTumwaterRoot(opts.sessionDir);
+        let prepared;
+        try {
+            prepared = backend.prepare?.(runSpec);
         }
-        // Armed now that the child exists, so the parser's parse-time onBlindRead (fires during
-        // feed, always after spawn) can reach it.
-        terminateRun = () => terminateChild(child);
-        // The run's two watchdog clocks (src/pi/pi-watchdogs.ts): the tick deadline and the quiet
-        // watchdog (quiet-kill plus the stalled-tool-call warning). The flags their timers set
-        // (timedOut/timedOutProgressing/quietKilled/sawOutput) read live off the returned handle.
-        const wd = startPiWatchdogs({
-            progressCount: () => parser.progressCount,
-            openToolCalls: () => parser.openToolCalls,
-            tickTimeoutMs: opts.config.runTimeoutSeconds * 1000,
-            quietMs: opts.config.quietTimeoutSeconds * 1000,
-            stallMs: Math.max(0, opts.config.toolCallStallSeconds) * 1000,
-            // The run's backend id: claude never sends content updates, so the watchdog judges its
-            // every open call by the buffered wall-clock threshold (plans/agent-backends.md).
-            agent: backend.id,
-            // The gate's fresh-session runs (reviewer and conflict resolver) get one deadline
-            // extension while they are still making progress: a large diff's review otherwise
-            // times out mid-verification and the next attempt re-reads it from scratch
-            // (BUGS.md 2026-10-07). Authoring runs resume their session next tick, so one
-            // deadline stays right for them.
-            extendOnProgress: opts.kind === "gate",
-            kill: () => terminateChild(child),
-            onToolCallStalled: opts.onToolCallStalled,
-        });
-        let aborted = false;
-        const onAbort = () => {
-            aborted = true;
-            terminateChild(child);
-        };
-        runOnAbort(opts.signal, onAbort);
-        // Quiet watchdog and its stall warning: src/pi/pi-watchdogs.ts.
-        const onLine = (line) => rawLog.stream.write(line + "\n");
-        // Write one complete native line and feed its translation to the parser (which also hands
-        // the canonical lines to onLine for the raw log).
-        const emitNativeLine = (line) => {
-            if (!nativeLog.broken)
-                nativeLog.stream.write(line + "\n");
-            for (const canonical of translator.translate(line))
-                parser.feed(canonical + "\n", onLine);
-        };
-        // Split native stdout into complete lines, translate each, and feed the canonical lines to
-        // the parser (which also hands them to onLine for the raw log). A trailing partial native
-        // line stays buffered exactly as the parser's own buffer once held it. On the final flush
-        // (`final`), a remaining tail is emitted as one line: a backend may close after flushing a
-        // complete JSON event but not its newline terminator, and dropping that tail loses the
-        // run's authoritative result (cost, final text). A genuinely truncated fragment parses as
-        // no data (parseJsonObject → []), so this can only recover the last event.
-        const feedCanonical = (text, final = false) => {
-            // A buffered overflow: discard this line's remainder up to (and including) its newline, so
-            // the stream resynchronizes on the next real event line instead of emitting a truncated one.
-            if (nativeOverflow) {
-                const nl = text.indexOf("\n");
-                if (nl < 0)
-                    return;
-                nativeOverflow = false;
-                text = text.slice(nl + 1);
+        catch (error) {
+            if (warnRoot !== undefined) {
+                warnEventBestEffort(warnRoot, TUMWATER_SOURCE, `agent prepare failed, run continues: ${errorMessage(error)}`);
             }
-            nativeTail += text;
-            let start = 0;
-            for (;;) {
-                const nl = nativeTail.indexOf("\n", start);
-                if (nl < 0)
-                    break;
-                emitNativeLine(nativeTail.slice(start, nl));
-                start = nl + 1;
+        }
+        // Only a backend with a `prepare` step (codex) awaits it; for every other backend the run
+        // spawns synchronously, preserving the pre-`prepare` timing a logical-clock watchdog test
+        // relies on (pi-watchdogs advances a fake clock immediately after runPi returns).
+        if (prepared !== undefined) {
+            try {
+                await prepared;
             }
-            if (start > 0)
-                nativeTail = nativeTail.slice(start);
-            if (nativeTail.length > MAX_NATIVE_LINE_CHARS) {
-                // No newline within the cap: drop the line and warn. On the final flush there is no
-                // remainder to skip, so only the buffer is cleared.
-                nativeTail = "";
-                if (!final) {
-                    nativeOverflow = true;
-                    opts.onAgentWarning?.(`native output line exceeded ${MAX_NATIVE_LINE_CHARS / (1024 * 1024)} MiB without a newline and was discarded`);
+            catch (error) {
+                if (warnRoot !== undefined) {
+                    warnEventBestEffort(warnRoot, TUMWATER_SOURCE, `agent prepare failed, run continues: ${errorMessage(error)}`);
                 }
             }
-            else if (final && nativeTail !== "") {
-                emitNativeLine(nativeTail);
-                nativeTail = "";
-            }
-        };
-        child.stdout?.on("data", (chunk) => {
-            wd.noteByte();
-            feedCanonical(decoder.write(chunk));
-        });
-        child.stderr?.on("data", (chunk) => {
-            // stderr is rare and meaningful (crash traces, warnings): treat it as progress.
-            wd.noteStderr();
-            const text = stderrDecoder.write(chunk);
-            fallbackClone ??= backend.matchStderrWarning?.(text, stderrTail);
-            stderrTail = (stderrTail + text).slice(-STDERR_MATCH_TAIL);
-            stderr += text;
-            if (stderr.length > 64 * 1024)
-                stderr = stderr.slice(-64 * 1024);
-        });
-        const finish = (result) => {
-            if (settled)
-                return;
-            settled = true;
-            // A blind image read (plans/image-input.md "Detecting a blind read"): surface it to the
-            // caller once, at settle, with the action its kind earned — the authoring run was killed
-            // ("fail"), a gate run only recorded it ("logged"). The caller logs the image_blind event
-            // with its own loop/tick context.
-            if (parser.imageBlind) {
-                opts.onBlindRead?.(parser.imageBlind.path, opts.kind === "author" ? "fail" : "logged");
-            }
-            // Best-effort: an unremovable scratch dir (read-only subdir, a straggler still writing) must
-            // not throw out of the close handler before the run's result resolves.
-            try {
-                fs.rmSync(runTmp, { recursive: true, force: true, maxRetries: 3 });
-            }
-            catch {
-                /* left for the OS temp sweep */
+        }
+        try {
+            const invocation = backend.invocation(runSpec);
+            // The id the pre-spawn ledger record carries: a backend that mints one ahead of the run
+            // (claude, a codex resume), else the session name (pi, a fresh codex run — its id is born
+            // in the stream). The stream-mint pass below compares against it so a codex run appends
+            // its streamed thread id exactly once, and only when it differs from this.
+            const preSpawnSessionId = invocation.sessionId ?? opts.sessionName;
+            // Record the run in the session ledger before its spawn, so a later resume can pick the
+            // newest session of its own kind instead of whatever file is newest in the dir. The id is
+            // the backend's own when it mints one ahead of the run (claude's UUID, or the resumed
+            // record's id); pi mints none and keeps the session name.
+            recordSession(opts.sessionDir, {
+                agent: backend.id,
+                id: preSpawnSessionId,
+                kind: opts.kind,
+                name: opts.sessionName,
+                cwd: opts.cwd,
+                ...(opts.config.model !== undefined ? { model: opts.config.model } : {}),
+                at: Date.now(),
+            });
+            const translator = backend.translator();
+            // Decode stdout incrementally instead of per chunk: a raw Buffer.toString("utf8")
+            // replaces any multi-byte character whose bytes straddle two 'data' events with U+FFFD,
+            // corrupting that line's text (commit subjects, summaries, transcripts). StringDecoder
+            // holds back the incomplete trailing bytes until the next chunk completes them.
+            const decoder = new StringDecoder("utf8");
+            // stderr gets its own incremental decoder for the same reason: the failure message and
+            // the stderr-keyed matchers (crash, stream-severed, config) read this buffer, so a
+            // character whose bytes straddle two 'data' events must not become U+FFFD.
+            const stderrDecoder = new StringDecoder("utf8");
+            let stderr = "";
+            // The fallback-clone warning arrives at the START of a run, while `stderr` keeps only the
+            // last 64 KiB; match each chunk (with a short carried tail for a straddle) so a chatty run
+            // that pushes the warning out of that window still surfaces the mispriced id.
+            let fallbackClone;
+            let stderrTail = "";
+            let settled = false;
+            // The translator's native line buffer: feed the decoder's text through it and only complete
+            // lines reach the translator, whose canonical output feeds the parser (and the raw log).
+            // `nativeOverflow` marks a buffered line that passed MAX_NATIVE_LINE_CHARS without a newline:
+            // its remainder is skipped to the next newline so it can never be mistaken for an event.
+            let nativeTail = "";
+            let nativeOverflow = false;
+            const child = spawn(resolved.bin, invocation.args, {
+                cwd: opts.cwd,
+                // A backend that feeds the prompt on stdin (every registered one) gets a pipe the runner
+                // writes and ends below; one that returns no stdin keeps stdio[0] "ignore".
+                stdio: [invocation.stdin !== undefined ? "pipe" : "ignore", "pipe", "pipe"],
+                // pi sets its process title at startup, and so does every npm its tool calls run: on
+                // macOS each would register with LaunchServices and leak a launchservicesd port.
+                // Detached so pi leads its own process group: terminateChild signals the group, so a
+                // run's tool-call grandchildren — killed or finished — die with it instead of leaking
+                // to launchd.
+                detached: true,
+                // The run's mark, inherited by every tool call and its descendants: pi 0.87.1's bash
+                // tool spawns each command detached in its OWN group, so the group sweep below cannot
+                // reach what a tool call backgrounds (BUGS.md 2026-09-30) — the mark is the only
+                // attribution that follows a reparented orphan. Appended to any inherited mark so a
+                // nested harness under test keeps the outer run's.
+                env: { ...invocation.env, TMPDIR: runTmp },
+            });
+            if (invocation.stdin !== undefined) {
+                // A backend that dies before draining its stdin — an immediately-failing startup such as
+                // an unknown flag, an unresumable session, or a not-logged-in exit — leaves this write
+                // nothing to feed. Once the prompt exceeds the OS pipe buffer the write then fails EPIPE,
+                // and an unhandled 'error' event on the stdin stream is thrown from the event loop and
+                // takes the whole process (the whole team) down. The child's own exit status and stderr
+                // already report why the run died, so swallowing the failed write adds no silence the
+                // caller needs to break; git.ts's patchId carries the same guard for a patch-id that
+                // dies before reading its input.
+                child.stdin?.on("error", () => { });
+                child.stdin?.end(invocation.stdin);
             }
-            wd.stop();
-            opts.signal?.removeEventListener("abort", onAbort);
-            // Surface the translator's per-run warnings once, after all native lines were fed.
-            for (const warning of translator.warnings?.() ?? [])
-                opts.onAgentWarning?.(warning);
-            // Resolve only once the logs have flushed: writes complete on libuv's threadpool, so
-            // resolving before 'finish' can leave the tail of <role>.pi.jsonl (or the native log)
-            // unwritten — a tick that dies right after runAgent settles (an abort during a restart
-            // drain, a supervisor swap) loses its last lines. end()'s callback fires on 'finish';
-            // if a stream errors instead it never does, so settle from 'error' too — a broken log
-            // degrades to a lost log, never a stuck tick.
-            let resolved = false;
-            const settle = () => {
-                if (!resolved) {
-                    resolved = true;
-                    resolve(result);
+            // Armed now that the child exists, so the parser's parse-time onBlindRead (fires during
+            // feed, always after spawn) can reach it.
+            terminateRun = () => terminateChild(child);
+            // The run's two watchdog clocks (src/pi/pi-watchdogs.ts): the run deadline and the quiet
+            // watchdog (quiet-kill plus the stalled-tool-call warning). The flags their timers set
+            // (timedOut/timedOutProgressing/quietKilled/sawOutput) read live off the returned handle.
+            const wd = startPiWatchdogs({
+                progressCount: () => parser.progressCount,
+                openToolCalls: () => parser.openToolCalls,
+                runTimeoutMs: opts.config.runTimeoutSeconds * 1000,
+                quietMs: opts.config.quietTimeoutSeconds * 1000,
+                stallMs: Math.max(0, opts.config.toolCallStallSeconds) * 1000,
+                // The run's backend id: claude never sends content updates, so the watchdog judges its
+                // every open call by the buffered wall-clock threshold (plans/agent-backends.md).
+                agent: backend.id,
+                // The gate's fresh-session runs (reviewer and conflict resolver) get one deadline
+                // extension while they are still making progress: a large diff's review otherwise
+                // times out mid-verification and the next attempt re-reads it from scratch
+                // (BUGS.md 2026-10-07). Authoring agent runs resume their session on the next one, so one
+                // deadline stays right for them.
+                extendOnProgress: opts.kind === "gate",
+                kill: () => terminateChild(child),
+                onToolCallStalled: opts.onToolCallStalled,
+            });
+            let aborted = false;
+            // A blind image read on an authoring run deliberately kills it, like the watchdogs do.
+            const wasKilled = () => aborted || wd.timedOut || wd.quietKilled || blindRead !== undefined;
+            const onAbort = () => {
+                aborted = true;
+                terminateChild(child);
+            };
+            runOnAbort(opts.signal, onAbort);
+            // Quiet watchdog and its stall warning: src/pi/pi-watchdogs.ts.
+            const onLine = (line) => rawLog.stream.write(line + "\n");
+            // The translator's session id, once the stream has named it (codex's `thread.started`).
+            // The pre-spawn record for a fresh codex run carries the session name; the id it actually
+            // ran with is born in the stream, so the first time this returns one the pre-spawn record
+            // lacked, append a second ledger record carrying it (same kind, name, cwd and model) — the
+            // record a later `exec resume` resumes (design §4 "Sessions").
+            let streamMintedSession = false;
+            const emitNativeLine = (line) => {
+                if (!nativeLog.broken)
+                    nativeLog.stream.write(line + "\n");
+                for (const canonical of translator.translate(line))
+                    parser.feed(canonical + "\n", onLine);
+                const sid = translator.sessionId?.();
+                if (sid !== undefined && sid !== preSpawnSessionId && !streamMintedSession) {
+                    streamMintedSession = true;
+                    recordSession(opts.sessionDir, {
+                        agent: backend.id,
+                        id: sid,
+                        kind: opts.kind,
+                        name: opts.sessionName,
+                        cwd: opts.cwd,
+                        ...(opts.config.model !== undefined ? { model: opts.config.model } : {}),
+                        at: Date.now(),
+                    });
                 }
             };
-            let pending = 0;
-            const flushed = () => {
-                pending -= 1;
-                if (pending === 0)
-                    settle();
+            // Split native stdout into complete lines, translate each, and feed the canonical lines to
+            // the parser (which also hands them to onLine for the raw log). A trailing partial native
+            // line stays buffered exactly as the parser's own buffer once held it. On the final flush
+            // (`final`), a remaining tail is emitted as one line: a backend may close after flushing a
+            // complete JSON event but not its newline terminator, and dropping that tail loses the
+            // run's authoritative result (cost, final text). A genuinely truncated fragment parses as
+            // no data (parseJsonObject → []), so this can only recover the last event.
+            const feedCanonical = (text, final = false) => {
+                // A buffered overflow: discard this line's remainder up to (and including) its newline, so
+                // the stream resynchronizes on the next real event line instead of emitting a truncated one.
+                if (nativeOverflow) {
+                    const nl = text.indexOf("\n");
+                    if (nl < 0)
+                        return;
+                    nativeOverflow = false;
+                    text = text.slice(nl + 1);
+                }
+                nativeTail += text;
+                let start = 0;
+                for (;;) {
+                    const nl = nativeTail.indexOf("\n", start);
+                    if (nl < 0)
+                        break;
+                    emitNativeLine(nativeTail.slice(start, nl));
+                    start = nl + 1;
+                }
+                if (start > 0)
+                    nativeTail = nativeTail.slice(start);
+                if (nativeTail.length > MAX_NATIVE_LINE_CHARS) {
+                    // No newline within the cap: drop the line and warn. On the final flush there is no
+                    // remainder to skip, so only the buffer is cleared.
+                    nativeTail = "";
+                    if (!final) {
+                        nativeOverflow = true;
+                        opts.onAgentWarning?.(`native output line exceeded ${MAX_NATIVE_LINE_CHARS / (1024 * 1024)} MiB without a newline and was discarded`);
+                    }
+                }
+                else if (final && nativeTail !== "") {
+                    emitNativeLine(nativeTail);
+                    nativeTail = "";
+                }
             };
-            for (const log of [rawLog, nativeLog]) {
-                log.stream.on("error", settle);
-                if (!log.broken) {
-                    pending += 1;
-                    log.stream.end(flushed);
+            child.stdout?.on("data", (chunk) => {
+                wd.noteByte();
+                feedCanonical(decoder.write(chunk));
+            });
+            child.stderr?.on("data", (chunk) => {
+                // stderr is rare and meaningful (crash traces, warnings): treat it as progress.
+                wd.noteStderr();
+                const text = stderrDecoder.write(chunk);
+                fallbackClone ??= backend.matchStderrWarning?.(text, stderrTail);
+                stderrTail = (stderrTail + text).slice(-STDERR_MATCH_TAIL);
+                stderr += text;
+                if (stderr.length > 64 * 1024)
+                    stderr = stderr.slice(-64 * 1024);
+            });
+            const finish = (result) => {
+                if (settled)
+                    return;
+                settled = true;
+                // A blind image read (plans/image-input.md "Detecting a blind read"): surface it to the
+                // caller once, at settle, with the action its kind earned — the authoring run was killed
+                // ("fail"), a gate run only recorded it ("logged"). The caller logs the image_blind event
+                // with its own role/run context.
+                if (parser.imageBlind) {
+                    opts.onBlindRead?.(parser.imageBlind.path, opts.kind === "author" ? "fail" : "logged");
                 }
-            }
-            if (pending === 0)
-                settle();
-        };
-        // Every PiRunResult is built here from what the parser has seen plus how the run ended,
-        // so adding a field to PiRunResult touches this single place. The spawn-error path passes
-        // only an errorMessage override: at that point no output ever arrived, so the parser holds
-        // exactly its initial values — which is precisely what a failed spawn reports.
-        const resultFromParser = (overrides) => ({
-            ok: false,
-            finalText: parser.finalText,
-            nothingToDo: parser.declaredNothingToDo,
-            refused: parser.refused,
-            refusedReason: parser.refusedReason || undefined,
-            verdictText: parser.verdictText || undefined,
-            outputTokens: parser.outputTokens,
-            promptTokens: parser.promptTokens,
-            cacheReadTokens: parser.cacheReadTokens,
-            preEditPromptTokens: parser.preEditPromptTokens,
-            firstEditTurn: parser.firstEditTurn,
-            peakContextTokens: parser.peakContextTokens,
-            turns: parser.turns,
-            costUsd: parser.costUsd,
-            stopReason: parser.stopReason,
-            errorMessage: undefined,
-            timedOut: false,
-            timedOutProgressing: false,
-            quietKilled: false,
-            aborted,
-            contextExceeded: parser.contextExceeded,
-            transientServerTimeout: parser.transientServerTimeout,
-            transientRateLimit: parser.transientRateLimit,
-            transientBackend: parser.transientBackend,
-            backendKind: parser.backendFailureKind,
-            configError: parser.configError,
-            retryAfterSeconds: parser.retryAfterSeconds,
-            transientPiCrash: false,
-            fallbackClone,
-            finalMessageContentless: parser.finalMessageContentless,
-            producedAssistantContent: parser.producedAssistantContent,
-            compacted: parser.compacted,
-            budgetCapped: parser.budgetCapped,
-            resumeMissing: parser.resumeMissing,
-            billing: parser.billing,
-            rateWindows: parser.rateWindows.length > 0 ? parser.rateWindows : undefined,
-            usedOverage: parser.usedOverage,
-            ...overrides,
-        });
-        child.on("error", (err) => {
-            finish(resultFromParser({
-                errorMessage: spawnErrorMessage(resolved, err.message, backend),
-            }));
-        });
-        // Sweep the run however it ended, a normal exit included, in two passes:
-        //
-        // 1. The group pi led: pi exits before its orphans — a tool call's `(server &)` or
-        //    `cd … && server &` is reparented to PID 1 but stays in pi's group — and the harness
-        //    cannot rely on the model's own cleanup (BUGS.md 2026-09-23: qa's unauthenticated
-        //    `gui --all-interfaces` listened on the LAN for 7.5 hours after a tick that ended
-        //    "Everything checked out"). On 'exit', not 'close': pi has just been reaped, so the
-        //    pgid still names only its group (never reissued while a member lives), and an orphan
-        //    holding pi's stdio open dies now instead of holding 'close' — and the run — open.
-        //    Synchronous, so it adds nothing to the run's resolution; on the kill paths it
-        //    re-sends a SIGTERM the group already had.
-        //
-        // 2. The marker sweep: pi 0.87.1's bash tool starts every command detached, in its own
-        //    process group, so whatever a tool call backgrounds sits in a group whose leader is
-        //    not pi and pass 1 never reaches it (BUGS.md 2026-09-30 — leaked servers and test
-        //    workers outlived their ticks by hours). Every process the run started carries the
-        //    run's TUMWATER_RUN mark in its environment, so the same-user scan finds them
-        //    wherever they were reparented. Fire-and-forget: one process-table scan, never
-        //    awaited — the run resolves on pi's output, and the sweep's own SIGKILL escalation
-        //    (10 s) is unref'd like signalTree's.
-        child.on("exit", () => {
-            terminateChild(child);
-            void sweepRunMarker(runMarker).catch(() => { });
-        });
-        child.on("close", (code) => {
-            // Flush any bytes the decoder held back at stream end and any unterminated final line
-            // so the tail is not lost, then let the translator flush its own pending canonical
-            // line(s) — a batching backend's unclosed last assistant message, which a killed run
-            // never closes with a later event.
-            feedCanonical(decoder.end(), true);
-            for (const canonical of translator.finalize?.() ?? [])
-                parser.feed(canonical + "\n", onLine);
-            // A blind image read on an authoring run deliberately killed it (terminateRun above),
-            // so its exit is a kill like the watchdogs' — the half-done work is discarded.
-            const killed = aborted || wd.timedOut || wd.quietKilled || blindRead !== undefined;
-            // The backend's post-run reconciliation (opencode's authoritative session export), only
-            // when the run is not already settled (a failed spawn settles in the 'error' handler
-            // before 'close') and was not killed — a killed run's session is half-done and no export
-            // should spend its 10 s on it. Its lines are written and parsed like streamed ones, so
-            // they reach the raw log and the parser's authoritative fold (run_cost/run_usage).
-            if (!settled && !killed) {
-                for (const canonical of backend.afterRun?.(runSpec, invocation, translator) ?? []) {
-                    parser.feed(canonical + "\n", onLine);
+                // Best-effort: an unremovable scratch dir (read-only subdir, a straggler still writing) must
+                // not throw out of the close handler before the run's result resolves.
+                try {
+                    removeTree(runTmp);
                 }
-            }
-            const failed = killed ||
-                parser.stopReason === "error" ||
-                (code !== 0 && !parser.finalText.trim());
-            // The backend classifies the exit's stderr (pi: the transient JSON-parse crash, a
-            // provider-wide backend failure, a permanent config error). The runner merges that with
-            // the parser's own event-derived flags — one exit has one cause.
-            const cls = backend.classifyExit({ code, stderr, killed });
-            const stderrBackend = cls.backendKind;
-            const configError = !killed &&
-                cls.transientPiCrash !== true &&
-                stderrBackend === undefined &&
-                (parser.configError || cls.configError === true);
-            // The blind-read failure names both the file and the model (plans/image-input.md
-            // "Failing the tick"): take it over any generic exit text so lastError is actionable.
-            const errorMessage = blindRead !== undefined
-                ? `read ${blindRead}, but ${opts.config.model ?? "the model"} cannot read images`
-                : aborted
-                    ? "stopped by tumwater shutdown"
-                    : wd.quietKilled
-                        ? `killed as hung: no agent progress for over ${opts.config.quietTimeoutSeconds}s`
-                        : wd.timedOut
-                            ? wd.timedOutProgressing
-                                ? `timed out after ${wd.timeoutBudgetMs / 1000}s while still making progress — session and worktree edits preserved for resume`
-                                : `timed out after ${wd.timeoutBudgetMs / 1000}s`
-                            : (parser.errorMessage ?? (failed ? stderr.trim().slice(-500) || `the agent exited ${code}` : undefined));
-            finish(resultFromParser({
-                ok: !failed,
-                transientPiCrash: cls.transientPiCrash === true,
-                transientBackend: parser.transientBackend || cls.transientBackend === true,
-                backendKind: parser.backendFailureKind ?? stderrBackend,
-                configError,
-                // Kept distinct on purpose: a hung tool call leaves its session and worktree edits
-                // intact, so the loop resumes them (quiet_killed) instead of discarding them as an
-                // unfulfilled timeout does. A deadline that fired on a run still making progress
-                // gets the same treatment (BUGS.md 2026-09-29).
-                timedOut: wd.timedOut,
-                timedOutProgressing: wd.timedOut && wd.timedOutProgressing,
-                quietKilled: wd.quietKilled,
-                imageBlind: parser.imageBlind,
-                errorMessage,
-            }));
-        });
+                catch {
+                    /* left for the OS temp sweep */
+                }
+                wd.stop();
+                opts.signal?.removeEventListener("abort", onAbort);
+                // Surface the translator's per-run warnings once, after all native lines were fed.
+                for (const warning of translator.warnings?.() ?? [])
+                    opts.onAgentWarning?.(warning);
+                // Resolve only once the logs have flushed: writes complete on libuv's threadpool, so
+                // resolving before 'finish' can leave the tail of <role>.pi.jsonl (or the native log)
+                // unwritten — a run that dies right after runAgent settles (an abort during a restart
+                // drain, a supervisor swap) loses its last lines. end()'s callback fires on 'finish';
+                // if a stream errors instead it never does, so settle from 'error' too — a broken log
+                // degrades to a lost log, never a stuck run.
+                let resolved = false;
+                const settle = () => {
+                    if (!resolved) {
+                        resolved = true;
+                        resolve(result);
+                    }
+                };
+                let pending = 0;
+                const flushed = () => {
+                    pending -= 1;
+                    if (pending === 0)
+                        settle();
+                };
+                for (const log of [rawLog, nativeLog]) {
+                    log.stream.on("error", settle);
+                    if (!log.broken) {
+                        pending += 1;
+                        log.stream.end(flushed);
+                    }
+                }
+                if (pending === 0)
+                    settle();
+            };
+            // The run state the settlement-half handlers (run-settle.ts) read when their event
+            // fires. The getters read through to the run's still-mutating feed state, so a handler
+            // sees the current value rather than a snapshot taken when its listener was registered.
+            const state = {
+                child,
+                resolved,
+                backend,
+                runMarker,
+                parser,
+                translator,
+                decoder,
+                wd,
+                finish,
+                feedCanonical,
+                onLine,
+                runSpec,
+                invocation,
+                stderr: () => stderr,
+                fallbackClone: () => fallbackClone,
+                settled: () => settled,
+                blindRead: () => blindRead,
+                aborted: () => aborted,
+                wasKilled: () => wasKilled(),
+                kind: opts.kind,
+                config: opts.config,
+                onLeftoversSwept: opts.onLeftoversSwept,
+            };
+            child.on("error", (err) => {
+                settleError(state, err);
+            });
+            // Sweep the run however it ended, a normal exit included, in two passes:
+            //
+            // 1. The group pi led: pi exits before its orphans — a tool call's `(server &)` or
+            //    `cd … && server &` is reparented to PID 1 but stays in pi's group — and the harness
+            //    cannot rely on the model's own cleanup (BUGS.md 2026-09-23: qa's unauthenticated
+            //    `gui --all-interfaces` listened on the LAN for 7.5 hours after a run that ended
+            //    "Everything checked out"). On 'exit', not 'close': pi has just been reaped, so the
+            //    pgid still names only its group (never reissued while a member lives), and an orphan
+            //    holding pi's stdio open dies now instead of holding 'close' — and the run — open.
+            //    Synchronous, so it adds nothing to the run's resolution; on the kill paths it
+            //    re-sends a SIGTERM the group already had.
+            //
+            // 2. The marker sweep: pi 0.87.1's bash tool starts every command detached, in its own
+            //    process group, so whatever a tool call backgrounds sits in a group whose leader is
+            //    not pi and pass 1 never reaches it (BUGS.md 2026-09-30 — leaked servers and test
+            //    workers outlived their runs by hours). Every process the run started carries the
+            //    run's TUMWATER_RUN mark in its environment, so the same-user scan finds them
+            //    wherever they were reparented. Fire-and-forget: one process-table scan, never
+            //    awaited — the run resolves on pi's output, and the sweep's own SIGKILL escalation
+            //    (10 s) is unref'd like signalTree's.
+            child.on("exit", () => {
+                settleExit(state);
+            });
+            child.on("close", (code) => {
+                settleClose(state, code);
+            });
+        }
+        catch (err) {
+            // A synchronous throw in the run's build-and-spawn stage (claude's invocation rejects a
+            // run with no resolved model) rejects the run, preserving the contract a synchronous
+            // executor's throw used to get from the Promise constructor.
+            reject(err instanceof Error ? err : new Error(`runAgent: ${String(err)}`));
+        }
     });
 }
 /** The historical name for the neutral runner: every existing call site, fake, and test keeps