tumwater 0.2.0 → 0.3.0

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

@@ -0,0 +1,214 @@
+/** The settlement half of a backend agent run (the split of src/agent/run-agent.ts along the
+ * same seam the runner-run → runner-outcome split used): everything that happens after the
+ * run's live feed — the spawn-`error` result, the `exit` orphan sweep, and the `close`-time
+ * flush/reconcile/classify that builds the `PiRunResult`. run-agent.ts keeps the lifecycle
+ * (pre-spawn setup, `prepare`, spawn, decoders, stream pipeline, watchdogs, the feed) and
+ * delegates its `error`/`exit`/`close` listeners here, so the streaming half stays readable.
+ *
+ * Each handler takes the run's live state (`RunSettleState`, defined in run-agent.ts and
+ * imported here only as a type) and reads what it closes over at the moment its event fires —
+ * the live flags it needs are getters on that state. There is no runtime import cycle:
+ * run-agent imports these functions at runtime, and this module imports only run-agent's type.
+ */
+import { backendBinConfigKey, backendBinSourceLabel } from "../pi/pi-bin.js";
+import { terminateChild } from "../process/process.js";
+import { leftoversSweptMessage, sweepRunMarker } from "../process/run-marker.js";
+/** Prefix of PiRunResult.errorMessage when the agent process never started (no session file
+ * is created for such a run). The resolved binary follows it, so a configured agentBin
+ * reads "failed to spawn <bin>" rather than blaming an ambient "pi". */
+const SPAWN_ERROR_PREFIX = "failed to spawn";
+/** The spawn-error message for a resolved binary: the default source keeps today's text
+ * ("failed to spawn pi: …"); a configured source names the binary and where it came from —
+ * the backend's own env var and config key (backendBinConfigKey) — so a wrong
+ * `backends.claude.bin` does not read as pi's legacy `agentBin`. */
+function spawnErrorMessage(resolved, errMessage, backend) {
+    const source = resolved.source === "default"
+        ? ""
+        : ` (resolved from ${backendBinSourceLabel(resolved.source, backend.binEnv, backendBinConfigKey(backend.id))})`;
+    return `${SPAWN_ERROR_PREFIX} ${resolved.bin}${source}: ${errMessage}`;
+}
+/** The failed result of a run that never started: all counters zero, all flags false. */
+export function setupFailureResult(agent, message) {
+    return {
+        ok: false,
+        finalText: "",
+        nothingToDo: false,
+        refused: false,
+        agent,
+        outputTokens: 0,
+        promptTokens: 0,
+        cacheReadTokens: 0,
+        preEditPromptTokens: 0,
+        peakContextTokens: 0,
+        turns: 0,
+        costUsd: 0,
+        errorMessage: message,
+        timedOut: false,
+        timedOutProgressing: false,
+        aborted: false,
+        quietKilled: false,
+        contextExceeded: false,
+        transientServerTimeout: false,
+        transientPiCrash: false,
+        transientRateLimit: false,
+        transientBackend: false,
+        configError: false,
+        finalMessageContentless: false,
+        producedAssistantContent: false,
+        compacted: false,
+    };
+}
+/** Every PiRunResult is built here from what the parser has seen plus how the run ended, so
+ * adding a field to PiRunResult touches this single place. The spawn-error path passes only
+ * an errorMessage override: at that point no output ever arrived, so the parser holds exactly
+ * its initial values — which is precisely what a failed spawn reports. */
+function resultFromParser(state, overrides) {
+    const parser = state.parser;
+    return {
+        ok: false,
+        finalText: parser.finalText,
+        nothingToDo: parser.declaredNothingToDo,
+        refused: parser.refused,
+        refusedReason: parser.refusedReason || undefined,
+        verdictText: parser.verdictText || undefined,
+        agent: state.backend.id,
+        outputTokens: parser.outputTokens,
+        promptTokens: parser.promptTokens,
+        cacheReadTokens: parser.cacheReadTokens,
+        preEditPromptTokens: parser.preEditPromptTokens,
+        firstEditTurn: parser.firstEditTurn,
+        peakContextTokens: parser.peakContextTokens,
+        turns: parser.turns,
+        costUsd: parser.costUsd,
+        stopReason: parser.stopReason,
+        errorMessage: undefined,
+        timedOut: false,
+        timedOutProgressing: false,
+        quietKilled: false,
+        aborted: state.aborted(),
+        contextExceeded: parser.contextExceeded,
+        transientServerTimeout: parser.transientServerTimeout,
+        transientRateLimit: parser.transientRateLimit,
+        transientBackend: parser.transientBackend,
+        backendKind: parser.backendFailureKind,
+        configError: parser.configError,
+        retryAfterSeconds: parser.retryAfterSeconds,
+        transientPiCrash: false,
+        fallbackClone: state.fallbackClone(),
+        finalMessageContentless: parser.finalMessageContentless,
+        producedAssistantContent: parser.producedAssistantContent,
+        compacted: parser.compacted,
+        budgetCapped: parser.budgetCapped,
+        resumeMissing: parser.resumeMissing,
+        billing: parser.billing,
+        rateWindows: parser.rateWindows.length > 0 ? parser.rateWindows : undefined,
+        usedOverage: parser.usedOverage,
+        ...overrides,
+    };
+}
+/** The run's `error` event: the process never spawned. Only the spawn-error cause is set; no
+ * output ever arrived, so the parser still holds its initial values (what a failed spawn
+ * reports), and `finish` settles the run so the `close` event no-ops. */
+export function settleError(state, err) {
+    state.finish(resultFromParser(state, {
+        errorMessage: spawnErrorMessage(state.resolved, err.message, state.backend),
+    }));
+}
+/** The run's `exit` event: sweep whatever the run (or a tool call it started) left running,
+ * however the run ended, a normal exit included, in two passes:
+ *
+ * 1. The group pi led: pi exits before its orphans — a tool call's `(server &)` or
+ *    `cd … && server &` is reparented to PID 1 but stays in pi's group — and the harness
+ *    cannot rely on the model's own cleanup. On 'exit', not 'close': pi has just been reaped,
+ *    so the pgid still names only its group (never reissued while a member lives), and an
+ *    orphan holding pi's stdio open dies now instead of holding 'close' — and the run — open.
+ *    Synchronous, so it adds nothing to the run's resolution; on the kill paths it re-sends a
+ *    SIGTERM the group already had.
+ *
+ * 2. The marker sweep: pi 0.87.1's bash tool starts every command detached, in its own
+ *    process group, so whatever a tool call backgrounds sits in a group whose leader is not
+ *    pi and pass 1 never reaches it. Every process the run started carries the run's
+ *    TUMWATER_RUN mark in its environment, so the same-user scan finds them wherever they
+ *    were reparented. Fire-and-forget: one process-table scan, never awaited — the run
+ *    resolves on pi's output, and the sweep's own SIGKILL escalation (10 s) is unref'd like
+ *    signalTree's.
+ */
+export function settleExit(state) {
+    terminateChild(state.child);
+    void sweepRunMarker(state.runMarker)
+        .then((n) => {
+        const msg = leftoversSweptMessage(state.kind, n, state.wasKilled());
+        if (msg)
+            state.onLeftoversSwept?.(msg);
+    })
+        .catch(() => { });
+}
+/** The run's `close` event: the process died and all its streams closed. Flush what the
+ * decoders held back, reconcile the backend's post-run work, classify the exit cause, and
+ * settle the run's result. */
+export function settleClose(state, code) {
+    const { backend, runSpec, invocation, translator, onLine } = state;
+    // Flush any bytes the decoder held back at stream end and any unterminated final line so the
+    // tail is not lost, then let the translator flush its own pending canonical line(s) — a
+    // batching backend's unclosed last assistant message, which a killed run never closes with a
+    // later event.
+    state.feedCanonical(state.decoder.end(), true);
+    for (const canonical of translator.finalize?.() ?? [])
+        state.parser.feed(canonical + "\n", onLine);
+    // A blind image read on an authoring run deliberately killed it, so its exit is a kill like
+    // the watchdogs' — the half-done work is discarded.
+    const killed = state.wasKilled();
+    // The backend's post-run reconciliation (opencode's authoritative session export), only when
+    // the run is not already settled (a failed spawn settles in the 'error' handler before
+    // 'close') and was not killed — a killed run's session is half-done and no export should
+    // spend its 10 s on it. Its lines are written and parsed like streamed ones, so they reach
+    // the raw log and the parser's authoritative fold (run_cost/run_usage).
+    if (!state.settled() && !killed) {
+        for (const canonical of backend.afterRun?.(runSpec, invocation, translator) ?? []) {
+            state.parser.feed(canonical + "\n", onLine);
+        }
+    }
+    const failed = killed ||
+        state.parser.stopReason === "error" ||
+        (code !== 0 && !state.parser.finalText.trim());
+    // The backend classifies the exit's stderr (pi: the transient JSON-parse crash, a
+    // provider-wide backend failure, a permanent config error). The runner merges that with the
+    // parser's own event-derived flags — one exit has one cause.
+    const stderr = state.stderr();
+    const cls = backend.classifyExit({ code, stderr, killed });
+    const stderrBackend = cls.backendKind;
+    const configError = !killed &&
+        cls.transientPiCrash !== true &&
+        stderrBackend === undefined &&
+        (state.parser.configError || cls.configError === true);
+    // The blind-read failure names both the file and the model (plans/image-input.md
+    // "Failing the run"): take it over any generic exit text so lastError is actionable.
+    const blindRead = state.blindRead();
+    const errorMessage = blindRead !== undefined
+        ? `read ${blindRead}, but ${state.config.model ?? "the model"} cannot read images`
+        : state.aborted()
+            ? "stopped by tumwater shutdown"
+            : state.wd.quietKilled
+                ? `killed as hung: no agent progress for over ${state.config.quietTimeoutSeconds}s`
+                : state.wd.timedOut
+                    ? state.wd.timedOutProgressing
+                        ? `timed out after ${state.wd.timeoutBudgetMs / 1000}s while still making progress — session and worktree edits preserved for resume`
+                        : `timed out after ${state.wd.timeoutBudgetMs / 1000}s`
+                    : (state.parser.errorMessage ?? (failed ? stderr.trim().slice(-500) || `the agent exited ${code}` : undefined));
+    state.finish(resultFromParser(state, {
+        ok: !failed,
+        transientPiCrash: cls.transientPiCrash === true,
+        transientBackend: state.parser.transientBackend || cls.transientBackend === true,
+        backendKind: state.parser.backendFailureKind ?? stderrBackend,
+        configError,
+        // Kept distinct on purpose: a hung tool call leaves its session and worktree edits
+        // intact, so the runner resumes them (quiet_killed) instead of discarding them as an
+        // unfulfilled timeout does. A deadline that fired on a run still making progress gets
+        // the same treatment (BUGS.md 2026-09-29).
+        timedOut: state.wd.timedOut,
+        timedOutProgressing: state.wd.timedOut && state.wd.timedOutProgressing,
+        quietKilled: state.wd.quietKilled,
+        imageBlind: state.parser.imageBlind,
+        errorMessage,
+    }));
+}

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

@@ -11,8 +11,9 @@
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
-import { ensureParentDir, readTextOrNull, statOrNull, terminateTornTail, walkFiles, writeTextAtomic } from "../files/files.js";
+import { daysAgoMs, dirEntryNames, ensureParentDir, readTextOrNull, statOrNull, terminateTornTail, walkFiles, writeTextAtomic } from "../files/files.js";
 import { isJsonObject } from "../files/json-object.js";
+import { findRollout } from "./codex/codex-rollout.js";
 /** The ledger file name every session dir holds. Deliberately a `.jsonl` name so it sits beside
  * the backend's own session files; readers that count session files must exclude it. */
 const SESSION_LEDGER_FILE = "sessions.jsonl";
@@ -21,7 +22,7 @@ export function sessionLedgerPath(dir) {
     return path.join(dir, SESSION_LEDGER_FILE);
 }
 /** Append one run's record to `dir`'s ledger, before its spawn. Best-effort: an unwritable
- * session dir or a full disk must degrade to "no resumable session" on a later tick, never
+ * session dir or a full disk must degrade to "no resumable session" on a later run, never
  * fail the run it was trying to describe. A crash or power loss mid-append leaves the previous
  * record without its newline; terminating that torn tail first keeps the next record on its
  * own line instead of gluing the two into one unparseable line that loses both runs' records
@@ -42,14 +43,8 @@ export function recordSession(dir, record) {
  * unregistered backend. The ledger file shares the dir and is a `.jsonl` too, so it is
  * excluded — it is the harness's record of runs, not a session. */
 export function hasResumableSession(dir) {
-    try {
-        return fs
-            .readdirSync(dir)
-            .some((f) => f.endsWith(".jsonl") && f !== SESSION_LEDGER_FILE);
-    }
-    catch {
-        return false; // Missing directory — nothing to resume.
-    }
+    // A missing directory reads empty — nothing to resume.
+    return dirEntryNames(dir).some((f) => f.endsWith(".jsonl") && f !== SESSION_LEDGER_FILE);
 }
 /** Every valid record in `dir`'s ledger, oldest first. A missing ledger reads as no records;
  * a torn, malformed, or shape-invalid line is skipped rather than poisoning the rest (a crash
@@ -136,9 +131,11 @@ export function sessionResumable(dir, opts, sessionFileExists) {
 /** Drop ledger lines older than `days` from every session dir under `sessionsRoot`. The ledger
  * file's mtime keeps it young while its role runs, so pruneOldFiles never ages it out; trimming
  * its lines is what actually bounds it, under the same window the session files prune by.
- * Returns the number of lines removed; a missing root or unreadable dir reads as nothing to do. */
+ * Returns the number of lines removed; a missing root or unreadable dir reads as nothing to do.
+ * A ledger that cannot be rewritten (a full disk, a read-only dir) is left as it was and not
+ * counted, because this pass runs in the orchestrator's poll loop, where a throw ends the team. */
 export function pruneSessionLedgers(sessionsRoot, days) {
-    const cutoff = Date.now() - days * 24 * 3600 * 1000;
+    const cutoff = daysAgoMs(days);
     let pruned = 0;
     walkFiles(sessionsRoot, (file, entry) => {
         if (!entry.isFile() || entry.name !== SESSION_LEDGER_FILE)
@@ -148,22 +145,29 @@ export function pruneSessionLedgers(sessionsRoot, days) {
             return;
         const lines = text.split("\n").filter((line) => line !== "");
         const kept = [];
+        let dropped = 0;
         for (const line of lines) {
             let at;
             try {
                 at = JSON.parse(line).at;
             }
             catch {
-                pruned += 1; // Malformed line: no timestamp to keep, so it ages out.
+                dropped += 1; // Malformed line: no timestamp to keep, so it ages out.
                 continue;
             }
             if (typeof at === "number" && at >= cutoff)
                 kept.push(line);
             else
-                pruned += 1;
+                dropped += 1;
         }
         if (kept.length !== lines.length) {
-            writeTextAtomic(file, kept.length > 0 ? kept.join("\n") + "\n" : "");
+            try {
+                writeTextAtomic(file, kept.length > 0 ? kept.join("\n") + "\n" : "");
+            }
+            catch {
+                return;
+            }
+            pruned += dropped;
         }
     });
     return pruned;
@@ -180,7 +184,7 @@ const SESSION_DELETE_TIMEOUT_MS = 10_000;
  * reported success, and prunes spill files with the same window. The caller (retention) runs
  * this BEFORE pruneSessionLedgers trims the lines, so the full ledger is still in view. */
 export function pruneOpencodeSessions(sessionsRoot, days, opts) {
-    const cutoff = Date.now() - days * 24 * 3600 * 1000;
+    const cutoff = daysAgoMs(days);
     let deleted = 0;
     if (opts.bin !== undefined) {
         walkFiles(sessionsRoot, (file) => {
@@ -223,3 +227,69 @@ export function pruneOpencodeSessions(sessionsRoot, days, opts) {
     }
     return deleted;
 }
+/** Delete each Codex session the ledger records as expired, with one
+ * `codex delete --force <id>` each (bounded), plus the rollout-file fallback. Codex's sessions
+ * live under `CODEX_HOME` (part 8/9), OUTSIDE `.tumwater/` and outside the session dirs this
+ * pass walks, so trimming the ledger line alone would orphan them; the CLI's `delete --force`
+ * is the one way to reach them headless (design finding 21: without `--force` Codex refuses to
+ * delete without a terminal). Best-effort and backend-specific, kept out of the generic
+ * `pruneSessionLedgers` line pass: it returns the deletes that reported success. Whether or not
+ * a delete succeeded the session's own rollout file is removed as the fallback (the OpenCode
+ * spill-file fallback's twin), so the ledger line and rollout do not outlive the window. The
+ * caller (retention) runs this BEFORE pruneSessionLedgers trims the lines, so the full ledger
+ * is still in view. */
+export function pruneCodexSessions(sessionsRoot, days, opts) {
+    const cutoff = daysAgoMs(days);
+    let deleted = 0;
+    // Codex reuses a resumed session's UUID, so one id can carry several ledger records — each
+    // resume appends a fresh line with the same id (design §4 resumes by id). Only an id whose
+    // EVERY record is expired is a session safe to trim: an older expired record beside a
+    // still-fresh resume must not `delete` the live session or unlink its rollout, so the live
+    // ids are gathered first and every candidate id is checked against them.
+    const live = new Set();
+    const expired = new Set();
+    walkFiles(sessionsRoot, (file) => {
+        if (!file.endsWith(SESSION_LEDGER_FILE))
+            return;
+        for (const record of readSessions(path.dirname(file))) {
+            if (record.agent !== "codex")
+                continue;
+            (record.at >= cutoff ? live : expired).add(record.id);
+        }
+    });
+    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.
+            }
+        }
+        // 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
+        // this is what trims it.
+        const home = opts.env?.CODEX_HOME;
+        if (home !== undefined) {
+            const rollout = findRollout(home, id);
+            if (rollout !== null) {
+                try {
+                    fs.unlinkSync(rollout);
+                }
+                catch {
+                    // Best effort: a vanished or unwritable rollout is not a failure.
+                }
+            }
+        }
+    }
+    return deleted;
+}

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

@@ -0,0 +1,220 @@
+/** The per-backend subscription account state: which billing pays for a backend's 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/<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.
+ *
+ * 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
+ * milliseconds (the run parser reports unix seconds; observeAccount converts once here), so
+ * consumers compare it to `Date.now()` directly. The claude account (src/agent/claude/
+ * claude-account.ts) is this module specialized to the "claude" backend: for its file the
+ * logical `plan` field is stored under the historical key `subscriptionType`, so claude's file
+ * keeps today's shape. */
+import { readJsonFile, writeJsonAtomic } from "../files/json-files.js";
+import { finiteNumber, isJsonObject, setOwn } from "../files/json-object.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
+ * §8). Such a run is a transient of the world, not a failure of the session: its session and
+ * worktree edits are kept and resumed after `resetsAt` (part 6e) rather than committed as
+ * partial work or reset. API-billed runs and overage are budget/fallback matters, not a
+ * window hold, so they read false; a backend that reports no window also reads false (a pi
+ * 429, for example). */
+export function subscriptionWindowRejected(run) {
+    return (run.transientRateLimit &&
+        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` (config `backends.<id>.windowReserve`), 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. */
+export function windowLabel(type) {
+    const m = /^(\w+)_(hour|day|week)$/.exec(type);
+    if (!m)
+        return type.replace(/_/g, " ");
+    const words = { one: "1", two: "2", three: "3", four: "4", five: "5", six: "6", seven: "7", eight: "8", nine: "9", ten: "10" };
+    const unit = m[2] === "hour" ? "h" : m[2] === "day" ? "d" : "w";
+    const word = m[1] ?? "";
+    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). */
+export function utilizationPct(utilization) {
+    return Math.round(utilization * 100);
+}
+/** Order two window entries by the windowEntries rule: status severity, then the reported
+ * utilization (a missing reading sorts below any number), then the earlier reset, then the
+ * type name. Exported so a list of per-backend blocks can be ordered by their primary entry
+ * the same way windowEntries orders one account's windows (part 3a/9). */
+export function compareWindowEntries(a, b) {
+    const rank = (WINDOW_RANK[b.status] ?? 1) - (WINDOW_RANK[a.status] ?? 1);
+    if (rank !== 0)
+        return rank;
+    const util = (b.utilization ?? -1) - (a.utilization ?? -1);
+    if (util !== 0)
+        return util;
+    const reset = (a.resetsAt ?? Number.POSITIVE_INFINITY) - (b.resetsAt ?? Number.POSITIVE_INFINITY);
+    if (reset !== 0)
+        return reset;
+    return a.type.localeCompare(b.type);
+}
+/** The account's windows as a list, most constrained first (by compareWindowEntries). Empty
+ * when the account reported none. */
+export function windowEntries(account) {
+    return Object.entries(account.windows)
+        .map(([type, w]) => ({ type, ...w }))
+        .sort((a, b) => compareWindowEntries(a, b));
+}
+/** 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));
+    if (doc === null)
+        return null;
+    const billing = doc.billing === "subscription" || doc.billing === "api" ? (doc.billing) : undefined;
+    const observedAt = finiteNumber(doc.observedAt, Number.NaN);
+    if (billing === undefined || !Number.isFinite(observedAt))
+        return null;
+    const windows = {};
+    if (isJsonObject(doc.windows)) {
+        for (const [type, value] of Object.entries(doc.windows)) {
+            const window = readWindow(value, observedAt, now);
+            if (window !== undefined)
+                setWindow(windows, type, window);
+        }
+    }
+    return {
+        billing,
+        ...(typeof doc.subscriptionType === "string" ? { plan: doc.subscriptionType } : {}),
+        observedAt,
+        windows,
+    };
+}
+/** One window entry from the file, healed: a non-object or a status-less entry is dropped, a
+ * missing per-window `observedAt` falls back to the file's, and a past `resetsAt` flips the
+ * status to `reset` and drops the overage flags. */
+function readWindow(value, fileObservedAt, now) {
+    if (!isJsonObject(value) || typeof value.status !== "string")
+        return undefined;
+    const observedAt = finiteNumber(value.observedAt, fileObservedAt);
+    const resetsAt = finiteNumber(value.resetsAt, Number.NaN);
+    const resets = Number.isFinite(resetsAt);
+    // utilization heals like the two stamps above: JSON's `1e999` parses to Infinity, and a
+    // non-finite fraction would render as `Infinity%` in the badges and poison the
+    // windowEntries comparator (Infinity - Infinity is NaN).
+    const utilization = finiteNumber(value.utilization, undefined);
+    const reset = resets && resetsAt <= now;
+    const window = {
+        status: reset ? "reset" : value.status,
+        ...(resets ? { resetsAt } : {}),
+        ...(utilization !== undefined ? { utilization } : {}),
+        // a reset window is no longer in overage: dropping both keeps every reader in agreement
+        ...(!reset && typeof value.overageStatus === "string" ? { overageStatus: value.overageStatus } : {}),
+        ...(!reset && value.isUsingOverage === true ? { isUsingOverage: true } : {}),
+        observedAt,
+    };
+    return window;
+}
+/** Store one window under its `rateLimitType`. A plain `windows[type] = window` loses a type
+ * of `__proto__`: the assignment hits Object.prototype's setter and rewrites the map's
+ * prototype instead of adding an own entry, so the window vanishes from every
+ * Object.entries/values reader. Defining the own property keeps even that key — the same
+ * inherited-key guard claude-stream's TOOL_NAMES lookup uses. */
+function setWindow(windows, type, window) {
+    setOwn(windows, type, window);
+}
+/** Overwrite a backend's account file with `account`, creating the state directory. The
+ * orchestrator's one writer; a failure to write is the caller's to handle (best-effort at the
+ * run boundary). Written through writeJsonAtomic (tmp + rename): a crash or ENOSPC mid-write
+ * leaves the previous file whole, not a torn one the reader heals to "no subscription" — which
+ * would silently drop the billing answer and the window hold until the next run re-observed
+ * them. The claude file's `plan` is serialized under its historical `subscriptionType` key. */
+export function writeAccount(root, backend, account) {
+    writeJsonAtomic(accountPath(root, backend), {
+        billing: account.billing,
+        ...(account.plan !== undefined ? { subscriptionType: account.plan } : {}),
+        observedAt: account.observedAt,
+        windows: account.windows,
+    }, true);
+}
+/** Fold one run's billing and rate-window readings into a backend's account file: the run's
+ * `billing` overwrites the stored answer, and each reported window replaces the stored reading
+ * for its `type`, stamped with `observedAt`. A run that reported neither billing nor windows
+ * leaves the file untouched (and returns whatever was already there). */
+export function observeAccount(root, backend, run, now = Date.now()) {
+    const existing = readAccount(root, backend, now);
+    const billing = run.billing ?? existing?.billing;
+    const reported = run.rateWindows ?? [];
+    if (billing === undefined || (run.billing === undefined && reported.length === 0))
+        return existing;
+    const windows = { ...(existing?.windows ?? {}) };
+    for (const w of reported)
+        setWindow(windows, w.type, windowFromRun(w, now));
+    const account = {
+        billing,
+        ...(existing?.plan !== undefined ? { plan: existing.plan } : {}),
+        observedAt: now,
+        windows,
+    };
+    writeAccount(root, backend, account);
+    return account;
+}
+/** One run's rate-window reading in the file's shape: unix-seconds `resetsAt` becomes epoch ms,
+ * and absent optional fields stay absent. */
+function windowFromRun(w, now) {
+    // The write choke point heals utilization like readWindow does, so a non-finite value
+    // handed straight to observeAccount can never re-enter the file through a save.
+    const utilization = finiteNumber(w.utilization, undefined);
+    return {
+        status: w.status,
+        ...(typeof w.resetsAt === "number" ? { resetsAt: w.resetsAt * 1000 } : {}),
+        ...(utilization !== undefined ? { utilization } : {}),
+        ...(typeof w.overageStatus === "string" ? { overageStatus: w.overageStatus } : {}),
+        ...(w.isUsingOverage === true ? { isUsingOverage: true } : {}),
+        observedAt: now,
+    };
+}