tumwater 0.1.3 → 0.3.0

package/README.md

@@ -1,14 +1,23 @@
 # tumwater
 
-tumwater is an opinionated autonomous development harness built on
-[pi](https://github.com/badlogic/pi-mono). You write a short project brief, and a fleet of
-role-driven loops (feature, bugfix, planning, tests, cleanup, docs, and more) builds the project
+> ### ⚠️ Warning: tumwater eats tokens
+>
+> tumwater runs models continuously, all day, on every role. A busy team can burn through
+> **on the order of a billion tokens a day or more**. On pay-per-token API keys that is real,
+> unbounded money; on subscription backends it burns through your plan's usage windows just as
+> fast. Set `maxDailyCostUsd` before you start, and watch actual spend with `tumwater report`
+> and `tumwater status`.
+
+tumwater is an opinionated autonomous development team, built on
+[pi](https://github.com/badlogic/pi-mono). You write a short project brief, and a team of
+roles (feature, bugfix, planning, tests, cleanup, docs, and more) builds the project
 one small, reviewed commit at a time. It came from wanting to write only the brief and let a team
-of always-on specialists do the rest: each loop owns one concern, lands one change per tick,
+of always-on specialists do the rest: each role owns one concern, merges one change per run,
 sleeps when it has nothing to do, and wakes when main moves. All project state lives in the
-local git repo, and no remote is ever touched.
+local git repo, and no remote is ever touched. The words used here (team, role, run, merge) are
+defined in [docs/glossary.md](docs/glossary.md).
 
-![The tumwater web dashboard running tumwater's own fleet: a sidebar with the project, its fleet status, the Fleet, History, Usage, Failures, and Settings views, today's spend against the cap, and the pause control; an alert that the running build is behind main; the director prompt box; today's progress (loops in flight, commits landed, ticks, open backlog); and the loops grouped by what they are doing, each with its status, current work or last result, spend, and controls](docs/gui.png)
+![The tumwater web dashboard running tumwater's own team: a sidebar with the project, its team status, and the Team, History, Usage, Failures, and Settings views, with today's spend against the cap and the pause control; the director prompt box; and today's progress (roles running, commits merged, runs, open backlog) above the roles grouped by what they are doing, each with its status, current work or last result, spend, and controls](docs/gui.png)
 
 ## Install
 
@@ -23,13 +32,19 @@ instead: `npm install && npm run build && npm link`.
 
 With `claude` installed and logged in, `npm run smoke:claude` is an opt-in live check of the
 claude backend: it drives the real CLI through a throwaway repo (a few cents of API-equivalent
-spend on a subscription) and is not part of `npm test`, which stays green without claude.
+spend on a subscription) and is not part of `npm test`, which stays green without claude. `npm run
+smoke:opencode` is the same live check for the opencode backend, driving the real `opencode` CLI
+against its free DeepSeek tier; it needs an OpenCode V2 install (`brew install opencode`) and is
+also outside `npm test`. `npm run smoke:codex` is the same live check for the codex backend,
+driving the real `codex` CLI against a logged-in ChatGPT subscription; it needs a Codex install
+and is also outside `npm test`.
 
 ## Status
 
 <!-- tumwater:status:start -->
-**v0.1.3**: working harness. The director and 14 of the 15 roles are enabled by default; `telemetry`,
-which files harness bugs from tumwater's own event log, is opt-in (`roles.telemetry.enabled`).
+**v0.3.0**: working tumwater. The director and 14 of the 16 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`).
 
 Open work: [PLANS.md](PLANS.md) (planned), [BUGS.md](BUGS.md) (open bugs),
 [QUESTIONS.md](QUESTIONS.md) (open questions).
@@ -41,40 +56,74 @@ Open work: [PLANS.md](PLANS.md) (planned), [BUGS.md](BUGS.md) (open bugs),
 cd your-project                 # a new or existing directory
 tumwater init "Build a tiny markdown-to-html converter CLI in Python."
                                 # --template, --file, and --adopt pick a starting point (see docs/cli.md)
-tumwater run                    # start the loops (Ctrl+C to stop)
-tumwater run --gui              # ... and serve the browser dashboard at http://127.0.0.1:7180
-tumwater run --for 2h           # run for a bounded window, then drain, summarize, and exit
-tumwater run --once             # one round of ticks for cron/CI; exits 3 if a loop's tick failed
+tumwater start                  # start the team (Ctrl+C to stop)
+tumwater start --gui            # ... and serve the browser dashboard at http://127.0.0.1:7180
+tumwater start --tui            # ... and attach the terminal TUI in the same window
+tumwater start --for 2h         # run for a bounded window, then finish current work, summarize, and exit
+tumwater start --once           # one round of runs for cron/CI; exits 3 if a run failed
 ```
 
 A fresh or empty project is seeded with `"bootstrap": {"untilPlansDone": 5}`, which holds the
-maintenance loops until 5 plans are done; remove it from `tumwater.json` to end that early.
+maintenance roles until 5 plans are done; remove it from `tumwater.json` to end that early.
 
-From another terminal, `tumwater tui` or the browser dashboard watches the fleet, `tumwater status`
-and `tumwater logs -f` check it, `tumwater brief --file <path>` replaces the initial prompt,
-`tumwater prompt "<text>"` queues a request for the director, `tumwater plan` and `tumwater bug`
-file backlog entries, and `tumwater pause`, `resume`, `wake`, and `stop` control the loops.
-`tumwater doctor` audits the fleet and `tumwater report` shows usage and cost. `gui
+From another terminal, `tumwater tui` or the browser dashboard watches the team, `tumwater status`
+and `tumwater logs -f` check it, `tumwater brief --file <path>` replaces the brief,
+`tumwater prompt "<text>"` sends a message to the director's inbox, `tumwater plan` and
+`tumwater bug` file backlog entries, `tumwater revert <sha>` undoes one merged change on main,
+and `tumwater pause`, `resume`, `wake`, and `stop` control the roles. `tumwater doctor` audits the team and `tumwater report` shows usage and cost. `gui
 --all-interfaces` exposes the dashboard, and with it the director prompt, to your whole network,
 so pair it with `--token <secret>`.
 
+`tumwater prompt --attach <image>` gives a role an image to read at its next run. When a role's
+model cannot read images, the command refuses the attachment up front (naming the fix) unless
+the role reroutes a blind read to a vision model, in which case it says where the message will
+run; `tumwater doctor` probes each claimed image-input model once (cached 7 days, `--reprobe` to
+force) and the dashboards and `tumwater role <id>` say which roles read images and where a blind
+run reroutes.
+
 Every command, flag, and TUI key is in [docs/cli.md](docs/cli.md); `tumwater help` prints the
-same list, and `tumwater completion bash|zsh` prints shell completion. Settings live in
-`tumwater.json` and edits apply live while the fleet runs; see [docs/config.md](docs/config.md).
+same list, and `tumwater completion bash|zsh|fish` prints shell completion. Settings live in
+`tumwater.json` and edits apply live while the team runs; see [docs/config.md](docs/config.md).
 
 **Backends:** any OpenAI-compatible model pi can reach works, chosen by `model` in `tumwater.json`
-with a `fallback` that a failing role switches to. `agent: "claude"` runs bare selectors on Claude
-Code instead. Requirements, the fallback and usage-window behavior, and how subscription runs are
-billed (as notional spend, outside the daily cap) are in [docs/backends.md](docs/backends.md).
+with a `fallback` that a failing role switches to. `backend` beside `model` picks who runs it:
+`"backend": "claude"` runs a model id on Claude Code, `"backend": "opencode"` on the OpenCode CLI — its free
+DeepSeek tier needs no login or API key — and `"backend": "codex"` on the Codex CLI's ChatGPT subscription
+(no API key; its two usage windows behave like a claude subscription's). Requirements, the fallback, free-ness, and usage-window
+behavior, and how subscription runs are billed (as estimated spend, outside the daily cap) are in
+[docs/backends.md](docs/backends.md).
+
+**Mixing providers:** `model` says which model, `backend` says which program runs it (`pi`, the
+default, `claude`, `opencode` or `codex`). A tier entry, a role, a review and a fallback step each take an
+object with both, so one config can mix a Claude strong tier with pi providers:
+
+```json
+{
+  "model": {
+    "default": "huggingface/deepseek-ai/DeepSeek-V4.1-Flash:deepinfra",
+    "strong": { "backend": "claude", "model": "claude-opus-5-5" }
+  },
+  "fallback": "omlx/Qwen3.8-27B-MLX-oQ4e-mtp"
+}
+```
+
+The default tier runs on pi through Hugging Face, the strong model jobs (the director, the plan
+role, the reviewer, and the conflict resolver) run on the claude CLI's included usage, and the fallback runs on pi through
+oMLX — all concurrently, under each provider's cap (set it with `maxConcurrentPerProvider`;
+`tumwater status` shows how many runs each key has going out of its cap). An OpenCode tier is
+`{ "backend": "opencode", "model": "deepseek-v4.1-flash-free" }`, so its free tier can sit beside pi
+and claude in one config; a codex tier is `{ "backend": "codex", "model": "gpt-6.1-sol" }`, so a ChatGPT
+subscription can cover the team's default tier beside pi and claude. A Claude model that should stay on pi (billed per token) is the plain
+`anthropic/claude-…` selector. See [plans/agent-backends.md §3](plans/agent-backends.md).
 
-For how the loops, review gate, scheduling, and self-redeploy work, see
+For how the roles, review gate, scheduling, and updates work, see
 [docs/how-it-works.md](docs/how-it-works.md). For a measured comparison of tumwater's own
 code against human-written open source, see [docs/code-metrics.md](docs/code-metrics.md).
 
-## Appendix: initial prompt
+## Appendix: the brief
 
-The brief this repository was started from, kept for history. The harness still reads it from
-between the markers below on every tick.
+The brief this repository was started from, kept for history. tumwater still reads the brief from
+between the markers below on every run.
 
 <!-- tumwater:prompt:start -->
 Idea: agentic harness

package/dist/build-info.json

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

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

@@ -0,0 +1,23 @@
+/** Appending a backend's configured passthrough args to an already-built argv. Shared by the
+ * claude, opencode and codex argv builders (claude-args.ts, opencode-args.ts and codex-args.ts),
+ * whose passthrough handling is otherwise identical, so the three backends reject a reserved
+ * flag by the same rule and the same message shape. A passthrough arg equal to a flag the
+ * harness itself sets is appended AFTER the harness's own copy, and all three backends' parsers
+ * are last-wins, so it would silently override the model, the session choice, or the isolation
+ * flags — each such arg is rejected here with the offending arg named. `moduleName` names the
+ * blocking backend in the error (e.g. `claudeArgs`, `opencodeArgs` or `codexArgs`); `reserved`
+ * is that backend's HARNESS_*_FLAGS set. */
+export function appendPassthroughArgs(args, passthrough, reserved, moduleName) {
+    for (const arg of passthrough ?? []) {
+        // Match the flag itself even when it carries its value as `--flag=value`.
+        const flag = arg.split("=", 1)[0];
+        if (reserved.has(flag)) {
+            // Name the reserved flag (the arg may carry it as `--flag=value`, so `flag` here is the
+            // normalized token) and the fix, so the operator knows exactly which passthrough to drop
+            // rather than which of several harness-set flags the arg collided with.
+            throw new Error(`${moduleName}: passthrough arg ${JSON.stringify(arg)} repeats a flag tumwater sets (` +
+                `${flag} is reserved) — drop it from your passthrough args`);
+        }
+        args.push(arg);
+    }
+}

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

@@ -1,8 +1,10 @@
 /** The backend seam (plans/agent-backends.md "The seam"): what one non-interactive agent
  * run needs from its backend — how to build the command, how to translate its native stdout
  * into tumwater's canonical event stream, and how to classify its exit. src/agent/run-agent.ts
- * owns everything backend-neutral (spawn, marker, watchdogs, abort, group kill and marker
- * sweep, stderr capture); a backend registered here supplies the rest. src/agent/run-agent.ts
+ * owns everything backend-neutral (spawn, marker, watchdogs, abort, stderr capture); the
+ * post-run settlement — the group-kill and marker sweeps on exit, the spawn-error result and
+ * the close-time reconcile/classify that builds the `PiRunResult` — lives in
+ * src/agent/run-settle.ts. A backend registered here supplies the rest. src/agent/run-agent.ts
  * registers the pi and claude adapters here.
  *
  * The registry is keyed by id and fed by explicit registration (src/agent/run-agent.ts
@@ -10,7 +12,7 @@
  * real one. */
 import { hasResumableSession } from "./session-ledger.js";
 /** The backend id used when a config names none: pi, the harness's default backend. */
-export const DEFAULT_AGENT = "pi";
+export const DEFAULT_BACKEND = "pi";
 const registry = new Map();
 /** Register one backend under its id, replacing any previous entry with the same id. */
 export function registerAgentBackend(backend) {
@@ -18,7 +20,7 @@ export function registerAgentBackend(backend) {
 }
 /** The backend registered under `id`, or undefined when none is — the caller decides whether
  * an unknown id is a hard error. */
-export function agentBackend(id) {
+export function backendById(id) {
     return registry.get(id);
 }
 /** Whether the backend for `opts.agent` can resume a session in `dir` for a run of
@@ -26,9 +28,9 @@ export function agentBackend(id) {
  * "Sessions"), so a claude author or gate run resumes through its ledger id instead of being
  * read as having no session. Falls back to the backend-neutral session-file check when the
  * backend is unregistered or supplies no `resumable` hook. */
-export function agentSessionResumable(dir, opts) {
-    const backend = agentBackend(opts.agent);
+export function backendSessionResumable(dir, opts, configDir) {
+    const backend = backendById(opts.agent);
     if (backend?.resumable)
-        return backend.resumable(dir, opts);
+        return backend.resumable(dir, opts, configDir);
     return hasResumableSession(dir);
 }

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

@@ -0,0 +1,77 @@
+/**
+ * The per-backend capabilities that the config, prompt, watchdog, progress and doctor layers
+ * read (plans/opencode-backend.md "Groundwork: the claude-only branches become backend
+ * traits"). Pure — imports nothing from the runtime registry (agent-backend.ts) — so those
+ * layers can read a backend's traits without pulling the registry in. That is the same reason
+ * `BACKEND_DEFAULT_MODELS` lives in src/config/model-selector.ts.
+ *
+ * An id with no entry reads as pi, because src/agent/run-agent.ts routes an unregistered id to
+ * the pi backend.
+ */
+import { HARNESS_CLAUDE_FLAGS } from "./claude/claude-args.js";
+import { HARNESS_OPENCODE_FLAGS } from "./opencode/opencode-args.js";
+import { HARNESS_CODEX_FLAGS } from "./codex/codex-args.js";
+import { HARNESS_PI_FLAGS } from "../config/config-schema.js";
+/** Whether the backend streams tool output. pi streams content-bearing tool updates, so its
+ * calls are classified per command; claude, opencode and codex send none, so silence carries no
+ * hang signal and every call is judged by the buffered threshold (plans/agent-backends.md
+ * "Watchdogs and progress"). Only claude, opencode and codex are false; an unknown id reads as
+ * pi. */
+export function streamsToolOutput(backend) {
+    // Only claude, opencode and codex stream no tool output; every other id (including an
+    // unregistered one) reads as pi, which does stream.
+    return backend !== "claude" && backend !== "opencode" && backend !== "codex";
+}
+/** Whether the backend's model jobs resolve through pi's models.json. True for pi only (and an
+ * unknown id, which reads as pi); a claude, opencode or codex job reads no pi pricing and needs
+ * no definitions file. */
+export function usesPiModels(backend) {
+    // Only claude, opencode and codex read no pi models.json; every other id (including an
+    // unregistered one) reads as pi, which does.
+    return backend !== "claude" && backend !== "opencode" && backend !== "codex";
+}
+/** The reason string config validation prints for a reserved `backends.<id>.args` flag, or
+ * undefined when the flag is not reserved for that backend. Wraps the HARNESS_*_FLAGS sets for
+ * claude (HARNESS_CLAUDE_FLAGS), opencode (HARNESS_OPENCODE_FLAGS), codex (HARNESS_CODEX_FLAGS)
+ * and pi (HARNESS_PI_FLAGS), keeping each backend's reason wording. The flag is the bare name —
+ * checkReservedArgs splits `--mode=x` on `=` before calling. */
+export function reservedPassthroughFlag(backend, flag) {
+    switch (backend) {
+        case "pi":
+            return HARNESS_PI_FLAGS.get(flag);
+        case "claude":
+            return HARNESS_CLAUDE_FLAGS.has(flag) ? "it is managed by tumwater" : undefined;
+        case "opencode":
+            return HARNESS_OPENCODE_FLAGS.has(flag) ? "it is managed by tumwater" : undefined;
+        case "codex":
+            // The standalone-flag screen; the `-c <key>=…` / `--config <key>=…` config-key screen is
+            // arity-aware (a `-c` token and its key are different argv elements), so config-validation
+            // owns it against HARNESS_CODEX_CONFIG_KEYS (codex-args.ts) rather than here.
+            return HARNESS_CODEX_FLAGS.has(flag) ? "it is managed by tumwater" : undefined;
+        default:
+            // An unknown backend has no known harness argv to clash with, so nothing is reserved.
+            return undefined;
+    }
+}
+/** A seam's model as one readable token: `<provider>/<model>` for a pi seam (and any unknown
+ * id, which reads as pi), the bare model for claude — or "claude backend" when there is none —
+ * `opencode/<model>` for opencode, whose ids all read under the opencode namespace, and the
+ * bare model for codex — or "codex default" when there is none. The one home of the label,
+ * shared by the doctor report and the image-input surface strings so they cannot drift. */
+export function modelLabel(backend, provider, model) {
+    if (backend === "claude")
+        return model ?? "claude backend";
+    if (backend === "opencode")
+        return `opencode/${model ?? "?"}`;
+    if (backend === "codex")
+        return model ?? "codex default";
+    return `${provider ?? "?"}/${model ?? "?"}`;
+}
+/** A backend id's display name as the status surfaces show it: title-cased
+ * (`id.charAt(0).toUpperCase() + id.slice(1)`, so `"claude"` → `"Claude"`, `"codex"` →
+ * `"Codex"`). The one home of the spelling the subscription window's per-backend block label
+ * (part 3a/9) and the later display parts share, so a backend's name cannot drift between
+ * them. */
+export function backendDisplayName(id) {
+    return id.charAt(0).toUpperCase() + id.slice(1);
+}

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

@@ -1,172 +1,79 @@
-/** The claude account state: which billing pays for claude runs, and the newest subscription
+/** The claude account state: the claude backend's subscription account (src/agent/
+ * 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.
  *
- * 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; observeClaudeAccount converts once here),
- * so consumers compare it to `Date.now()` directly. */
+ * 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),
+ * specialized to the backend id "claude", plus the claude-only seed (auth status, the API-key
+ * and third-party-provider billing checks) that no other backend shares. 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; the store converts once), so consumers compare it to
+ * `Date.now()` directly. */
 import { spawnSync } from "node:child_process";
-import { readJsonFile, writeJsonAtomic } from "../../files/json-files.js";
-import { finiteNumber, isJsonObject, parseJsonObject } from "../../files/json-object.js";
-import { claudeAccountPath } from "../../paths.js";
-import { claudeBackend } from "./claude-backend.js";
+import os from "node:os";
+import { resolvedBackendConfig } from "../../config/config-views.js";
+import { parseJsonObject } from "../../files/json-object.js";
+import { observeAccount, readAccount, subscriptionWindowRejected, utilizationPct, windowEntries, windowLabel, windowReserved, windowUsedUp, writeAccount, } from "../subscription-account.js";
+import { claudeBackend, claudeConfigDir } from "./claude-backend.js";
 import { claudeEnv, claudeThirdPartyProvider } from "./claude-env.js";
-/** True when a failed run ended on a subscription usage window the account reported as
- * `rejected` without overage — the signal the fleet 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 claude and overage are budget/fallback matters, not a
- * window hold, so they read false; a pi 429 reports no window and also reads false. */
-export function subscriptionWindowRejected(run) {
-    return (run.transientRateLimit &&
-        run.billing === "subscription" &&
-        (run.rateWindows ?? []).some((w) => w.status === "rejected" && w.isUsingOverage !== true));
-}
-/** 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 claudeWindowLabel(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 account's windows as a list, most constrained first: by status severity, then the
- * reported utilization (a missing reading sorts below any number), then the earlier reset, then
- * the type name — so a tie always orders the same way. Empty when the account reported none. */
-export function claudeWindowEntries(account) {
-    return Object.entries(account.windows)
-        .map(([type, w]) => ({ type, ...w }))
-        .sort((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);
-    });
-}
-/** Read the persisted account state, 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. */
+/** Read the persisted claude account state, 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 readClaudeAccount(root, now = Date.now()) {
-    const doc = readJsonFile(claudeAccountPath(root));
-    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" ? { subscriptionType: 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`. */
-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
-    // claudeWindowEntries comparator (Infinity - Infinity is NaN).
-    const utilization = finiteNumber(value.utilization, undefined);
-    const window = {
-        status: resets && resetsAt <= now ? "reset" : value.status,
-        ...(resets ? { resetsAt } : {}),
-        ...(utilization !== undefined ? { utilization } : {}),
-        ...(typeof value.overageStatus === "string" ? { overageStatus: value.overageStatus } : {}),
-        ...(value.isUsingOverage === true ? { isUsingOverage: true } : {}),
-        observedAt,
-    };
-    return window;
+    return readAccount(root, "claude", now);
 }
-/** 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 (the display, the hold, and accountUsesOverage). 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) {
-    Object.defineProperty(windows, type, { value: window, enumerable: true, writable: true, configurable: true });
-}
-/** Overwrite the 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 tick 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. */
+/** Overwrite the claude 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. */
 export function writeClaudeAccount(root, account) {
-    writeJsonAtomic(claudeAccountPath(root), account, true);
+    writeAccount(root, "claude", account);
 }
-/** Fold one run's billing and rate-window readings into the 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). */
+/** Fold one run's billing and rate-window readings into the claude 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 observeClaudeAccount(root, run, now = Date.now()) {
-    const existing = readClaudeAccount(root, 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?.subscriptionType !== undefined ? { subscriptionType: existing.subscriptionType } : {}),
-        observedAt: now,
-        windows,
-    };
-    writeClaudeAccount(root, account);
-    return account;
+    return observeAccount(root, "claude", run, now);
 }
-/** 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 observeClaudeAccount 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,
-    };
+/** 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);
+}
+/** The fraction of a subscription usage window consumed as a whole-number percent —
+ * subscription-account.ts's utilizationPct, under its historical claude name. */
+export function claudeUtilizationPct(utilization) {
+    return utilizationPct(utilization);
 }
-/** Seed the 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 API. An existing file is left
- * alone, and a probe that cannot run or is not logged in leaves the file absent
- * (readClaudeAccount then reads "no subscription"). Returns the account written, or null. */
+/** The account's windows as a list, most constrained first — subscription-account.ts's
+ * windowEntries, under its historical claude name. */
+export function claudeWindowEntries(account) {
+    return windowEntries(account);
+}
+/** 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
+ * API. An existing file is left alone, and a probe that cannot run or is not logged in leaves
+ * the file absent (readClaudeAccount then reads "no subscription"). Returns the account
+ * written, or null. A failed write also returns null and never throws, so the first claude
+ * run's observeClaudeAccount fills the file in. */
 export function seedClaudeAccount(root, config, now = Date.now()) {
     const existing = readClaudeAccount(root, now);
     if (existing !== null)
@@ -176,11 +83,16 @@ export function seedClaudeAccount(root, config, now = Date.now()) {
         return null;
     const account = {
         billing: billing.billing,
-        ...(billing.subscriptionType !== undefined ? { subscriptionType: billing.subscriptionType } : {}),
+        ...(billing.plan !== undefined ? { plan: billing.plan } : {}),
         observedAt: now,
         windows: {},
     };
-    writeClaudeAccount(root, account);
+    try {
+        writeClaudeAccount(root, account);
+    }
+    catch {
+        return null;
+    }
     return account;
 }
 /** The billing the environment implies, or null when it cannot be decided: an API key wins, a
@@ -197,12 +109,12 @@ function seedBilling(config) {
         return null;
     const subscription = claudeAuthUsesSubscription(auth);
     return subscription
-        ? { billing: "subscription", ...(auth.subscriptionType !== undefined ? { subscriptionType: auth.subscriptionType } : {}) }
+        ? { billing: "subscription", ...(auth.subscriptionType !== undefined ? { plan: auth.subscriptionType } : {}) }
         : { billing: "api" };
 }
 /** Parse `claude auth status` stdout, returning null when it is not a JSON object or does not
  * report a boolean `loggedIn` — the one home of the read, shared by this module's
- * probeAuthStatus and doctor's claudeAuthProbe (doctor-model-checks.ts). An optional string
+ * probeAuthStatus and doctor's claudeAuthProbe (doctor-claude-checks.ts). An optional string
  * field reads as absent when the reply names something else. */
 export function parseClaudeAuthStatus(stdout) {
     const doc = parseJsonObject(stdout);
@@ -216,7 +128,7 @@ export function parseClaudeAuthStatus(stdout) {
 }
 /** True when an auth-status reply names claude.ai subscription billing — a subscription type
  * (its presence alone signals one) or the explicit claude.ai auth method — rather than API
- * billing. Shared by seedBilling below and doctor's checkClaudeAuth (doctor-model-checks.ts),
+ * billing. Shared by seedBilling below and doctor's checkClaudeAuth (doctor-claude-checks.ts),
  * which must not disagree about which seams are subscription-billed. */
 export function claudeAuthUsesSubscription(auth) {
     return auth.subscriptionType !== undefined || auth.authMethod === "claude.ai";
@@ -225,7 +137,15 @@ export function claudeAuthUsesSubscription(auth) {
  * short deadline. Null when the probe could not run or its reply was unreadable. */
 function probeAuthStatus(config) {
     const resolved = claudeBackend.resolveBin(config);
-    const env = claudeEnv(process.env, { quietTimeoutSeconds: 0 });
+    const configDir = resolvedBackendConfig(config, "claude").configDir;
+    const env = claudeEnv(process.env, {
+        quietTimeoutSeconds: 0,
+        // The seed probes auth under the same env a real run gets, so a team config dir's login
+        // is what it reports (plans/notes-command.md "Keeping funes out of team runs").
+        ...(configDir !== undefined
+            ? { configDir: claudeConfigDir(process.env, os.homedir(), configDir) }
+            : {}),
+    });
     try {
         const result = spawnSync(resolved.bin, ["auth", "status"], {
             env,