tumwater 0.4.0 → 0.4.2

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

@@ -1,62 +1,41 @@
 /** 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, and stderr capture. The backend (src/agent/agent-backend.ts, with
+ * needs regardless of which agent it drives — 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
+ * matcher, and the exit classification. This file keeps the coordinator — setup, the watchdog
+ * wiring, abort, the child's stream-attachment and the settlement-state assembly — and
+ * delegates the build-and-spawn stage (the marker,
+ * parser, bin resolution, `prepare`, invocation and spawn) to src/agent/run-spawn.ts, the
+ * streaming pipeline (native-to-canonical stdout split, the stderr window, the stream-minted
+ * session record and the settle/flush) to src/agent/run-stream.ts, and 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, removeTree, rotateIfLarge } from "../files/files.js";
+import { ensureDir, removeTree } from "../files/files.js";
 import { runOnAbort, terminateChild } from "../process/process.js";
-import { makeRunMarker } from "../process/run-marker.js";
-import { PiStreamParser } from "../pi/pi-stream.js";
 import { startPiWatchdogs } from "../pi/pi-watchdogs.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";
-import { piModelsPath, readPiProviders } from "../pi/pi-models.js";
-/** How many trailing stderr characters are carried into the next chunk's warning match, so a
- * warning split across two `data` events is still seen. The warnings are short lines, so a few
- * hundred characters always cover a straddle. */
-const STDERR_MATCH_TAIL = 512;
-/** The largest native stdout line the runner will buffer. A complete native event is one JSON
- * 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 run
- * timeout (4 h by default) exhausts the harness's memory. */
-export const MAX_NATIVE_LINE_CHARS = 16 * 1024 * 1024;
+import { openAppendLog, spawnPiRun } from "./run-spawn.js";
+import { createAgentStream } from "./run-stream.js";
+// The streaming pipeline's over-long-native-line cap stays reachable from here, the historical
+// home the test suite still imports it from, even though the value now lives in run-stream.ts.
+export { MAX_NATIVE_LINE_CHARS } from "./run-stream.js";
 // The seam's adapters. Registering here — where the lookup happens — keeps the registration
 // explicit and lets a test register a fake under its own id.
 registerAgentBackend(piBackend);
 registerAgentBackend(claudeBackend);
 registerAgentBackend(opencodeBackend);
 registerAgentBackend(codexBackend);
-function openAppendLog(file, maxBytes) {
-    ensureParentDir(file);
-    rotateIfLarge(file, maxBytes);
-    const log = { stream: fs.createWriteStream(file, { flags: "a" }), broken: false };
-    log.stream.on("error", () => {
-        log.broken = true;
-    });
-    return log;
-}
 /** Run the configured agent backend non-interactively in a worktree and distill the result.
  * Never throws: a setup failure (session dir, log file, scratch dir) resolves as a failed run
  * whose errorMessage names it. */
@@ -95,209 +74,33 @@ export function runAgent(opts) {
             resolve(setupFailureResult(backend.id, `could not prepare the agent run: ${errorMessage(err)}`));
             return;
         }
-        // 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;
-        let parser;
-        let runMarker;
-        let resolved;
-        let binDir;
-        let runSpec;
         try {
-            // 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 (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;
-        }
-        // 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);
-        }
-        catch (error) {
-            if (warnRoot !== undefined) {
-                warnEventBestEffort(warnRoot, TUMWATER_SOURCE, `agent prepare failed, run continues: ${errorMessage(error)}`);
-            }
-        }
-        // 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;
-            }
-            catch (error) {
-                if (warnRoot !== undefined) {
-                    warnEventBestEffort(warnRoot, TUMWATER_SOURCE, `agent prepare failed, run continues: ${errorMessage(error)}`);
-                }
-            }
-        }
-        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);
-            }
-            // 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 whole build-and-spawn stage — the marker write, parser construction, run marker,
+            // backend-bin resolution, notes shim, run spec, the backend's optional `prepare`, the
+            // session-ledger record, translator/decoders, and the child spawn — now lives in
+            // spawnPiRun (src/agent/run-spawn.ts) and returns the SpawnedRun bundle. A synchronous
+            // throw anywhere in it (a broken marker write, parser construction, backend.resolveBin,
+            // claude's invocation rejecting a run with no model) propagates out of the await and is
+            // rejected by the catch below, matching what a synchronous executor's throw used to get
+            // from the Promise constructor.
+            // A backend without a `prepare` step (pi, claude, opencode) builds and spawns synchronously
+            // and hands the bundle straight back, so the `instanceof` below takes the sync leg and the
+            // watchdogs (a setInterval registration) start in the same synchronous step the logical-clock
+            // watchdog tests pin (they advance the fake clock immediately after runPi returns). A backend
+            // WITH a `prepare` (codex) returns a promise that resolves after its trust is settled.
+            const spawnedResult = spawnPiRun(backend, { raw: rawLog }, runTmp, opts);
+            const spawned = spawnedResult instanceof Promise ? await spawnedResult : spawnedResult;
+            // Bind the coordinator's objects from the bundle, then hand the stream-side objects (parser,
+            // translator, decoders) to createAgentStream below, which owns them with the pipeline.
+            const child = spawned.child;
+            const resolved = spawned.resolved;
+            const runSpec = spawned.runSpec;
+            const invocation = spawned.invocation;
+            const parser = spawned.parser;
+            const translator = spawned.translator;
+            const decoder = spawned.decoder;
+            const runMarker = spawned.runMarker;
+            const blindRead = spawned.blindRead;
             // 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.
@@ -321,148 +124,30 @@ export function runAgent(opts) {
             });
             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 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(),
-                    });
-                }
-            };
-            // 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 = "";
-                }
-            };
-            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);
+            // The streaming pipeline — native-to-canonical stdout split with the over-long-line
+            // discard, the stderr window and its fallback-clone warning matcher, the stream-minted
+            // session's second ledger record, and the settle/flush that resolves the run — now lives
+            // in src/agent/run-stream.ts behind the AgentStream interface. run-agent only wires the
+            // child's `data` events to it and binds its getters into the settlement state below.
+            const stream = createAgentStream({
+                opts,
+                backend,
+                spawned,
+                wd,
+                onAbort,
+                rawLog,
+                nativeLog,
+                runTmp,
+                resolve,
             });
-            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");
-                }
-                // 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);
-                }
-                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();
-            };
+            child.stdout?.on("data", (chunk) => stream.feedStdout(chunk));
+            child.stderr?.on("data", (chunk) => stream.feedStderr(chunk));
             // 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.
@@ -475,15 +160,15 @@ export function runAgent(opts) {
                 translator,
                 decoder,
                 wd,
-                finish,
-                feedCanonical,
-                onLine,
+                finish: stream.finish,
+                feedCanonical: stream.feedCanonical,
+                onLine: stream.onLine,
                 runSpec,
                 invocation,
-                stderr: () => stderr,
-                fallbackClone: () => fallbackClone,
-                settled: () => settled,
-                blindRead: () => blindRead,
+                stderr: stream.stderr,
+                fallbackClone: stream.fallbackClone,
+                settled: stream.settled,
+                blindRead: () => blindRead(),
                 aborted: () => aborted,
                 wasKilled: () => wasKilled(),
                 kind: opts.kind,
@@ -523,7 +208,16 @@ export function runAgent(opts) {
         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.
+            // executor's throw used to get from the Promise constructor. No child was spawned, so no
+            // `error`/`close` ever fires and the settle path that removes the private TMPDIR
+            // (run-stream.ts's finish) never runs — remove it here, best-effort like finish does, so
+            // a broken run does not leave a `tumwater-run-*` temp dir behind.
+            try {
+                removeTree(runTmp);
+            }
+            catch {
+                /* left for the OS temp sweep */
+            }
             reject(err instanceof Error ? err : new Error(`runAgent: ${String(err)}`));
         }
     });

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

@@ -2,8 +2,9 @@
  * same seam the runner-run → runner-outcome split used): everything that happens after the
  * run's live feed — the spawn-`error` result, the `exit` orphan sweep, and the `close`-time
  * flush/reconcile/classify that builds the `PiRunResult`. run-agent.ts keeps the lifecycle
- * (pre-spawn setup, `prepare`, spawn, decoders, stream pipeline, watchdogs, the feed) and
- * delegates its `error`/`exit`/`close` listeners here, so the streaming half stays readable.
+ * (setup, watchdogs, the feed), delegates its build-and-spawn stage to src/agent/run-spawn.ts,
+ * its streaming pipeline to src/agent/run-stream.ts and its `error`/`exit`/`close` listeners
+ * here, so the streaming half stays readable.
  *
  * Each handler takes the run's live state (`RunSettleState`, defined in run-agent.ts and
  * imported here only as a type) and reads what it closes over at the moment its event fires —
@@ -143,6 +144,27 @@ export function settleExit(state) {
     })
         .catch(() => { });
 }
+/** Settle the run's `lastError` text in priority order: a failed blind image read names both
+ * the file and the model (plans/image-input.md "Failing the run"), then the abort, quiet-kill
+ * and timeout causes the watchdogs and signal path set, then the parser's own event-derived
+ * error, else the raw stderr tail. Undefined for a run that simply ended with a message. */
+function settleErrorMessage(state, blindRead, failed, stderr, code) {
+    if (blindRead !== undefined) {
+        return `read ${blindRead}, but ${state.config.model ?? "the model"} cannot read images`;
+    }
+    if (state.aborted())
+        return "stopped by tumwater shutdown";
+    if (state.wd.quietKilled) {
+        return `killed as hung: no agent progress for over ${state.config.quietTimeoutSeconds}s`;
+    }
+    if (state.wd.timedOut) {
+        return state.wd.timedOutProgressing
+            ? `timed out after ${state.wd.timeoutBudgetMs / 1000}s while still making progress — session and worktree edits preserved for resume`
+            : `timed out after ${state.wd.timeoutBudgetMs / 1000}s`;
+    }
+    return (state.parser.errorMessage ??
+        (failed ? stderr.trim().slice(-500) || `the agent exited ${code}` : undefined));
+}
 /** The run's `close` event: the process died and all its streams closed. Flush what the
  * decoders held back, reconcile the backend's post-run work, classify the exit cause, and
  * settle the run's result. */
@@ -181,20 +203,8 @@ export function settleClose(state, code) {
         cls.transientPiCrash !== true &&
         stderrBackend === undefined &&
         (state.parser.configError || cls.configError === true);
-    // The blind-read failure names both the file and the model (plans/image-input.md
-    // "Failing the run"): take it over any generic exit text so lastError is actionable.
     const blindRead = state.blindRead();
-    const errorMessage = blindRead !== undefined
-        ? `read ${blindRead}, but ${state.config.model ?? "the model"} cannot read images`
-        : state.aborted()
-            ? "stopped by tumwater shutdown"
-            : state.wd.quietKilled
-                ? `killed as hung: no agent progress for over ${state.config.quietTimeoutSeconds}s`
-                : state.wd.timedOut
-                    ? state.wd.timedOutProgressing
-                        ? `timed out after ${state.wd.timeoutBudgetMs / 1000}s while still making progress — session and worktree edits preserved for resume`
-                        : `timed out after ${state.wd.timeoutBudgetMs / 1000}s`
-                    : (state.parser.errorMessage ?? (failed ? stderr.trim().slice(-500) || `the agent exited ${code}` : undefined));
+    const errorMessage = settleErrorMessage(state, blindRead, failed, stderr, code);
     state.finish(resultFromParser(state, {
         ok: !failed,
         transientPiCrash: cls.transientPiCrash === true,