tumwater 0.4.2 → 0.4.4

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

@@ -11,7 +11,7 @@
  * 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-stream.ts forwards each as an
+ * on the seam's optional `warnings()` — src/agent/agent-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";
@@ -71,47 +71,80 @@ function canonicalBlock(block) {
             return undefined;
     }
 }
-/** How a `result` event's error signals classify into the canonical `tumwaterKind` (and, for
- * a transient backend, its kind), trusted by `PiStreamParser` before its text regexes. Empty
- * when the result is not an error or carries no signal the vocabulary names — a SIGTERM
- * (`terminal_reason: "aborted_tools"`) is deliberate: the harness killed the run, so no
- * provider classification applies. `status` is `api_error_status`, which is null on the
- * not-logged-in result, so the text checks carry that case. */
-function classifyResult(result) {
-    const terminal = optionalString(result.terminal_reason);
+/** `terminal === "aborted_tools"` is deliberate: the harness killed the run, so no provider
+ * classification applies — the chain stops there. `error_max_budget_usd`, as a terminal
+ * reason or in the text, caps the budget. */
+function terminalAndBudgetClassification(terminal, text) {
     if (terminal === "aborted_tools")
         return {};
     if (terminal === "error_max_budget_usd")
         return { kind: "budgetCapped" };
-    const text = joinParts([optionalString(result.result), optionalString(result.error)], " ");
     if (/error_max_budget_usd/i.test(text))
         return { kind: "budgetCapped" };
-    const status = nonNegativeNumber(result.api_error_status, undefined);
+    return undefined;
+}
+function statusClassification(status) {
     if (status === 429)
         return { kind: "transientRateLimit" };
     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.
+    return undefined;
+}
+/** 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. */
+function contextOverflowClassification(text) {
     if (/prompt is too long/i.test(text))
         return { kind: "contextExceeded" };
+    return undefined;
+}
+function configStatusClassification(status) {
     if (status !== undefined && CONFIG_STATUS.has(status))
         return { kind: "configError" };
-    // Text fallbacks, for the statuses claude leaves null or omits.
+    return undefined;
+}
+function resumeMissingClassification(text) {
     if (/No conversation found with session ID/i.test(text))
         return { kind: "resumeMissing" };
+    return undefined;
+}
+function configTextClassification(text) {
     if (/Not logged in|issue with the selected model|does not support this model/i.test(text))
         return { kind: "configError" };
+    return undefined;
+}
+function transientTextClassification(text) {
     if (/\b429\b|rate limit/i.test(text))
         return { kind: "transientRateLimit" };
     if (/overloaded|internal server error|bad gateway|service unavailable|gateway timeout|\b5\d\d\b/i.test(text))
         return { kind: "transientBackend", backendKind: "server" };
     const prose = transientProseKind(text);
-    if (prose)
-        return prose;
+    return prose;
+}
+/** Text fallbacks, for the statuses claude leaves null or omits. */
+function httpStatusTextClassification(text) {
     if (/\b(400|401|403|404)\b/i.test(text))
         return { kind: "configError" };
-    return {};
+    return undefined;
+}
+/** How a `result` event's error signals classify into the canonical `tumwaterKind` (and, for
+ * a transient backend, its kind), trusted by `PiStreamParser` before its text regexes. Empty
+ * when the result is not an error or carries no signal the vocabulary names — a SIGTERM
+ * (`terminal_reason: "aborted_tools"`) is deliberate: the harness killed the run, so no
+ * provider classification applies. `status` is `api_error_status`, which is null on the
+ * not-logged-in result, so the text checks carry that case. */
+function classifyResult(result) {
+    const terminal = optionalString(result.terminal_reason);
+    const text = joinParts([optionalString(result.result), optionalString(result.error)], " ");
+    const status = nonNegativeNumber(result.api_error_status, undefined);
+    return (terminalAndBudgetClassification(terminal, text) ??
+        statusClassification(status) ??
+        contextOverflowClassification(text) ??
+        configStatusClassification(status) ??
+        resumeMissingClassification(text) ??
+        configTextClassification(text) ??
+        transientTextClassification(text) ??
+        httpStatusTextClassification(text) ??
+        {});
 }
 /** Build a fresh per-run claude translator. */
 export function claudeTranslator(opts = {}) {
@@ -250,43 +283,10 @@ export function claudeTranslator(opts = {}) {
         const info = objectOrEmpty(event.rate_limit_info);
         const rateLimitType = optionalString(info.rateLimitType);
         const status = optionalString(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 = optionalString(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; secondsUntilUnixStamp folds it to whole seconds.
-            out.retryAfterSeconds = secondsUntilUnixStamp(resetsAt, Date.now());
-        }
-        return [JSON.stringify(out), ...windows];
+        return [
+            JSON.stringify(claudeRateLimitReading(info, rateLimitType, status)),
+            ...claudeRateLimitWindowReadings(info, rateLimitType),
+        ];
     };
     const handleResult = (event) => {
         sawActivity = true;
@@ -363,6 +363,63 @@ export function claudeTranslator(opts = {}) {
         },
     };
 }
+/** One reading per sibling `unifiedWindows` window other than the binding window. */
+function claudeRateLimitWindowReadings(info, rateLimitType) {
+    // 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));
+    }
+    return windows;
+}
+/** The binding window's own `unifiedWindows` record, if a rate-limit type was named. */
+function claudeRateLimitOwnWindow(info, rateLimitType) {
+    return rateLimitType === undefined ? undefined : objectOrEmpty(objectOrEmpty(info.unifiedWindows)[rateLimitType]);
+}
+/** The binding window's reset time: the top-level `resetsAt` falling back to its own record. */
+function claudeRateLimitResetsAt(info, own) {
+    return nonNegativeNumber(info.resetsAt, undefined) ?? nonNegativeNumber(own?.resetsAt, undefined);
+}
+/** The binding window's utilization: the top-level `utilization` falling back to its own record. */
+function claudeRateLimitUtilization(info, own) {
+    return nonNegativeNumber(info.utilization, undefined) ?? nonNegativeNumber(own?.utilization, undefined);
+}
+/** The binding window's canonical reading: its optional fields, plus a rejected window's
+ * retry-after. */
+function claudeRateLimitReading(info, rateLimitType, status) {
+    const own = claudeRateLimitOwnWindow(info, rateLimitType);
+    const resetsAt = claudeRateLimitResetsAt(info, own);
+    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 = claudeRateLimitUtilization(info, own);
+    if (utilization !== undefined)
+        out.utilization = utilization;
+    const overageStatus = optionalString(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; secondsUntilUnixStamp folds it to whole seconds.
+        out.retryAfterSeconds = secondsUntilUnixStamp(resetsAt, Date.now());
+    }
+    return out;
+}
 /** The run's billing, from `system/init.apiKeySource`: claude.ai OAuth reports `"none"`, an
  * environment key reports `ANTHROPIC_API_KEY`, a helper reports `apiKeyHelper`. A
  * third-party provider overrides both — it is API billing even when the init omitted a

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

@@ -84,6 +84,14 @@ export function parseCodexLoginStatus(stdout) {
         return "api";
     return null;
 }
+/** The refusal message for a codex logged in with an API key, shared by the startup gate, the
+ * live-config warn and the doctor's codex auth check (decision 5): Codex reports no cost, so
+ * per-token billing would spend money the budget cap cannot see. `home` names the codex home
+ * the operator should re-login under; the gate and the live warn pass the literal "<home>"
+ * placeholder because they do not resolve one, while the doctor passes the resolved home. */
+export function codexApiKeyRefusalMessage(home) {
+    return `Codex is logged in with an API key; tumwater runs Codex on a ChatGPT subscription only — run \`CODEX_HOME=${home} codex login --device-auth\``;
+}
 /** The billing the login probe names, or null when it cannot be decided. */
 function seedBilling(config) {
     const status = probeLoginStatus(config);

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

@@ -106,11 +106,11 @@ export const EFFORT_BY_THINKING = {
  * spawn on a model that lists it. */
 const KNOWN_EFFORTS = new Set(Object.values(EFFORT_BY_THINKING));
 /** Map a thinking level to the Codex `model_reasoning_effort` it means, gated by the model's own
- * catalog. `levels` is the model's `supported_reasoning_levels` (design finding 14), which a
- * stream-minted catalog (part 8/9) supplies; until then the caller passes `undefined`, and the
- * result is returned unclamped. An unknown thinking level returns `undefined` (no effort flag) —
- * the level simply has no Codex effort, unlike a thinking level that maps but the model does not
- * support, which is also `undefined`. */
+ * catalog. `levels` is the model's `supported_reasoning_levels` (design finding 14), which the
+ * codex catalog (part 8/9) supplies; when the caller has no catalog it passes `undefined`, and
+ * the result is returned unclamped. An unknown thinking level returns `undefined` (no effort
+ * flag) — the level simply has no Codex effort, unlike a thinking level that maps but the model
+ * does not support, which is also `undefined`. */
 export function codexEffort(thinking, levels) {
     if (!Object.hasOwn(EFFORT_BY_THINKING, thinking))
         return undefined;

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-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; 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.
@@ -12,7 +12,7 @@
  * thread and the existing `handoff` path takes over (design §4). Together with the `resumable`
  * hook, that is every resume point's one rule.
  *
- * Registration lives in src/agent/run-agent.ts beside the pi, claude and opencode adapters; a
+ * Registration lives in src/agent/agent-run.ts beside the pi, claude and opencode adapters; a
  * test selects codex by setting `config.agent = "codex"` on a run. A run carrying a note gets
  * the notes path in its environment (the `tumwater-notes` command on PATH reads it), as the
  * pi and claude adapters do. */

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

@@ -1,18 +1,31 @@
+/** Building the environment for one codex run (plans/codex-backend.md "The invocation" §3,
+ * findings 10, 13) — pure scrub-and-set over a base environment, with no subprocess. The caller
+ * layers the run-marker, the macOS LaunchServices preload and the notes shim on first, then hands
+ * the result here.
+ *
+ * Inherited state from a host Codex or Claude Code session breaks the team run: a Codex child
+ * keeps every `CODEX_*` it was given (finding 13), and `--ignore-user-config` still reads a host
+ * home whose `config.toml` a run writes into (finding 10). So every `CODEX_*`, the host Claude
+ * session's `CLAUDECODE` / `CLAUDE_CODE_*`, and both API keys an operator might carry
+ * (`OPENAI_API_KEY`, `CODEX_API_KEY`) are scrubbed — pi's OpenAI key must never switch Codex to
+ * per-token billing behind tumwater's back (decision 5). Everything else survives, including the
+ * run marker and the PATH that carries the notes shim.
+ *
+ * The set half points Codex at a home of the team's own (`CODEX_HOME`) when one is configured, so
+ * team sessions and trust entries stay out of the operator's `~/.codex` (finding 10). Unset, runs
+ * keep the operator's home. */
+import { scrubEnv } from "../env-scrub.js";
 /** Build the codex process environment from `base`. Never mutates `base`. */
 export function codexEnv(base, opts = {}) {
-    const env = {};
-    for (const [key, value] of Object.entries(base)) {
-        if (key === "CLAUDECODE")
-            continue;
-        if (key.startsWith("CODEX_"))
-            continue;
-        if (key.startsWith("CLAUDE_CODE_"))
-            continue;
-        if (key === "OPENAI_API_KEY" || key === "CODEX_API_KEY")
-            continue;
-        env[key] = value;
-    }
-    if (opts.home)
-        env.CODEX_HOME = opts.home;
-    return env;
+    return scrubEnv(base, {
+        keep: (key) => key !== "CLAUDECODE" &&
+            !key.startsWith("CODEX_") &&
+            !key.startsWith("CLAUDE_CODE_") &&
+            key !== "OPENAI_API_KEY" &&
+            key !== "CODEX_API_KEY",
+        then: (env) => {
+            if (opts.home)
+                env.CODEX_HOME = opts.home;
+        },
+    });
 }

package/dist/src/agent/codex/codex-hook-trust.js

@@ -37,29 +37,48 @@ function hookListMessages(cwd) {
  * `eventName: "preToolUse"` and `command` exactly the guard definition's (finding 3), or null
  * when none matches. The key and hash are returned as codex reports them. */
 function findTrust(result, definition) {
+    for (const group of hookGroups(result)) {
+        for (const hook of groupHooks(group)) {
+            const trust = matchHookTrust(hook, definition);
+            if (trust !== null)
+                return trust;
+        }
+    }
+    return null;
+}
+/** The top-level group list from `hooks/list`'s `result.data`, or `[]` when the result is not
+ * an object or has no array `data`. */
+function hookGroups(result) {
     if (typeof result !== "object" || result === null)
-        return null;
+        return [];
     const data = result.data;
-    if (!Array.isArray(data))
+    if (Array.isArray(data))
+        return data;
+    return [];
+}
+/** One group's hook list from its `hooks` field, or `[]` when the group is not an object or
+ * has no array `hooks`. */
+function groupHooks(group) {
+    if (typeof group !== "object" || group === null)
+        return [];
+    const hooks = group.hooks;
+    if (Array.isArray(hooks))
+        return hooks;
+    return [];
+}
+/** The trust of one hook when it is the guard's — `source` `sessionFlags`, `eventName`
+ * `preToolUse`, `command` exactly the definition's, with string `key` and `currentHash` — or
+ * null. */
+function matchHookTrust(hook, definition) {
+    if (typeof hook !== "object" || hook === null)
         return null;
-    for (const group of data) {
-        if (typeof group !== "object" || group === null)
-            continue;
-        const hooks = group.hooks;
-        if (!Array.isArray(hooks))
-            continue;
-        for (const hook of hooks) {
-            if (typeof hook !== "object" || hook === null)
-                continue;
-            const h = hook;
-            if (h.source !== "sessionFlags" || h.eventName !== "preToolUse")
-                continue;
-            if (h.command !== definition.command)
-                continue;
-            if (typeof h.key === "string" && typeof h.currentHash === "string") {
-                return { key: h.key, hash: h.currentHash };
-            }
-        }
+    const h = hook;
+    if (h.source !== "sessionFlags" || h.eventName !== "preToolUse")
+        return null;
+    if (h.command !== definition.command)
+        return null;
+    if (typeof h.key === "string" && typeof h.currentHash === "string") {
+        return { key: h.key, hash: h.currentHash };
     }
     return null;
 }

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

@@ -29,6 +29,33 @@ function windowStatus(windowType, rateLimitReachedType, usedPercent) {
         return "allowed_warning";
     return "allowed";
 }
+/** The carrier type of one rollout line: an `event_msg` wrapper's `payload.type` when the
+ * outer `type` is `event_msg`, else the outer `type` itself. `task_started`, `task_complete`
+ * and `token_count` come wrapped in an `event_msg` whose `payload.type` discriminates;
+ * `turn_context` and `token_usage_record` name themselves in the outer `type`. Read either. */
+function lineCarrierType(parsed, payload) {
+    return optionalString(parsed.type) === "event_msg" ? optionalString(payload.type) : optionalString(parsed.type);
+}
+/** Whether a `task_started` line begins the read turn and, when it does, its turn id. Each new
+ * task_started begins a fresh turn (a resume appends a second run to the same file), so the
+ * collectors restart at the block we are reading. With no turn id (the adapter's read) every
+ * task_started restarts them and the last block wins; with one, only the requested turn's does. */
+function turnStartReading(payload, sinceTurnStart) {
+    const turnId = optionalString(payload.turn_id);
+    return { turnId, readsTurn: sinceTurnStart === undefined || turnId === sinceTurnStart };
+}
+/** The usage figure a `token_usage_record` line contributes — its `turn_token_usage` when it
+ * carries input or output tokens, else undefined. */
+function usageFromRecord(payload) {
+    const turnUsage = objectOrEmpty(payload.turn_token_usage);
+    return isJsonObject(turnUsage) && (turnUsage.input_tokens !== undefined || turnUsage.output_tokens !== undefined) ? turnUsage : undefined;
+}
+/** The rate limits and `plan_type` a `token_count` line contributes, from its `rate_limits`
+ * object (assigned even when empty). */
+function rateLimitsFromCount(payload) {
+    const rateLimits = objectOrEmpty(payload.rate_limits);
+    return { rateLimits, planType: optionalString(rateLimits.plan_type) };
+}
 /** Scan ONE turn's records out of a rollout's text, tracking `task_started` blocks and
  * collecting the read turn's `turn_context.model`, `token_usage_record` usage, `token_count`
  * rate limits and `plan_type`. `rolloutLines` decides emptiness from `sawTurn`/`lastUsage`;
@@ -47,17 +74,11 @@ function scanTurnRecords(text, sinceTurnStart) {
         if (!parsed)
             continue; // a torn or foreign line belongs to no turn
         const payload = objectOrEmpty(parsed.payload);
-        // `task_started`, `task_complete` and `token_count` come wrapped in an `event_msg` whose
-        // `payload.type` discriminates; `turn_context` and `token_usage_record` name themselves in
-        // the outer `type`. Read either.
-        const ptype = optionalString(parsed.type) === "event_msg" ? optionalString(payload.type) : optionalString(parsed.type);
+        const ptype = lineCarrierType(parsed, payload);
         if (ptype === "task_started") {
-            currentTurn = optionalString(payload.turn_id);
-            // Each new task_started begins a fresh turn (a resume appends a second run to the same
-            // file), so the collectors restart at the block we are reading. With no turn id (the
-            // adapter's read) every task_started restarts them and the last block wins; with one,
-            // only the requested turn's does.
-            if (sinceTurnStart === undefined || currentTurn === sinceTurnStart) {
+            const start = turnStartReading(payload, sinceTurnStart);
+            currentTurn = start.turnId;
+            if (start.readsTurn) {
                 sawTurn = true;
                 lastUsage = undefined;
                 lastRateLimits = undefined;
@@ -73,19 +94,14 @@ function scanTurnRecords(text, sinceTurnStart) {
                 if (model === undefined)
                     model = optionalString(payload.model);
                 break;
-            case "token_usage_record": {
-                const turnUsage = objectOrEmpty(payload.turn_token_usage);
-                if (isJsonObject(turnUsage) && (turnUsage.input_tokens !== undefined || turnUsage.output_tokens !== undefined)) {
-                    lastUsage = turnUsage;
-                }
+            case "token_usage_record":
+                lastUsage = usageFromRecord(payload) ?? lastUsage;
                 break;
-            }
             case "token_count": {
-                const rateLimits = objectOrEmpty(payload.rate_limits);
-                lastRateLimits = rateLimits;
-                const plan = optionalString(rateLimits.plan_type);
-                if (plan !== undefined)
-                    planType = plan;
+                const reading = rateLimitsFromCount(payload);
+                lastRateLimits = reading.rateLimits;
+                if (reading.planType !== undefined)
+                    planType = reading.planType;
                 break;
             }
             default:
@@ -94,52 +110,73 @@ function scanTurnRecords(text, sinceTurnStart) {
     }
     return { sawTurn, lastUsage, lastRateLimits, model, planType };
 }
-/** Assemble the reading's canonical `run_usage`, `billing` and up-to-two `rate_limit` lines
- * (in that order), plus the `switchedTo` model comparison, from scanned records. */
-function buildRolloutLines(records, requestedModel) {
-    // `rolloutLines` guarantees `lastUsage` is a Json object before calling (its presence check
-    // stays there, so this builder never reads `sawTurn`); narrow the shared interface here.
-    const lastUsage = records.lastUsage;
-    const { lastRateLimits, model, planType } = records;
-    const lines = [];
+/** The `run_usage` line of a turn's scanned usage: this run's own input (net of what the
+ * cache already held), output and cache figures (finding 4: the stream reports only the
+ * whole-thread total; the rollout records this run's own). */
+function runUsageLine(lastUsage) {
     const input = finite(lastUsage.input_tokens) ?? 0;
     const cacheRead = finite(lastUsage.cached_input_tokens) ?? 0;
-    lines.push(JSON.stringify({
+    return JSON.stringify({
         type: "run_usage",
         input: Math.max(0, input - cacheRead),
         output: finite(lastUsage.output_tokens) ?? 0,
         cacheRead,
         cacheWrite: finite(lastUsage.cache_write_input_tokens) ?? 0,
-    }));
-    if (planType !== undefined) {
-        // A reading with a plan_type bills on the subscription (finding 5; API-key login is
-        // refused, decision 5).
-        lines.push(JSON.stringify({ type: "billing", billing: "subscription" }));
-    }
+    });
+}
+/** The `billing` line of a turn with a plan_type: a reading with a plan_type bills on the
+ * subscription (finding 5; API-key login is refused, decision 5). */
+function billingLine() {
+    // A reading with a plan_type bills on the subscription (finding 5; API-key login is
+    // refused, decision 5).
+    return JSON.stringify({ type: "billing", billing: "subscription" });
+}
+/** The up-to-two `rate_limit` lines of a turn's scanned rate limits: the primary (5 h) and
+ * the secondary (weekly) windows when both are present and well-formed. */
+function rateLimitLines(lastRateLimits) {
     // Two windows when present: the primary (5 h) and the secondary (weekly). A killed run's
     // rollout has a token_usage_record but no token_count, so it yields run_usage with no
     // rate_limit (finding 23).
-    if (lastRateLimits !== undefined) {
-        const reached = optionalString(lastRateLimits.rate_limit_reached_type);
-        for (const key of ["primary", "secondary"]) {
-            const windowRaw = lastRateLimits[key];
-            if (!isJsonObject(windowRaw))
-                continue;
-            const minutes = finite(windowRaw.window_minutes);
-            if (minutes === undefined)
-                continue;
-            const typeName = windowTypeName(minutes);
-            const usedPercent = finite(windowRaw.used_percent);
-            lines.push(JSON.stringify({
-                type: "rate_limit",
-                rateLimitType: typeName,
-                status: windowStatus(typeName, reached, usedPercent),
-                ...(usedPercent !== undefined ? { utilization: usedPercent / 100 } : {}),
-                ...(finite(windowRaw.resets_at) !== undefined ? { resetsAt: finite(windowRaw.resets_at) } : {}),
-            }));
-        }
+    if (lastRateLimits === undefined)
+        return [];
+    const reached = optionalString(lastRateLimits.rate_limit_reached_type);
+    const lines = [];
+    for (const key of ["primary", "secondary"]) {
+        const windowRaw = lastRateLimits[key];
+        if (!isJsonObject(windowRaw))
+            continue;
+        const minutes = finite(windowRaw.window_minutes);
+        if (minutes === undefined)
+            continue;
+        const typeName = windowTypeName(minutes);
+        const usedPercent = finite(windowRaw.used_percent);
+        lines.push(JSON.stringify({
+            type: "rate_limit",
+            rateLimitType: typeName,
+            status: windowStatus(typeName, reached, usedPercent),
+            ...(usedPercent !== undefined ? { utilization: usedPercent / 100 } : {}),
+            ...(finite(windowRaw.resets_at) !== undefined ? { resetsAt: finite(windowRaw.resets_at) } : {}),
+        }));
+    }
+    return lines;
+}
+/** The model this turn switched to when its `turn_context.model` differs from what the run
+ * requested (finding 24): the model itself, else undefined for no switch. */
+function switchedToModel(model, requestedModel) {
+    return model !== undefined && model !== requestedModel ? model : undefined;
+}
+/** Assemble the reading's canonical `run_usage`, `billing` and up-to-two `rate_limit` lines
+ * (in that order), plus the `switchedTo` model comparison, from scanned records. */
+function buildRolloutLines(records, requestedModel) {
+    // `rolloutLines` guarantees `lastUsage` is a Json object before calling (its presence check
+    // stays there, so this builder never reads `sawTurn`); narrow the shared interface here.
+    const lastUsage = records.lastUsage;
+    const lines = [runUsageLine(lastUsage)];
+    if (records.planType !== undefined) {
+        lines.push(billingLine());
     }
-    const switchedTo = model !== undefined && requestedModel !== undefined && model !== requestedModel ? model : undefined;
+    lines.push(...rateLimitLines(records.lastRateLimits));
+    const switchedTo = switchedToModel(records.model, requestedModel);
     return { lines, ...(switchedTo !== undefined ? { switchedTo } : {}) };
 }
 /** Read the records of ONE turn out of a rollout's text. A rollout is one file per thread that

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

@@ -10,7 +10,7 @@
  * state (the open tool calls, the turn's usage fallback, the unmapped native types seen), so
  * call it once per run. Unmapped native types, the distinct text of `error` items, and a
  * command abandoned at the end of its turn are recorded once each on the seam's optional
- * `warnings()` — src/agent/run-stream.ts forwards each as an `agent_unknown_event` warning
+ * `warnings()` — src/agent/agent-stream.ts forwards each as an `agent_unknown_event` warning
  * after the run. `sessionId()` reports the thread id once `thread.started` has named it.
  */
 import { nonNegativeNumber, objectOrEmpty, parseJsonObject } from "../../files/json-object.js";

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

@@ -0,0 +1,18 @@
+/** Shared environment-building skeleton for the three agent backend env builders
+ * (claude-env.ts, codex-env.ts, opencode-env.ts). Each backend isolates one run the same shape:
+ * copy the keys of `base` that survive the scrub, then let the backend set its own run vars.
+ * The copy half never writes anything but `keep`-accepted keys of `base`, so a caller's base
+ * (the process env, or a layered run-marker/notes/preload env) is never mutated — the invariant
+ * the per-backend tests pin. */
+/** Build a process environment from `base` under `scrub` without mutating `base`: copy the
+ * `keep`-accepted base entries into a fresh object, then hand it to `then` for the backend's
+ * own additions. */
+export function scrubEnv(base, scrub) {
+    const env = {};
+    for (const [key, value] of Object.entries(base)) {
+        if (scrub.keep(key))
+            env[key] = value;
+    }
+    scrub.then(env);
+    return env;
+}