tumwater 0.3.0 → 0.4.1

package/README.md

@@ -42,7 +42,7 @@ and is also outside `npm test`.
 ## Status
 
 <!-- tumwater:status:start -->
-**v0.3.0**: working tumwater. The director and 14 of the 16 roles are enabled by default; `selfcheck`,
+**v0.4.1**: 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`).
 

package/dist/build-info.json

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

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

@@ -1,7 +1,10 @@
 /** 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-agent.ts
- * owns everything backend-neutral (spawn, marker, watchdogs, abort, stderr capture); the
+ * 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
+ * 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
  * 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

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

@@ -75,3 +75,23 @@ export function modelLabel(backend, provider, model) {
 export function backendDisplayName(id) {
     return id.charAt(0).toUpperCase() + id.slice(1);
 }
+/** A seam's own-default label when neither a provider nor a model resolves:
+ * `<backend> default` — pi's historical `pi default` for the pi backend (and an unknown id,
+ * which reads as pi), `claude default` for claude, and so on. The one home of the label
+ * `role-render.ts`'s Model line and the status rows share, so the two surfaces cannot
+ * disagree about what a seam without a model is named. */
+export function backendDefaultLabel(backend) {
+    // Only claude, opencode and codex carry their own `<backend> default`; pi, an absent
+    // backend and any unregistered id (which reads as pi) all carry pi's historical `pi
+    // default`, matching streamsToolOutput's reads-as-pi window.
+    if (backend === "claude" || backend === "opencode" || backend === "codex")
+        return `${backend} default`;
+    return "pi default";
+}
+/** The HTTP status codes the native claude and codex stream translators read as a transient
+ * backend (server) failure — the `transientBackend` classification with `backendKind:
+ * "server"`. 529 is Anthropic's "overloaded" spelling, which codex's `turn.failed` error
+ * carries too. One home for the set the two adapters' classifiers share, so a status added
+ * 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]);

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-agent.ts owns the spawn and records this run in the session
+ * backend-specific. src/agent/run-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.
  *
@@ -20,7 +20,7 @@ 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 { backendBaseEnv, withNotesPath } from "../../process/run-marker.js";
+import { backendRunEnv } from "../../process/run-marker.js";
 import { resolveBinForBackend } from "../../pi/pi-bin.js";
 import { expandHomeTilde } from "../../files/files.js";
 import { claudeArgs } from "./claude-args.js";
@@ -147,7 +147,7 @@ export const claudeBackend = {
         // the marker the same way pi's adapter carries it (withNotesPath); from part 2/4 the run
         // saves its note through the `tumwater-notes` command on PATH, so no MCP server reaches the
         // run and `--strict-mcp-config` (always in claude-args.ts) keeps it that way.
-        const base = withNotesPath(backendBaseEnv(run.runMarker, undefined, run.binDir), run.notesPath);
+        const base = backendRunEnv(run);
         const env = claudeEnv(base, {
             quietTimeoutSeconds: run.config.quietTimeoutSeconds,
             ...(expandedConfigDir !== undefined ? { configDir: expandedConfigDir } : {}),

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

@@ -11,11 +11,13 @@
  * Pure translation: no spawn, no backend registration, no config. The factory keeps per-run
  * state (the pending split-block assistant message, the unmapped native types seen, whether a
  * `run_cost` arrived), so call it once per run. Unmapped native types are recorded once each
- * on the seam's optional `warnings()` — src/agent/run-agent.ts forwards each as an
+ * on the seam's optional `warnings()` — src/agent/run-stream.ts forwards each as an
  * `agent_unknown_event` warning after the run. `cost_unknown` is recorded the same way when a
  * run produced no authoritative `run_cost`. */
 import { joinParts } from "../../text/text.js";
+import { secondsUntil } from "../../text/datetime.js";
 import { canonicalUsageBlock, isJsonObject, objectOrEmpty, nonNegativeNumber, parseJsonObject } from "../../files/json-object.js";
+import { SERVER_TRANSIENT_STATUS } from "../backend-traits.js";
 /** claude's tool names → the canonical pi names the readers already know. Glob/Grep are kept
  * lower-cased; MultiEdit collapses onto edit (pi has one edit tool). Anything else is
  * lower-cased so a future tool still reads as a name rather than as `undefined`. */
@@ -28,9 +30,6 @@ const TOOL_NAMES = {
     Glob: "glob",
     Grep: "grep",
 };
-/** claude's HTTP status classes that mean a transient backend failure. 529 is Anthropic's
- * "overloaded" spelling. */
-const SERVER_STATUS = new Set([500, 502, 503, 504, 529]);
 /** claude's HTTP status classes that mean a permanent configuration error. */
 const CONFIG_STATUS = new Set([400, 401, 403, 404]);
 function str(value) {
@@ -93,7 +92,7 @@ function classifyResult(result) {
     const status = nonNegativeNumber(result.api_error_status, undefined);
     if (status === 429)
         return { kind: "transientRateLimit" };
-    if (status !== undefined && SERVER_STATUS.has(status))
+    if (status !== undefined && SERVER_TRANSIENT_STATUS.has(status))
         return { kind: "transientBackend", backendKind: "server" };
     // The context-overflow text wins over a configuration status: claude reports an oversized
     // prompt as HTTP 400 ("prompt is too long"), whose status alone would read as configError.
@@ -169,6 +168,167 @@ export function claudeTranslator(opts = {}) {
         seen.add(kind);
         warnings.add(kind);
     };
+    const handleSystem = (event) => {
+        const subtype = str(event.subtype);
+        if (subtype === "init") {
+            const out = [];
+            const cwd = str(event.cwd);
+            const id = str(event.session_id);
+            out.push(JSON.stringify({ type: "session", ...(cwd !== undefined ? { cwd } : {}), ...(id !== undefined ? { id } : {}) }));
+            out.push(JSON.stringify({ type: "agent_start" }));
+            const billing = billingOf(str(event.apiKeySource), opts.thirdPartyProvider === true);
+            if (billing)
+                out.push(JSON.stringify({ type: "billing", billing }));
+            return out;
+        }
+        if (subtype === "api_retry") {
+            const attempt = nonNegativeNumber(event.attempt, undefined);
+            const maxAttempts = nonNegativeNumber(event.max_retries, undefined);
+            const status = nonNegativeNumber(event.error_status, undefined);
+            const error = str(event.error) ?? "";
+            const errorMessage = joinParts([status !== undefined ? `status ${status}` : "", error], ": ");
+            return [
+                JSON.stringify({
+                    type: "auto_retry_start",
+                    ...(attempt !== undefined ? { attempt } : {}),
+                    ...(maxAttempts !== undefined ? { maxAttempts } : {}),
+                    errorMessage: errorMessage || "api retry",
+                }),
+            ];
+        }
+        if (subtype === "compact_boundary")
+            return [JSON.stringify({ type: "compaction_start" })];
+        // A thinking-token estimate during extended thinking: known, carries nothing canonical.
+        if (subtype === "thinking_tokens")
+            return [];
+        record(`system:${subtype ?? "unknown"}`);
+        return [];
+    };
+    const handleAssistant = (event) => {
+        sawActivity = true;
+        const message = objectOrEmpty(event.message);
+        const id = str(message.id) ?? `anon-${anonymous++}`;
+        // A new id flushes the open message; a continuing one flushes nothing. Either way the
+        // fresh or open pending then folds this event's content, usage, and stop reason the
+        // same way — that shared fold is why both branches live on one path.
+        let out = [];
+        if (pending?.id !== id) {
+            out = flush();
+            pending = { id, content: [], usage: canonicalUsage(isJsonObject(message.usage) ? message.usage : undefined) };
+        }
+        const blocks = Array.isArray(message.content) ? message.content : [];
+        for (const raw of blocks) {
+            if (!isJsonObject(raw))
+                continue;
+            const block = canonicalBlock(raw);
+            if (!block)
+                continue;
+            pending.content.push(block);
+            if (block.type === "toolCall")
+                out.push(startToolCall(block));
+        }
+        // Usage repeats on every event of the same message; the last read wins and is counted
+        // once because the fold emits one message_end per id.
+        pending.usage = canonicalUsage(isJsonObject(message.usage) ? message.usage : undefined);
+        const stopReason = str(message.stop_reason);
+        if (stopReason !== undefined)
+            pending.stopReason = stopReason;
+        return out;
+    };
+    const handleUser = (event) => {
+        const out = flush();
+        const message = objectOrEmpty(event.message);
+        const blocks = Array.isArray(message.content) ? message.content : [];
+        for (const raw of blocks) {
+            if (!isJsonObject(raw) || raw.type !== "tool_result")
+                continue;
+            out.push(JSON.stringify({
+                type: "tool_execution_end",
+                toolCallId: str(raw.tool_use_id) ?? "",
+                isError: raw.is_error === true,
+            }));
+        }
+        return out;
+    };
+    const handleRateLimitEvent = (event) => {
+        const info = objectOrEmpty(event.rate_limit_info);
+        const rateLimitType = str(info.rateLimitType);
+        const status = str(info.status);
+        // claude 2.1.295 reports every window's utilization and reset under `unifiedWindows`,
+        // keyed by window type, and only the binding window's status at the top level.
+        const windows = [];
+        for (const [type, raw] of Object.entries(objectOrEmpty(info.unifiedWindows))) {
+            if (type === rateLimitType || !isJsonObject(raw))
+                continue;
+            const reading = { type: "rate_limit", rateLimitType: type };
+            const windowResets = nonNegativeNumber(raw.resetsAt, undefined);
+            if (windowResets !== undefined)
+                reading.resetsAt = windowResets;
+            const windowUtil = nonNegativeNumber(raw.utilization, undefined);
+            if (windowUtil !== undefined)
+                reading.utilization = windowUtil;
+            windows.push(JSON.stringify(reading));
+        }
+        const own = rateLimitType === undefined ? undefined : objectOrEmpty(objectOrEmpty(info.unifiedWindows)[rateLimitType]);
+        const resetsAt = nonNegativeNumber(info.resetsAt, undefined) ?? nonNegativeNumber(own?.resetsAt, undefined);
+        const out = { type: "rate_limit" };
+        if (rateLimitType !== undefined)
+            out.rateLimitType = rateLimitType;
+        if (status !== undefined)
+            out.status = status;
+        if (resetsAt !== undefined)
+            out.resetsAt = resetsAt;
+        const utilization = nonNegativeNumber(info.utilization, undefined) ?? nonNegativeNumber(own?.utilization, undefined);
+        if (utilization !== undefined)
+            out.utilization = utilization;
+        const overageStatus = str(info.overageStatus);
+        if (overageStatus !== undefined)
+            out.overageStatus = overageStatus;
+        if (info.isUsingOverage === true)
+            out.isUsingOverage = true;
+        if (status === "rejected" && resetsAt !== undefined) {
+            // resetsAt is a unix-seconds stamp; secondsUntil folds it (×1000) to whole seconds.
+            out.retryAfterSeconds = secondsUntil(resetsAt * 1000, Date.now());
+        }
+        return [JSON.stringify(out), ...windows];
+    };
+    const handleResult = (event) => {
+        sawActivity = true;
+        const out = flush();
+        // The assistant events' usage is the message-start snapshot, so the result's total
+        // is the run's real output-token count (thinking included).
+        const outputTokens = nonNegativeNumber(objectOrEmpty(event.usage).output_tokens, undefined);
+        if (outputTokens !== undefined)
+            out.push(JSON.stringify({ type: "run_usage", outputTokens }));
+        const total = nonNegativeNumber(event.total_cost_usd, undefined);
+        if (total !== undefined) {
+            sawRunCost = true;
+            out.push(JSON.stringify({ type: "run_cost", total }));
+        }
+        else {
+            warnings.add("cost_unknown");
+        }
+        if (event.is_error === true) {
+            const { kind, backendKind } = classifyResult(event);
+            const message = {
+                role: "assistant",
+                content: [],
+                stopReason: "error",
+            };
+            const errorMessage = str(event.result) ?? str(event.error);
+            if (errorMessage !== undefined)
+                message.errorMessage = errorMessage;
+            // tumwaterKind/backendKind ride the canonical EVENT (not its message): the parser
+            // reads event.tumwaterKind and trusts it before its text regexes.
+            out.push(JSON.stringify({
+                type: "message_end",
+                message,
+                ...(kind !== undefined ? { tumwaterKind: kind } : {}),
+                ...(backendKind !== undefined ? { backendKind } : {}),
+            }));
+        }
+        return out;
+    };
     const translate = (line) => {
         const parsed = parseJsonObject(line);
         if (!parsed)
@@ -176,167 +336,11 @@ export function claudeTranslator(opts = {}) {
         const event = parsed;
         const type = str(event.type);
         switch (type) {
-            case "system": {
-                const subtype = str(event.subtype);
-                if (subtype === "init") {
-                    const out = [];
-                    const cwd = str(event.cwd);
-                    const id = str(event.session_id);
-                    out.push(JSON.stringify({ type: "session", ...(cwd !== undefined ? { cwd } : {}), ...(id !== undefined ? { id } : {}) }));
-                    out.push(JSON.stringify({ type: "agent_start" }));
-                    const billing = billingOf(str(event.apiKeySource), opts.thirdPartyProvider === true);
-                    if (billing)
-                        out.push(JSON.stringify({ type: "billing", billing }));
-                    return out;
-                }
-                if (subtype === "api_retry") {
-                    const attempt = nonNegativeNumber(event.attempt, undefined);
-                    const maxAttempts = nonNegativeNumber(event.max_retries, undefined);
-                    const status = nonNegativeNumber(event.error_status, undefined);
-                    const error = str(event.error) ?? "";
-                    const errorMessage = joinParts([status !== undefined ? `status ${status}` : "", error], ": ");
-                    return [
-                        JSON.stringify({
-                            type: "auto_retry_start",
-                            ...(attempt !== undefined ? { attempt } : {}),
-                            ...(maxAttempts !== undefined ? { maxAttempts } : {}),
-                            errorMessage: errorMessage || "api retry",
-                        }),
-                    ];
-                }
-                if (subtype === "compact_boundary")
-                    return [JSON.stringify({ type: "compaction_start" })];
-                // A thinking-token estimate during extended thinking: known, carries nothing canonical.
-                if (subtype === "thinking_tokens")
-                    return [];
-                record(`system:${subtype ?? "unknown"}`);
-                return [];
-            }
-            case "assistant": {
-                sawActivity = true;
-                const message = objectOrEmpty(event.message);
-                const id = str(message.id) ?? `anon-${anonymous++}`;
-                // A new id flushes the open message; a continuing one flushes nothing. Either way the
-                // fresh or open pending then folds this event's content, usage, and stop reason the
-                // same way — that shared fold is why both branches live on one path.
-                let out = [];
-                if (pending?.id !== id) {
-                    out = flush();
-                    pending = { id, content: [], usage: canonicalUsage(isJsonObject(message.usage) ? message.usage : undefined) };
-                }
-                const blocks = Array.isArray(message.content) ? message.content : [];
-                for (const raw of blocks) {
-                    if (!isJsonObject(raw))
-                        continue;
-                    const block = canonicalBlock(raw);
-                    if (!block)
-                        continue;
-                    pending.content.push(block);
-                    if (block.type === "toolCall")
-                        out.push(startToolCall(block));
-                }
-                // Usage repeats on every event of the same message; the last read wins and is counted
-                // once because the fold emits one message_end per id.
-                pending.usage = canonicalUsage(isJsonObject(message.usage) ? message.usage : undefined);
-                const stopReason = str(message.stop_reason);
-                if (stopReason !== undefined)
-                    pending.stopReason = stopReason;
-                return out;
-            }
-            case "user": {
-                const out = flush();
-                const message = objectOrEmpty(event.message);
-                const blocks = Array.isArray(message.content) ? message.content : [];
-                for (const raw of blocks) {
-                    if (!isJsonObject(raw) || raw.type !== "tool_result")
-                        continue;
-                    out.push(JSON.stringify({
-                        type: "tool_execution_end",
-                        toolCallId: str(raw.tool_use_id) ?? "",
-                        isError: raw.is_error === true,
-                    }));
-                }
-                return out;
-            }
-            case "rate_limit_event": {
-                const info = objectOrEmpty(event.rate_limit_info);
-                const rateLimitType = str(info.rateLimitType);
-                const status = str(info.status);
-                // claude 2.1.295 reports every window's utilization and reset under `unifiedWindows`,
-                // keyed by window type, and only the binding window's status at the top level.
-                const windows = [];
-                for (const [type, raw] of Object.entries(objectOrEmpty(info.unifiedWindows))) {
-                    if (type === rateLimitType || !isJsonObject(raw))
-                        continue;
-                    const reading = { type: "rate_limit", rateLimitType: type };
-                    const windowResets = nonNegativeNumber(raw.resetsAt, undefined);
-                    if (windowResets !== undefined)
-                        reading.resetsAt = windowResets;
-                    const windowUtil = nonNegativeNumber(raw.utilization, undefined);
-                    if (windowUtil !== undefined)
-                        reading.utilization = windowUtil;
-                    windows.push(JSON.stringify(reading));
-                }
-                const own = rateLimitType === undefined ? undefined : objectOrEmpty(objectOrEmpty(info.unifiedWindows)[rateLimitType]);
-                const resetsAt = nonNegativeNumber(info.resetsAt, undefined) ?? nonNegativeNumber(own?.resetsAt, undefined);
-                const out = { type: "rate_limit" };
-                if (rateLimitType !== undefined)
-                    out.rateLimitType = rateLimitType;
-                if (status !== undefined)
-                    out.status = status;
-                if (resetsAt !== undefined)
-                    out.resetsAt = resetsAt;
-                const utilization = nonNegativeNumber(info.utilization, undefined) ?? nonNegativeNumber(own?.utilization, undefined);
-                if (utilization !== undefined)
-                    out.utilization = utilization;
-                const overageStatus = str(info.overageStatus);
-                if (overageStatus !== undefined)
-                    out.overageStatus = overageStatus;
-                if (info.isUsingOverage === true)
-                    out.isUsingOverage = true;
-                if (status === "rejected" && resetsAt !== undefined) {
-                    // resetsAt is a unix-seconds stamp; retryAfterSeconds is the wait the runner honors.
-                    out.retryAfterSeconds = Math.max(0, Math.round(resetsAt - Date.now() / 1000));
-                }
-                return [JSON.stringify(out), ...windows];
-            }
-            case "result": {
-                sawActivity = true;
-                const out = flush();
-                // The assistant events' usage is the message-start snapshot, so the result's total
-                // is the run's real output-token count (thinking included).
-                const outputTokens = nonNegativeNumber(objectOrEmpty(event.usage).output_tokens, undefined);
-                if (outputTokens !== undefined)
-                    out.push(JSON.stringify({ type: "run_usage", outputTokens }));
-                const total = nonNegativeNumber(event.total_cost_usd, undefined);
-                if (total !== undefined) {
-                    sawRunCost = true;
-                    out.push(JSON.stringify({ type: "run_cost", total }));
-                }
-                else {
-                    warnings.add("cost_unknown");
-                }
-                if (event.is_error === true) {
-                    const { kind, backendKind } = classifyResult(event);
-                    const message = {
-                        role: "assistant",
-                        content: [],
-                        stopReason: "error",
-                    };
-                    const errorMessage = str(event.result) ?? str(event.error);
-                    if (errorMessage !== undefined)
-                        message.errorMessage = errorMessage;
-                    // tumwaterKind/backendKind ride the canonical EVENT (not its message): the parser
-                    // reads event.tumwaterKind and trusts it before its text regexes.
-                    out.push(JSON.stringify({
-                        type: "message_end",
-                        message,
-                        ...(kind !== undefined ? { tumwaterKind: kind } : {}),
-                        ...(backendKind !== undefined ? { backendKind } : {}),
-                    }));
-                }
-                return out;
-            }
+            case "system": return handleSystem(event);
+            case "assistant": return handleAssistant(event);
+            case "user": return handleUser(event);
+            case "rate_limit_event": return handleRateLimitEvent(event);
+            case "result": return handleResult(event);
             case "tool_progress":
                 // A 30 s heartbeat of a running tool call: known, and the open call already tracks
                 // liveness.

package/dist/src/agent/claude/{write-guard-hook.js → claude-write-guard-hook.js}

@@ -1,5 +1,5 @@
 /** The PreToolUse hook claude runs before each file write in a team run (claude-write-guard.ts
- * installs it through `--settings`): `node write-guard-hook.js <worktree>` with claude's hook
+ * installs it through `--settings`): `node claude-write-guard-hook.js <worktree>` with the hook
  * payload on stdin. To block the write it prints a `deny` decision with the refusal as its reason:
  * the model reads only the reason, where a refusal by exit 2 would also quote the whole hook
  * command. It prints nothing to let the write run. Any failure of its own lets the write run, so a

package/dist/src/agent/claude/claude-write-guard.js

@@ -7,7 +7,7 @@
  * `--setting-sources project` leaves the operator's own hooks out of a run, while `--settings`
  * still loads this one. The hook gets the run's worktree as an argument rather than reading
  * claude's `cwd`, which follows the Bash tool's `cd` into subdirectories. The entry point is
- * write-guard-hook.ts beside this file. */
+ * claude-write-guard-hook.ts beside this file. */
 import { fileURLToPath } from "node:url";
 import { shellQuote, strayWriteRefusal } from "../write-guard.js";
 /** claude's file-writing tools a team run has: claude-args.ts's `--tools` allows only these two,
@@ -16,12 +16,13 @@ const WRITE_TOOLS = ["Edit", "Write"];
 /** Seconds claude waits for the hook before running the tool anyway. */
 const HOOK_TIMEOUT_SECONDS = 30;
 /** The `--settings` value for a run in `cwd`: one PreToolUse hook on the file-writing tools that
- * runs the compiled write-guard-hook.js with this process's node, falling back to `node` on PATH
- * when that binary has moved (as the notes shim does), and the run's worktree as its argument. The
+ * runs the compiled claude-write-guard-hook.js with this process's node, falling back to
+ * `node` on PATH when that binary has moved (as the notes shim does), and the run's worktree
+ * as its argument. The
  * hook path resolves from this module, so a staged build (.tumwater/build/<sha>) runs its own
  * copy. */
 export function writeGuardSettings(cwd, nodeBin = process.execPath) {
-    const hook = fileURLToPath(new URL("./write-guard-hook.js", import.meta.url));
+    const hook = fileURLToPath(new URL("./claude-write-guard-hook.js", import.meta.url));
     const command = `n=${shellQuote(nodeBin)}; [ -x "$n" ] || n=node; exec "$n" ${shellQuote(hook)} ${shellQuote(cwd)}`;
     return JSON.stringify({
         hooks: {

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

@@ -1,7 +1,7 @@
 /** The codex adapter for the agent seam (plans/codex-backend.md §4, §5, §6): it shapes one
  * run's argv/stdin/env, translates codex's `exec --json` stream, reads the authoritative
  * rollout after the process exits, and classifies the exit's stderr — everything
- * backend-specific. src/agent/run-agent.ts owns the spawn and records this run in the session
+ * backend-specific. src/agent/run-spawn.ts spawns the run and records this run in the session
  * ledger; codex mints its own session id (a thread id, or the resumed record's id) in the
  * stream's `thread.started`, which the runner's stream-mint pass appends to the ledger and
  * `invocation` returns so a later `exec resume` can reach it.
@@ -19,7 +19,7 @@
 import fs from "node:fs";
 import { loadConfigSafe } from "../../config/config.js";
 import { resolvedBackendConfig } from "../../config/config-views.js";
-import { backendBaseEnv, withNotesPath } from "../../process/run-marker.js";
+import { backendRunEnv } from "../../process/run-marker.js";
 import { resolveBinForBackend } from "../../pi/pi-bin.js";
 import { teamRootOf, nearestTumwaterRoot } from "../../paths.js";
 import { warnEventBestEffort, TUMWATER_SOURCE } from "../../events/events.js";
@@ -120,7 +120,7 @@ export const codexBackend = {
         // The notes path rides beside the run marker, as the pi and claude adapters' envs do
         // (withNotesPath); from part 2/4 the run saves its note through the `tumwater-notes`
         // command on PATH, so codex configures no MCP server for notes.
-        const base = withNotesPath(backendBaseEnv(run.runMarker, undefined, run.binDir), run.notesPath);
+        const base = backendRunEnv(run);
         // A team home of its own (`CODEX_HOME`) keeps team sessions and trust entries out of the
         // operator's `~/.codex` (design §4, finding 10); unset leaves the operator's home.
         const home = codexHome(resolvedBackendConfig(run.config, "codex"));
@@ -162,7 +162,7 @@ export const codexBackend = {
         // invocation later reads was looked up under the run's own config. It never throws a run
         // away: a failed lookup records `off` (and warns once) and the run continues without the
         // guard's trust.
-        const base = withNotesPath(backendBaseEnv(run.runMarker, undefined, run.binDir), run.notesPath);
+        const base = backendRunEnv(run);
         const home = codexHome(resolvedBackendConfig(run.config, "codex"));
         const env = codexEnv(base, { home });
         const root = nearestTumwaterRoot(run.sessionDir);

package/dist/src/agent/codex/codex-rollout.js

@@ -12,6 +12,7 @@
  */
 import fs from "node:fs";
 import path from "node:path";
+import { walkFiles } from "../../files/files.js";
 import { isJsonObject, nonNegativeNumber, objectOrEmpty, parseJsonObject } from "../../files/json-object.js";
 import { windowTypeName } from "./codex-stream.js";
 function str(value) {
@@ -155,25 +156,13 @@ export function findRollout(home, id) {
     if (!fs.existsSync(sessionsRoot))
         return null;
     const suffix = `-${id}.jsonl`;
-    const stack = [sessionsRoot];
-    while (stack.length > 0) {
-        const dir = stack.pop();
-        let entries;
-        try {
-            entries = fs.readdirSync(dir, { withFileTypes: true });
-        }
-        catch {
-            continue; // an unreadable dir is simply no match, never a failure
-        }
-        for (const entry of entries) {
-            const full = path.join(dir, entry.name);
-            if (entry.isDirectory()) {
-                stack.push(full);
-            }
-            else if (entry.isFile() && entry.name.startsWith("rollout-") && entry.name.endsWith(suffix)) {
-                return full;
-            }
-        }
-    }
-    return null;
+    let found = null;
+    // The walk-and-swallow recursion is files.ts's walkFiles (an unreadable dir is no match);
+    // the id match alone decides, so only the one id's rollout can win. The sessions tree is one
+    // directory per active day, so walking it whole to the first match stays small.
+    walkFiles(sessionsRoot, (file, entry) => {
+        if (found === null && entry.name.startsWith("rollout-") && entry.name.endsWith(suffix))
+            found = file;
+    });
+    return found;
 }