tumwater 0.1.3 → 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.3**: working harness. The director and 14 of the 15 roles are enabled by default; `telemetry`,
-which files harness bugs from tumwater's own event log, is opt-in (`roles.telemetry.enabled`).
+**v0.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).
@@ -41,40 +45,71 @@ Open work: [PLANS.md](PLANS.md) (planned), [BUGS.md](BUGS.md) (open bugs),
 cd your-project                 # a new or existing directory
 tumwater init "Build a tiny markdown-to-html converter CLI in Python."
                                 # --template, --file, and --adopt pick a starting point (see docs/cli.md)
-tumwater run                    # start the loops (Ctrl+C to stop)
-tumwater run --gui              # ... and serve the browser dashboard at http://127.0.0.1:7180
-tumwater run --for 2h           # run for a bounded window, then drain, summarize, and exit
-tumwater run --once             # one round of ticks for cron/CI; exits 3 if a loop's tick failed
+tumwater start                  # start the team (Ctrl+C to stop)
+tumwater start --gui            # ... and serve the browser dashboard at http://127.0.0.1:7180
+tumwater start --tui            # ... and attach the terminal TUI in the same window
+tumwater start --for 2h         # run for a bounded window, then finish current work, summarize, and exit
+tumwater start --once           # one round of runs for cron/CI; exits 3 if a run failed
 ```
 
 A fresh or empty project is seeded with `"bootstrap": {"untilPlansDone": 5}`, which holds the
-maintenance loops until 5 plans are done; remove it from `tumwater.json` to end that early.
+maintenance roles until 5 plans are done; remove it from `tumwater.json` to end that early.
 
-From another terminal, `tumwater tui` or the browser dashboard watches the fleet, `tumwater status`
-and `tumwater logs -f` check it, `tumwater brief --file <path>` replaces the initial prompt,
-`tumwater prompt "<text>"` queues a request for the director, `tumwater plan` and `tumwater bug`
-file backlog entries, and `tumwater pause`, `resume`, `wake`, and `stop` control the loops.
-`tumwater doctor` audits the fleet and `tumwater report` shows usage and cost. `gui
+From another terminal, `tumwater tui` or the browser dashboard watches the team, `tumwater status`
+and `tumwater logs -f` check it, `tumwater brief --file <path>` replaces the brief,
+`tumwater prompt "<text>"` sends a message to the director's inbox, `tumwater plan` and
+`tumwater bug` file backlog entries, `tumwater revert <sha>` undoes one merged change on main,
+and `tumwater pause`, `resume`, `wake`, and `stop` control the roles. `tumwater doctor` audits the team and `tumwater report` shows usage and cost. `gui
 --all-interfaces` exposes the dashboard, and with it the director prompt, to your whole network,
 so pair it with `--token <secret>`.
 
+`tumwater prompt --attach <image>` gives a role an image to read at its next run. When a role's
+model cannot read images, the command refuses the attachment up front (naming the fix) unless
+the role reroutes a blind read to a vision model, in which case it says where the message will
+run; `tumwater doctor` probes each claimed image-input model once (cached 7 days, `--reprobe` to
+force) and the dashboards and `tumwater role <id>` say which roles read images and where a blind
+run reroutes.
+
 Every command, flag, and TUI key is in [docs/cli.md](docs/cli.md); `tumwater help` prints the
-same list, and `tumwater completion bash|zsh` prints shell completion. Settings live in
-`tumwater.json` and edits apply live while the fleet runs; see [docs/config.md](docs/config.md).
+same list, and `tumwater completion bash|zsh|fish` prints shell completion. Settings live in
+`tumwater.json` and edits apply live while the team runs; see [docs/config.md](docs/config.md).
 
 **Backends:** any OpenAI-compatible model pi can reach works, chosen by `model` in `tumwater.json`
-with a `fallback` that a failing role switches to. `agent: "claude"` runs bare selectors on Claude
-Code instead. Requirements, the fallback and usage-window behavior, and how subscription runs are
-billed (as notional spend, outside the daily cap) are in [docs/backends.md](docs/backends.md).
+with a `fallback` that a failing role switches to. `backend: "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 loops, review gate, scheduling, and self-redeploy work, see
+For how the roles, review gate, scheduling, and updates work, see
 [docs/how-it-works.md](docs/how-it-works.md). For a measured comparison of tumwater's own
 code against human-written open source, see [docs/code-metrics.md](docs/code-metrics.md).
 
-## Appendix: initial prompt
+## Appendix: the brief
 
-The brief this repository was started from, kept for history. The harness still reads it from
-between the markers below on every tick.
+The brief this repository was started from, kept for history. tumwater still reads the brief from
+between the markers below on every run.
 
 <!-- tumwater:prompt:start -->
 Idea: agentic harness

package/dist/build-info.json

@@ -1,5 +1,5 @@
 {
-  "sha": "e44157e8609091b848898ab0e370e0995d931404",
-  "builtAt": 1791912860508,
+  "sha": "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 };
 }

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

@@ -16,32 +16,47 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
 import { randomUUID } from "node:crypto";
 import { resolvedAgentConfig } from "../../config/config-views.js";
 import { MODEL_TIERS } from "../../config/config-schema.js";
 import { routeModel } from "../../config/model-selector.js";
-import { agentBaseEnv } from "../../process/run-marker.js";
+import { agentBaseEnv, withNotesPath } from "../../process/run-marker.js";
 import { resolveBackendBin } from "../../pi/pi-bin.js";
+import { expandHomeTilde } from "../../files/files.js";
 import { claudeArgs } from "./claude-args.js";
 import { claudeEnv, claudeThirdPartyProvider } from "./claude-env.js";
 import { claudeTranslator } from "./claude-stream.js";
 import { resumableSession } from "../session-ledger.js";
-/** claude's per-cwd project directory name under `~/.claude/projects/`: every character that
- * is not a letter or digit becomes `-`. Exported with `claudeTranscriptPath` so the PATH fake
- * and the tests create and look for exactly the file the resume check reads. */
+/** claude's per-cwd project directory name under the claude config dir's `projects/`:
+ * every character that is not a letter or digit becomes `-`. Exported with
+ * `claudeTranscriptPath` so the PATH fake and the tests create and look for exactly the file
+ * the resume check reads. */
 export function claudeProjectSlug(cwd) {
     return cwd.replace(/[^A-Za-z0-9]/g, "-");
 }
+/** claude's config directory: `$CLAUDE_CONFIG_DIR` when non-empty (a leading `~` expands
+ * against the home dir), else `~/.claude`. A configured team `configDir` (the expanded
+ * `backends.claude.configDir`) wins over any inherited env var — the team's own directory is
+ * never overridden by the operator's shell. This mirrors claude's own lookup and pi's
+ * `piAgentDir`; exported so doctor reads the same dir the adapter writes transcripts into. */
+export function claudeConfigDir(env = process.env, homeDir = os.homedir(), configured) {
+    if (configured)
+        return expandHomeTilde(configured, homeDir);
+    const dir = env.CLAUDE_CONFIG_DIR;
+    if (!dir)
+        return path.join(homeDir, ".claude");
+    return expandHomeTilde(dir, homeDir);
+}
 /** The transcript file claude writes for a session started in `cwd`: its resume check must find
  * a real file before passing `--resume`. claude's own layout is
- * `~/.claude/projects/<slug>/<sessionId>.jsonl`; exported so the fake and the resume logic
- * cannot drift. */
-export function claudeTranscriptPath(cwd, id) {
-    return path.join(os.homedir(), ".claude", "projects", claudeProjectSlug(cwd), `${id}.jsonl`);
+ * `<config>/projects/<slug>/<sessionId>.jsonl`; exported so the fake and the resume logic
+ * cannot drift. `configDir` is the configured team dir, threaded through so the resume check
+ * looks where the run's own env will write. */
+export function claudeTranscriptPath(cwd, id, env = process.env, homeDir = os.homedir(), configDir) {
+    return path.join(claudeConfigDir(env, homeDir, configDir), "projects", claudeProjectSlug(cwd), `${id}.jsonl`);
 }
 /** The CLI version every gated claude model needs (plans/agent-backends.md finding 9): on
- * 2.1.216 Opus 5.5 is refused outright and Haiku 5.5 is mispriced about 250×, and fleet runs
+ * 2.1.216 Opus 5.5 is refused outright and Haiku 5.5 is mispriced about 250×, and team runs
  * set DISABLE_AUTOUPDATER so they never update themselves. The gated models are the three
  * tier defaults, derived from AGENT_DEFAULT_MODELS through the same routing the config uses
  * rather than listed again, so this table cannot drift from the models a seam resolves. */
@@ -65,37 +80,27 @@ function classifyClaudeExit(info) {
     }
     return {};
 }
-/** The inline `--mcp-config` JSON that runs the bundled role-notes server (part 5/7): the
- * same dist module pi's extension resolves to, spawned by the same node running this harness
- * so it needs no PATH lookup. */
-function roleNotesMcpConfig() {
-    const server = fileURLToPath(new URL("../mcp/role-notes-server.js", import.meta.url));
-    return JSON.stringify({ mcpServers: { tumwater: { command: process.execPath, args: [server] } } });
-}
 /** The ledger record this run may resume, or null: the newest record of `opts.kind` for
  * claude, at `opts.cwd` when one is given, whose transcript file exists. Shared by
  * `resolveClaudeSession` and the backend's `resumable` hook, so the resume guard and the
  * invocation can never drift on what counts as resumable. */
-function claudeResumableRecord(dir, opts) {
+function claudeResumableRecord(dir, opts, configDir) {
     const record = resumableSession(dir, opts);
     if (record === null)
         return null;
     if (opts.cwd !== undefined && record.cwd !== opts.cwd)
         return null;
-    if (!fs.existsSync(claudeTranscriptPath(record.cwd, record.id)))
+    if (!fs.existsSync(claudeTranscriptPath(record.cwd, record.id, process.env, os.homedir(), configDir)))
         return null;
     return record;
 }
 /** The session id this run uses: for a continue, the ledger's newest record of this kind when
  * it is claude's, this cwd's, and its transcript file exists; otherwise a fresh UUID. Returns
- * the id and the `--resume` id when resuming. */
-function resolveClaudeSession(run) {
+ * the id and the `--resume` id when resuming. `configDir` is the configured team dir, so the
+ * resume check looks where the run's own env will write transcripts. */
+function resolveClaudeSession(run, configDir) {
     if (run.continueSession) {
-        const record = claudeResumableRecord(run.sessionDir, {
-            kind: run.kind,
-            agent: "claude",
-            cwd: run.cwd,
-        });
+        const record = claudeResumableRecord(run.sessionDir, { kind: run.kind, agent: "claude", cwd: run.cwd }, configDir);
         if (record !== null)
             return { sessionId: record.id, resumeSessionId: record.id };
     }
@@ -117,35 +122,35 @@ export const claudeBackend = {
         if (run.config.model === undefined) {
             throw new Error("claude backend: no model resolved for this run");
         }
-        const { sessionId, resumeSessionId } = resolveClaudeSession(run);
+        // The configured team config dir (plans/notes-command.md "Keeping funes out of team runs"):
+        // the run's env, its resume lookup, and the account seed all follow it; unset, nothing changes.
+        const claudeCfg = resolvedAgentConfig(run.config, "claude");
+        const configDir = claudeCfg.configDir;
+        const expandedConfigDir = configDir !== undefined ? claudeConfigDir(process.env, os.homedir(), configDir) : undefined;
+        const { sessionId, resumeSessionId } = resolveClaudeSession(run, configDir);
         const { args, stdin } = claudeArgs({
             cwd: run.cwd,
             model: run.config.model,
             thinking: run.config.thinking,
             ...(resumeSessionId !== undefined ? { resumeSessionId } : { sessionId }),
-            // The operator's `agents.claude.args` passthrough, appended after the harness flags (the
+            // The operator's `backends.claude.args` passthrough, appended after the harness flags (the
             // builder rejects any entry that repeats a harness-managed flag). resolvedAgentConfig
             // owns the view so a caller cannot mutate the loaded config through the returned array.
-            args: resolvedAgentConfig(run.config, "claude").args,
+            args: claudeCfg.args,
             prompt: run.prompt,
             // The caller computes the remaining daily budget for an API-billed claude run and the
             // adapter forwards it; a subscription run or the director passes none (part 7a/7).
             ...(run.maxBudgetUsd !== undefined ? { maxBudgetUsd: run.maxBudgetUsd } : {}),
-            // claude does not load the bundled pi extensions, so a run carrying a notebook gets the
-            // role_notes MCP server instead. Passed on EVERY claude invocation that carries a
-            // notebook — fresh or resumed, a transient retry, a SUMMARY follow-up — because claude
-            // keeps no flags across --resume, so a resume without this would lose the tool.
-            ...(run.notesPath !== undefined ? { mcpConfig: roleNotesMcpConfig() } : {}),
         });
         // agentBaseEnv applies the run marker and the macOS preload (shared with the pi adapter);
         // claudeEnv layers the backend's own scrub-and-set on top. The notebook path rides beside
-        // the marker the same way pi's adapter carries it (pi-backend.ts withNotesPath), so the
-        // spawned MCP server — which inherits this environment — reads the same notes file.
-        const base = run.notesPath === undefined
-            ? agentBaseEnv(run.runMarker)
-            : { ...agentBaseEnv(run.runMarker), TUMWATER_NOTES_PATH: run.notesPath };
+        // the marker the same way pi's adapter carries it (withNotesPath); from part 2/4 the run
+        // saves its note through the `tumwater-notes` command on PATH, so no MCP server reaches the
+        // run and `--strict-mcp-config` (always in claude-args.ts) keeps it that way.
+        const base = withNotesPath(agentBaseEnv(run.runMarker, undefined, run.binDir), run.notesPath);
         const env = claudeEnv(base, {
             quietTimeoutSeconds: run.config.quietTimeoutSeconds,
+            ...(expandedConfigDir !== undefined ? { configDir: expandedConfigDir } : {}),
         });
         return { args, stdin, env, sessionId };
     },
@@ -155,8 +160,13 @@ export const claudeBackend = {
         // seed the account file, so both must classify it the same way.
         return claudeTranslator({ thirdPartyProvider: claudeThirdPartyProvider(process.env) });
     },
-    resumable(dir, opts) {
-        return claudeResumableRecord(dir, opts) !== null;
+    resumable(dir, opts, configDir) {
+        return claudeResumableRecord(dir, opts, configDir) !== null;
+    },
+    // Every Claude model reads images (Claude Code's Read tool returns them as image blocks), so
+    // a claude seam is always capable — the doctor probes nothing and never works around it.
+    imageInput() {
+        return true;
     },
     classifyExit: classifyClaudeExit,
 };