tumwater 0.1.0 → 0.1.2

package/README.md

@@ -10,10 +10,26 @@ local git repo, and no remote is ever touched.
 
 ![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)
 
+## Install
+
+Requires Node 20.3 or later on macOS or Linux.
+
+```bash
+npm install -g tumwater
+```
+
+Or run any command without installing: `npx tumwater`. To run from a checkout of this repo
+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.
+
 ## Status
 
 <!-- tumwater:status:start -->
-**v0.1**: working harness. All 13 roles and the director are enabled by default.
+**v0.1.1**: 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`).
 
 Open work: [PLANS.md](PLANS.md) (planned), [BUGS.md](BUGS.md) (open bugs),
 [QUESTIONS.md](QUESTIONS.md) (open questions).
@@ -22,8 +38,6 @@ Open work: [PLANS.md](PLANS.md) (planned), [BUGS.md](BUGS.md) (open bugs),
 ## Usage
 
 ```bash
-npm install -g tumwater     # or run any command with npx tumwater
-                            # from a checkout: npm install && npm run build && npm link
 cd your-project             # a new or existing directory
 tumwater init "Build a tiny markdown-to-html converter CLI in Python."
                             # add --template <id> to seed from a bundled starting point
@@ -31,41 +45,96 @@ tumwater init "Build a tiny markdown-to-html converter CLI in Python."
                             # prints the catalog
                             # add --file <path> to read the brief from a file
                             # add --adopt to adopt an existing repo as-is
+                            # a fresh/empty project is seeded with
+                            # "bootstrap": {"untilPlansDone": 5}, holding the maintenance
+                            # loops until 5 plans are done; remove "bootstrap" from
+                            # tumwater.json to end that early
 tumwater run                # start the loops (Ctrl+C to stop)
+tumwater run --gui          # ... and serve the browser dashboard at http://127.0.0.1:7180 from the same process
+tumwater run --for 2h       # run for a bounded window (capped at 90d), then drain and exit like Ctrl+C would
+tumwater run --once         # one full round of ticks, drains its landings, and exits (for cron/CI);
+                            # add --role <id> to scope the round to one loop
 ```
 
 Then, from another terminal:
 
 | To | Run |
 | --- | --- |
-| Watch the fleet | `tumwater tui`, or `tumwater gui` for the browser dashboard at http://127.0.0.1:7180 |
-| Watch per-tick history | `tumwater history [--role <id>] [-n N] [--since <duration>] [--grep <text>]`, or `tumwater history --json` for the rows as JSON; `tumwater tick <role> <n>` for one tick's full event trail (a summary header — when it ran, how long, result, usage — followed by the tick's events, oldest first; `--json` prints the payload as JSON, `null` when the log holds no such tick) |
-| Check state | `tumwater status`, `tumwater logs -f`, `tumwater logs --since <duration>`, `tumwater logs --grep <text>`, `tumwater logs --json` (the event feed as NDJSON, for scripts), `tumwater logs --role <id>`, `tumwater backlog` (planned features, open bugs, open questions as Markdown), `tumwater backlog --json` (the backlog as JSON, for scripts), `tumwater role <id>` (one loop's standing prompt — find text, `instructions` override, resolved model and interval, enabled/paused state — plus its next tick's assembled prompt, which shows the oldest queued prompt without consuming it (one is dequeued per tick; `--json` for scripts)) |
+| Watch the fleet | `tumwater tui`, or the browser dashboard at http://127.0.0.1:7180 — `tumwater gui` on its own, or `tumwater run --gui` to boot the fleet and the dashboard together |
+| Watch per-tick history | `tumwater history [--role <id>] [-n N] [--since <duration>] [--grep <text>] [--result <changes|none|problems>]`, or `tumwater history --json` for the rows as JSON; `tumwater tick <role> <n>` for one tick's full event trail (a summary header — when it ran, how long, result, usage — followed by the tick's events, oldest first; `--last` shows the newest completed tick's trail instead of numbering one; `--json` prints the payload as JSON, `null` when the log holds no such tick) |
+| Check state | `tumwater status`, `tumwater logs -f`, `tumwater logs --since <duration>`, `tumwater logs --grep <text>`, `tumwater logs --json` (the event feed as NDJSON, for scripts), `tumwater logs --role <id>`, `tumwater queue [--json]` (the durable land queue in execution order — one line per waiting landing with its position, loop, tick, pinned sha, age, and summary; `--json` for scripts), `tumwater backlog` (planned features, open bugs, open questions as Markdown, each held entry's heading marked `[refused]`, `[needs review]`, `[needs replan]`, or `[blocked: requires …]`), `tumwater backlog --json` (the backlog as JSON, for scripts, with a `holds.plans`/`holds.bugs` array parallel to `plans`/`bugs`), `tumwater role <id>` (one loop's standing prompt — find text, `instructions` override, resolved model and interval, enabled/paused state, its notebook — plus its next tick's assembled prompt, which shows the oldest queued prompt without consuming it (one is dequeued per tick; `--json` for scripts); `--clear-notes` clears that loop's notebook and `--notes-file <path>` (`-` for stdin) replaces it (4 KB cap); the dashboard's loop drawer edits or clears the notebook the same way, and the TUI's notebook view (Ctrl+N) clears it with Ctrl+X pressed twice) |
 | See a loop's pending change | `tumwater diff --role <id>` — that loop's branch's unlanded commits (with the patch) and its worktree's uncommitted edits (staged and unstaged); without `--role`, one line per loop holding pending work; `--json` prints the payload as data |
-| Steer the project | `tumwater prompt "prefer no third-party deps"` queues a request for the director; add `--role <id>` to aim it at one loop's next tick, `tumwater prompt --list` shows the queued prompts numbered and grouped by loop, with how long each has waited (`--json` for scripts), and `tumwater prompt --cancel <n>` removes the Nth entry as `--list` shows them (add `--role <id>` when several loops share that number) |
-| Answer open questions | `tumwater questions` lists QUESTIONS.md's open questions numbered (as the loops wrote them); `tumwater questions answer <n> "decision text"` moves the Nth entry to ## Answered with your dated answer (loops read the file back on their next tick); `--json` prints the list as data |
-| Control the loops | `tumwater pause [--for <duration>]` / `resume [--role <id>]` (fleet or one loop; `--for 2h` auto-resumes, capped at 90d; add `--reason <text>` on a fleet pause to state why — it shows on `status`, the TUI, and the dashboard), `tumwater wake` (skip backoff), `tumwater abort --role <id>`, `tumwater stop` (drain and exit, like Ctrl+C) |
-| Audit | `tumwater doctor` (pre-flight; `--json` prints the report as JSON, for scripts), `tumwater report` (usage and cost; totals include landing runs — reviewer + conflict resolution), `tumwater report --since <duration>` (totals over a trailing window, capped at 7d), `tumwater report --json` (the `--days`/`--since`/`--failures` reports as JSON, for scripts), `tumwater report --failures` (the failure digest: per-role outcomes, each role's time and spend by outcome, and the top five loss causes ranked by agent-hours, with a marker naming how many were cut) |
-
-`tumwater help` lists every command and flag; `tumwater help <command>` shows one command's usage. `gui --all-interfaces` exposes the dashboard, and
-with it the director prompt, to your whole network, so pair it with `--token <secret>`.
-
-Settings live in `tumwater.json`: enabled roles, model, intervals, the daily spend cap
+| Steer the project | `tumwater prompt "prefer no third-party deps"` queues a request for the director; add `--role <id>` to aim it at one loop's next tick, `--file <path>` (`-` for stdin) to read the text from a file, or `--at <duration>` to defer it until the duration passes (45s, 90m, 1h30m, 1d; capped at 90d), `tumwater prompt --list` shows the queued prompts numbered and grouped by loop, with how long each has waited (`--json` for scripts), and `tumwater prompt --cancel <n>` removes the Nth entry as `--list` shows them, and `tumwater prompt --edit <n> "new text" [--attach <path>]` rewrites the Nth entry in place (or `--edit <n> --file <path>` takes the replacement from a file), keeping its position and wait time, and appends any `--attach` images after the ones it already carries (both take `--role <id>` when several loops share that number), and `--attach <path>` (repeatable, up to 4 images — png, jpg, jpeg, gif, webp, bmp, each at most 5 MiB) attaches an image the receiving loop reads at its next tick, whether it is queued or edited; `tumwater bug "<symptom>"` files a bug into BUGS.md's Open section and wakes the bugfix loop, `tumwater plan "<title>" [body...]` — or `--file <path>` (`-` for stdin) to file one from a markdown file, its first line the title and the rest the body, kept line for line — files a plan request into PLANS.md's Planned section and wakes the feature loop — both stamped as operator-reported (the other half of `tumwater backlog`), `--list` shows a command's own entries numbered with their eligibility marks (`--json` for scripts), and `--cancel <n>` retracts one or `--edit <n> "<text>"` rewrites one in place (or `--edit <n> --file <path>` takes the replacement from a file, keeping its lines), neither with a wake; the dashboard's plan/bug drawer cancels an entry the same way, after a confirming second click, and the TUI's backlog pane does too, with Ctrl+X pressed twice on the selected entry (Ctrl+E edits its title; Ctrl+N files a new plan or bug by title and wakes its loop), the drawer edits an entry's title and body in place, and the Plans/Bugs tabs' New form files one with an optional markdown body |
+| Answer open questions | `tumwater questions` lists QUESTIONS.md's open questions numbered (as the loops wrote them); `tumwater questions answer <n> "decision text"` moves the Nth entry to ## Answered with your dated answer (`--file <path>`, `-` for stdin, records a multiline decision with its lines kept; loops read the file back on their next tick); `--json` prints the list as data; the dashboard's question drawer records an answer with its lines kept, as `--file` does, and the TUI's backlog pane answers the selected question with Ctrl+A |
+| Control the loops | `tumwater pause [--for <duration>]` / `resume [--role <id>]` (fleet or one loop; `--for 2h` auto-resumes, capped at 90d; add `--reason <text>` on a fleet pause to state why — it shows on `status`, the TUI, and the dashboard; the TUI's Ctrl+F takes a duration and reason too, and its Ctrl+P on a loop's transcript takes a duration, and its Ctrl+W takes a duration or `cancel`), `tumwater wake` (skip backoff; `wake --in 45m` schedules the wake for 45 minutes from now — the marker is written immediately but consumed no earlier than the deadline, like `pause --for`'s auto-resume, and each scheduled wake stands on its own, so later wakes do not cancel it, while `tumwater wake --cancel [--role <id>]` drops the pending scheduled wakes (or that loop's share of them), `tumwater wake --list [--role <id>] [--json]` lists them, and the dashboard's Wake later menu and loop drawer cancel pending wakes the same way; the dashboard's loop drawer schedules one loop's wake the same way ("Wake later…"); `tumwater status` and the dashboard's loop rows show the pending wake until it fires), `tumwater reclaim [--dry-run]` (drop gitignored build outputs from every harness worktree; `--dry-run` lists the candidates and cleans nothing), `tumwater retire --role <id>` (remove a disabled loop's worktree, branch, and per-role state — use after setting `enabled: false` for that role; `--force` overrides the safety rails), `tumwater abort --role <id>`, `tumwater stop` (drain and exit, like Ctrl+C), `tumwater reset-counters [--role <id>]` (zero the per-loop counters the dashboards show, starting a fresh observation window — scheduling is untouched; the dashboard's Loops card and loop drawer reach the same reset) |
+| Audit | `tumwater doctor` (pre-flight, naming a standing fleet or per-role pause or quiet-hours window holding now, today's spend against the daily cap, and the maintenance allowance's rolling-24 h use; `--json` prints the report as JSON, for scripts; the dashboard's Settings view runs the same checks in its Health check card), `tumwater report` (usage and cost, with landed commits by role and the work/maintenance split; totals include landing runs — reviewer + conflict resolution), `tumwater report --role <id>` (scopes the day or `--since` report to one loop's ticks, tokens, cost, and commits; landing runs and backlog tallies are fleet-wide and omitted; with `--failures`, scopes the failure digest to that loop too), `tumwater report --since <duration>` (totals over a trailing window, capped at 7d; with `--failures`, the failure digest over that window instead), `tumwater report --json` (the `--days`/`--since`/`--failures` reports as JSON, for scripts), `tumwater report --failures` (the failure digest: per-role outcomes, each role's time and spend by outcome, and the top five loss causes ranked by agent-hours, with a marker naming how many were cut; `--since <duration>` windows the digest over a trailing span, capped at 7d, compared against the equal-length window before it) |
+
+`tumwater help` lists every command and flag; `tumwater help <command>` shows one command's
+usage. `gui --all-interfaces` exposes the dashboard, and with it the director prompt, to your
+whole network, so pair it with `--token <secret>`.
+
+Settings live in `tumwater.json`: enabled roles, model (either one selector or a map of tiers
+`small`/`default`/`strong` — omitted tiers inherit `default`; per-tier `fallback` overrides may
+name a model or `"pause"`, and a role's `model` may name a tier; see
+[plans/model-tiers.md](plans/model-tiers.md)),
+intervals, per-role `instances` (`feature` and `bugfix` may each run 1–8 parallel runners, every one
+with its own branch and state; default 1), the daily spend cap
 (`maxDailyCostUsd`, with optional per-role caps `maxDailyCostUsdPerRole` — a loop over its own
-cap starts no new ticks until the next local day or a live edit), a nightly `quietHours` window
-(e.g. `"23:00-07:00"` local time) during
-which role loops start no new ticks (the director is exempt), user-defined `customLoops`, and an
+cap starts no new ticks until the next local day or a live edit), a
+`maintenancePerWorkLanding` ratio (default 2; a rolling 24 h allowance of that many
+code-maintenance landings per feature/bugfix/director landing, plus a floor of 12 — when the
+window reaches it the scheduler holds the enabled maintenance loops until it rolls under, and a
+fresh `tumwater wake <role>` or a queued prompt for one admits a single tick anyway), a nightly
+`quietHours` window (e.g. `"23:00-07:00"` local time) during
+which role loops start no new ticks (the director is exempt), with optional per-role windows
+`quietHoursPerRole` — a loop inside its own window starts no new ticks, whether or not the
+fleet-wide window covers now — a `diskHoldGB` free-space floor (default 10; when the volume
+holding the worktrees drops below it, no new work starts until free space recovers 5 GB above it;
+0 disables), a `diskReclaimGB` pressure-reclaim threshold (default 40; below it idle worktrees
+drop their gitignored build outputs before the hold engages; 0 disables), and a
+`worktreeIdleReclaimHours` window (default 24; an hourly pass drops a worktree's gitignored build
+outputs once it has sat unused that long, whatever the free space; 0 disables), a
+`worktreeSlots` count of pooled checkouts shared by role ticks and landing vets (default
+`maxConcurrent` + 1; the director's worktree sits outside the pool) — user-defined
+`customLoops`, and an
 optional `notify` shell command run when the fleet needs a human (a budget pause, a budget warning
 at 80% of the cap while the gate is still open, an error-streak
-breaker trip, a failed landing, a blocked restart — the command gets `TUMWATER_EVENT_TYPE`,
-`TUMWATER_EVENT_LOOP`, and `TUMWATER_EVENT_MESSAGE` in its environment).
+breaker trip, a failed landing, a blocked restart, a posted question — the command gets
+`TUMWATER_EVENT_TYPE`, `TUMWATER_EVENT_LOOP`, and `TUMWATER_EVENT_MESSAGE` in its environment;
+verify it with `tumwater notify --test`).
 Edits apply live while the fleet runs.
 From the terminal, `tumwater config` prints the effective config as JSON, `tumwater config get
-<key>` reads one resolved value, and `tumwater config set <key> <value>` writes one top-level
-key.
-
-**Backends:** any OpenAI-compatible model pi can reach works; set `provider` and `model` in
-`tumwater.json`. See [docs/backends.md](docs/backends.md) for requirements and a worked setup.
+<key>` reads one resolved value, `tumwater config set <key> <value>` writes one top-level
+key, and `tumwater config unset <key>` removes one — the inverse of `set`, so a value reverts
+to its default or disappears from its map or section; dotted keys
+(`maxDailyCostUsdPerRole.feature 1.5`, `roles.qa.model x`) merge one entry into the existing
+map or role entry, while bare keys replace the whole value. `roles` always merges the built-in
+catalog per entry at load, so a bare `config set roles` replaces the file's section but cannot
+disable a role by omission — disable one with `tumwater config set roles.<id>.enabled false`.
+
+**Backends:** any OpenAI-compatible model pi can reach works; set `model` in `tumwater.json` to
+one `provider/id[:thinking]` selector (plus `fallback` to a free selector), or a map of tiers
+`small`/`default`/`strong`. A role whose primary keeps failing with provider-class errors
+(three consecutive 429s or backend failures) runs its next ticks on its tier's resolved
+`fallback` pair and probes the primary once the 5-minute cooldown elapses, returning to it
+when a probe answers; `tumwater status`, the TUI, the dashboard, and `tumwater role <id>` name
+the off-model episode. Set `agent` to run bare selectors and the no-model default on another
+backend — `claude` runs on Claude Code, with per-tier defaults (`claude-sonnet-5-5` and
+friends) and per-backend `agents.claude.bin`/`agents.claude.args` overrides; a selector whose
+provider names a backend id (`claude/claude-opus-5-5`) always routes there. A claude run's
+cost comes from the CLI's own price table. A run paid by a claude.ai subscription is exempt
+from the daily dollar cap: its API-equivalent cost is tracked as notional spend and shown on
+its own line in `tumwater report`, never in the cap; a run billed to an API key — or one that
+saw `isUsingOverage` — counts against the cap like a priced pi model. A subscription claude
+model with no overage also counts as free for the budget badge and fallback decisions, so at
+the cap it stays put while priced pi seams move to their fallback. A rejected claude.ai
+subscription usage window holds subscription claude seams until it resets (a first
+`allowed_warning` is logged too); `tumwater status`, the TUI, the dashboard, and
+`tumwater role <id>` show the window in place of the daily spend on a subscription-only fleet
+(or beside it on a mixed one, where the daily spend covers priced seams only), and a run cut off
+by a rejected window keeps its session and worktree edits and resumes once the window resets.
+See
+[docs/backends.md](docs/backends.md) for requirements and a worked setup.
 
 For how the loops, review gate, scheduling, and self-redeploy work, see
 [docs/how-it-works.md](docs/how-it-works.md). For a measured comparison of tumwater's own

package/dist/build-info.json

@@ -1,5 +1,5 @@
 {
-  "sha": "4c69994273d9f4d707b0c5a6e7d00f50a3b265e6",
-  "builtAt": 1791110618512,
+  "sha": "90a6c2c27eb822740efee37d84a0518b76b4d7bb",
+  "builtAt": 1791821277046,
   "root": "/home/runner/work/tumwater/tumwater"
 }

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

@@ -0,0 +1,34 @@
+/** 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
+ * registers the pi and claude adapters here.
+ *
+ * The registry is keyed by id and fed by explicit registration (src/agent/run-agent.ts
+ * registers both adapters at load), so a test can register a fake backend without importing a
+ * 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";
+const registry = new Map();
+/** Register one backend under its id, replacing any previous entry with the same id. */
+export function registerAgentBackend(backend) {
+    registry.set(backend.id, 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) {
+    return registry.get(id);
+}
+/** Whether the backend for `opts.agent` can resume a session in `dir` for a run of
+ * `opts.kind`: the one resume guard every resume point uses (plans/agent-backends.md
+ * "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);
+    if (backend?.resumable)
+        return backend.resumable(dir, opts);
+    return hasResumableSession(dir);
+}

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

@@ -0,0 +1,243 @@
+/** The claude account state: 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. */
+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 { 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. */
+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;
+}
+/** 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. */
+export function writeClaudeAccount(root, account) {
+    writeJsonAtomic(claudeAccountPath(root), account, true);
+}
+/** 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). */
+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;
+}
+/** 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,
+    };
+}
+/** 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. */
+export function seedClaudeAccount(root, config, now = Date.now()) {
+    const existing = readClaudeAccount(root, now);
+    if (existing !== null)
+        return existing;
+    const billing = seedBilling(config);
+    if (billing === null)
+        return null;
+    const account = {
+        billing: billing.billing,
+        ...(billing.subscriptionType !== undefined ? { subscriptionType: billing.subscriptionType } : {}),
+        observedAt: now,
+        windows: {},
+    };
+    writeClaudeAccount(root, account);
+    return account;
+}
+/** The billing the environment implies, or null when it cannot be decided: an API key wins, a
+ * third-party provider env (`CLAUDE_CODE_USE_BEDROCK`/`_VERTEX`/`_FOUNDRY`) is API billing, and
+ * otherwise `claude auth status` names the login. */
+function seedBilling(config) {
+    const apiKey = process.env.ANTHROPIC_API_KEY;
+    if (typeof apiKey === "string" && apiKey !== "")
+        return { billing: "api" };
+    if (claudeThirdPartyProvider(process.env))
+        return { billing: "api" };
+    const auth = probeAuthStatus(config);
+    if (!auth?.loggedIn)
+        return null;
+    const subscription = claudeAuthUsesSubscription(auth);
+    return subscription
+        ? { billing: "subscription", ...(auth.subscriptionType !== undefined ? { subscriptionType: 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
+ * field reads as absent when the reply names something else. */
+export function parseClaudeAuthStatus(stdout) {
+    const doc = parseJsonObject(stdout);
+    if (doc === null || typeof doc.loggedIn !== "boolean")
+        return null;
+    return {
+        loggedIn: doc.loggedIn,
+        subscriptionType: typeof doc.subscriptionType === "string" ? doc.subscriptionType : undefined,
+        authMethod: typeof doc.authMethod === "string" ? doc.authMethod : undefined,
+    };
+}
+/** 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),
+ * which must not disagree about which seams are subscription-billed. */
+export function claudeAuthUsesSubscription(auth) {
+    return auth.subscriptionType !== undefined || auth.authMethod === "claude.ai";
+}
+/** Run `claude auth status` under the same scrubbed environment a real run gets, bounded by a
+ * 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 });
+    try {
+        const result = spawnSync(resolved.bin, ["auth", "status"], {
+            env,
+            encoding: "utf8",
+            timeout: 10_000,
+            killSignal: "SIGKILL",
+        });
+        if (result.status !== 0 || typeof result.stdout !== "string")
+            return null;
+        return parseClaudeAuthStatus(result.stdout);
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,104 @@
+/** Building the claude command line for one tick (plans/agent-backends.md "The claude
+ * invocation") — pure argv construction plus the prompt-on-stdin pairing, with no subprocess,
+ * backend registration, or session ledger. Part 3c supplies the session decision (which
+ * `--session-id` or `--resume` to pass) and the notes MCP config path; this module turns those
+ * inputs into the invocation's argv.
+ *
+ * The environment is built separately (claude-env.ts) so each concern has one module.
+ *
+ * `NODE_OPTIONS` preload decision (2026-10-09): claude 2.1.295 on macOS is a single-file
+ * Mach-O native executable (`file` reports `Mach-O 64-bit executable arm64`) and ignores
+ * `NODE_OPTIONS` — it exits 0 and prints its version both with tumwater's `--import=data:`
+ * preload and with a deliberately broken `--require` path. So the preload stays on claude's
+ * environment: claude itself is unaffected, while the Bash tool's `npm` grandchildren inherit
+ * it and skip their LaunchServices check-in (src/process/process.ts). The `--settings` Bash-env
+ * fallback the design holds in reserve is not needed. */
+import fs from "node:fs";
+import path from "node:path";
+/** Flags the harness passes itself. A passthrough arg equal to one of these is appended AFTER
+ * the harness's own copy, and claude's argument parser is last-wins — so it would silently
+ * override the isolation flags, the session choice, or the model the harness resolved. Each is
+ * rejected by claudeArgs with the offending arg named. This is exactly the design's reserved
+ * set (plans/agent-backends.md "Config"); config validation (config-validation.ts) mirrors this
+ * set for `agents.claude.args`, so a value that passes validation is never accepted by
+ * validation and then thrown here. */
+export const HARNESS_CLAUDE_FLAGS = new Set([
+    "-p",
+    "--print",
+    "--output-format",
+    "--verbose",
+    "--model",
+    "--effort",
+    "--session-id",
+    "--resume",
+    "-r",
+    "--continue",
+    "-c",
+    "--permission-mode",
+    "--tools",
+    "--setting-sources",
+    "--strict-mcp-config",
+    "--mcp-config",
+    "--disable-slash-commands",
+    "--exclude-dynamic-system-prompt-sections",
+    "--append-system-prompt-file",
+    "--max-budget-usd",
+]);
+/** claude's effort levels are pi's thinking levels with `off`/`minimal` clamped to `low`:
+ * claude has no lower setting, and doctor notes the clamp (plans/agent-backends.md "Config").
+ * `off` and `minimal` are the only remapped entries; the rest are 1:1. */
+const EFFORT_BY_THINKING = {
+    off: "low",
+    minimal: "low",
+    low: "low",
+    medium: "medium",
+    high: "high",
+    xhigh: "xhigh",
+    max: "max",
+};
+/** True when the worktree has an `AGENTS.md` and no `CLAUDE.md`: claude does not read
+ * `AGENTS.md` on its own, so the adapter appends it — but only when the repo has no
+ * `CLAUDE.md`, which `--setting-sources project` already loads (finding 1). */
+function shouldAppendAgents(cwd) {
+    return fs.existsSync(path.join(cwd, "AGENTS.md")) && !fs.existsSync(path.join(cwd, "CLAUDE.md"));
+}
+/** Build one run's claude argv and stdin. The prompt is never an argv element (claude reads
+ * `-p` input from stdin). Throws on an unusable invocation — no session choice, both session
+ * choices, an unknown thinking level, or a passthrough arg that repeats a harness flag — since
+ * each would otherwise silently change what the harness asked for. */
+export function claudeArgs(opts) {
+    if ((opts.sessionId === undefined) === (opts.resumeSessionId === undefined)) {
+        throw new Error("claudeArgs: pass exactly one of sessionId or resumeSessionId");
+    }
+    const args = ["-p", "--output-format", "stream-json", "--verbose", "--model", opts.model];
+    if (opts.thinking !== undefined) {
+        // Own-property test, not a bare index: a level like `constructor` or `toString` would
+        // otherwise inherit a function from Object.prototype and bypass the rejection below.
+        if (!Object.hasOwn(EFFORT_BY_THINKING, opts.thinking)) {
+            throw new Error(`claudeArgs: unknown thinking level ${JSON.stringify(opts.thinking)}`);
+        }
+        args.push("--effort", EFFORT_BY_THINKING[opts.thinking]);
+    }
+    if (opts.sessionId !== undefined)
+        args.push("--session-id", opts.sessionId);
+    else
+        args.push("--resume", opts.resumeSessionId);
+    args.push("--permission-mode", "bypassPermissions", "--tools", "Bash,Read,Edit,Write,Glob,Grep", "--setting-sources", "project", "--strict-mcp-config");
+    if (opts.mcpConfig !== undefined)
+        args.push("--mcp-config", opts.mcpConfig);
+    args.push("--disable-slash-commands", "--exclude-dynamic-system-prompt-sections");
+    if (shouldAppendAgents(opts.cwd))
+        args.push("--append-system-prompt-file", "AGENTS.md");
+    if (opts.maxBudgetUsd !== undefined && opts.maxBudgetUsd > 0) {
+        args.push("--max-budget-usd", String(opts.maxBudgetUsd));
+    }
+    for (const arg of opts.args ?? []) {
+        // Match the flag itself even when it carries its value as `--flag=value`.
+        const flag = arg.split("=", 1)[0];
+        if (HARNESS_CLAUDE_FLAGS.has(flag)) {
+            throw new Error(`claudeArgs: passthrough arg ${JSON.stringify(arg)} repeats a harness flag`);
+        }
+        args.push(arg);
+    }
+    return { args, stdin: opts.prompt };
+}