tumwater 0.4.2 → 0.4.4

package/dist/src/agent/image-input.js

@@ -1,12 +1,14 @@
 /** The seam's answer to "who in this team can read images" (plans/image-input.md
- * "Capability"). One resolver, `seamImageInput`, is the only place that rule lives, so the
- * answer is never reached two ways. It lives at runtime level because it needs the backend
- * registry: a claude seam is always capable through the AgentBackend.imageInput hook, a pi
- * seam reads the model's `input` in models.json, and any other backend answers null unless it
- * declares a hook. */
-import { configForRole } from "../config/config-views.js";
-import { seamAgent } from "../config/model-selector.js";
-import { piModelImageInput, piModelsPath, readPiProviders } from "../pi/pi-models.js";
+ * "Capability"). One resolver, `seamImageInput`, is the only place that rule lives; the reroute
+ * target (imageReroute) and the per-role surfaces (roleImageInfo) both read it, so the answer
+ * is never reached two ways. It lives at runtime level because it needs the backend registry:
+ * a claude seam is always capable through the AgentBackend.imageInput hook, a pi seam reads the
+ * model's `input` in models.json, and any other backend answers null unless it declares a hook. */
+import { configForRole, roleSeamTier, withModelOverrides } from "../config/config-views.js";
+import { BORROW_ORDER, resolveTierFallbacks } from "../config/config-fallbacks.js";
+import { seamAgent } from "../config/config-model-selector.js";
+import { modelLabel } from "./backend-traits.js";
+import { piModelImageInput, piPairFree, piModelsPath, readPiProviders } from "../pi/pi-models.js";
 import { piListedImageInput } from "../pi/pi-listed-models.js";
 import { backendById } from "./agent-backend.js";
 /** One seam's image-input capability (plans/image-input.md "Capability"): `true` when the
@@ -32,12 +34,67 @@ export function seamImageInput(seam, providers, listed = null) {
         return null;
     return piModelImageInput(providers, seam.provider, seam.model) ?? piListedImageInput(listed, seam.provider, seam.model);
 }
+/** The image-capable reroute target for `role`, or null when no peer tier can read images
+ * (plans/image-input.md "Reroute target"). Walks the role's seam tier through BORROW_ORDER,
+ * skipping the tier itself — small → default → strong, default → strong → small, strong →
+ * default (a strong-tier seam never drops to small, the same rule as the budget fallback) —
+ * and takes the first tier whose model reads images. `regime` picks the pair set (see
+ * RerouteRegime); `modelsPath` and `account` are injectable so tests need no real pi install
+ * or account. */
+export function imageReroute(config, role, regime = "primary", modelsPath = piModelsPath(), account = null, providers = null, listed = null) {
+    const tier = roleSeamTier(config, role);
+    const candidates = BORROW_ORDER[tier].filter((t) => t !== tier);
+    if (candidates.length === 0)
+        return null;
+    const providerMap = providers ?? readPiProviders(modelsPath);
+    const capable = (rc) => seamImageInput(rc, providerMap, listed) === true;
+    if (regime === "primary") {
+        for (const t of candidates) {
+            const rc = withModelOverrides(config, t, {});
+            if (capable(rc))
+                return { tier: t, config: rc };
+        }
+        return null;
+    }
+    // Fallback regime: only the tiers' free fallback pairs qualify (resolveTierFallbacks over the
+    // price check), never a priced primary model — a reroute must not spend past the cap.
+    const resolved = resolveTierFallbacks(config, (p) => 
+    // The free-ness lookup reads the one claude account held here (part 2a/9).
+    piPairFree(providerMap, p, (b) => (b === "claude" ? account : null)));
+    for (const t of candidates) {
+        const pair = resolved[t].pair;
+        if (!pair)
+            continue;
+        const rc = withModelOverrides(config, t, {
+            provider: pair.provider,
+            model: pair.model,
+            thinking: pair.thinking,
+        });
+        if (capable(rc))
+            return { tier: t, config: rc };
+    }
+    return null;
+}
+/** The config of imageReroute, for callers that want only the target model. */
+export function imageRerouteTarget(config, role, regime = "primary", modelsPath = piModelsPath(), account = null, providers = null, listed = null) {
+    return imageReroute(config, role, regime, modelsPath, account, providers, listed)?.config ?? null;
+}
+/** A seam's model as one readable token, the same label the doctor's `image input` check used
+ * (`claude/<id>` for a claude seam, `provider/model` for pi), delegated to backend-traits'
+ * modelLabel. Used by roleImageInfo alone. */
+function seamImageLabel(backend, provider, model) {
+    return modelLabel(backend, provider, model);
+}
 /** Compute RoleImageInfo for one role. `modelsPath` and `listed` are injectable; the providers
- * catalog is read (stat-cached) here. The reroute field is a literal null — the peer-tier image
- * reroute was subtracted (part 5g/6), so no role names a reroute target; 5h removes the field. */
+ * catalog is read (stat-cached) here and also handed to imageReroute so a poll that asks many
+ * roles still parses the catalog once. */
 export function roleImageInfo(config, role, modelsPath = piModelsPath(), listed = null) {
     const providers = readPiProviders(modelsPath);
     const rc = configForRole(config, role);
     const imageInput = seamImageInput(rc, providers, listed);
-    return { imageInput, imageReroute: null };
+    const rr = imageReroute(config, role, "primary", modelsPath, null, providers, listed);
+    const imageRerouteStr = rr
+        ? `${rr.tier} (${seamImageLabel(rr.config.agent, rr.config.provider, rr.config.model)})`
+        : null;
+    return { imageInput, imageReroute: imageRerouteStr };
 }

package/dist/src/agent/notes-shim.js

@@ -1,5 +1,5 @@
 /** Installing the per-team `tumwater-notes` shim every backend's run finds on its PATH
- * (plans/notes-command.md "Reaching it from a run"): run-spawn calls `ensureNotesShim(root)`
+ * (plans/notes-command.md "Reaching it from a run"): agent-spawn calls `ensureNotesShim(root)`
  * before building each invocation, and the backend prepends the returned dir to the run's
  * PATH (backendBaseEnv's `binDir`, src/process/run-marker.ts). The shim is a two-line `sh`
  * script that execs the compiled notes CLI, so a model's shell — pi's, Claude Code's or
@@ -20,7 +20,7 @@ export const NOTES_SHIM_NAME = "tumwater-notes";
 /** Install the `tumwater-notes` shim under `<root>/.tumwater/bin` and return that directory.
  * The shim is written atomically with mode 0755, only when its content differs from what is
  * already there (a redeploy that changes `<dist>` rewrites it). Never throws: a failure to
- * write is the caller's to absorb — run-spawn logs one warning and runs without the shim. */
+ * write is the caller's to absorb — agent-spawn logs one warning and runs without the shim. */
 export function ensureNotesShim(root, execPath = process.execPath) {
     const dir = notesShimDir(root);
     const target = path.join(dir, NOTES_SHIM_NAME);

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

@@ -1,7 +1,7 @@
 /** The opencode adapter for the agent seam (plans/opencode-backend.md "The invocation",
  * "Sessions", §6). It shapes one run's argv/stdin/env, translates opencode's `run --format
  * json` into the canonical stream, runs the authoritative session export after the process
- * exits, and classifies the exit's stderr — everything backend-specific. src/agent/run-spawn.ts
+ * exits, and classifies the exit's stderr — everything backend-specific. src/agent/agent-spawn.ts
  * spawns the run and records this run in the session ledger; opencode mints its own session id
  * (a `ses_…` id, or the resumed record's id), which `invocation` returns so the ledger can
  * carry it.
@@ -13,7 +13,7 @@
  * the only thing that stops a follow-up running against an empty session. Anything else mints a
  * fresh id (design §4).
  *
- * Registration lives in src/agent/run-agent.ts beside the pi and claude adapters; a test selects
+ * Registration lives in src/agent/agent-run.ts beside the pi and claude adapters; a test selects
  * opencode by setting `config.agent = "opencode"` 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. */
@@ -79,42 +79,44 @@ export function opencodeSpillDir(root) {
 function catalogModelKey(model) {
     return opencodeModelKey(model);
 }
-/** Run `opencode session export <id> --standalone` (the same database the run used, bounded at
- * 10 s) and return whether it reported success — the existence check that decides a resume.
- * Nonzero exit, a timeout, or a spawn failure all read as "no such session", which is the safe
- * direction: `--session` would otherwise silently create a missing session. */
-function opencodeSessionExists(id, env, bin, cwd) {
+/** Run the bounded `opencode session export <id> --standalone` spawn that both the resume
+ * existence check and the reconciling export issue, under the same env/cwd and the shared
+ * 10 s bound. `capture` is false for the existence check, which reads only the exit status:
+ * `stdio: "ignore"` keeps the export — which carries every message of the session — out of
+ * memory and below the default 1 MiB `maxBuffer`, whose `ENOBUFS` kill would otherwise make a
+ * large but real session read as absent and mint a fresh one. Returns the spawn result, or null
+ * when the spawn itself threw — a missing binary or an invalid option, resolved the same way
+ * both callers treated a throw. The command line, env, cwd and timeout live here once, so the
+ * existence check and the reconciling export cannot drift on what they run. */
+function runSessionExport(id, env, bin, cwd, capture = true) {
     try {
-        const res = spawnSync(bin, ["session", "export", id, "--standalone"], {
+        return spawnSync(bin, ["session", "export", id, "--standalone"], {
             env,
             cwd,
             timeout: EXPORT_TIMEOUT_MS,
-            stdio: "ignore",
+            encoding: "utf8",
+            stdio: capture ? "pipe" : "ignore",
         });
-        return res.status === 0;
     }
     catch {
-        return false;
+        return null;
     }
 }
+/** Run `opencode session export <id> --standalone` (the same database the run used, bounded at
+ * 10 s) and return whether it reported success — the existence check that decides a resume.
+ * Nonzero exit, a timeout, or a spawn failure all read as "no such session", which is the safe
+ * direction: `--session` would otherwise silently create a missing session. */
+function opencodeSessionExists(id, env, bin, cwd) {
+    const res = runSessionExport(id, env, bin, cwd, false);
+    return res?.status === 0;
+}
 /** Run the reconciling export after a successful run and return its two canonical lines
  * (`run_cost`, `run_usage`) from the session's `info`. Anything that goes wrong — a spawn or
  * timeout, a nonzero exit, unparseable or malformed output — returns `[]`, and the caller
  * (afterRun) reports `opencode_usage_partial` so the run keeps its streamed numbers. */
 function opencodeExport(result) {
-    let res;
-    try {
-        res = spawnSync(result.bin, ["session", "export", result.id, "--standalone"], {
-            env: result.env,
-            cwd: result.cwd,
-            timeout: EXPORT_TIMEOUT_MS,
-            encoding: "utf8",
-        });
-    }
-    catch {
-        return [];
-    }
-    if (res.status !== 0 || !res.stdout)
+    const res = runSessionExport(result.id, result.env, result.bin, result.cwd);
+    if (res?.status !== 0 || !res.stdout)
         return [];
     let parsed;
     try {

package/dist/src/agent/opencode/opencode-catalog.js

@@ -9,6 +9,7 @@
 import { spawnSync } from "node:child_process";
 import { isJsonObject, validEntries } from "../../files/json-object.js";
 import { readJsonFile, writeJsonAtomic } from "../../files/json-files.js";
+import { cachedByStat } from "../../files/stat-cache.js";
 import { errorMessage } from "../../text/text.js";
 import { DAY_MS } from "../../text/datetime.js";
 import { opencodeModelsPath } from "../../paths.js";
@@ -21,6 +22,25 @@ const CATALOG_URL = "https://models.dev/api.json";
 const CATALOG_FETCH_TIMEOUT_MS = 30_000;
 /** How long a fetched cache is trusted before it is refreshed. */
 const CATALOG_CACHE_TTL_MS = DAY_MS;
+/** Per-catalog cache of the parsed catalog, keyed by the models.json path: the status
+ * snapshot and the budget gate both poll it every second while the file changes only when a
+ * refresh re-fetches models.dev — and it grows with the models.dev catalog — so an
+ * unchanged file costs one stat per poll instead of a re-read plus a JSON.parse and a
+ * validation of the whole file (the same stat-keyed contract readOpencodeCache's siblings
+ * readCodexCatalog, readPiProviders and readMergeQueue already use). Any write invalidates
+ * via dev/ino/mtime/size (stat-cache.cachedByStat's freshness check). */
+const catalogCache = new Map();
+/** A structural copy of a parsed catalog, so a caller that mutates its own result (e.g.
+ * observeOpencodeRun sets `billedAt` on an entry) never reaches the shared cache entry; the
+ * next poll re-derives from the file. The entries are plain data (`efforts` arrays included)
+ * so a shallow model-object spread suffices. */
+function cloneCache(cache) {
+    const models = {};
+    for (const [key, entry] of Object.entries(cache.models)) {
+        models[key] = entry.efforts !== undefined ? { ...entry, efforts: [...entry.efforts] } : { ...entry };
+    }
+    return { fetchedAt: cache.fetchedAt, cliVersion: cache.cliVersion, models };
+}
 const defaultFetch = async (url, timeoutMs) => {
     const res = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
     if (!res.ok)
@@ -33,6 +53,53 @@ const defaultFetch = async (url, timeoutMs) => {
 export async function fetchOpencodeCatalog(fetchFn = defaultFetch) {
     return fetchFn(CATALOG_URL, CATALOG_FETCH_TIMEOUT_MS);
 }
+/** The catalog root `parseOpencodeCatalog` iterates: models.dev's live api.json puts the provider
+ * map at the top level, OpenCode's cached copy wraps that same map under a `body` key. */
+function catalogRoot(body) {
+    const root = isJsonObject(body) ? body : {};
+    // models.dev's api.json IS the provider map; OpenCode's cached copy wraps that map under `body`.
+    const wrapped = root.body;
+    return isJsonObject(wrapped) ? wrapped : root;
+}
+/** The free/priced reads from a per-model cost block: whether it is present and yields two zero
+ * per-M prices. A missing cost block is unknown price data, and treating it as $0 is the unsafe
+ * direction for a budget gate. */
+function modelPricing(m) {
+    const cost = isJsonObject(m.cost) ? m.cost : undefined;
+    const input = cost?.input ?? 0;
+    const output = cost?.output ?? 0;
+    return {
+        costed: cost !== undefined,
+        free: cost !== undefined && input === 0 && output === 0,
+        inputPerM: input,
+        outputPerM: output,
+    };
+}
+/** The effort levels from a per-model object: the `values` of the `reasoning_options` entries
+ * whose `type` is `"effort"`. */
+function modelEfforts(m) {
+    if (!Array.isArray(m.reasoning_options))
+        return [];
+    return m.reasoning_options.flatMap((r) => isJsonObject(r) && r.type === "effort" && Array.isArray(r.values) ? r.values : []);
+}
+/** Build one catalog model from an untrusted per-model object, null when it is malformed. */
+function catalogModelFrom(m) {
+    const pricing = modelPricing(m);
+    const model = { free: pricing.free };
+    if (pricing.costed) {
+        model.inputPerM = pricing.inputPerM;
+        model.outputPerM = pricing.outputPerM;
+    }
+    if (isJsonObject(m.limit) && m.limit.context !== undefined)
+        model.context = m.limit.context;
+    if (isJsonObject(m.modalities) && Array.isArray(m.modalities.input)) {
+        model.images = m.modalities.input.includes("image");
+    }
+    const efforts = modelEfforts(m);
+    if (efforts.length > 0)
+        model.efforts = efforts;
+    return isOpencodeCatalogModel(model) ? model : null;
+}
 /** Parse models.dev's `api.json` into the models the config routes through OpenCode: always the
  * `opencode` provider, plus every provider named in `providers` (the config's
  * `opencode/<provider>/…` routes — `opencode-go` and so on). The live `GET /api.json` returns
@@ -43,11 +110,7 @@ export async function fetchOpencodeCatalog(fetchFn = defaultFetch) {
  * provider or model is skipped, never thrown on. */
 export function parseOpencodeCatalog(body, providers) {
     const out = {};
-    const root = isJsonObject(body) ? body : {};
-    // models.dev's api.json IS the provider map; OpenCode's cached copy wraps that map under `body`.
-    const wrapped = root.body;
-    const catalog = isJsonObject(wrapped) ? wrapped : root;
-    for (const [provider, providerInfo] of Object.entries(catalog)) {
+    for (const [provider, providerInfo] of Object.entries(catalogRoot(body))) {
         if (provider !== "opencode" && !providers.includes(provider))
             continue;
         if (!isJsonObject(providerInfo) || !isJsonObject(providerInfo.models))
@@ -55,28 +118,8 @@ export function parseOpencodeCatalog(body, providers) {
         for (const [id, m] of Object.entries(providerInfo.models)) {
             if (!isJsonObject(m))
                 continue;
-            // Only a present cost block marks a model free: a missing cost block is unknown price data,
-            // and treating it as $0 is the unsafe direction for a budget gate.
-            const cost = isJsonObject(m.cost) ? m.cost : undefined;
-            const input = cost?.input ?? 0;
-            const output = cost?.output ?? 0;
-            const model = { free: cost !== undefined && input === 0 && output === 0 };
-            if (cost !== undefined) {
-                model.inputPerM = input;
-                model.outputPerM = output;
-            }
-            if (isJsonObject(m.limit) && m.limit.context !== undefined)
-                model.context = m.limit.context;
-            if (isJsonObject(m.modalities) && Array.isArray(m.modalities.input)) {
-                model.images = m.modalities.input.includes("image");
-            }
-            if (Array.isArray(m.reasoning_options)) {
-                const efforts = m.reasoning_options
-                    .flatMap((r) => isJsonObject(r) && r.type === "effort" && Array.isArray(r.values) ? r.values : []);
-                if (efforts.length > 0)
-                    model.efforts = efforts;
-            }
-            if (isOpencodeCatalogModel(model))
+            const model = catalogModelFrom(m);
+            if (model !== null)
                 out[`${provider}/${id}`] = model;
         }
     }
@@ -137,15 +180,21 @@ function isOpencodeCatalogModel(value) {
  * fills the file in. Entries that are not well-formed catalog models are dropped, so a foreign
  * entry reads as a model missing from the cache — not free. */
 export function readOpencodeCache(root) {
-    const existing = readJsonFile(opencodeModelsPath(root));
-    if (existing !== null && typeof existing.fetchedAt === "number" && isJsonObject(existing.models)) {
-        return {
-            fetchedAt: existing.fetchedAt,
-            cliVersion: typeof existing.cliVersion === "string" ? existing.cliVersion : undefined,
-            models: validEntries(existing.models, isOpencodeCatalogModel),
-        };
-    }
-    return { fetchedAt: 0, models: {} };
+    const file = opencodeModelsPath(root);
+    const cached = cachedByStat(catalogCache, file, file, () => {
+        // readJsonFile is the shared "missing or torn reads as no data" policy; a torn write
+        // or a malformed file reads as an empty cache (fetchedAt 0), exactly as before.
+        const existing = readJsonFile(file);
+        if (existing !== null && typeof existing.fetchedAt === "number" && isJsonObject(existing.models)) {
+            return {
+                fetchedAt: existing.fetchedAt,
+                cliVersion: typeof existing.cliVersion === "string" ? existing.cliVersion : undefined,
+                models: validEntries(existing.models, isOpencodeCatalogModel),
+            };
+        }
+        return { fetchedAt: 0, models: {} };
+    }, cloneCache);
+    return cached ?? { fetchedAt: 0, models: {} };
 }
 /** Persist the catalog cache atomically under `.tumwater/state/`. */
 export function writeOpencodeCache(root, cache) {

package/dist/src/agent/opencode/opencode-config.js

@@ -38,29 +38,47 @@ const DENIED_PERMISSIONS = [
 function isCommentStart(src, i) {
     return src[i] === "/" && (src[i + 1] === "/" || src[i + 1] === "*");
 }
+/** True when `c` is a JSONC whitespace character. */
+function isWhitespace(c) {
+    return c === " " || c === "\t" || c === "\n" || c === "\r";
+}
+/** Advance `j` past a `//` line comment (a caller-supplied position where `src[j] === "/"`
+ * and `src[j + 1] === "/"`), not past the terminating newline. */
+function skipLineComment(src, j) {
+    while (j < src.length && src[j] !== "\n")
+        j += 1;
+    return j;
+}
+/** Advance `j` past a `/*`-style block comment (a caller-supplied position where `src[j] ===
+ * "/"` and `src[j + 1] === "*"`), ending after its closing two characters. An unterminated
+ * comment leaves `j` at `src.length + 2`, overshooting past the end — today's behaviour, kept. */
+function skipBlockComment(src, j) {
+    j += 2;
+    while (j < src.length && !(src[j] === "*" && src[j + 1] === "/"))
+        j += 1;
+    j += 2;
+    return j;
+}
+/** Advance `j` past one comment, dispatching on the second character: `//` to the line-comment
+ * scan, `/*` to the block-comment scan (a caller-supplied position where `isCommentStart`
+ * holds). */
+function skipComment(src, j) {
+    return src[j + 1] === "/" ? skipLineComment(src, j) : skipBlockComment(src, j);
+}
 /** Advance `j` past any whitespace and comments, for a position that is never inside a string.
  * Returns the index of the next significant (non-comment, non-whitespace) character, or
  * `src.length` when the input ends in comments/whitespace. */
 function skipWhitespaceAndComments(src, j) {
     while (j < src.length) {
-        const c = src[j];
-        if (c === " " || c === "\t" || c === "\n" || c === "\r") {
+        if (isWhitespace(src[j])) {
             j += 1;
-            continue;
         }
-        if (c === "/" && src[j + 1] === "/") {
-            while (j < src.length && src[j] !== "\n")
-                j += 1;
-            continue;
+        else if (isCommentStart(src, j)) {
+            j = skipComment(src, j);
         }
-        if (c === "/" && src[j + 1] === "*") {
-            j += 2;
-            while (j < src.length && !(src[j] === "*" && src[j + 1] === "/"))
-                j += 1;
-            j += 2;
-            continue;
+        else {
+            break;
         }
-        break;
     }
     return j;
 }

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

@@ -14,22 +14,21 @@
  * the model to pass `timeout` for the check (§5). `XDG_CONFIG_HOME` and its siblings are NOT
  * set: OpenCode's shell-tool children inherit the environment, and pointing XDG at a private
  * dir would stop `git` reading `~/.config/git/config`, losing commits' author identity (§3). */
+import { scrubEnv } from "../env-scrub.js";
 /** Build the opencode process environment from `base`. Never mutates `base`. */
 export function opencodeEnv(base, opts) {
-    const env = {};
-    for (const [key, value] of Object.entries(base)) {
+    return scrubEnv(base, {
         // Everything an inherited OpenCode session set is scrubbed — server, config, database,
         // client and session id — except the operator's API key, which is operator intent and must
         // survive. `AI_AGENT` goes too, so the shell tool sets its own (finding 16).
-        if (key === "OPENCODE" || (key.startsWith("OPENCODE_") && key !== "OPENCODE_API_KEY") || key === "AI_AGENT")
-            continue;
-        env[key] = value;
-    }
-    env.OPENCODE_DISABLE_CLAUDE_CODE = "1";
-    env.OPENCODE_DISABLE_CLAUDE_CODE_SKILLS = "1";
-    env.OPENCODE_DISABLE_AUTOUPDATE = "1";
-    env.OPENCODE_DISABLE_FILEWATCHER = "1";
-    env.OPENCODE_DB = opts.dbPath;
-    env.OPENCODE_CONFIG_CONTENT = opts.configContent;
-    return env;
+        keep: (key) => !(key === "OPENCODE" || (key.startsWith("OPENCODE_") && key !== "OPENCODE_API_KEY") || key === "AI_AGENT"),
+        then: (env) => {
+            env.OPENCODE_DISABLE_CLAUDE_CODE = "1";
+            env.OPENCODE_DISABLE_CLAUDE_CODE_SKILLS = "1";
+            env.OPENCODE_DISABLE_AUTOUPDATE = "1";
+            env.OPENCODE_DISABLE_FILEWATCHER = "1";
+            env.OPENCODE_DB = opts.dbPath;
+            env.OPENCODE_CONFIG_CONTENT = opts.configContent;
+        },
+    });
 }

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

@@ -28,49 +28,71 @@ const TOOL_NAMES = {
 /** A Retry-After hint spelled out in a rate-limit error's message text ("retry after 30s" /
  * "retry in 30 seconds"). */
 const RETRY_AFTER = /retry (?:after|in) (\d+)\s*s(?:econds?)?\b/i;
-/** How an `error` line classifies into the canonical `tumwaterKind` (and, for a transient
- * backend, its kind), trusted by `PiStreamParser` before its text regexes. The error's
- * `type` — the provider signal the plan's table maps (provider.auth, provider.no-route,
- * unknown) — is consulted FIRST, the message text second (plans/opencode-backend.md §8 and
- * its classification table). */
-function classifyError(err) {
-    const message = typeof err.message === "string" ? err.message : "";
-    const type = typeof err.type === "string" ? err.type : "";
-    const status = err.status;
-    // The free tier refuses intermittently (a provider failure, not a config error): three
-    // refusals in a row move the tier to its fallback through the existing model-failure
-    // episode. Typed `provider.auth` WITH status 403 — the free tier's own refusal — or the
-    // text naming the free tier. A `provider.auth` with any other status (a 401 bad
-    // credential) is not a refusal and falls through to the config-error row below.
+;
+/** Is this the free tier's intermittent refusal (a provider failure, not a config error)?
+ * Three refusals in a row move the tier to its fallback through the existing model-failure
+ * episode. Typed `provider.auth` WITH status 403 — the free tier's own refusal — or the
+ * text naming the free tier. A `provider.auth` with any other status (a 401 bad
+ * credential) is not a refusal and falls through to the config-error row. */
+function freeTierClassification(type, status, message) {
     if ((type === "provider.auth" && status === 403) || /free\s?tier|FreeTierError/i.test(message))
         return { kind: "transientBackend", backendKind: "server", freeTier: true };
-    // Rate limiting — 429 or rate-limit text — is the world saying "later", inherently
-    // retryable; carry the echoed Retry-After hint when the message spells it.
+    return undefined;
+}
+/** Is this a rate limit (429 or rate-limit text) — the world saying "later", inherently
+ * retryable? Carry the echoed Retry-After hint when the message spells it. */
+function rateLimitClassification(status, message) {
     if (status === 429 || /\b429\b|rate limit|too many requests/i.test(message)) {
         const retry = RETRY_AFTER.exec(message);
         return { kind: "transientRateLimit", ...(retry ? { retryAfterSeconds: Number(retry[1]) } : {}) };
     }
-    // An unknown model or variant, and the malformed `ses_` id, are permanent config errors
-    // (a misconfiguration, not a transient outage): typed `provider.no-route` / `unknown`, or
-    // the model-not-found / 401 text.
+    return undefined;
+}
+/** Is this a permanent config error — an unknown model or variant, or the malformed `ses_`
+ * id (a misconfiguration, not a transient outage): typed `provider.no-route` / `unknown`,
+ * or the model-not-found / 401 text? */
+function configErrorClassification(type, status, message) {
     if (type === "provider.no-route" ||
         type === "unknown" ||
         status === 401 ||
         /unknown model|unknown provider|model not found|provider not found|unauthorized|status\s*401|\b401\b/i.test(message))
         return { kind: "configError" };
-    // Context overflow that compaction could not fix. Matched STRICTLY (the same shape pi's
-    // own CONTEXT_ERROR matches), so a message that merely mentions "context" or "too long"
-    // in passing — a plugin error, say — is never misread as an overflow that would then be
-    // trusted by PiStreamParser over its own tighter regex.
+    return undefined;
+}
+/** Did context overflow in a way compaction could not fix? Matched STRICTLY (the same shape
+ * pi's own CONTEXT_ERROR matches), so a message that merely mentions "context" or "too long"
+ * in passing — a plugin error, say — is never misread as an overflow that would then be
+ * trusted by PiStreamParser over its own tighter regex. */
+function contextOverflowClassification(message) {
     if (/context (size|length|window)?\s*(has been |was )?exceeded|exceeds? (the )?context|too (long|large) for .*context/i.test(message))
         return { kind: "contextExceeded" };
-    // Transient server, connection and timeout failures.
+    return undefined;
+}
+/** Is this a transient server, connection or timeout failure? The server statuses and text
+ * first, then the shared connection/timeout prose vocabulary (see `transientProseKind`). */
+function transientClassification(message) {
     if (/\b(500|501|502|503|504|529)\b|internal server error|bad gateway|service unavailable|gateway timeout|overloaded/i.test(message))
         return { kind: "transientBackend", backendKind: "server" };
     const prose = transientProseKind(message);
     if (prose)
         return prose;
-    return {};
+    return undefined;
+}
+/** How an `error` line classifies into the canonical `tumwaterKind` (and, for a transient
+ * backend, its kind), trusted by `PiStreamParser` before its text regexes. The error's
+ * `type` — the provider signal the plan's table maps (provider.auth, provider.no-route,
+ * unknown) — is consulted FIRST, the message text second (plans/opencode-backend.md §8 and
+ * its classification table). */
+function classifyError(err) {
+    const message = typeof err.message === "string" ? err.message : "";
+    const type = typeof err.type === "string" ? err.type : "";
+    const status = err.status;
+    return (freeTierClassification(type, status, message) ??
+        rateLimitClassification(status, message) ??
+        configErrorClassification(type, status, message) ??
+        contextOverflowClassification(message) ??
+        transientClassification(message) ??
+        {});
 }
 /** The step's token counts and cost → pi's canonical usage block: the four counts, their sum
  * as `totalTokens`, and `cost.total` = the step's USD cost (plans/opencode-backend.md §6).

package/dist/src/agent/session-ledger.js

@@ -39,7 +39,7 @@ export function recordSession(dir, record) {
     }
 }
 /** The one run's ledger record, minus the id the two recording sites mint differently — the
- * pre-spawn id in run-spawn.ts, or the stream-minted session id in run-stream.ts. One place
+ * pre-spawn id in agent-spawn.ts, or the stream-minted session id in agent-stream.ts. One place
  * for the record's non-id shape (agent, kind, name, cwd, the optional model and the stamp), so
  * the two appends cannot drift on the model spread or the required fields. `agent` is the
  * owning backend's id; the run options supply the rest. */
@@ -191,6 +191,24 @@ export function pruneSessionLedgers(sessionsRoot, days) {
 /** How long one `opencode session delete <id> --standalone` may take before it gives up: the
  * session export measured 0.18 s live, so 10 s is a generous bound on a slow or wedged CLI. */
 const SESSION_DELETE_TIMEOUT_MS = 10_000;
+/** Run one bounded headless CLI session delete (`bin args…`) under `env`, best-effort: a
+ * spawn that throws (a missing binary, an unwritable env) returns false without throwing, so
+ * a failed delete never fails the prune. Shared by the OpenCode and Codex session purges below
+ * so neither drift on the 10 s bound, the status-0 success rule, or the swallow policy. */
+function sessionDeleteSucceeds(bin, args, env) {
+    try {
+        const res = spawnSync(bin, args, {
+            env,
+            timeout: SESSION_DELETE_TIMEOUT_MS,
+            stdio: "ignore",
+        });
+        return res.status === 0;
+    }
+    catch {
+        // Best effort: an unwritable env or a missing binary must not fail the prune.
+        return false;
+    }
+}
 /** Delete each OpenCode session the ledger records as expired, with one
  * `opencode session delete <id> --standalone` each (bounded), plus the spill files older than
  * the window in the team's shell spill dir. The session's spill files and server state live
@@ -209,18 +227,8 @@ export function pruneOpencodeSessions(sessionsRoot, days, opts) {
             for (const record of readSessions(path.dirname(file))) {
                 if (record.agent !== "opencode" || record.at >= cutoff)
                     continue;
-                try {
-                    const res = spawnSync(opts.bin, ["session", "delete", record.id, "--standalone"], {
-                        env: opts.env,
-                        timeout: SESSION_DELETE_TIMEOUT_MS,
-                        stdio: "ignore",
-                    });
-                    if (res.status === 0)
-                        deleted += 1;
-                }
-                catch {
-                    // Best effort: an unwritable env or a missing binary must not fail the prune.
-                }
+                if (sessionDeleteSucceeds(opts.bin, ["session", "delete", record.id, "--standalone"], opts.env))
+                    deleted += 1;
             }
         });
     }
@@ -276,20 +284,8 @@ export function pruneCodexSessions(sessionsRoot, days, opts) {
     for (const id of expired) {
         if (live.has(id))
             continue;
-        if (opts.bin !== undefined) {
-            try {
-                const res = spawnSync(opts.bin, ["delete", "--force", id], {
-                    env: opts.env,
-                    timeout: SESSION_DELETE_TIMEOUT_MS,
-                    stdio: "ignore",
-                });
-                if (res.status === 0)
-                    deleted += 1;
-            }
-            catch {
-                // Best effort: an unwritable env or a missing binary must not fail the prune.
-            }
-        }
+        if (opts.bin !== undefined && sessionDeleteSucceeds(opts.bin, ["delete", "--force", id], opts.env))
+            deleted += 1;
         // Fallback: unlink the home's rollout for this session so neither the ledger line nor
         // its file outlives the window. A real `codex delete` removes the rollout itself, so a
         // successful delete has nothing left to unlink; a failed or skipped delete does, and