tumwater 0.2.0 → 0.4.0

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

@@ -0,0 +1,137 @@
+/** The director's staged config-write request — one verb split out of config-write.ts (the
+ * operator-editor mutators stay there, addressed by key through config-keys.ts). The director
+ * stages a JSON request file in its worktree; this module consumes it: parse the request,
+ * keep only its `customRoles` array, apply it as a whole-config write, and delete the file on
+ * every path. A request is shaped and lives differently from the interactive `config set` /
+ * `unset` verbs (a staged file that must never reach a diff, not direct CLI text), so the
+ * runtime (run-verdict.ts) imports this module rather than the whole editor. It
+ * still shares the write machinery with the editor — withConfigLock and rawConfigObject from
+ * config-write-core.ts (the editor verbs live in config-write.ts), validateConfig from
+ * config-validation.ts, writeJsonAtomic from json-files.js — because a request is a
+ * whole-config write too. */
+import fs from "node:fs";
+import { isDeepStrictEqual } from "node:util";
+import { configPath, configRequestPath } from "../paths.js";
+import { errorMessage } from "../text/text.js";
+import { readTextOrNull } from "../files/files.js";
+import { writeJsonAtomic } from "../files/json-files.js";
+import { isJsonObject } from "../files/json-object.js";
+import { withConfigLock, rawConfigObject } from "./config-write-core.js";
+import { show } from "./config-field-checks.js";
+import { validateConfig } from "./config-validation.js";
+import { normalizeConfigKeys } from "./config-aliases.js";
+import { collapseBackendAliases, loadConfig } from "./config.js";
+/** Consume the director's config-write request file (plans/portability.md §3/7). After its pi
+ * run the director may leave `.tumwater-config-request.json` at its worktree root:
+ * `{ "customRoles": [ { "name", "task" }, … ] }` — the whole array, replacing the current one.
+ * Applied atomically to the live config, sharing the editor's trap (fresh loadConfig that
+ * bypasses the stat cache, validateConfig, then writeJsonAtomic — readers poll every ~2 s), so
+ * the orchestrator's live reload starts the new role with no commit, no review
+ * gate, and no merge, and the request file never enters a diff.
+ *
+ * The permitted key set is enforced here, not in prose: `customRoles` is accepted and every
+ * other top-level key is collected into `ignored` and dropped (the caller logs the warning that
+ * names them). Validation runs BEFORE any write and nothing here dereferences a request entry
+ * first — a structurally malformed entry (`[null]`, a non-string name) is left for
+ * validateConfig to reject, so on failure nothing is written and the previous config stays
+ * live. The request file is deleted on EVERY path (including every failure), so a malformed
+ * request cannot retry forever and the file cannot survive into `git add -A`.
+ *
+ * Roles entries for custom roles the request removes are stripped before validation, from the
+ * FILE's own `roles` section rather than the catalog-merged map (the rule every other
+ * whole-config write follows, see preserveFileRoles): loadConfig seeds one `roles.<name>` per
+ * current custom role and validateConfig rejects an id that is neither a catalog role nor a
+ * requested custom-role name, so without the strip a removal would never apply. Only
+ * structurally valid names feed the strip — a malformed entry stays in the array for
+ * validateConfig to reject.
+ *
+ * Returns null when no request file exists. `applied` names the custom roles now live (empty
+ * unless the write happened); `ignored` lists the discarded top-level keys; `error`, when set,
+ * names why nothing (or only part of the work) was done — the caller turns it and `ignored`
+ * into warning events. `unchanged` is set when the request's array equals the live one;
+ * nothing is written. */
+export function applyConfigRequest(root, wt) {
+    const requestFile = configRequestPath(wt);
+    const raw = readTextOrNull(requestFile);
+    if (raw === null)
+        return null; // no request this run
+    const ignored = [];
+    let applied = [];
+    let error;
+    let unchanged;
+    try {
+        const unnormalized = JSON.parse(raw);
+        if (!isJsonObject(unnormalized))
+            throw new Error(`config request must be a JSON object (got ${show(unnormalized)})`);
+        // Old key spellings read as the new ones; a request setting both fails with the pair named.
+        const normalized = normalizeConfigKeys(unnormalized);
+        if (normalized.problems.length > 0)
+            throw new Error(normalized.problems.join("; "));
+        const parsed = normalized.raw;
+        for (const key of Object.keys(parsed)) {
+            if (key !== "customRoles")
+                ignored.push(key);
+        }
+        const entries = parsed.customRoles;
+        if (!Array.isArray(entries))
+            throw new Error(`config request's customRoles must be an array (got ${show(entries)})`);
+        // The load-to-write sequence is one critical section under withConfigLock: a concurrent
+        // `config set`/dashboard write between the load and this write must not be dropped by the
+        // whole-file overwrite (see writeConfigMutation).
+        withConfigLock(root, () => {
+            const current = loadConfig(root); // fresh — bypasses the stat cache: a writer sees the latest file
+            // Same as the live array: write nothing, like writeConfigMutation's no-op skip.
+            if (isDeepStrictEqual(entries, current.customRoles)) {
+                unchanged = true;
+                return;
+            }
+            // Strip roles.<id> entries for custom roles this request removes (see docstring).
+            // Structurally valid names only; anything else stays for validateConfig to reject — never
+            // dereference a request entry before validation.
+            const requestedNames = new Set();
+            for (const entry of entries) {
+                if (isJsonObject(entry) && typeof entry.name === "string")
+                    requestedNames.add(entry.name);
+            }
+            // Base the roles rewrite on the FILE's own section, not the loaded (catalog-merged)
+            // map: this whole-config write must not re-expand a partial section to every built-in
+            // (preserveFileRoles' rule). Only the removed custom roles' entries are stripped, and
+            // only from what the file actually holds.
+            const rawRolesCandidate = rawConfigObject(root).roles;
+            const roles = isJsonObject(rawRolesCandidate)
+                ? { ...(rawRolesCandidate) }
+                : {};
+            for (const c of current.customRoles) {
+                if (!requestedNames.has(c.name))
+                    delete roles[c.name];
+            }
+            const candidate = { ...current, customRoles: entries };
+            const candidateRecord = candidate;
+            if (rawRolesCandidate === undefined)
+                delete candidateRecord.roles;
+            else
+                candidateRecord.roles = roles;
+            // Collapse legacy/new pi spellings before writing so a merged config (which always
+            // carries the default piArgs) never lands both forms in the file — the next load's raw
+            // pass rejects a file holding both `piArgs` and `backends.pi.args`.
+            const collapsed = collapseBackendAliases(candidate);
+            validateConfig(collapsed); // throws listing every problem — nothing is written on failure
+            writeJsonAtomic(configPath(root), collapsed, true);
+            applied = collapsed.customRoles.map((c) => c.name);
+        });
+    }
+    catch (err) {
+        applied = []; // no write happened, or it must not be reported as applied
+        error = errorMessage(err);
+    }
+    // Delete the request on EVERY path — success, rejection, malformed JSON — so it can never be
+    // staged by commitAll, reach a review gate, or retry forever. A failed unlink is surfaced as
+    // an error so the caller logs it (the file would otherwise survive into the diff).
+    try {
+        fs.unlinkSync(requestFile);
+    }
+    catch (err) {
+        error ??= `config request file could not be deleted: ${errorMessage(err)}`;
+    }
+    return unchanged ? { applied, ignored, error, unchanged } : { applied, ignored, error };
+}

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

@@ -1,30 +1,29 @@
-// 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
  * level — the schema facts, single-homed here so adding a key edits one file: its type,
  * 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
+ * types.ts grab-bag — the runtime types a run produces now live beside their consumers
+ * (RunResult and RunOutcome in run-outcome.ts, RunnerState in runner-state.ts, HarnessEvent
  * 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
- * hunt starts here, a tick-lifecycle trace starts beside the type it traces. Sibling
- * modules: config.ts (defaults + load), config-validation.ts (validation), config-write.ts
- * (writes). */
+ * hunt starts here, a run-lifecycle trace starts beside the type it traces. Sibling
+ * modules: config.ts (defaults + load), config-validation.ts (validation), config-write-core.ts
+ * (machinery) + config-write.ts and config-request.ts (writes). */
 import { objectOrEmpty } from "../files/json-object.js";
 /** The model tiers a selector map may name (plans/model-tiers.md). A tier left out of the
  * `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"];
+export const FALLBACK_STEP_KEYS = ["backend", "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", "opencode"];
+ * ids so validation rejects a typo'd backend at load time instead of falling back to pi. A
+ * model id never names a backend: the backend is the `backend` key's. */
+export const BACKEND_IDS = ["pi", "claude", "opencode", "codex"];
 /** 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,6 +40,8 @@ export function modelTierMap(model) {
         return { default: model };
     return objectOrEmpty(model);
 }
+/** The keys an object tier entry may hold (validation feeds checkKnownKeys). */
+export const SELECTOR_ENTRY_KEYS = ["backend", "model", "thinking"];
 /** 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)
@@ -92,11 +93,16 @@ export const TOP_LEVEL_KEYS = [
 export const BACKOFF_KEYS = ["initialSeconds", "factor", "maxSeconds"];
 /** 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"];
+ * `configDir`/`windowReserve` are claude/codex-only (CLAUDE_AGENT_KEYS / CODEX_BACKEND_KEYS),
+ * so they are not silently inert on pi/opencode. */
+export const BACKEND_KEYS = ["bin", "args"];
+/** The keys a claude `backends.claude` entry may hold — the shared agent keys plus `configDir`
+ * and `windowReserve`, the per-backend fields only the claude adapter reads. */
+export const CLAUDE_AGENT_KEYS = [...BACKEND_KEYS, "configDir", "windowReserve"];
+/** The keys a codex `backends.codex` entry may hold — the same as claude's: the shared agent keys
+ * plus `configDir` (which becomes `CODEX_HOME` for the codex processes, plans/codex-backend.md
+ * §4) and `windowReserve` (the part 2 per-backend reserve). */
+export const CODEX_BACKEND_KEYS = [...BACKEND_KEYS, "configDir", "windowReserve"];
 /** The keys tumwater.json's `bootstrap` section may hold. */
 export const BOOTSTRAP_KEYS = ["untilPlansDone"];
 export const ROLE_ENTRY_KEYS = [
@@ -104,15 +110,16 @@ export const ROLE_ENTRY_KEYS = [
     "instructions",
     "provider",
     "model",
+    "backend",
     "thinking",
     "minRunIntervalSeconds",
     "instances",
 ];
-export const REVIEW_KEYS = ["enabled", "exemptPaths", "provider", "model", "thinking", "timeoutSeconds"];
+export const REVIEW_KEYS = ["enabled", "exemptPaths", "afterMerge", "provider", "model", "backend", "thinking", "timeoutSeconds"];
 /** The `check` section's keys (plans/portability.md §6/7): the project's own verification
  * command, the optional cheaper gate-only command, their
  * working directory (relative to the worktree), and their timeout. */
-export const CHECK_KEYS = ["command", "gateCommand", "cwd", "timeoutSeconds"];
+export const CHECK_KEYS = ["command", "gateCommand", "mergeCommand", "cwd", "timeoutSeconds"];
 /** The provider/model/thinking triple every model-override section shares — top level,
  * `review`, `fallbackModel` (plans/fallback-model.md), and each `roles.<id>` entry — so one
  * mental model and one validator cover them all. */
@@ -126,7 +133,7 @@ export const THINKING_LEVELS = new Set(["off", "minimal", "low", "medium", "high
  * --session-dir …`, the provider/model/thinking triple, and the session resume/name flags).
  * A piArgs entry equal to one of these is appended AFTER the harness's own copy, and pi's
  * argument parser is last-wins — so it silently overrides the harness: `--mode text` makes
- * every tick's stream unparseable, `--model` spends on a model tumwater.json never named, and
+ * every run's stream unparseable, `--model` spends on a model tumwater.json never named, and
  * `--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([
@@ -145,14 +152,14 @@ export const HARNESS_PI_FLAGS = new Map([
     // 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:
+export const CUSTOM_ROLE_KEYS = ["name", "task"];
+/** A custom role's name becomes a worktree dir and a git ref, so it is validated strictly:
  * lowercase alphanumerics plus dash/underscore, starting with an alphanumeric, ≤ 32 chars. */
 export const CUSTOM_NAME_RE = /^[a-z0-9][a-z0-9_-]{0,31}$/;
-/** A custom loop's task rides into every one of that loop's tick prefills, so it is capped:
- * unbounded text would be a standing per-tick cost. */
+/** A custom role's task rides into every one of that role's run prefills, so it is capped:
+ * unbounded text would be a standing per-run cost. */
 export const CUSTOM_TASK_MAX_CHARS = 4096;
-/** A role's extra instructions ride into every one of that role's tick prefills, so they are
- * capped like a custom loop's task: unbounded text would be a standing per-tick cost (and
+/** A role's extra instructions ride into every one of that role's run prefills, so they are
+ * capped like a custom role's task: unbounded text would be a standing per-run cost (and
  * could crowd the prompt toward the model's context ceiling). */
 export const ROLE_INSTRUCTIONS_MAX_CHARS = 4096;

package/dist/src/config/config-selector-checks.js

@@ -0,0 +1,123 @@
+import { BACKEND_IDS, FALLBACK_STEP_KEYS, MODEL_TIERS } from "./config-schema.js";
+import { checkKnownKeys, show } from "./config-field-checks.js";
+import { isJsonObject } from "../files/json-object.js";
+import { isNonBlankString } from "../text/text.js";
+import { typoSuffix } from "../text/suggest.js";
+import { isBackendId, parseModelSelector } from "./model-selector.js";
+/** Model-selector and fallback-chain checks that validateConfig (config-validation.ts) runs
+ * on each model-choosing section: empty selector halves, `fallback` lists and steps, and an
+ * entry's `backend` against its model. Each takes the `problems` list to append to and reads
+ * nothing else, so they live beside the generic checkers in config-field-checks.ts rather
+ * than inside validateConfig's body. */
+/** 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 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. */
+export function checkSelectorHalves(obj, prefix, key, legacyProvider, problems) {
+    checkSelectorValue(`${prefix}${key}`, obj[key], legacyProvider, problems);
+}
+/** Reject the retired model-id spellings that named a backend: a first segment that is a backend
+ * id (`claude/claude-opus-5-5`) and a bare `claude-…` id resolving to pi. Each message names the
+ * value and the edit — `backend` is its own key, never part of the model id. `backend` is the
+ * one the selector resolves to; an opencode seam's `opencode/<id>` is a legitimate OpenCode id
+ * and stays. A tier-name or non-string value is not a selector and is skipped. */
+export function checkRetiredSelector(name, v, backend, problems) {
+    if (!isNonBlankString(v) || MODEL_TIERS.includes(v))
+        return;
+    const slash = v.indexOf("/");
+    const first = slash === -1 ? undefined : v.slice(0, slash);
+    if ((first === "claude" || first === "opencode") && backend !== "opencode")
+        problems.push(`${name} ${show(v)} names the backend "${first}" in its model id — write backend: "${first}" beside model: ${show(v.slice(slash + 1))}`);
+    else if (slash !== -1 && backend === "claude")
+        problems.push(`${name} ${show(v)} is a provider/model id but the backend is claude, which would run it as a paid claude model — add backend: "pi" beside it`);
+    else if (slash === -1 && v.startsWith("claude-") && backend === "pi")
+        problems.push(`${name} ${show(v)} is a claude model id but the backend is pi — add backend: "claude" beside it, or write ${show(`anthropic/${v}`)} to keep it on pi`);
+}
+/** 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 `{ backend?, model, maxDailyCostUsd? }` object (checkFallbackStep). */
+export function checkFallbackList(name, list, problems, inheritedBackend = "pi") {
+    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, inheritedBackend);
+        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);
+            checkRetiredSelector(at, el, inheritedBackend, problems);
+        }
+    });
+}
+/** Validate one object step `{ backend?, model, maxDailyCostUsd? }`: only those keys, `backend` as
+ * checkEntryBackend checks it, `model` a non-blank
+ * selector (not `"pause"`) and `maxDailyCostUsd`, when present, a positive finite number. */
+export function checkFallbackStep(at, step, problems, inheritedBackend = "pi") {
+    checkKnownKeys(step, FALLBACK_STEP_KEYS, at, problems);
+    checkEntryBackend(step, 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);
+        checkRetiredSelector(`${at}.model`, m, typeof step.backend === "string" ? step.backend : inheritedBackend, 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)})`);
+}
+/** Validate the `backend` of one model-choosing entry (a tier entry, a role or `review`): it must
+ * name a registered backend, and — when the entry also names a model — the model must be a
+ * valid id for that backend: claude's `--model` takes its own ids (no `/`), pi needs
+ * `provider/id` and no backend id as the provider namespace. A tier-name `model` (roles,
+ * review) is a reference, not an id, and is skipped. */
+export function checkEntryBackend(o, at, problems) {
+    const b = o.backend;
+    if (b === undefined)
+        return;
+    if (!isNonBlankString(b)) {
+        if (typeof b === "string")
+            problems.push(`${at}.backend must not be empty (got ${show(b)})`);
+        else
+            problems.push(`${at}.backend must be a string (got ${show(b)})`);
+        return;
+    }
+    if (!isBackendId(b)) {
+        problems.push(`${at}.backend must name a backend (${BACKEND_IDS.join(", ")}; got ${show(b)})${typoSuffix(b, BACKEND_IDS)}`);
+        return;
+    }
+    const m = o.model;
+    if (!isNonBlankString(m) || MODEL_TIERS.includes(m))
+        return;
+    const sel = parseModelSelector(m);
+    if (b === "claude" && sel.provider !== undefined)
+        problems.push(`${at}.model ${show(m)} has a "/" but ${at}.backend is "claude" — claude takes its own model ids (e.g. "claude-sonnet-5-5")`);
+    if (b === "pi" && sel.provider === undefined)
+        problems.push(`${at}.model ${show(m)} has no provider but ${at}.backend is "pi" — pi needs \`provider/id\``);
+    if (b === "pi" && isBackendId(sel.provider))
+        problems.push(`${at}.model ${show(m)} names the backend "${sel.provider}" as its provider but ${at}.backend is "pi" — drop the "${sel.provider}/" namespace`);
+}
+/** 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
+ * their entries instead of looking one key up on an object, run the identical check: a
+ * selector's empty half is the same silent-ignore class wherever the string lives. */
+export function checkSelectorValue(name, v, legacyProvider, problems) {
+    if (!isNonBlankString(v))
+        return;
+    const legacy = isNonBlankString(legacyProvider) ? legacyProvider : undefined;
+    const sel = parseModelSelector(v, legacy);
+    if (sel.provider?.trim() === "")
+        problems.push(`${name} ${show(v)} parses to an empty provider half — pi would silently run its default model`);
+    if (sel.model.trim() === "")
+        problems.push(`${name} ${show(v)} parses to an empty model half — pi would silently run its default model`);
+}

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

@@ -0,0 +1,80 @@
+/** The agent-execution section rules of tumwater.json validation: `agentBin`, `baseBranch`,
+ * the `backend` id, `piArgs` and the `backends` object (per-backend `bin`/`args`, the
+ * claude/codex config-dir scan, the codex `-c <key>=…` arity-aware scan, the reserved
+ * passthrough-flag screen), and the legacy `agentBin`/`piArgs` back-compat pair. Extracted
+ * from the single validateConfig gate (config-validation.ts) so an agent-key edit lands as a
+ * per-theme diff instead of a whole-gate one. Called from the gate where this block runs
+ * today, so problem order across the whole pass is unchanged.
+ *
+ * The helpers passed in are closures the gate binds once (the problems-bound field checkers
+ * and the per-backend config-dir / codex-config-key scans); everything else these rules need
+ * is imported directly. */
+import { BACKEND_IDS, BACKEND_KEYS, CLAUDE_AGENT_KEYS, CODEX_BACKEND_KEYS, HARNESS_PI_FLAGS, } from "./config-schema.js";
+import { isJsonObject } from "../files/json-object.js";
+import { typoSuffix } from "../text/suggest.js";
+import { isBackendId } from "./model-selector.js";
+import { reservedPassthroughFlag } from "../agent/backend-traits.js";
+import { checkObjectSection, checkReservedArgs, show, } from "./config-field-checks.js";
+/** Validate the agent-execution block: the bare `backend`, `agentBin`, `baseBranch` and
+ * `piArgs` keys, the `backends` object in full, and the legacy spellings' back-compat pair. */
+export function validateAgentsBlock(r, problems, rawFile, helpers) {
+    const { checkString, checkStringArray, checkKnownKeys, checkBackendConfig, checkCodexConfigKeys } = helpers;
+    // An empty baseBranch would silently fall back to the checked-out branch — the one value
+    // the operator's explicit setting must never degrade to unannounced.
+    checkString(r, "", "baseBranch", false);
+    // An empty agentBin would silently fall back to "pi" — the same silent-ignore class: the
+    // operator named a binary, so a blank value must fail validation, not run the default.
+    checkString(r, "", "agentBin", 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, "", "backend", false);
+    if (typeof r.backend === "string" && !isBackendId(r.backend))
+        problems.push(`backend must name a backend (${BACKEND_IDS.join(", ")}; got ${show(r.backend)})${typoSuffix(r.backend, BACKEND_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
+    // position and the flag so one edit removes it.
+    if (Array.isArray(r.piArgs))
+        checkReservedArgs(problems, r.piArgs, "piArgs", (flag) => HARNESS_PI_FLAGS.get(flag));
+    // Agent backends (plans/agent-backends.md "Config"): each entry is an object with an
+    // optional non-empty `bin` string and an optional array-of-strings `args`. A passthrough arg
+    // 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 backends whose reserved sets
+    // are known (claude-args.ts HARNESS_CLAUDE_FLAGS, opencode-args.ts HARNESS_OPENCODE_FLAGS,
+    // codex-args.ts HARNESS_CODEX_FLAGS, config-schema.ts HARNESS_PI_FLAGS).
+    checkObjectSection(r, "backends", problems, (o) => {
+        for (const [id, entry] of Object.entries(o)) {
+            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, id === "claude" ? CLAUDE_AGENT_KEYS : id === "codex" ? CODEX_BACKEND_KEYS : BACKEND_KEYS, prefix, problems);
+            checkString(entry, `${prefix}.`, "bin", false);
+            checkStringArray(entry, `${prefix}.`, "args");
+            if (id === "claude" || id === "codex")
+                checkBackendConfig(entry, prefix);
+            if (id === "codex" && Array.isArray(entry.args))
+                checkCodexConfigKeys(entry, prefix);
+            if (!Array.isArray(entry.args))
+                continue; // Already reported by checkStringArray.
+            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
+    // field both ways. This is a property of the FILE's own keys — the merged config always
+    // carries a default `piArgs`, so only the raw pass (rawFile) can tell an explicit legacy
+    // value from the default. The effective value resolves through config-views.ts
+    // resolvedBackendConfig; a load-time mirror into `agents` would instead leak a duplicate
+    // spelling into every later config write.
+    if (rawFile && isJsonObject(r.backends)) {
+        const pi = r.backends.pi;
+        if (isJsonObject(pi)) {
+            if (r.agentBin !== undefined && pi.bin !== undefined)
+                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 backends.pi.args set the same value — keep one (backends.pi.args is the current spelling; piArgs is its old name)");
+        }
+    }
+}

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

@@ -0,0 +1,116 @@
+/** The model-declaration section rules of tumwater.json validation: the top-level `model`
+ * selector-or-map block, and the fallback/fallbackModel block. Extracted from the single
+ * validateConfig gate (config-validation.ts) so a model-key edit lands as a per-theme diff
+ * instead of a whole-gate one. The two blocks run at different points of the gate — the
+ * top-level model block before the agent and numeric sections, the fallback block after the
+ * review section — so this module exports two entry points, each called where its block runs
+ * today, keeping problem order byte-identical.
+ *
+ * These rules sit on top of the generic machinery in config-field-checks.ts and
+ * config-selector-checks.ts; the helpers passed in are the closures the gate binds once
+ * (the problems-bound checkers and the r-derived backend/legacy-provider resolution shared
+ * with the gate's own remaining sections). */
+import { MODEL_TRIPLE_KEYS, SELECTOR_ENTRY_KEYS, THINKING_LEVELS, TIER_MAP_KEYS, } from "./config-schema.js";
+import { isJsonObject } from "../files/json-object.js";
+import { isNonBlankString } from "../text/text.js";
+import { checkKnownKeys, checkObjectSection, show, } from "./config-field-checks.js";
+import { checkEntryBackend, checkFallbackList, checkFallbackStep, checkRetiredSelector, checkSelectorHalves, checkSelectorValue, } from "./config-selector-checks.js";
+/** Validate the top-level `model` selector-or-map block and its provider/backend resolution.
+ * Keeps the exact problem order the gate produced at this point: the selector/tier-map check,
+ * the empty-half check, the retired-spelling no-provider check, the legacy-provider pair and
+ * each tier entry. */
+export function validateModelBlock(r, problems, helpers) {
+    const { checkModelTriple, checkString, topBackend, checkLegacyProvider } = helpers;
+    // The top level's `model` may be a selector string or a map by tier (plans/model-tiers.md);
+    // provider/thinking validate as before. A string selector that parses to an empty provider
+    // or model half is reported separately (checkSelectorHalves).
+    checkModelTriple(r, "", "tier-map");
+    checkSelectorHalves(r, "", "model", r.provider, problems);
+    if (r.provider === undefined)
+        checkRetiredSelector("model", r.model, topBackend, problems);
+    checkLegacyProvider(r.provider, "", topBackend);
+    // A map's entries are selector strings too, resolved by config-views' topTierSelector with
+    // parseModelSelector; the keyed check above sees only the object, so each entry runs the
+    // same empty-half check (the map form cannot coexist with a legacy provider, so it parses
+    // as a pure selector).
+    if (isJsonObject(r.model))
+        for (const [tier, sel] of Object.entries(r.model)) {
+            if (!isJsonObject(sel)) {
+                checkSelectorValue(`model.${tier}`, sel, undefined, problems);
+                checkRetiredSelector(`model.${tier}`, sel, topBackend, problems);
+                continue;
+            }
+            // An object tier entry: the model written beside the backend that runs it.
+            const at = `model.${tier}`;
+            checkKnownKeys(sel, SELECTOR_ENTRY_KEYS, at, problems);
+            checkString(sel, `${at}.`, "model", false);
+            const t = sel.thinking;
+            if (t !== undefined && !(isNonBlankString(t) && THINKING_LEVELS.has(t)))
+                problems.push(`${at}.thinking must be one of ${[...THINKING_LEVELS].join(", ")} (got ${show(t)})`);
+            checkEntryBackend(sel, at, problems);
+            checkSelectorValue(`${at}.model`, sel.model, undefined, problems);
+            checkRetiredSelector(`${at}.model`, sel.model, typeof sel.backend === "string" ? sel.backend : topBackend, problems);
+        }
+}
+/** Validate the `fallback` string-or-map block and the free-fallback-model (`fallbackModel`)
+ * shape. The single call site in the gate is the point where these problems are appended
+ * today, so the order across the whole pass is unchanged. */
+export function validateFallbackBlock(r, problems, helpers) {
+    const { checkModelTriple, checkLegacyProvider, tierBackend, eachTierBackend } = helpers;
+    // The free fallback model (plans/fallback-model.md): shape only — whether the named pair is
+    // actually cost-free is a question about pi's models.json, not about this file, so it is
+    // answered at run time (src/pi/pi-models.ts) rather than failing a load here. An empty object is
+    // rejected: it names nothing, so it would silently never engage.
+    // The selector-string shorthand `fallback` (plans/model-tiers.md) validates as one non-empty
+    // string; the map form takes per-tier entries whose values are selector strings or "pause"
+    // (each tier's entry is consulted when that tier runs at the cap; part 5a/8). Setting both
+    // forms — or the map form and `fallbackModel` — is an error naming both keys, since which
+    // one wins is not a question the file should ever pose.
+    if ("fallback" in r && r.fallback !== undefined) {
+        const f = r.fallback;
+        if (isJsonObject(f)) {
+            checkKnownKeys(f, TIER_MAP_KEYS, "fallback", problems);
+            for (const [tier, v] of Object.entries(f)) {
+                if (Array.isArray(v))
+                    checkFallbackList(`fallback.${tier}`, v, problems, tierBackend(tier));
+                else if (isJsonObject(v))
+                    checkFallbackStep(`fallback.${tier}`, v, problems, tierBackend(tier));
+                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);
+                    checkRetiredSelector(`fallback.${tier}`, v, tierBackend(tier), problems);
+                }
+            }
+        }
+        else if (Array.isArray(f)) {
+            eachTierBackend((b, out) => checkFallbackList("fallback", f, out, b));
+        }
+        else if (!isNonBlankString(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 model id`);
+        }
+        else {
+            // A selector-string fallback still parses to halves: report an empty one.
+            checkSelectorHalves({ fallback: f }, "", "fallback", undefined, problems);
+            eachTierBackend((b, out) => checkRetiredSelector("fallback", f, b, out));
+        }
+    }
+    if ("fallback" in r && "fallbackModel" in r)
+        problems.push(`fallback and fallbackModel both name the budget fallback — keep only one (got fallback ${show(r.fallback)} and fallbackModel ${show(r.fallbackModel)})`);
+    checkObjectSection(r, "fallbackModel", problems, (o) => {
+        checkKnownKeys(o, MODEL_TRIPLE_KEYS, "fallbackModel", problems);
+        checkModelTriple(o, "fallbackModel.");
+        // legacyFallbackPair (config-fallbacks.ts) forces a fallbackModel that names its own
+        // provider onto backend pi whatever the team's backend, so a legacy provider that is a
+        // backend id there is the same silent-pi-pair flaw the checks above reject.
+        checkLegacyProvider(o.provider, "fallbackModel.", "pi");
+        if (!("provider" in o) && !("model" in o))
+            problems.push(`fallbackModel must name a provider or a model (got ${show(o)})`);
+    });
+}