tumwater 0.1.1 → 0.1.3

package/README.md

@@ -21,10 +21,14 @@ 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.1**: working harness. The director and 14 of the 15 roles are enabled by default; `telemetry`,
+**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`).
 
 Open work: [PLANS.md](PLANS.md) (planned), [BUGS.md](BUGS.md) (open bugs),
@@ -34,79 +38,34 @@ 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
+                                # --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
 ```
 
-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>]`, 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 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, 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)) |
-| 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"` rewrites the Nth entry in place, keeping its position and wait time (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; `tumwater bug "<symptom>"` files a bug into BUGS.md's Open section and wakes the bugfix loop, `tumwater plan "<title>" [body...]` 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`) |
-| 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; `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), `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) |
-| Audit | `tumwater doctor` (pre-flight; `--json` prints the report as JSON, for scripts), `tumwater report` (usage and cost, with landed commits by role and the work/maintenance split; 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 (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 — the command gets `TUMWATER_EVENT_TYPE`,
-`TUMWATER_EVENT_LOOP`, and `TUMWATER_EVENT_MESSAGE` in its environment).
-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; 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.
-
-**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. See [docs/backends.md](docs/backends.md) for requirements and a
-worked setup.
+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.
+
+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
+--all-interfaces` exposes the dashboard, and with it the director prompt, to your whole network,
+so pair it with `--token <secret>`.
+
+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).
+
+**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).
 
 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": "dd415e942c5569f2a1c468345a9277febbdaaed0",
-  "builtAt": 1791538389108,
+  "sha": "e44157e8609091b848898ab0e370e0995d931404",
+  "builtAt": 1791912860508,
   "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 };
+}