tumwater 0.4.1 → 0.4.3

package/README.md

@@ -42,7 +42,7 @@ and is also outside `npm test`.
 ## Status
 
 <!-- tumwater:status:start -->
-**v0.4.1**: working tumwater. The director and 15 of the 17 roles are enabled by default; `selfcheck`,
+**v0.4.3**: working tumwater. The director and 15 of the 17 roles are enabled by default; `selfcheck`,
 which files tumwater bugs from tumwater's own event log, and `feedback`, which files them as GitHub
 issues on znation/tumwater, are opt-in (`roles.selfcheck.enabled`, `roles.feedback.enabled`).
 
@@ -77,8 +77,7 @@ so pair it with `--token <secret>`.
 `tumwater prompt --attach <image>` gives a role an image to read at its next run. When a role's
 model cannot read images, the command refuses the attachment up front (naming the fix) unless
 the role reroutes a blind read to a vision model, in which case it says where the message will
-run; `tumwater doctor` probes each claimed image-input model once (cached 7 days, `--reprobe` to
-force) and the dashboards and `tumwater role <id>` say which roles read images and where a blind
+run; the dashboards and `tumwater role <id>` say which roles read images and where a blind
 run reroutes.
 
 Every command, flag, and TUI key is in [docs/cli.md](docs/cli.md); `tumwater help` prints the
@@ -109,8 +108,7 @@ object with both, so one config can mix a Claude strong tier with pi providers:
 
 The default tier runs on pi through Hugging Face, the strong model jobs (the director, the plan
 role, the reviewer, and the conflict resolver) run on the claude CLI's included usage, and the fallback runs on pi through
-oMLX — all concurrently, under each provider's cap (set it with `maxConcurrentPerProvider`;
-`tumwater status` shows how many runs each key has going out of its cap). An OpenCode tier is
+oMLX — all concurrently, under the team's `maxConcurrent` cap. An OpenCode tier is
 `{ "backend": "opencode", "model": "deepseek-v4.1-flash-free" }`, so its free tier can sit beside pi
 and claude in one config; a codex tier is `{ "backend": "codex", "model": "gpt-6.1-sol" }`, so a ChatGPT
 subscription can cover the team's default tier beside pi and claude. A Claude model that should stay on pi (billed per token) is the plain

package/dist/build-info.json

@@ -1,5 +1,5 @@
 {
-  "sha": "defe3e5dd243a9eb3c844751752328d88f5ad674",
-  "builtAt": 1792989016668,
+  "sha": "45348f61e3e060de873bbd10ce8cdea30e4102d6",
+  "builtAt": 1793264084617,
   "root": "/home/runner/work/tumwater/tumwater"
 }

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

@@ -1,16 +1,16 @@
 /** The backend seam (plans/agent-backends.md "The seam"): what one non-interactive agent
  * run needs from its backend — how to build the command, how to translate its native stdout
- * into tumwater's canonical event stream, and how to classify its exit. src/agent/run-spawn.ts
- * builds and spawns the run (the marker, parser, bin resolution and spawn); src/agent/run-agent.ts
+ * into tumwater's canonical event stream, and how to classify its exit. src/agent/agent-spawn.ts
+ * builds and spawns the run (the marker, parser, bin resolution and spawn); src/agent/agent-run.ts
  * keeps the coordinator — the backend-neutral watchdogs, the abort wiring and the settlement-state
- * assembly — while src/agent/run-stream.ts owns the streaming pipeline (native-to-canonical stdout
- * split and the stderr window) and the settle/flush; the
+ * assembly — while src/agent/agent-stream.ts owns the streaming pipeline (the native-to-canonical
+ * stdout split and the stderr window) and the settle/flush; the
  * post-run settlement — the group-kill and marker sweeps on exit, the spawn-error result and
  * the close-time reconcile/classify that builds the `PiRunResult` — lives in
- * src/agent/run-settle.ts. A backend registered here supplies the rest. src/agent/run-agent.ts
+ * src/agent/agent-settle.ts. A backend registered here supplies the rest. src/agent/agent-run.ts
  * registers the pi and claude adapters here.
  *
- * The registry is keyed by id and fed by explicit registration (src/agent/run-agent.ts
+ * The registry is keyed by id and fed by explicit registration (src/agent/agent-run.ts
  * registers both adapters at load), so a test can register a fake backend without importing a
  * real one. */
 import { hasResumableSession } from "./session-ledger.js";

package/dist/src/agent/{run-agent.js → agent-run.js}

@@ -6,16 +6,16 @@
  * 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
+ * parser, bin resolution, `prepare`, invocation and spawn) to src/agent/agent-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
+ * session record and the settle/flush) to src/agent/agent-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
+ * classify) to src/agent/agent-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 fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { ensureDir } from "../files/files.js";
+import { ensureDir, removeTree } from "../files/files.js";
 import { runOnAbort, terminateChild } from "../process/process.js";
 import { startPiWatchdogs } from "../pi/pi-watchdogs.js";
 import { DEFAULT_BACKEND, backendById, registerAgentBackend } from "./agent-backend.js";
@@ -24,12 +24,12 @@ 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 { openAppendLog, spawnPiRun } from "./run-spawn.js";
-import { createAgentStream } from "./run-stream.js";
+import { setupFailureResult, settleClose, settleError, settleExit } from "./agent-settle.js";
+import { openAppendLog, spawnPiRun } from "./agent-spawn.js";
+import { createAgentStream } from "./agent-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";
+// home the test suite still imports it from, even though the value now lives in agent-stream.ts.
+export { MAX_NATIVE_LINE_CHARS } from "./agent-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);
@@ -78,7 +78,7 @@ export function runAgent(opts) {
             // 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
+            // spawnPiRun (src/agent/agent-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
@@ -133,7 +133,7 @@ export function runAgent(opts) {
             // 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
+            // in src/agent/agent-stream.ts behind the AgentStream interface. agent-run only wires the
             // child's `data` events to it and binds its getters into the settlement state below.
             const stream = createAgentStream({
                 opts,
@@ -148,7 +148,7 @@ export function runAgent(opts) {
             });
             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
+            // The run state the settlement-half handlers (agent-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 = {
@@ -208,7 +208,29 @@ 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
+            // (agent-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 */
+            }
+            // The two append-log streams opened before the build-and-spawn stage (the raw and
+            // backend-native transcripts) are never handed to a stream-settlement path on this throw
+            // — there is no child and no finish(), so nothing else would ever end them — end them
+            // here best-effort (the same cleanup the outer setup-failure catch makes) or every
+            // rejected run leaks two open transcript descriptors that accumulate in the
+            // long-lived orchestrator process.
+            try {
+                rawLog?.stream.end();
+                nativeLog?.stream.end();
+            }
+            catch {
+                /* best-effort */
+            }
             reject(err instanceof Error ? err : new Error(`runAgent: ${String(err)}`));
         }
     });

package/dist/src/agent/{run-settle.js → agent-settle.js}

@@ -1,15 +1,15 @@
-/** The settlement half of a backend agent run (the split of src/agent/run-agent.ts along the
+/** The settlement half of a backend agent run (the split of src/agent/agent-run.ts along the
  * 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
- * (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
+ * flush/reconcile/classify that builds the `PiRunResult`. agent-run.ts keeps the lifecycle
+ * (setup, watchdogs, the feed), delegates its build-and-spawn stage to src/agent/agent-spawn.ts,
+ * its streaming pipeline to src/agent/agent-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
+ * Each handler takes the run's live state (`RunSettleState`, defined in agent-run.ts and
  * imported here only as a type) and reads what it closes over at the moment its event fires —
  * the live flags it needs are getters on that state. There is no runtime import cycle:
- * run-agent imports these functions at runtime, and this module imports only run-agent's type.
+ * agent-run imports these functions at runtime, and this module imports only agent-run's type.
  */
 import { backendBinConfigKey, backendBinSourceLabel } from "../pi/pi-bin.js";
 import { terminateChild } from "../process/process.js";
@@ -144,58 +144,91 @@ export function settleExit(state) {
     })
         .catch(() => { });
 }
-/** 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. */
-export function settleClose(state, code) {
-    const { backend, runSpec, invocation, translator, onLine } = state;
+/** 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));
+}
+/** Flush the tail the decoders and translator held back at stream end: the decoder's last
+ * bytes and unterminated final line, then a batching backend's unclosed final assistant
+ * message (which a killed run never closes with a later event). */
+function flushRunTail(state) {
     // 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.
     state.feedCanonical(state.decoder.end(), true);
-    for (const canonical of translator.finalize?.() ?? [])
-        state.parser.feed(canonical + "\n", onLine);
-    // A blind image read on an authoring run deliberately killed it, so its exit is a kill like
-    // the watchdogs' — the half-done work is discarded.
-    const killed = state.wasKilled();
+    for (const canonical of state.translator.finalize?.() ?? [])
+        state.parser.feed(canonical + "\n", state.onLine);
+}
+/** Reconcile the backend's post-run work (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). */
+function reconcileBackendAfterRun(state, killed) {
     // 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 (!state.settled() && !killed) {
-        for (const canonical of backend.afterRun?.(runSpec, invocation, translator) ?? []) {
-            state.parser.feed(canonical + "\n", onLine);
+        for (const canonical of state.backend.afterRun?.(state.runSpec, state.invocation, state.translator) ?? []) {
+            state.parser.feed(canonical + "\n", state.onLine);
         }
     }
-    const failed = killed ||
+}
+/** Whether the exit reads as failed: killed, a parser error stop, or a non-zero code with no
+ * final text. */
+function closeFailed(state, code, killed) {
+    return (killed ||
         state.parser.stopReason === "error" ||
-        (code !== 0 && !state.parser.finalText.trim());
+        (code !== 0 && !state.parser.finalText.trim()));
+}
+/** Whether the exit is a permanent config error — a non-killed exit with no transient pi crash
+ * and no backend kind, whose parser flag or backend classification say config error. */
+function closeConfigError(state, cls, killed) {
+    return (!killed &&
+        cls.transientPiCrash !== true &&
+        cls.backendKind === undefined &&
+        (state.parser.configError || cls.configError === true));
+}
+/** 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. */
+export function settleClose(state, code) {
+    const { backend } = state;
+    flushRunTail(state);
+    // A blind image read on an authoring run deliberately killed it, so its exit is a kill like
+    // the watchdogs' — the half-done work is discarded.
+    const killed = state.wasKilled();
+    reconcileBackendAfterRun(state, killed);
+    const failed = closeFailed(state, code, killed);
     // 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 stderr = state.stderr();
     const cls = backend.classifyExit({ code, stderr, killed });
     const stderrBackend = cls.backendKind;
-    const configError = !killed &&
-        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 configError = closeConfigError(state, cls, killed);
     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,

package/dist/src/agent/{run-spawn.js → agent-spawn.js}

@@ -3,10 +3,10 @@
  * parser, the run marker, backend-bin resolution, the notes shim, the run spec, the backend's
  * optional `prepare`, the session-ledger record, the native-to-canonical translator, the two
  * incremental decoders, and the child spawn. It returns the `SpawnedRun` bundle the coordinator
- * (src/agent/run-agent.ts) binds its watchdogs and settlement wiring to, and passes to
- * createAgentStream (src/agent/run-stream.ts).
- * Part 1/2 of the runAgent split: the streaming pipeline (part 2/2) lives in run-stream.ts.
- * This module imports only run-agent's type surface, so
+ * (src/agent/agent-run.ts) binds its watchdogs and settlement wiring to, and passes to
+ * createAgentStream (src/agent/agent-stream.ts).
+ * Part 1/2 of the runAgent split: the streaming pipeline (part 2/2) lives in agent-stream.ts.
+ * This module imports only agent-run's type surface, so
  * there is no runtime import cycle. */
 import { spawn } from "node:child_process";
 import fs from "node:fs";
@@ -15,7 +15,7 @@ import { ensureParentDir, rotateIfLarge } from "../files/files.js";
 import { terminateChild } from "../process/process.js";
 import { makeRunMarker } from "../process/run-marker.js";
 import { PiStreamParser } from "../pi/pi-stream.js";
-import { recordSession } from "./session-ledger.js";
+import { recordSession, sessionRecordFor } from "./session-ledger.js";
 import { errorMessage } from "../text/text.js";
 import { warnEventBestEffort, TUMWATER_SOURCE } from "../events/events.js";
 import { seamImageInput } from "./image-input.js";
@@ -44,15 +44,7 @@ function buildAndSpawn(backend, opts, pre) {
     // 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(),
-    });
+    recordSession(opts.sessionDir, sessionRecordFor(backend.id, preSpawnSessionId, opts));
     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
@@ -108,6 +100,15 @@ function buildAndSpawn(backend, opts, pre) {
         blindRead: () => blind.read,
     };
 }
+/** Warn on a run's own root that a backend's optional `prepare` step failed, then let the run
+ * go on without it — the shared tail of the synchronous-throw and async-rejection prepare guards
+ * below, so both warn the same way. `warnRoot` is undefined when the session dir has no team
+ * root; the warning is then skipped because there is no tumwater event log to write to. */
+function warnPrepareFailed(warnRoot, error) {
+    if (warnRoot !== undefined) {
+        warnEventBestEffort(warnRoot, TUMWATER_SOURCE, `agent prepare failed, run continues: ${errorMessage(error)}`);
+    }
+}
 /** Build and spawn one non-interactive agent run, from the marker write through the child spawn,
  * and return the bundle the run's stream pipeline, watchdogs and settlement wiring consume. The
  * caller's setup (opened logs, the run's private TMPDIR) is passed in; a synchronous throw here
@@ -146,8 +147,7 @@ export function spawnPiRun(backend, logs, runTmp, opts) {
     }
     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.
+        // image read blind even when pi adds no note — 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
@@ -160,8 +160,12 @@ export function spawnPiRun(backend, logs, runTmp, opts) {
         },
     });
     // 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();
+    // it and the exit sweep can name it. When the session sits under a team root, the mark is
+    // stamped with that root's token so a dead-marked orphan can be attributed to this checkout
+    // and never reaped as another team's (BUGS.md, "Reap the doctor's orphans, part 1/3"); a
+    // session with no team root (a lab script, a smoke run, a prompt-lab replay) stays rootless.
+    const markerRoot = nearestTumwaterRoot(opts.sessionDir);
+    const runMarker = makeRunMarker(process.pid, markerRoot);
     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
@@ -211,9 +215,7 @@ export function spawnPiRun(backend, logs, runTmp, opts) {
         prepared = backend.prepare?.(runSpec);
     }
     catch (error) {
-        if (warnRoot !== undefined) {
-            warnEventBestEffort(warnRoot, TUMWATER_SOURCE, `agent prepare failed, run continues: ${errorMessage(error)}`);
-        }
+        warnPrepareFailed(warnRoot, error);
     }
     if (prepared === undefined) {
         // No `prepare` step: build and spawn synchronously and hand the bundle straight back, so
@@ -226,9 +228,7 @@ export function spawnPiRun(backend, logs, runTmp, opts) {
             await prepared;
         }
         catch (error) {
-            if (warnRoot !== undefined) {
-                warnEventBestEffort(warnRoot, TUMWATER_SOURCE, `agent prepare failed, run continues: ${errorMessage(error)}`);
-            }
+            warnPrepareFailed(warnRoot, error);
         }
         return buildAndSpawn(backend, opts, { runSpec, parser, runMarker, resolved, blind, runTmp });
     })();

package/dist/src/agent/{run-stream.js → agent-stream.js}

@@ -3,13 +3,13 @@
  * canonical stdout line splitting with its 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's promise. It is the part of the runAgent split (part
- * 2/2) that the coordinator (src/agent/run-agent.ts) delegates to behind the `AgentStream`
- * interface: run-agent wires the child's `data` events to `feedStdout`/`feedStderr`, binds the
+ * 2/2) that the coordinator (src/agent/agent-run.ts) delegates to behind the `AgentStream`
+ * interface: agent-run wires the child's `data` events to `feedStdout`/`feedStderr`, binds the
  * settlement state's stream getters, and keeps the watchdogs, abort wiring and the
- * `error`/`exit`/`close` listeners itself. This module imports only run-agent's, run-spawn's
- * and run-settle's type surfaces, so there is no runtime import cycle. */
+ * `error`/`exit`/`close` listeners itself. This module imports only agent-run's, agent-spawn's
+ * and agent-settle's type surfaces, so there is no runtime import cycle. */
 import { removeTree } from "../files/files.js";
-import { recordSession } from "./session-ledger.js";
+import { recordSession, sessionRecordFor } from "./session-ledger.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. */
@@ -60,15 +60,7 @@ export function createAgentStream(input) {
         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(),
-            });
+            recordSession(opts.sessionDir, sessionRecordFor(backend.id, sid, opts));
         }
     };
     // Split native stdout into complete lines, translate each, and feed the canonical lines to

package/dist/src/agent/backend-traits.js

@@ -3,9 +3,9 @@
  * read (plans/opencode-backend.md "Groundwork: the claude-only branches become backend
  * traits"). Pure — imports nothing from the runtime registry (agent-backend.ts) — so those
  * layers can read a backend's traits without pulling the registry in. That is the same reason
- * `BACKEND_DEFAULT_MODELS` lives in src/config/model-selector.ts.
+ * `BACKEND_DEFAULT_MODELS` lives in src/config/config-model-selector.ts.
  *
- * An id with no entry reads as pi, because src/agent/run-agent.ts routes an unregistered id to
+ * An id with no entry reads as pi, because src/agent/agent-run.ts routes an unregistered id to
  * the pi backend.
  */
 import { HARNESS_CLAUDE_FLAGS } from "./claude/claude-args.js";
@@ -95,3 +95,17 @@ export function backendDefaultLabel(backend) {
  * for one cannot go missing from the other (opencode classifies the same failure from message
  * text, not a status code, so it is not in the set). */
 export const SERVER_TRANSIENT_STATUS = new Set([500, 502, 503, 504, 529]);
+/** Classify a failure message's prose into the transient-backend failure it names, when the
+ * wire carries no structured signal: a dropped connection or a timeout, read from the message
+ * text by claude's and opencode's stream translators, which both fall back to prose for the
+ * statuses their native events leave to the message (claude's classifyResult and opencode's
+ * classifyError end with this same connection/then-timeout tail). The single home of the
+ * connection/timeout vocabulary, so the two backends' tail regexes cannot drift. undefined
+ * when the text names neither. */
+export function transientProseKind(text) {
+    if (/connection|econn|refused|reset|terminated/i.test(text))
+        return { kind: "transientBackend", backendKind: "connection" };
+    if (/timed out|timeout/i.test(text))
+        return { kind: "transientBackend", backendKind: "timeout" };
+    return undefined;
+}

package/dist/src/agent/claude/claude-account.js

@@ -17,7 +17,7 @@ import { spawnSync } from "node:child_process";
 import os from "node:os";
 import { resolvedBackendConfig } from "../../config/config-views.js";
 import { parseJsonObject } from "../../files/json-object.js";
-import { observeAccount, readAccount, subscriptionWindowRejected, utilizationPct, windowEntries, windowLabel, windowReserved, windowUsedUp, writeAccount, } from "../subscription-account.js";
+import { observeAccount, readAccount, subscriptionWindowRejected, windowEntries, windowLabel, windowReserved, windowUsedUp, writeAccount, } from "../subscription-account.js";
 import { claudeBackend, claudeConfigDir } from "./claude-backend.js";
 import { claudeEnv, claudeThirdPartyProvider } from "./claude-env.js";
 /** Read the persisted claude account state, or null when it is absent or unreadable. A file
@@ -57,13 +57,6 @@ export { subscriptionWindowRejected, windowReserved };
 export function claudeWindowLabel(type) {
     return windowLabel(type);
 }
-/** The fraction of a subscription usage window consumed as a whole-number percent —
- * subscription-account.ts's utilizationPct, under its historical claude name. */
-export function claudeUtilizationPct(utilization) {
-    return utilizationPct(utilization);
-}
-/** The account's windows as a list, most constrained first — subscription-account.ts's
- * windowEntries, under its historical claude name. */
 export function claudeWindowEntries(account) {
     return windowEntries(account);
 }

package/dist/src/agent/claude/claude-backend.js

@@ -1,7 +1,7 @@
 /** The claude adapter for the agent seam (plans/agent-backends.md "The seam", "Sessions",
  * "The claude invocation"). It shapes one run's argv/stdin/env, translates claude's
  * `stream-json` into the canonical stream, and classifies the exit's stderr — everything
- * backend-specific. src/agent/run-spawn.ts spawns the run and records this run in the session
+ * backend-specific. src/agent/agent-spawn.ts spawns the run and records this run in the session
  * ledger; claude mints its own session id (a fresh UUID, or the resumed record's id), which
  * `invocation` returns so the ledger can carry it.
  *
@@ -11,7 +11,7 @@
  * missing transcript, a different cwd, or another kind's newer session all review fresh rather
  * than resuming the wrong conversation.
  *
- * Registration lives in src/agent/run-agent.ts beside the pi adapter, so a test can register a
+ * Registration lives in src/agent/agent-run.ts beside the pi adapter, so a test can register a
  * fake under its own id; a test selects claude by setting `config.agent = "claude"` on a run. */
 import fs from "node:fs";
 import os from "node:os";
@@ -19,7 +19,7 @@ import path from "node:path";
 import { randomUUID } from "node:crypto";
 import { resolvedBackendConfig } from "../../config/config-views.js";
 import { MODEL_TIERS } from "../../config/config-schema.js";
-import { routeModel } from "../../config/model-selector.js";
+import { routeModel } from "../../config/config-model-selector.js";
 import { backendRunEnv } from "../../process/run-marker.js";
 import { resolveBinForBackend } from "../../pi/pi-bin.js";
 import { expandHomeTilde } from "../../files/files.js";

package/dist/src/agent/claude/claude-env.js

@@ -17,6 +17,7 @@
  * the foreground. `BASH_MAX_TIMEOUT_MS` is derived from `quietTimeoutSeconds` so claude's own
  * Bash timeout fires before tumwater's quiet kill and the model sees a tool error rather than a
  * dead run. */
+import { scrubEnv } from "../env-scrub.js";
 /** The cloud-provider switches that make a claude run bill as API rather than a claude.ai
  * subscription: Bedrock, Vertex, and Azure Foundry. They carry operator intent, so the run
  * environment keeps them (the allowlist below); claude-account's seedBilling and this module's
@@ -54,35 +55,30 @@ const MIN_BASH_MAX_TIMEOUT_MS = 1_000;
 /** Build the claude process environment from `base`. Never mutates `base`. */
 export function claudeEnv(base, opts) {
     const hadClaudeCode = base.CLAUDECODE !== undefined;
-    const env = {};
-    for (const [key, value] of Object.entries(base)) {
-        if (key === "CLAUDECODE" || key === "CLAUDE_PID" || key === "CLAUDE_EFFORT")
-            continue;
-        if (key.startsWith("CLAUDE_CODE_") && !CLAUDE_CODE_ALLOWLIST.has(key))
-            continue;
-        if (key.startsWith("CLAUDE_AGENT_SDK_"))
-            continue;
-        // The host session's proxy, not the operator's: only when CLAUDECODE says we are inside one.
-        if (key === "ANTHROPIC_BASE_URL" && hadClaudeCode)
-            continue;
-        env[key] = value;
-    }
-    env.CLAUDE_CODE_DISABLE_AUTO_MEMORY = "1";
-    env.CLAUDE_CODE_DISABLE_BACKGROUND_TASKS = "1";
-    env.BASH_DEFAULT_TIMEOUT_MS = String(BASH_DEFAULT_TIMEOUT_MS);
-    if (opts.quietTimeoutSeconds > 0) {
-        // 60 s under the quiet kill, so claude's tool error arrives before the run is declared hung;
-        // floored so a quiet window under 60 s never derives a non-positive cap.
-        const derived = opts.quietTimeoutSeconds * 1000 - 60_000;
-        env.BASH_MAX_TIMEOUT_MS = String(Math.max(derived, MIN_BASH_MAX_TIMEOUT_MS));
-    }
-    env.DISABLE_AUTOUPDATER = "1";
-    env.DISABLE_TELEMETRY = "1";
-    env.DISABLE_ERROR_REPORTING = "1";
-    // A team config dir (plans/notes-command.md "Keeping funes out of team runs"): force claude's
-    // own config and transcripts under it, so a funes hook on ~/.claude/projects never indexes
-    // team runs. Unset leaves any inherited CLAUDE_CONFIG_DIR (or claude's default) untouched.
-    if (opts.configDir)
-        env.CLAUDE_CONFIG_DIR = opts.configDir;
-    return env;
+    return scrubEnv(base, {
+        keep: (key) => (key !== "CLAUDECODE" && key !== "CLAUDE_PID" && key !== "CLAUDE_EFFORT") &&
+            !(key.startsWith("CLAUDE_CODE_") && !CLAUDE_CODE_ALLOWLIST.has(key)) &&
+            !key.startsWith("CLAUDE_AGENT_SDK_") &&
+            // The host session's proxy, not the operator's: only when CLAUDECODE says we are inside one.
+            !(key === "ANTHROPIC_BASE_URL" && hadClaudeCode),
+        then: (env) => {
+            env.CLAUDE_CODE_DISABLE_AUTO_MEMORY = "1";
+            env.CLAUDE_CODE_DISABLE_BACKGROUND_TASKS = "1";
+            env.BASH_DEFAULT_TIMEOUT_MS = String(BASH_DEFAULT_TIMEOUT_MS);
+            if (opts.quietTimeoutSeconds > 0) {
+                // 60 s under the quiet kill, so claude's tool error arrives before the run is
+                // declared hung; floored so a short quiet window never derives a non-positive cap.
+                const derived = opts.quietTimeoutSeconds * 1000 - 60_000;
+                env.BASH_MAX_TIMEOUT_MS = String(Math.max(derived, MIN_BASH_MAX_TIMEOUT_MS));
+            }
+            env.DISABLE_AUTOUPDATER = "1";
+            env.DISABLE_TELEMETRY = "1";
+            env.DISABLE_ERROR_REPORTING = "1";
+            // A team config dir (plans/notes-command.md "Keeping funes out of team runs"): force claude's
+            // own config and transcripts under it, so a funes hook on ~/.claude/projects never indexes
+            // team runs. Unset leaves any inherited CLAUDE_CONFIG_DIR (or claude's default) untouched.
+            if (opts.configDir)
+                env.CLAUDE_CONFIG_DIR = opts.configDir;
+        },
+    });
 }