tumwater 0.4.3 → 0.4.5

package/README.md

@@ -42,7 +42,7 @@ and is also outside `npm test`.
 ## Status
 
 <!-- tumwater:status:start -->
-**v0.4.3**: working tumwater. The director and 15 of the 17 roles are enabled by default; `selfcheck`,
+**v0.4.5**: 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": "45348f61e3e060de873bbd10ce8cdea30e4102d6",
-  "builtAt": 1793264084617,
+  "sha": "6440aaa1705f2accb491fa2155a5da6aadee05d8",
+  "builtAt": 1793604373395,
   "root": "/home/runner/work/tumwater/tumwater"
 }

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

@@ -107,6 +107,7 @@ export function runAgent(opts) {
             const wd = startPiWatchdogs({
                 progressCount: () => parser.progressCount,
                 openToolCalls: () => parser.openToolCalls,
+                pendingReply: () => parser.pendingReply,
                 runTimeoutMs: opts.config.runTimeoutSeconds * 1000,
                 quietMs: opts.config.quietTimeoutSeconds * 1000,
                 stallMs: Math.max(0, opts.config.toolCallStallSeconds) * 1000,
@@ -120,7 +121,8 @@ export function runAgent(opts) {
                 // deadline stays right for them.
                 extendOnProgress: opts.kind === "gate",
                 kill: () => terminateChild(child),
-                onToolCallStalled: opts.onToolCallStalled,
+                onStallWarning: opts.onStallWarning,
+                onUnansweredReply: opts.onUnansweredReply,
             });
             let aborted = false;
             // A blind image read on an authoring run deliberately kills it, like the watchdogs do.

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

@@ -2,8 +2,8 @@
  * subscription-account.ts) — which billing pays for claude runs, and the newest subscription
  * usage-window reading each run reported (plans/agent-backends.md §7 "Billing" and §8 "The
  * subscription usage window"). Persisted at `.tumwater/state/claude-account.json`, written only
- * by the orchestrator process, so the sibling parts that throttle or display the subscription
- * window (6b/7–6e/7) read one answer instead of re-deriving it per surface.
+ * by the orchestrator process, so the sibling parts read one answer instead of re-deriving it
+ * per surface.
  *
  * Everything here is a thin wrapper over the generic per-backend store (found
  * grounds/codex-backend.md "Groundwork: the subscription account is per backend", item 1),
@@ -17,7 +17,7 @@ import { spawnSync } from "node:child_process";
 import os from "node:os";
 import { resolvedBackendConfig } from "../../config/config-views.js";
 import { parseJsonObject } from "../../files/json-object.js";
-import { observeAccount, readAccount, subscriptionWindowRejected, windowEntries, windowLabel, windowReserved, windowUsedUp, writeAccount, } from "../subscription-account.js";
+import { observeAccount, readAccount, subscriptionWindowRejected, writeAccount, } from "../subscription-account.js";
 import { claudeBackend, claudeConfigDir } from "./claude-backend.js";
 import { claudeEnv, claudeThirdPartyProvider } from "./claude-env.js";
 /** Read the persisted claude account state, or null when it is absent or unreadable. A file
@@ -43,23 +43,9 @@ export function writeClaudeAccount(root, account) {
 export function observeClaudeAccount(root, run, now = Date.now()) {
     return observeAccount(root, "claude", run, now);
 }
-/** The subscription account's used-up usage window, or null — see subscription-account.ts's
- * windowUsedUp for the rule. */
-export function claudeWindowUsedUp(account, now, includeOverage = true, reserve) {
-    return windowUsedUp(account, now, includeOverage, reserve);
-}
-/** Re-export of the per-backend helpers under their historical claude names for callers that
- * predate the per-backend store (budget gates, team holds, the doctor, the role view, the
- * status poll). */
-export { subscriptionWindowRejected, windowReserved };
-/** The window type as a compact label — subscription-account.ts's windowLabel, under its
- * historical claude name. */
-export function claudeWindowLabel(type) {
-    return windowLabel(type);
-}
-export function claudeWindowEntries(account) {
-    return windowEntries(account);
-}
+/** Re-export of the per-backend rejection signal under its historical claude name for callers
+ * that predate the per-backend store (the runner's run-verdict and hold wiring). */
+export { subscriptionWindowRejected };
 /** Seed the claude account file before the first run (plans/agent-backends.md §7):
  * `ANTHROPIC_API_KEY` set means claude prefers the key, so billing is API; otherwise
  * `claude auth status` decides — a claude.ai OAuth login is a subscription, any other login is

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

@@ -84,12 +84,11 @@ export function parseCodexLoginStatus(stdout) {
         return "api";
     return null;
 }
-/** The refusal message when a codex seam is API-key logged in (decision 5): Codex reports no
- * cost, so per-token billing would spend money the budget cap cannot see. The one home of the
- * remedy text the startup gate, the live config editor, and the doctor all print, so the remedy
- * command and its wording cannot drift between them. `home` is the codex home named in the
- * remedy: the literal `<home>` placeholder where the call site does not resolve the home, else
- * the resolved `CODEX_HOME` path. */
+/** 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\``;
 }

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-rollout.js

@@ -163,7 +163,7 @@ function rateLimitLines(lastRateLimits) {
 /** 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 && requestedModel !== undefined && model !== requestedModel ? model : undefined;
+    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. */

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

@@ -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)
@@ -160,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/write-guard-plugin/index.js

@@ -4,20 +4,23 @@
  *
  * OpenCode 2.x has no hook that blocks a tool from running. It has a permission `evaluate` hook
  * that may turn a decision to `deny` with a `message`, which reaches the model as the tool's error
- * while the run goes on. Every file-writing tool asks for the `edit` action with the absolute
- * paths it writes as `resources`, and the hook runs under `--auto` too, since `--auto` only
- * answers what would otherwise be asked. Checked live on opencode 2.1.0 on 2026-10-23. A
- * configured plugin path must be a directory, which is why this is `index.js` in a directory of
- * its own.
+ * while the run goes on. The file-writing tools ask for the `edit` action (edit in place) and the
+ * `write` action (create or overwrite a file — a new path a `../` climb can point outside the
+ * checkout) with the absolute paths they write as `resources`, and the hook runs under `--auto`
+ * too, since `--auto` only answers what would otherwise be asked. Checked live on opencode 2.1.0
+ * on 2026-10-23. A configured plugin path must be a directory, which is why this is `index.js` in
+ * a directory of its own.
  *
  * The plugin's context names the run's directory (`location.directory`, the worktree OpenCode
  * runs in), which is the run directory the rule reads its checkout from. A failure of its own
  * leaves the decision alone, so a broken guard cannot stop every edit of a run. */
 import { strayWriteRefusal } from "../../write-guard.js";
-/** Deny an `edit` decision whose resources include a stray path from a run in `runDir`, naming
- * the first such path's refusal. Every other decision is left as it is. Exported for tests. */
+/** Deny an `edit` or `write` decision whose resources include a stray path from a run in
+ * `runDir`, naming the first such path's refusal. Every other decision is left as it is. Exported
+ * for tests. */
+const FILE_WRITE_ACTIONS = new Set(["edit", "write"]);
 export function guardEvaluate(event, runDir) {
-    if (event.action !== "edit" || !Array.isArray(event.resources))
+    if (!FILE_WRITE_ACTIONS.has(event.action) || !Array.isArray(event.resources))
         return;
     for (const resource of event.resources) {
         if (typeof resource !== "string" || resource === "")

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

@@ -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

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

@@ -3,8 +3,8 @@
  * "Billing" and §8 "The subscription usage window"). Persisted at
  * `.tumwater/state/<backend>-account.json` (plan design grounds/codex-backend.md "Groundwork:
  * the subscription account is per backend", item 1), written only by the orchestrator process,
- * so the sibling parts that throttle or display the subscription window read one answer instead
- * of re-deriving it per surface.
+ * so the free-ness rule and the window displays read one answer instead of re-deriving it per
+ * surface.
  *
  * The file is a cache, never a source of truth: a run that reports billing overwrites it, and a
  * missing or unreadable file reads as "no subscription". `resetsAt` is stored as epoch
@@ -15,6 +15,7 @@
  * keeps today's shape. */
 import { readJsonFile, writeJsonAtomic } from "../files/json-files.js";
 import { finiteNumber, isJsonObject, setOwn } from "../files/json-object.js";
+import { cachedByStat } from "../files/stat-cache.js";
 import { accountPath } from "../paths.js";
 /** True when a failed run ended on a subscription usage window the account reported as
  * `rejected` without overage — the signal the team hold throttles on (plans/agent-backends.md
@@ -28,45 +29,12 @@ export function subscriptionWindowRejected(run) {
         run.billing === "subscription" &&
         (run.rateWindows ?? []).some((w) => w.status === "rejected" && w.isUsingOverage !== true));
 }
-/** The subscription account's used-up usage window, or null: a window reading `rejected` with
- * no overage, or (with `includeOverage`, the default) a window whose current reading shows
- * `isUsingOverage`, and a `resetsAt` still ahead of `now`; among several, the one that resets
- * last. With a `reserve` (the subscription-window reserve), a window whose utilization has
- * reached its type's fraction counts too and comes back with `reserve: true`; a rejected or
- * overage window outranks a reserve one, so the flag is set only when no window is used up
- * for real. The budget gate's window move (pollBudgetGate) reads the default; the team hold
- * (windowObservation) passes `includeOverage: false`, because overage never holds a
- * seam. Only subscription billing produces one; a missing account reads null. */
-export function windowUsedUp(account, now, includeOverage = true, reserve) {
-    if (account?.billing !== "subscription")
-        return null;
-    let furthest = null;
-    let reserved = null;
-    for (const [type, w] of Object.entries(account.windows)) {
-        if (typeof w.resetsAt !== "number" || w.resetsAt <= now)
-            continue;
-        const used = w.isUsingOverage === true ? includeOverage : w.status === "rejected";
-        if (used) {
-            if (furthest === null || w.resetsAt > furthest.resetsAt)
-                furthest = { type, resetsAt: w.resetsAt };
-            continue;
-        }
-        if (windowReserved(w, reserve?.[type]) && (reserved === null || w.resetsAt > reserved.resetsAt))
-            reserved = { type, resetsAt: w.resetsAt, reserve: true };
-    }
-    return furthest ?? reserved;
-}
-/** Has this window's utilization reached its reserve fraction? False without a fraction or a
- * reading. */
-export function windowReserved(w, fraction) {
-    return fraction !== undefined && typeof w.utilization === "number" && w.utilization >= fraction;
-}
 /** Status severity for ordering: a rejected window limits, an allowed_warning nears its limit,
  * every other reading (allowed/ok) rides at the bottom, and a reset one no longer limits. */
 const WINDOW_RANK = { rejected: 3, allowed_warning: 2, reset: 0 };
 /** The window type as a compact label: `five_hour` → `5h`, `seven_day` → `7d`; an unknown
  * type falls back to its words with underscores as spaces. The one home of the window spelling
- * the status badge and the role view share. */
+ * the status badge and the role view share (the browser dashboard keeps its inline copy). */
 export function windowLabel(type) {
     const m = /^(\w+)_(hour|day|week)$/.exec(type);
     if (!m)
@@ -77,10 +45,8 @@ export function windowLabel(type) {
     return `${words[word] ?? word}${unit}`;
 }
 /** The fraction of a subscription usage window consumed (0–1) as a whole-number percent: a
- * `0.64` utilization reads `64`. The one home of the fraction→percent conversion, shared by
- * the status badge, the doctor's hold reason and the event formatter so they render a window's
- * fill identically (the browser dashboard's own window line is embedded client-side and keeps
- * its inline copy). */
+ * `0.64` utilization reads `64`. The one node-side home of the fraction→percent conversion
+ * (the browser dashboard's own window line is embedded client-side and keeps its inline copy). */
 export function utilizationPct(utilization) {
     return Math.round(utilization * 100);
 }
@@ -107,12 +73,30 @@ export function windowEntries(account) {
         .map(([type, w]) => ({ type, ...w }))
         .sort((a, b) => compareWindowEntries(a, b));
 }
+/** The parsed raw body of one backend's account file, keyed by that file's own stat — the same
+ * stat-keyed contract cachedByStat gives every observer that polls a slowly-changing file. The
+ * account file is written only by the orchestrator on a run's billing/window report, so it
+ * changes no faster than runs; on the status snapshot path readAccount ran per backend per poll
+ * as one more readJsonFile (read + parse) alongside the already stat-cached marker reads, and
+ * budget-gates/role-view read it on other polling surfaces. Writes go through writeJsonAtomic's
+ * tmp+rename (writeAccount), which bumps dev/ino/mtime/size, so a refresh invalidates like any
+ * edit. The `now`-dependent heal is NOT cached: only the raw body is, and readAccount reapplies
+ * its window/observedAt rules against each call's own `now` on a per-call copy, so a window
+ * whose `resetsAt` lapses still reads back as reset on the very call it does. Bounded inside
+ * cachedByStat. */
+const accountBodyCache = new Map();
+/** Serve `file`'s parsed raw JSON-object body from accountBodyCache: null when the file is
+ * missing, unreadable, torn, or not a plain object — the same no-data policy as readJsonFile —
+ * and a fresh per-call copy so readAccount's owns the object it reads fields off. Never throws. */
+function readAccountBody(file) {
+    return cachedByStat(accountBodyCache, file, file, () => readJsonFile(file), (body) => ({ ...body }));
+}
 /** Read the persisted account state for a backend, or null when it is absent or unreadable. A
  * file without a usable top-level `observedAt` reads as absent (the plan's torn-file rule),
  * and a window whose `resetsAt` is at or before `now` reads back with `status: "reset"` — the
  * reader, not every consumer, decides that the window no longer limits. */
 export function readAccount(root, backend, now = Date.now()) {
-    const doc = readJsonFile(accountPath(root, backend));
+    const doc = readAccountBody(accountPath(root, backend));
     if (doc === null)
         return null;
     const billing = doc.billing === "subscription" || doc.billing === "api" ? (doc.billing) : undefined;

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

@@ -27,25 +27,62 @@ function isWithin(p, dir) {
     const rel = path.relative(dir, p);
     return rel === "" || (rel !== ".." && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel));
 }
-/** `p` with its longest existing prefix resolved through realpath, so a symlink, a `/tmp` that is
- * `/private/tmp`, or a path typed in the wrong case on a case-insensitive disk compares as the
- * file it reaches. The part that does not exist yet (a file a write would create) is appended
- * unchanged. */
+/** `p` with its symlinks resolved as the file it reaches: each component is peeled and a
+ * symlink is followed to its target, so a symlinked checkout or a `/tmp` that is `/private/tmp`
+ * compares as the path it reaches. The not-yet-existing tail (a file a write would create) is
+ * appended unchanged. A broken symlink — target absent, the write/create case, where
+ * `realpathSync` throws ENOENT and the old longest-existing-prefix walk read the link as its
+ * own location inside the checkout — is followed to its target instead: the write would follow
+ * it, so the guard must see where it points. */
 function realish(p) {
-    let existing = p;
-    const rest = [];
-    for (;;) {
+    // Peel the path component by component, exactly as `realpath` does: a regular component is
+    // kept, a symlink is replaced by the components its target resolves to, and the first absent
+    // component ends the walk, so a not-yet-existing tail is appended unchanged. Replacing the
+    // link with its target — instead of keeping the link's own path — is what catches a broken
+    // symlink: its target is absent (the write/create case, where `realpathSync` throws ENOENT
+    // and the old longest-existing-prefix walk read the link as its location inside the
+    // checkout), yet the write would still follow it, so the guard must see where it points. A
+    // depth bound stops a symlink cycle (a → b → a) from looping instead of escaping through the
+    // tail.
+    let q = path.resolve(p).split(path.sep).filter(Boolean);
+    const out = [];
+    let depth = 0;
+    while (q.length > 0) {
+        const part = q[0]; // the loop's length check guarantees a first component
+        const here = path.join(path.sep, ...out, part);
+        let st;
         try {
-            return path.join(fs.realpathSync.native(existing), ...rest);
+            st = fs.lstatSync(here);
         }
         catch {
-            const parent = path.dirname(existing);
-            if (parent === existing)
-                return p;
-            rest.unshift(path.basename(existing));
-            existing = parent;
+            out.push(part, ...q.slice(1)); // absent: this and the rest are the not-yet-existing tail
+            break;
+        }
+        if (!st.isSymbolicLink()) {
+            out.push(part);
+            q = q.slice(1);
+        }
+        else if (depth++ > 100) {
+            out.push(part, ...q.slice(1)); // cycle: give up rather than loop
+            break;
+        }
+        else {
+            let raw;
+            try {
+                raw = fs.readlinkSync(here); // a relative target is relative to the link's dir
+            }
+            catch {
+                out.push(part, ...q.slice(1)); // unreadable: treat as the not-yet-existing tail
+                break;
+            }
+            // The target, absolute-resolved, becomes the whole remaining path to peel: the link's
+            // own directory is dropped and replaced by wherever the link points.
+            const target = path.isAbsolute(raw) ? raw : path.resolve(path.join(path.sep, ...out), raw);
+            q = [...target.split(path.sep).filter(Boolean), ...q.slice(1)];
+            out.length = 0;
         }
     }
+    return path.join(path.sep, ...out);
 }
 /** A tool's path argument as pi's tools resolve it (pi `resolveToCwd`): a leading `@` dropped,
  * `~` expanded to the home directory, and a relative path taken from `base`. */

package/dist/src/backlog/backlog-archive.js

@@ -319,10 +319,9 @@ function archiveCommitWhat(plan) {
 }
 /** One live backlog file's finished-history rows as liveFinishedHistory reports them, phrased
  * and joined: `file ## <section> holds N finished entries (X KB)` rows separated by "; " — the
- * shared detail head the doctor's `backlog archive` check (checkLiveFinished) and the always-on
- * `backlog-archive` alert (src/ui/team-alert-backlog.ts) both render, so the row shape, the
- * plural, and the KB rounding cannot drift between the two. Each caller appends its own trailing
- * explanation, so the two texts stay byte-identical up to that suffix. */
+ * detail head the doctor's `backlog archive` check (checkLiveFinished) renders, so the row
+ * shape, the plural, and the KB rounding stay stable. Each caller appends its own trailing
+ * explanation. */
 export function liveFinishedRowList(rows) {
     return rows.map((l) => `${l.file} ## ${l.section} holds ${plural(l.entries, "finished entry", "finished entries")} (${Math.round(l.bytes / 1024)} KB)`).join("; ");
 }