tumwater 0.1.2 → 0.2.0

package/README.md

@@ -1,14 +1,15 @@
 # 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
+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 +24,16 @@ 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`.
 
 ## Status
 
 <!-- tumwater:status:start -->
-**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`).
+**v0.1.4**: working tumwater. The director and 14 of the 15 roles are enabled by default; `selfcheck`,
+which files tumwater bugs from tumwater's own event log, is opt-in (`roles.selfcheck.enabled`).
 
 Open work: [PLANS.md](PLANS.md) (planned), [BUGS.md](BUGS.md) (open bugs),
 [QUESTIONS.md](QUESTIONS.md) (open questions).
@@ -38,112 +42,74 @@ Open work: [PLANS.md](PLANS.md) (planned), [BUGS.md](BUGS.md) (open bugs),
 ## Usage
 
 ```bash
-cd your-project             # a new or existing directory
+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
-                            # (blank, python-cli, node-cli, static-site); --list-templates
-                            # 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
+                                # --template, --file, and --adopt pick a starting point (see docs/cli.md)
+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
 ```
 
-Then, from another terminal:
-
-| To | Run |
-| --- | --- |
-| 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, `--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
-`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, 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, `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
+A fresh or empty project is seeded with `"bootstrap": {"untilPlansDone": 5}`, which holds the
+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 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|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. `backend: "claude"` runs bare model ids on Claude
+Code instead, and a model id that starts with `opencode/` runs on the OpenCode CLI — its free
+DeepSeek tier needs no login or API key. 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:** a bare model id that starts with `claude-` runs on the claude CLI even
+under the default `backend: "pi"`, so one config can mix a Claude strong tier with pi providers:
+
+```json
+{
+  "model": {
+    "default": "huggingface/deepseek-ai/DeepSeek-V4.1-Flash:deepinfra",
+    "strong": "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). A model id that starts
+with `opencode/` routes to the OpenCode CLI under any backend, so its free tier can sit beside pi
+and claude in one config. Prefix `anthropic/` (`anthropic/claude-…`)
+to keep a Claude model on pi instead (billed per token). See [plans/agent-backends.md §3](plans/agent-backends.md).
+
+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": "90a6c2c27eb822740efee37d84a0518b76b4d7bb",
-  "builtAt": 1791821277046,
+  "sha": "cff6961c92b598be9b21cc49a6faa66a16f11a8c",
+  "builtAt": 1792409331797,
   "root": "/home/runner/work/tumwater/tumwater"
 }

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

@@ -0,0 +1,24 @@
+// vocabulary: plain
+/** Appending a backend's configured passthrough args to an already-built argv. Shared by the
+ * claude and opencode argv builders (claude-args.ts and opencode-args.ts), whose passthrough
+ * handling is otherwise identical, so the two 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 both 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` or `opencodeArgs`); `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

@@ -26,9 +26,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) {
+export function agentSessionResumable(dir, opts, configDir) {
     const backend = agentBackend(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,60 @@
+// vocabulary: plain
+/**
+ * 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
+ * `AGENT_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_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 and opencode 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 and opencode are false; an unknown id reads as pi. */
+export function streamsToolOutput(agent) {
+    // Only claude and opencode stream no tool output; every other id (including an unregistered
+    // one) reads as pi, which does stream.
+    return agent !== "claude" && agent !== "opencode";
+}
+/** 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 or opencode job reads no pi pricing and needs no
+ * definitions file. */
+export function usesPiModels(agent) {
+    // Only claude and opencode read no pi models.json; every other id (including an unregistered
+    // one) reads as pi, which does.
+    return agent !== "claude" && agent !== "opencode";
+}
+/** 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 claude's HARNESS_CLAUDE_FLAGS
+ * and pi's 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(agent, flag) {
+    switch (agent) {
+        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;
+        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 —
+ * and `opencode/<model>` for opencode, whose ids all read under the opencode namespace. The
+ * one home of the label, shared by the doctor report and the image-input surface strings so
+ * they cannot drift. */
+export function modelLabel(agent, provider, model) {
+    if (agent === "claude")
+        return model ?? "claude backend";
+    if (agent === "opencode")
+        return `opencode/${model ?? "?"}`;
+    return `${provider ?? "?"}/${model ?? "?"}`;
+}

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

@@ -9,13 +9,15 @@
  * 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 os from "node:os";
+import { resolvedAgentConfig } from "../../config/config-views.js";
 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 { 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
+ * `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 claude and overage are budget/fallback matters, not a
@@ -25,6 +27,39 @@ export function subscriptionWindowRejected(run) {
         run.billing === "subscription" &&
         (run.rateWindows ?? []).some((w) => w.status === "rejected" && w.isUsingOverage !== true));
 }
+/** The subscription account's used-up usage window, or null: a window reading `rejected` with no
+ * overage, or (with `includeOverage`, the default) a window whose current reading shows
+ * `isUsingOverage`, and a `resetsAt` still ahead of `now`; among several, the one that resets
+ * last. With a `reserve` (config `claudeWindowReserve`), 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
+ * (claudeWindowObservation) passes `includeOverage: false`, because overage never holds a seam.
+ * Only subscription billing produces one; a missing account reads null. */
+export function claudeWindowUsedUp(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 };
@@ -40,6 +75,14 @@ export function claudeWindowLabel(type) {
     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 and the doctor's hold reason so the two render a window's fill
+ * identically (the browser dashboard's own window line is embedded client-side and keeps its
+ * inline copy). */
+export function claudeUtilizationPct(utilization) {
+    return Math.round(utilization * 100);
+}
 /** 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. */
@@ -67,7 +110,7 @@ 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 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;
@@ -88,7 +131,7 @@ export function readClaudeAccount(root, now = Date.now()) {
 }
 /** 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`. */
+ * status to `reset` and drops the overage flags. */
 function readWindow(value, fileObservedAt, now) {
     if (!isJsonObject(value) || typeof value.status !== "string")
         return undefined;
@@ -99,12 +142,14 @@ function readWindow(value, fileObservedAt, now) {
     // 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 reset = resets && resetsAt <= now;
     const window = {
-        status: resets && resetsAt <= now ? "reset" : value.status,
+        status: reset ? "reset" : value.status,
         ...(resets ? { resetsAt } : {}),
         ...(utilization !== undefined ? { utilization } : {}),
-        ...(typeof value.overageStatus === "string" ? { overageStatus: value.overageStatus } : {}),
-        ...(value.isUsingOverage === true ? { isUsingOverage: true } : {}),
+        // 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;
@@ -225,7 +270,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 = resolvedAgentConfig(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,

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

@@ -1,8 +1,9 @@
+// vocabulary: plain
 /** 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.
+ * `--session-id` or `--resume` to pass); this module turns those inputs into the invocation's
+ * argv.
  *
  * The environment is built separately (claude-env.ts) so each concern has one module.
  *
@@ -15,12 +16,13 @@
  * fallback the design holds in reserve is not needed. */
 import fs from "node:fs";
 import path from "node:path";
+import { appendPassthroughArgs } from "../agent-args.js";
 /** 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
+ * set for `backends.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",
@@ -68,14 +70,18 @@ function shouldAppendAgents(cwd) {
  * 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");
+        // Name which side fired so the invariant that would otherwise silently change the run's
+        // session is diagnosable at a glance: a conflicting pair (both set) differs from a missing
+        // choice (neither) and the two bugs have different fixes.
+        const state = opts.sessionId === undefined ? "neither is set" : "both are set";
+        throw new Error(`claudeArgs: pass exactly one of sessionId or resumeSessionId (${state})`);
     }
     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)}`);
+            throw new Error(`claudeArgs: unknown thinking level ${JSON.stringify(opts.thinking)} (known: ${Object.keys(EFFORT_BY_THINKING).join(", ")})`);
         }
         args.push("--effort", EFFORT_BY_THINKING[opts.thinking]);
     }
@@ -84,21 +90,12 @@ export function claudeArgs(opts) {
     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);
-    }
+    appendPassthroughArgs(args, opts.args, HARNESS_CLAUDE_FLAGS, "claudeArgs");
     return { args, stdin: opts.prompt };
 }