tumwater 0.1.2 → 0.2.0

package/dist/src/config/config-live.js

@@ -1,9 +1,12 @@
 import { changedConfigKeys, loadConfigCached } from "./config.js";
 import { loopIds } from "../roles/loop-ids.js";
-import { configForRole, fleetModelLabel, modelSelectorField } from "./config-views.js";
-import { bestEffortEventLogger } from "../events/events.js";
+import { configForRole, teamModelLabel, modelSelectorField } from "./config-views.js";
+import { seamsInUse } from "./config-fallbacks.js";
+import { bestEffortEventLogger, TUMWATER_SOURCE } from "../events/events.js";
 import { LoopRunner } from "../loop/loop.js";
 import { configPath } from "../paths.js";
+import { seedClaudeAccount } from "../agent/claude/claude-account.js";
+import { agentMissingMessage, findAgentBinary, resolveAgentBin } from "../pi/pi-bin.js";
 /** A live config reloader over the given wiring; poll it once per scheduler cycle (see
  * LiveConfigReload for the contract). */
 export function newLiveConfigReload(deps) {
@@ -21,9 +24,17 @@ export function newLiveConfigReload(deps) {
     // The cap last applied to the semaphore (live-resized on each reload), so a change logs
     // exactly one event per distinct value — not once per poll.
     let lastMaxConcurrent = Math.max(1, deps.config.maxConcurrent);
+    // The per-provider caps last applied to the semaphore (live-resized on each reload), so a
+    // change logs exactly one event per distinct value — not once per poll. Seeded from the
+    // startup config, so the first poll of an unchanged file emits nothing.
+    let lastKeyCaps = deps.config.maxConcurrentPerProvider ?? {};
+    // Roots this process has already attempted a live-edit claude-account seed for (see the
+    // reload block below), so repeated polls of a config that keeps a claude seam cannot respawn
+    // `claude auth status` on every cycle.
+    const liveClaudeSeedAttempted = new Set();
     // Best-effort event logging: poll() runs inside the orchestrator's poll loop
     // (src/orchestrator/orchestrator.ts), which has no catch, so an unwritable feed (ENOSPC,
-    // EACCES, the path replaced by a directory) would otherwise end the fleet — and, worse, skip
+    // EACCES, the path replaced by a directory) would otherwise end the team — and, worse, skip
     // the config application that follows the emission. bestEffortEventLogger (events.ts) holds
     // the shared "logging must not throw" policy.
     const { emit, warn } = bestEffortEventLogger(deps.root);
@@ -31,8 +42,8 @@ export function newLiveConfigReload(deps) {
         poll() {
             const reloaded = loadConfigCached(deps.root);
             // A missing file keeps the last-known-good config too, and never reloads as defaults: the
-            // fleet was started on a real file (startup refuses to run without one), so its vanishing
-            // mid-run is an incident — a landing's fast-forward deleted it on 2026-09-22 and the fleet
+            // team was started on a real file (startup refuses to run without one), so its vanishing
+            // mid-run is an incident — a merge's fast-forward deleted it on 2026-09-22 and the team
             // silently ran 8.6 h on defaults (BUGS.md 2026-09-23). One warning per vanish, not per
             // poll; its return logs one line, then the normal reload below diffs it against the
             // retained config — so config_changed names only what the returned file really changed.
@@ -54,11 +65,11 @@ export function newLiveConfigReload(deps) {
                 // changed (maxConcurrent and sessionRetentionDays have their own events elsewhere).
                 const changedKeys = changedConfigKeys(prevLive, reloaded.config);
                 if (changedKeys.length > 0) {
-                    emit({ loop: "harness", type: "config_changed", keys: changedKeys });
+                    emit({ source: TUMWATER_SOURCE, type: "config_changed", keys: changedKeys });
                     // A real model-wiring change gets its own event naming the new selector(s), which the
                     // key list cannot show; a non-model edit (instructions, an interval) emits nothing.
-                    const fromModel = fleetModelLabel(prevLive);
-                    const toModel = fleetModelLabel(reloaded.config);
+                    const fromModel = teamModelLabel(prevLive);
+                    const toModel = teamModelLabel(reloaded.config);
                     const roleDiffs = changedKeys
                         .filter((key) => key.startsWith("roles."))
                         .map((key) => {
@@ -70,13 +81,34 @@ export function newLiveConfigReload(deps) {
                         .filter((d) => d.from !== d.to);
                     if (fromModel !== toModel || roleDiffs.length > 0)
                         emit({
-                            loop: "harness",
+                            source: TUMWATER_SOURCE,
                             type: "model_changed",
                             from: fromModel,
                             to: toModel,
                             ...(roleDiffs.length > 0 ? { roles: roleDiffs } : {}),
                         });
                 }
+                // A live edit that routes a seam to a backend the previous config did not use: the
+                // team keeps running, but that backend must be verified and (for claude) its account
+                // seeded, exactly as startup would — so a claude reviewer added to a pi team does not
+                // start uncheckable. A missing binary is a warning event, never a crash; a present one
+                // logs its verdict as a backend_binary event. The seed is attempted once per root.
+                const prevAgents = new Set(seamsInUse(prevLive).map((s) => s.agent ?? "pi"));
+                for (const agent of new Set(seamsInUse(reloaded.config).map((s) => s.agent ?? "pi"))) {
+                    if (prevAgents.has(agent))
+                        continue;
+                    const resolved = resolveAgentBin(reloaded.config, agent);
+                    if (findAgentBinary(resolved)) {
+                        emit({ source: TUMWATER_SOURCE, type: "backend_binary", agent, found: true });
+                    }
+                    else {
+                        warn(`newly routed ${agent} backend: ${agentMissingMessage(resolved, agent)}`);
+                    }
+                    if (agent === "claude" && !liveClaudeSeedAttempted.has(deps.root)) {
+                        liveClaudeSeedAttempted.add(deps.root);
+                        seedClaudeAccount(deps.root, reloaded.config);
+                    }
+                }
                 prevLive = reloaded.config;
                 for (const r of deps.runners)
                     r.config = reloaded.config;
@@ -86,9 +118,29 @@ export function newLiveConfigReload(deps) {
                 const newMaxConcurrent = Math.max(1, reloaded.config.maxConcurrent);
                 if (newMaxConcurrent !== lastMaxConcurrent) {
                     deps.semaphore.setCapacity(newMaxConcurrent);
-                    emit({ loop: "harness", type: "max_concurrent_changed", from: lastMaxConcurrent, to: newMaxConcurrent });
+                    emit({ source: TUMWATER_SOURCE, type: "max_concurrent_changed", from: lastMaxConcurrent, to: newMaxConcurrent });
                     lastMaxConcurrent = newMaxConcurrent;
                 }
+                // Live-resize the per-provider caps (plans/provider-concurrency.md §7): an edit
+                // re-applies the whole map to the pool, and each changed provider fires its own
+                // `provider_concurrency_changed` event. setKeyCaps never preempts — shrinking only
+                // withholds future grants on that key until releases drain it under the new cap.
+                const nextKeyCaps = reloaded.config.maxConcurrentPerProvider ?? {};
+                deps.semaphore.setKeyCaps(nextKeyCaps);
+                for (const provider of new Set([...Object.keys(lastKeyCaps), ...Object.keys(nextKeyCaps)])) {
+                    const from = lastKeyCaps[provider];
+                    const to = nextKeyCaps[provider];
+                    if (from !== to) {
+                        emit({
+                            source: TUMWATER_SOURCE,
+                            type: "provider_concurrency_changed",
+                            provider,
+                            from: from ?? 0,
+                            to: to ?? 0,
+                        });
+                    }
+                }
+                lastKeyCaps = nextKeyCaps;
                 const nowEnabled = loopIds(reloaded.config);
                 // Enabling a role — or raising `roles.<id>.instances` — mid-run starts it: create the
                 // runner for each newly present loop id (its persisted state survives). A lowered
@@ -103,10 +155,10 @@ export function newLiveConfigReload(deps) {
                 }
                 for (const role of prevEnabled)
                     if (!nowEnabled.includes(role))
-                        warn(`role ${role} disabled — stopping ticks`);
+                        warn(`role ${role} disabled — no new runs`);
                 for (const role of nowEnabled)
                     if (!prevEnabled.has(role))
-                        warn(`role ${role} enabled — starting ticks`);
+                        warn(`role ${role} enabled — starting runs`);
                 prevEnabled = new Set(nowEnabled);
                 lastConfigError = null;
             }

package/dist/src/config/config-schema.js

@@ -1,3 +1,4 @@
+// vocabulary: plain
 /** The tumwater.json config schema shape: the types `config-validation.ts` validates a
  * loaded config into and every config read site consumes, plus the key allow-lists and
  * value shapes (`TOP_LEVEL_KEYS` and friends) that say what a valid file may hold at each
@@ -5,7 +6,7 @@
  * its default (config.ts), and its allow-list entry sit beside each other. Split out of the former
  * types.ts grab-bag — the runtime types a tick produces now live beside their consumers
  * (TickResult and TickOutcome in tick-outcome.ts, LoopState in loop-state.ts, HarnessEvent
- * in events.ts, LandingEntry in landing-queue.ts, and the pi-run types in run-agent.ts and
+ * in events.ts, MergeEntry in merge-queue.ts, and the pi-run types in run-agent.ts and
  * pi-run-result.ts) — so the schema the file on disk is validated against and the runtime
  * state the harness runs with
  * are two layers, changed for different reasons by different readers: a tumwater.json knob
@@ -17,11 +18,13 @@ import { objectOrEmpty } from "../files/json-object.js";
  * `model` map inherits `default`'s model; `fallback` map values may also be `"pause"`
  * (each tier's own entry is consulted when that tier runs at the cap; part 5a/8). */
 export const MODEL_TIERS = ["small", "default", "strong"];
+/** The keys an object fallback step may carry (validation's checkKnownKeys list). */
+export const FALLBACK_STEP_KEYS = ["model", "maxDailyCostUsd"];
 /** The agent backends an `agent` value may name (plans/agent-backends.md "Config"). The
  * registry (src/agent/agent-backend.ts) is the runtime source, but the schema reserves these
  * ids so validation rejects a typo'd backend at load time instead of falling back to pi. The
  * agent id doubles as the selector provider namespace: `claude/<id>` always routes to claude. */
-export const AGENT_IDS = ["pi", "claude"];
+export const AGENT_IDS = ["pi", "claude", "opencode"];
 /** The tier-map key list validation feeds checkKnownKeys: a `model` or `fallback` map whose
  * keys are not exactly these tiers is a typo that would silently never resolve. */
 export const TIER_MAP_KEYS = MODEL_TIERS;
@@ -41,32 +44,34 @@ export function modelTierMap(model) {
 /** Every key tumwater.json may hold, by level. Anything else is a typo that would be
  * silently ignored at runtime — the intended setting falls back to its default with no
  * warning — so validation (config-validation.ts's checkKnownKeys, fed from these tables)
- * fails fast instead (e.g. `tickTimeoutSecondss` does nothing). Kept in sync with the
+ * fails fast instead (e.g. `runTimeoutSecondss` does nothing). Kept in sync with the
  * interfaces above in this same file: adding a key edits the interface and its level's
  * list side by side. */
 export const TOP_LEVEL_KEYS = [
     "provider",
     "model",
     "thinking",
-    "agent",
+    "backend",
     "baseBranch",
     "agentBin",
-    "agents",
+    "backends",
     "check",
     "piArgs",
     "maxConcurrent",
-    "landBatchMax",
+    "maxConcurrentPerProvider",
+    "claudeWindowReserve",
+    "mergeBatchMax",
     "maxConcurrentChecks",
     "worktreeSlots",
-    "minTickIntervalSeconds",
-    "tickTimeoutSeconds",
+    "minRunIntervalSeconds",
+    "runTimeoutSeconds",
     "quietTimeoutSeconds",
     "toolCallStallSeconds",
     "logMaxBytes",
     "sessionRetentionDays",
     "maxDailyCostUsd",
     "maxDailyCostUsdPerRole",
-    "maintenancePerWorkLanding",
+    "maintenancePerWorkMerge",
     "quietHours",
     "quietHoursPerRole",
     "diskHoldGB",
@@ -81,13 +86,17 @@ export const TOP_LEVEL_KEYS = [
     "autoRestart",
     "bootstrap",
     "review",
-    "customLoops",
+    "customRoles",
     "roles",
 ];
 export const BACKOFF_KEYS = ["initialSeconds", "factor", "maxSeconds"];
-/** The keys an `agents.<id>` entry may hold; validation feeds checkKnownKeys so a typo'd
- * field (`agents.claude.binary`) is a load error rather than a silently inert entry. */
+/** The keys an `backends.<id>` entry may hold; validation feeds checkKnownKeys so a typo'd
+ * field (`backends.claude.binary`) is a load error rather than a silently inert entry.
+ * `configDir` is claude-only (CLAUDE_AGENT_KEYS), so it is not silently inert on pi/opencode. */
 export const AGENT_KEYS = ["bin", "args"];
+/** The keys a claude `backends.claude` entry may hold — the shared agent keys plus `configDir`,
+ * the one per-backend field only the claude adapter reads. */
+export const CLAUDE_AGENT_KEYS = [...AGENT_KEYS, "configDir"];
 /** The keys tumwater.json's `bootstrap` section may hold. */
 export const BOOTSTRAP_KEYS = ["untilPlansDone"];
 export const ROLE_ENTRY_KEYS = [
@@ -96,7 +105,7 @@ export const ROLE_ENTRY_KEYS = [
     "provider",
     "model",
     "thinking",
-    "minTickIntervalSeconds",
+    "minRunIntervalSeconds",
     "instances",
 ];
 export const REVIEW_KEYS = ["enabled", "exemptPaths", "provider", "model", "thinking", "timeoutSeconds"];
@@ -110,7 +119,7 @@ export const CHECK_KEYS = ["command", "gateCommand", "cwd", "timeoutSeconds"];
 export const MODEL_TRIPLE_KEYS = ["provider", "model", "thinking"];
 /** pi's accepted `--thinking` levels (pi's own `--help`). pi WARNS and falls back to its own
  * default on any other value rather than failing, so a misspelled level would silently run the
- * fleet at the wrong reasoning depth — the same silent-ignore class validation exists to
+ * team at the wrong reasoning depth — the same silent-ignore class validation exists to
  * catch. Kept in sync with pi's CLI (dist/cli/args.js VALID_THINKING_LEVELS). */
 export const THINKING_LEVELS = new Set(["off", "minimal", "low", "medium", "high", "xhigh", "max"]);
 /** pi flags the harness passes itself (src/pi/pi-args.ts's piArgs: `--print --mode json
@@ -121,17 +130,20 @@ export const THINKING_LEVELS = new Set(["off", "minimal", "low", "medium", "high
  * `--continue` resumes a session the harness did not choose. Each flag maps to why it is
  * refused; the model triple points at the setting that owns it. */
 export const HARNESS_PI_FLAGS = new Map([
-    ["--print", "the harness already runs pi non-interactively"],
-    ["-p", "the harness already runs pi non-interactively"],
-    ["--mode", "the harness requires pi's json output mode"],
-    ["--session-dir", "the harness owns each role's session directory"],
-    ["--continue", "the harness decides when to resume a session"],
-    ["-c", "the harness decides when to resume a session"],
-    ["-n", "the harness names the session"],
-    ["--name", "the harness names the session"],
+    ["--print", "tumwater already runs pi non-interactively"],
+    ["-p", "tumwater already runs pi non-interactively"],
+    ["--mode", "tumwater requires pi's json output mode"],
+    ["--session-dir", "tumwater owns each role's session directory"],
+    ["--continue", "tumwater decides when to resume a session"],
+    ["-c", "tumwater decides when to resume a session"],
+    ["-n", "tumwater names the session"],
+    ["--name", "tumwater names the session"],
     ["--provider", "set the top-level or per-role `provider` instead"],
     ["--model", "set the top-level or per-role `model` instead"],
     ["--thinking", "set the top-level or per-role `thinking` instead"],
+    // The harness passes --no-extensions itself (pi-args.ts's piArgs) so pi cannot load discovered
+    // extensions; a piArgs entry that re-enabled them would put operator MCP servers back in.
+    ["--no-extensions", "tumwater skips pi's discovered extensions itself"],
 ]);
 export const CUSTOM_LOOP_KEYS = ["name", "task"];
 /** A custom loop's name becomes a worktree dir and a git ref, so it is validated strictly:

package/dist/src/config/config-validation.js

@@ -1,13 +1,19 @@
-import { AGENT_IDS, AGENT_KEYS, BACKOFF_KEYS, BOOTSTRAP_KEYS, CHECK_KEYS, CUSTOM_LOOP_KEYS, CUSTOM_NAME_RE, CUSTOM_TASK_MAX_CHARS, HARNESS_PI_FLAGS, MODEL_TRIPLE_KEYS, REVIEW_KEYS, ROLE_ENTRY_KEYS, TOP_LEVEL_KEYS, ROLE_INSTRUCTIONS_MAX_CHARS, TIER_MAP_KEYS, } from "./config-schema.js";
+// vocabulary: plain
+import { AGENT_IDS, AGENT_KEYS, CLAUDE_AGENT_KEYS, BACKOFF_KEYS, BOOTSTRAP_KEYS, CHECK_KEYS, CUSTOM_LOOP_KEYS, CUSTOM_NAME_RE, CUSTOM_TASK_MAX_CHARS, FALLBACK_STEP_KEYS, HARNESS_PI_FLAGS, MODEL_TRIPLE_KEYS, REVIEW_KEYS, ROLE_ENTRY_KEYS, TOP_LEVEL_KEYS, ROLE_INSTRUCTIONS_MAX_CHARS, TIER_MAP_KEYS, } from "./config-schema.js";
 import { allRoleIds } from "../roles/roles.js";
 import { INSTANCE_ROLES, baseRoleOf } from "../roles/loop-ids.js";
 import { isJsonObject } from "../files/json-object.js";
+import { expandHomeTilde } from "../files/files.js";
+import os from "node:os";
+import path from "node:path";
 import { isNonBlankString, tooLongMessage } from "../text/text.js";
+import { typoSuffix } from "../text/suggest.js";
 import { PREFILL_REASON } from "../text/phrases.js";
 import { parseQuietHours } from "../scheduling/quiet-hours.js";
 import { isAgentId, parseModelSelector } from "./model-selector.js";
-import { HARNESS_CLAUDE_FLAGS } from "../agent/claude/claude-args.js";
-import { AT_LEAST_ONE, checkBooleanField, checkKnownKeys, checkKnownRoleId, checkModelTripleField, checkNumberField, checkObjectSection, checkReservedArgs, checkStringArrayField, checkStringField, NON_NEGATIVE, NON_NEGATIVE_OR_DISABLED, DOLLAR_CAP, POSITIVE, POSITIVE_INTEGER, show, typeName, } from "./config-field-checks.js";
+import { TUMWATER_SOURCE } from "../events/events.js";
+import { reservedPassthroughFlag } from "../agent/backend-traits.js";
+import { AT_LEAST_ONE, checkBooleanField, checkKnownKeys, checkKnownRoleId, checkModelTripleField, checkNumberField, checkObjectSection, checkReservedArgs, checkStringArrayField, checkStringField, NON_NEGATIVE, NON_NEGATIVE_OR_DISABLED, DOLLAR_CAP, MAX_DURATION_SECONDS, POSITIVE, POSITIVE_INTEGER, show, typeName, } from "./config-field-checks.js";
 /** Schema validation for tumwater.json: validateConfig, the gate every load and save passes
  * through (config.ts's load/save, config-write.ts's budget editing and director config
  * requests), judged against the key allow-lists and value shapes that live beside the types
@@ -18,12 +24,6 @@ import { AT_LEAST_ONE, checkBooleanField, checkKnownKeys, checkKnownRoleId, chec
  * unknown-key and known-role guards, the NumberRule table, and the per-field type checkers —
  * lives in config-field-checks.ts; this module is the section-by-section rules plus the
  * cross-field checks, and the one export gate (validateConfig) for them. */
-/** The upper bound every seconds field that feeds a ×1000 duration shares: 2147483 s
- * × 1000 stays inside node's signed-32-bit setTimeout/setInterval range (2^31−1 ms,
- * about 24.8 days). Above it node clamps the delay to 1ms — a one-zero typo like
- * `"tickTimeoutSeconds": 1e300` became Infinity ms, and every pi run died the moment it
- * started (BUGS.md 2026-10-03). */
-const MAX_DURATION_SECONDS = 2147483;
 const DURATION_POSITIVE = {
     ok: (n) => n > 0 && n <= MAX_DURATION_SECONDS,
     what: `a number greater than 0, at most ${MAX_DURATION_SECONDS}`,
@@ -64,7 +64,7 @@ function checkPerRoleMap(r, key, expectation, customNames, problems, checkValue)
     }
 }
 /** Validate tumwater.json values, so a typo fails fast with an actionable message instead
- * of misbehaving at runtime — e.g. a non-numeric tickTimeoutSeconds becomes NaN and kills
+ * of misbehaving at runtime — e.g. a non-numeric runTimeoutSeconds becomes NaN and kills
  * every pi run instantly, a non-numeric logMaxBytes rotates the event log on every write, an
  * unknown role id (a misspelled entry under `roles`) spawns a phantom loop that errors every
  * tick, and an unknown key is silently ignored so the intended setting never takes effect.
@@ -113,9 +113,9 @@ export function validateConfig(raw, label = "tumwater.json", rawFile = false) {
     // The agent backend for bare/no-model selectors (plans/agent-backends.md "Config"): a
     // non-blank id from the schema's reserved set. An unknown id would fall back to pi at run
     // time (src/agent/run-agent.ts), silently running the wrong backend against a named one.
-    checkString(r, "", "agent", false);
-    if (typeof r.agent === "string" && !isAgentId(r.agent))
-        problems.push(`agent must name a backend (${AGENT_IDS.join(", ")}; got ${show(r.agent)})`);
+    checkString(r, "", "backend", false);
+    if (typeof r.backend === "string" && !isAgentId(r.backend))
+        problems.push(`backend must name a backend (${AGENT_IDS.join(", ")}; got ${show(r.backend)})${typoSuffix(r.backend, AGENT_IDS)}`);
     checkStringArray(r, "", "piArgs");
     // A piArgs entry that repeats a harness-managed flag is appended after the harness's own and
     // pi's parser is last-wins, so it silently overrides it (see HARNESS_PI_FLAGS). Name the
@@ -127,25 +127,29 @@ export function validateConfig(raw, label = "tumwater.json", rawFile = false) {
     // that repeats a flag the backend's own harness invocation sets is appended last and wins,
     // so it silently overrides the harness — refused here for the two backends whose reserved
     // sets are known (claude-args.ts HARNESS_CLAUDE_FLAGS, config-schema.ts HARNESS_PI_FLAGS).
-    checkObjectSection(r, "agents", problems, (o) => {
+    checkObjectSection(r, "backends", problems, (o) => {
         for (const [id, entry] of Object.entries(o)) {
-            const prefix = `agents.${id}`;
+            const prefix = `backends.${id}`;
             if (!isJsonObject(entry)) {
                 problems.push(`${prefix} must be an object with optional bin and args (got ${show(entry)})`);
                 continue;
             }
-            checkKnownKeys(entry, AGENT_KEYS, prefix, problems);
+            checkKnownKeys(entry, id === "claude" ? CLAUDE_AGENT_KEYS : AGENT_KEYS, prefix, problems);
             checkString(entry, `${prefix}.`, "bin", false);
             checkStringArray(entry, `${prefix}.`, "args");
+            // claude's per-backend config dir (plans/notes-command.md "Keeping funes out of team runs"):
+            // a leading `~` expands; the value must be an absolute path after expansion, or claude would
+            // resolve a relative CLAUDE_CONFIG_DIR from the tick's cwd and write transcripts somewhere
+            // unexpected. Only claude accepts the key (CLAUDE_AGENT_KEYS), so it is inert nowhere.
+            if (id === "claude") {
+                checkString(entry, `${prefix}.`, "configDir", false);
+                if (typeof entry.configDir === "string" && entry.configDir !== "")
+                    if (!path.isAbsolute(expandHomeTilde(entry.configDir, os.homedir())))
+                        problems.push(`${prefix}.configDir must be an absolute path after ~ expansion (got ${show(entry.configDir)})`);
+            }
             if (!Array.isArray(entry.args))
                 continue; // Already reported by checkStringArray.
-            checkReservedArgs(problems, entry.args, `${prefix}.args`, (flag) => id === "claude"
-                ? HARNESS_CLAUDE_FLAGS.has(flag)
-                    ? "it is harness-managed"
-                    : undefined
-                : id === "pi"
-                    ? HARNESS_PI_FLAGS.get(flag)
-                    : undefined);
+            checkReservedArgs(problems, entry.args, `${prefix}.args`, (flag) => reservedPassthroughFlag(id, flag));
         }
     });
     // Legacy back-compat (plans/agent-backends.md "Back-compat"): a file must not spell one pi
@@ -154,21 +158,21 @@ export function validateConfig(raw, label = "tumwater.json", rawFile = false) {
     // value from the default. The effective value resolves through config-views.ts
     // resolvedAgentConfig; a load-time mirror into `agents` would instead leak a duplicate
     // spelling into every later config write.
-    if (rawFile && isJsonObject(r.agents)) {
-        const pi = r.agents.pi;
+    if (rawFile && isJsonObject(r.backends)) {
+        const pi = r.backends.pi;
         if (isJsonObject(pi)) {
             if (r.agentBin !== undefined && pi.bin !== undefined)
-                problems.push("agentBin and agents.pi.bin set the same value — keep one (agents.pi.bin is the current spelling; agentBin is its legacy alias)");
+                problems.push("agentBin and backends.pi.bin set the same value — keep one (backends.pi.bin is the current spelling; agentBin is its old name)");
             if (r.piArgs !== undefined && pi.args !== undefined)
-                problems.push("piArgs and agents.pi.args set the same value — keep one (agents.pi.args is the current spelling; piArgs is its legacy alias)");
+                problems.push("piArgs and backends.pi.args set the same value — keep one (backends.pi.args is the current spelling; piArgs is its old name)");
         }
     }
     checkNumber(r, "", "maxConcurrent", POSITIVE_INTEGER);
-    checkNumber(r, "", "landBatchMax", POSITIVE_INTEGER);
+    checkNumber(r, "", "mergeBatchMax", POSITIVE_INTEGER);
     checkNumber(r, "", "maxConcurrentChecks", POSITIVE_INTEGER);
     checkNumber(r, "", "worktreeSlots", POSITIVE_INTEGER);
-    checkNumber(r, "", "minTickIntervalSeconds", DURATION_NON_NEGATIVE);
-    checkNumber(r, "", "tickTimeoutSeconds", DURATION_POSITIVE);
+    checkNumber(r, "", "minRunIntervalSeconds", DURATION_NON_NEGATIVE);
+    checkNumber(r, "", "runTimeoutSeconds", DURATION_POSITIVE);
     checkNumber(r, "", "quietTimeoutSeconds", DURATION_OR_DISABLED);
     checkNumber(r, "", "toolCallStallSeconds", DURATION_OR_DISABLED);
     checkNumber(r, "", "logMaxBytes", POSITIVE);
@@ -176,7 +180,7 @@ export function validateConfig(raw, label = "tumwater.json", rawFile = false) {
     checkNumber(r, "", "maxDailyCostUsd", DOLLAR_CAP);
     // Work ratio 1a/4: the maintenance allowance ratio is a number of 0 or more (a larger value
     // effectively disables the cap, so there is no separate off switch).
-    checkNumber(r, "", "maintenancePerWorkLanding", NON_NEGATIVE);
+    checkNumber(r, "", "maintenancePerWorkMerge", NON_NEGATIVE);
     // Disk floor (plans/disk-floor.md, part 1/4): 0 disables the hold, so only a negative
     // value or a non-number is a problem.
     checkNumber(r, "", "diskHoldGB", NON_NEGATIVE);
@@ -281,19 +285,26 @@ export function validateConfig(raw, label = "tumwater.json", rawFile = false) {
         if (isJsonObject(f)) {
             checkKnownKeys(f, TIER_MAP_KEYS, "fallback", problems);
             for (const [tier, v] of Object.entries(f)) {
-                if (!isNonBlankString(v))
-                    problems.push(`fallback.${tier} must be a non-empty selector string or "pause" (got ${show(v)})`);
+                if (Array.isArray(v))
+                    checkFallbackList(`fallback.${tier}`, v, problems);
+                else if (isJsonObject(v))
+                    checkFallbackStep(`fallback.${tier}`, v, problems);
+                else if (!isNonBlankString(v))
+                    problems.push(`fallback.${tier} must be a non-empty model id or "pause" (got ${show(v)})`);
                 else if (v !== "pause")
                     // An entry is a pure selector (config-views' fallbackSelectorFields parses it with
                     // no legacy provider in scope); "pause" names no model and stays valid.
                     checkSelectorValue(`fallback.${tier}`, v, undefined, problems);
             }
         }
+        else if (Array.isArray(f)) {
+            checkFallbackList("fallback", f, problems);
+        }
         else if (!isNonBlankString(f)) {
-            problems.push(`fallback must be a selector string or a map by tier (got ${show(f)})`);
+            problems.push(`fallback must be a model id or a map by tier (got ${show(f)})`);
         }
         else if (f === "pause") {
-            problems.push(`fallback "pause" is only valid as a tier map value — a string fallback must name a selector`);
+            problems.push(`fallback "pause" is only valid as a tier map value — a string fallback must name a model id`);
         }
         else {
             // A selector-string fallback still parses to halves: report an empty one.
@@ -311,13 +322,46 @@ export function validateConfig(raw, label = "tumwater.json", rawFile = false) {
     /** A selector string that parses to an empty provider or model half (`"/id"`, `"p/"`) passes
    * the non-empty-string rule but never reaches pi: piArgs skips an empty value when it builds
    * its flags (config-field-checks' model-triple note), and fallbackPair drops an empty half, so
-   * the fleet silently runs pi's default model — the same silent-ignore class the empty-string
+   * the team silently runs pi's default model — the same silent-ignore class the empty-string
    * rules exist to prevent. Checked only when no legacy provider is in scope: under one, the
    * whole string is the id (config-views' parse), so a `/` in it is ordinary text and the parse
    * cannot produce an empty half. */
     function checkSelectorHalves(obj, prefix, key, legacyProvider, problems) {
         checkSelectorValue(`${prefix}${key}`, obj[key], legacyProvider, problems);
     }
+    /** Validate a `fallback` list (a tier's ordered chain): non-empty, each element a step — a
+     * non-blank model id that is not `"pause"` (a whole-tier value only) and parses to both
+     * halves, or a `{ model, maxDailyCostUsd? }` object (checkFallbackStep). */
+    function checkFallbackList(name, list, problems) {
+        if (list.length === 0)
+            problems.push(`${name} list must not be empty — name at least one model id`);
+        list.forEach((el, i) => {
+            const at = `${name}[${i}]`;
+            if (isJsonObject(el))
+                checkFallbackStep(at, el, problems);
+            else if (!isNonBlankString(el))
+                problems.push(`${name} list element ${i} must be a non-empty model id or a step object (got ${show(el)})`);
+            else if (el === "pause")
+                problems.push(`${name} list element ${i} is "pause" — "pause" is only valid as a whole-tier value`);
+            else
+                checkSelectorValue(at, el, undefined, problems);
+        });
+    }
+    /** Validate one object step `{ model, maxDailyCostUsd? }`: only those keys, `model` a non-blank
+     * selector (not `"pause"`) and `maxDailyCostUsd`, when present, a positive finite number. */
+    function checkFallbackStep(at, step, problems) {
+        checkKnownKeys(step, FALLBACK_STEP_KEYS, at, problems);
+        const m = step.model;
+        if (!isNonBlankString(m))
+            problems.push(`${at}.model must be a non-empty model id (got ${show(m)})`);
+        else if (m === "pause")
+            problems.push(`${at}.model is "pause" — "pause" is only valid as a whole-tier value`);
+        else
+            checkSelectorValue(`${at}.model`, m, undefined, problems);
+        const cap = step.maxDailyCostUsd;
+        if (cap !== undefined && !(typeof cap === "number" && Number.isFinite(cap) && cap > 0))
+            problems.push(`${at}.maxDailyCostUsd must be a positive number (got ${show(cap)})`);
+    }
     /** Report one selector string that parses to an empty provider or model half. `name` is the
      * config path the message names — `model`, a map entry's `model.small`, a section's
      * `roles.feature.model`. Split out of checkSelectorHalves so the map forms, which enumerate
@@ -337,16 +381,16 @@ export function validateConfig(raw, label = "tumwater.json", rawFile = false) {
     // they are validated strictly — a colliding name would silently shadow a built-in's prompt
     // (roleById wins in tickPrompt), validation makes that impossible instead of subtle. The
     // collected names feed the roles cross-check below: an id under `roles` is valid when it is
-    // in the catalog OR listed as a customLoops name.
+    // in the catalog OR listed as a customRoles name.
     const customNames = new Set();
-    if ("customLoops" in r) {
-        const cl = r.customLoops;
+    if ("customRoles" in r) {
+        const cl = r.customRoles;
         if (!Array.isArray(cl)) {
-            problems.push(`customLoops must be an array of { name, task } entries (got ${show(cl)})`);
+            problems.push(`customRoles must be an array of { name, task } entries (got ${show(cl)})`);
         }
         else {
             cl.forEach((entry, i) => {
-                const where = `customLoops[${i}]`;
+                const where = `customRoles[${i}]`;
                 if (!isJsonObject(entry)) {
                     problems.push(`${where} must be an object with keys name and task (got ${show(entry)})`);
                     return;
@@ -357,16 +401,19 @@ export function validateConfig(raw, label = "tumwater.json", rawFile = false) {
                     problems.push(`${where}.name must be a string matching /^[a-z0-9][a-z0-9_-]{0,31}$/ (got ${show(name)})`);
                 }
                 else if (!CUSTOM_NAME_RE.test(name)) {
-                    problems.push(`${where}.name "${name}" is not a valid loop name: start with a lowercase letter or digit, then at most 31 more of [a-z0-9_-]`);
+                    problems.push(`${where}.name "${name}" is not a valid role name: start with a lowercase letter or digit, then at most 31 more of [a-z0-9_-]`);
+                }
+                else if (name === TUMWATER_SOURCE) {
+                    problems.push(`${where}.name "${name}" is reserved: events tumwater writes about itself carry that source, so a role's events would be indistinguishable from them — pick another name`);
                 }
                 else if (allRoleIds().includes(name)) {
                     problems.push(`${where}.name "${name}" collides with a built-in role id — pick another name`);
                 }
                 else if (baseRoleOf(name) !== name) {
-                    problems.push(`${where}.name "${name}" would shadow the ${baseRoleOf(name)} loop's instance ids — pick another name`);
+                    problems.push(`${where}.name "${name}" would shadow the ${baseRoleOf(name)} role's instance ids — pick another name`);
                 }
                 else if (customNames.has(name)) {
-                    problems.push(`${where}.name "${name}" is duplicated in customLoops — names must be unique`);
+                    problems.push(`${where}.name "${name}" is duplicated in customRoles — names must be unique`);
                 }
                 else {
                     customNames.add(name);
@@ -392,7 +439,7 @@ export function validateConfig(raw, label = "tumwater.json", rawFile = false) {
         }
         else {
             for (const [id, rc] of Object.entries(roles)) {
-                // An id outside the catalog and customLoops cannot work: tickPrompt has no prompt for
+                // An id outside the catalog and customRoles cannot work: tickPrompt has no prompt for
                 // it and the loop would error every tick forever (checkKnownRoleId).
                 if (!checkKnownRoleId("roles", id, customNames, problems))
                     continue;
@@ -411,7 +458,7 @@ export function validateConfig(raw, label = "tumwater.json", rawFile = false) {
                 checkModelTriple(o, `roles.${id}.`, "tier-name");
                 checkSelectorHalves(o, `roles.${id}.`, "model", o.provider ?? r.provider, problems);
                 checkBoolean(o, `roles.${id}.`, "enabled");
-                checkNumber(o, `roles.${id}.`, "minTickIntervalSeconds", DURATION_NON_NEGATIVE);
+                checkNumber(o, `roles.${id}.`, "minRunIntervalSeconds", DURATION_NON_NEGATIVE);
                 // Only feature and bugfix may split (src/roles/loop-ids.ts INSTANCE_ROLES); an
                 // instances count under any other role would never spawn a runner, so reject it
                 // rather than let the operator believe it did something.
@@ -425,7 +472,7 @@ export function validateConfig(raw, label = "tumwater.json", rawFile = false) {
         }
     }
     // Per-role daily cost caps (src/gates/role-cap-gates.ts): each key must name a known role —
-    // built-in or customLoops — because a typo'd id would silently no-op the cap, the exact
+    // built-in or customRoles — because a typo'd id would silently no-op the cap, the exact
     // silent-ignore class the `roles.<id>` check exists to prevent (the customNames set above
     // is fully collected by this point, so a custom loop can be capped). Each value is a
     // spend threshold with the NON_NEGATIVE_OR_DISABLED semantics: 0 disables that role's cap.
@@ -440,7 +487,7 @@ export function validateConfig(raw, label = "tumwater.json", rawFile = false) {
     // Per-role quiet hours (src/scheduling/quiet-hours.ts): the same known-role gate as the
     // caps — a typo'd role id would silently no-op the window. Each value must parse as a
     // quiet-hours window (an empty string means off for that role, the same disablement the
-    // fleet-wide key takes), and the message names the key and the offending id/value verbatim.
+    // team-wide key takes), and the message names the key and the offending id/value verbatim.
     checkPerRoleMap(r, "quietHoursPerRole", '"HH:MM-HH:MM" windows', customNames, problems, (id, value) => {
         if (typeof value !== "string") {
             problems.push(`quietHoursPerRole.${id} must be a "HH:MM-HH:MM" string like "23:00-07:00" (an empty string means off) (got ${show(value)})`);
@@ -452,6 +499,43 @@ export function validateConfig(raw, label = "tumwater.json", rawFile = false) {
         if (!parsed.ok)
             problems.push(parsed.error);
     });
+    // Per-provider concurrency caps (plans/provider-concurrency.md §1): a map from provider
+    // key to a positive integer. Unlike the per-role maps above, an unknown provider name is
+    // NOT a validation error — providers live in pi's models.json, which validation does not
+    // read, and a fallback's provider may only come into use later (doctor warns in part 5/5).
+    // Each value must be a positive integer under a non-empty key.
+    if (r.maxConcurrentPerProvider !== undefined) {
+        const map = r.maxConcurrentPerProvider;
+        if (!isJsonObject(map)) {
+            problems.push(`maxConcurrentPerProvider must be an object mapping provider names to concurrency caps (got ${show(map)})`);
+        }
+        else {
+            for (const [provider, value] of Object.entries(map)) {
+                if (provider.trim() === "") {
+                    problems.push(`maxConcurrentPerProvider.<empty> — a provider key must not be empty`);
+                    continue;
+                }
+                if (typeof value !== "number" || !Number.isFinite(value) || !POSITIVE_INTEGER.ok(value)) {
+                    problems.push(`maxConcurrentPerProvider.${provider} must be ${POSITIVE_INTEGER.what} (got ${show(value)})`);
+                }
+            }
+        }
+    }
+    // The subscription-window reserve: a map from window type to a fraction, 0 < f <= 1.
+    if (r.claudeWindowReserve !== undefined) {
+        const map = r.claudeWindowReserve;
+        if (!isJsonObject(map)) {
+            problems.push(`claudeWindowReserve must be an object mapping window types to fractions (got ${show(map)})`);
+        }
+        else {
+            for (const [type, value] of Object.entries(map)) {
+                if (type.trim() === "")
+                    problems.push(`claudeWindowReserve.<empty> — a window type must not be empty`);
+                else if (typeof value !== "number" || !Number.isFinite(value) || value <= 0 || value > 1)
+                    problems.push(`claudeWindowReserve.${type} must be a fraction above 0 and at most 1 (got ${show(value)})`);
+            }
+        }
+    }
     // Cross-field (judged on the merged config, where both sides are always present; on a raw
     // file only when the file itself names both): scheduleBackoff clamps every idle wait — the
     // first included — to min(initialSeconds, maxSeconds), so a smaller max silently discards