tumwater 0.2.0 → 0.3.0

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

@@ -1,22 +1,24 @@
-// 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 { MODEL_TIERS, BACKOFF_KEYS, BOOTSTRAP_KEYS, CHECK_KEYS, CUSTOM_ROLE_KEYS, CUSTOM_NAME_RE, CUSTOM_TASK_MAX_CHARS, REVIEW_KEYS, ROLE_ENTRY_KEYS, TOP_LEVEL_KEYS, ROLE_INSTRUCTIONS_MAX_CHARS, } from "./config-schema.js";
+import { DIRECTOR_ROLE, allRoleIds } from "../roles/roles.js";
+import { INSTANCE_ROLES, baseRoleOf } from "../roles/runner-ids.js";
+import { isHarnessCodexConfigKey } from "../agent/codex/codex-args.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 { isBackendId } from "./model-selector.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";
+import { AT_LEAST_ONE, checkBooleanField, checkKnownKeys, checkKnownRoleId, checkModelTripleField, checkNumberField, checkObjectSection, codexConfigKey, checkStringArrayField, checkStringField, NON_NEGATIVE, NON_NEGATIVE_OR_DISABLED, DOLLAR_CAP, MAX_DURATION_SECONDS, POSITIVE, POSITIVE_INTEGER, show, typeName, } from "./config-field-checks.js";
+import { checkEntryBackend, checkRetiredSelector, checkSelectorHalves, } from "./config-selector-checks.js";
+import { validateAgentsBlock } from "./config-validation-agents.js";
+import { validateFallbackBlock, validateModelBlock, } from "./config-validation-model.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
+ * through (config.ts's load/save, config-write.ts's budget editing and
+ * config-request.ts's director config requests), judged against the key allow-lists and
+ * value shapes that live beside the types
  * they mirror in config-schema.ts. Split out of config.ts — which keeps defaultConfig and the
  * read side (load/save/cache, per-role views) — because this is a self-contained concern:
  * it depends only on the schema, the role catalog (allRoleIds), and message wording, not on
@@ -38,7 +40,7 @@ const DURATION_OR_DISABLED = {
 };
 /** A per-role instance count (`roles.feature.instances`): an integer from 1 to 8. Bounded so
  * a typo like `instances: 800` cannot spawn hundreds of runners, and integer so
- * `feature-1.5` — which no loop id can name — is refused. */
+ * `feature-1.5` — which no role id can name — is refused. */
 const INSTANCE_COUNT = {
     ok: (n) => Number.isInteger(n) && n >= 1 && n <= 8,
     what: "an integer from 1 to 8",
@@ -66,8 +68,8 @@ 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 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.
+ * unknown role id (a misspelled entry under `roles`) spawns a phantom role that errors every
+ * run, and an unknown key is silently ignored so the intended setting never takes effect.
  * Collects every problem so one edit can fix them all; throws a single Error listing them.
  * `label` names the file in the thrown messages — validateConfig also gates the tracked
  * example template, whose problems must not be misreported as tumwater.json's.
@@ -90,83 +92,91 @@ export function validateConfig(raw, label = "tumwater.json", rawFile = false) {
     const checkNumber = (obj, prefix, key, rule) => checkNumberField(problems, obj, prefix, key, rule);
     const checkBoolean = (obj, prefix, key) => checkBooleanField(problems, obj, prefix, key);
     const checkStringArray = (obj, prefix, key) => checkStringArrayField(problems, obj, prefix, key);
+    // claude's and codex's per-backend config dir (plans/notes-command.md "Keeping funes out
+    // of team runs" and plans/codex-backend.md §4): a leading `~` expands; the value must be an
+    // absolute path after expansion, or claude would resolve a relative CLAUDE_CONFIG_DIR (and
+    // codex a relative CODEX_HOME) from the run's cwd and write transcripts somewhere
+    // unexpected. Only claude and codex accept the key, so it is inert nowhere else. The nested
+    // reserve spelling (part 2b/9): the same 0 < f ≤ 1 rule the top-level `claudeWindowReserve`
+    // map gets, so a bad entry can never silently no-op a reserve.
+    const checkBackendConfig = (entry, prefix) => {
+        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 (entry.windowReserve === undefined)
+            return;
+        const wr = entry.windowReserve;
+        if (!isJsonObject(wr)) {
+            problems.push(`${prefix}.windowReserve must be an object mapping window types to fractions (got ${show(wr)})`);
+            return;
+        }
+        for (const [type, value] of Object.entries(wr)) {
+            if (type.trim() === "")
+                problems.push(`${prefix}.windowReserve.<empty> — a window type must not be empty`);
+            else if (typeof value !== "number" || !Number.isFinite(value) || value <= 0 || value > 1)
+                problems.push(`${prefix}.windowReserve.${type} must be a fraction above 0 and at most 1 (got ${show(value)})`);
+        }
+    };
+    // codex's `-c <key>=…` / `--config <key>=…` passthrough (plans/codex-backend.md §2/§3): a
+    // key tumwater sets on every run (HARNESS_CODEX_CONFIG_KEYS) — or one the write guard owns,
+    // `hooks` / `hooks.<…>` (part 3/9) — is appended AFTER the harness's own `-c` and Codex's
+    // parser is last-wins, so it would silently override the model, effort, sandbox mode,
+    // telemetry or the write guard the harness resolved. The standalone-flag screen above
+    // (reservedPassthroughFlag + checkReservedArgs) splits on `=` and cannot see a separate
+    // `-c` token, so codex gets its own arity-aware scan of the key. Any other key is the
+    // operator's own and passes.
+    const checkCodexConfigKeys = (entry, prefix) => {
+        const args = entry.args;
+        for (let i = 0; i < args.length; i++) {
+            const arg = args[i];
+            if (typeof arg !== "string")
+                continue;
+            const key = codexConfigKey(arg, typeof args[i + 1] === "string" ? args[i + 1] : undefined);
+            if (key !== undefined && isHarnessCodexConfigKey(key))
+                problems.push(`${prefix}.args[${i}] ${show(arg)} passes the config key ${key}, which tumwater manages — drop it or use another key`);
+        }
+    };
     const r = raw; // Narrowed to an object by isJsonObject above.
     checkKnownKeys(r, TOP_LEVEL_KEYS, label, problems);
     // 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);
-    // 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))
-            checkSelectorValue(`model.${tier}`, sel, undefined, problems);
-    // 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" && !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
-    // 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 two backends whose reserved
-    // sets are known (claude-args.ts HARNESS_CLAUDE_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 : 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) => reservedPassthroughFlag(id, flag));
-        }
+    // The backend a selector with no `backend` of its own resolves to (retired-spelling checks).
+    const topBackend = typeof r.backend === "string" ? r.backend : "pi";
+    // The backend a tier's primary resolves to, which that tier's fallback steps inherit.
+    const tierBackend = (tier) => {
+        // A tier left out of the map takes the `default` entry, as resolveTopTier does.
+        const e = isJsonObject(r.model) ? (r.model[tier] ?? r.model.default) : undefined;
+        return isJsonObject(e) && typeof e.backend === "string" ? e.backend : topBackend;
+    };
+    // A string or list `fallback` serves every tier, each inheriting its own tier's backend, so it
+    // is checked against each distinct one; the same message from two backends is reported once.
+    const eachTierBackend = (check) => {
+        const out = [];
+        for (const b of new Set(MODEL_TIERS.map(tierBackend)))
+            check(b, out);
+        for (const m of new Set(out))
+            problems.push(m);
+    };
+    // The retired spelling doubled a backend id as the provider namespace, so a `provider` that IS
+    // a backend id other than `pi` on a section that otherwise runs on pi is the old back-compat
+    // form: configForRole still resolves the section to pi and hands the bare provider name to
+    // pi, which has no such provider — reject it with the edit the step check names (write the
+    // backend beside the model, drop the provider). checkRetiredSelector covers the no-provider
+    // spellings; this catches the pair a provider in scope used to make valid.
+    const checkLegacyProvider = (provider, at, backend) => {
+        if (typeof provider === "string" && isBackendId(provider) && provider !== "pi" && backend === "pi")
+            problems.push(`${at}provider "${provider}" is the retired backend namespace but this section runs on pi — write backend: "${provider}" beside the model and drop the provider`);
+    };
+    validateModelBlock(r, problems, { checkModelTriple, checkString, topBackend, checkLegacyProvider });
+    validateAgentsBlock(r, problems, rawFile, {
+        checkString,
+        checkStringArray,
+        checkKnownKeys,
+        checkBackendConfig,
+        checkCodexConfigKeys,
     });
-    // 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
-    // resolvedAgentConfig; 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)");
-        }
-    }
     checkNumber(r, "", "maxConcurrent", POSITIVE_INTEGER);
     checkNumber(r, "", "mergeBatchMax", POSITIVE_INTEGER);
     checkNumber(r, "", "maxConcurrentChecks", POSITIVE_INTEGER);
@@ -204,7 +214,7 @@ export function validateConfig(raw, label = "tumwater.json", rawFile = false) {
     // New-project bootstrap (plans/work-ratio.md, "New-project bootstrap"): an absent section
     // means no bootstrap. `untilPlansDone` is a count of plans that must reach `## Done`, so it is
     // an integer of at least 1 — 0 or a fraction can never be reached and would hold the
-    // maintenance loops forever.
+    // maintenance roles forever.
     checkObjectSection(r, "bootstrap", problems, (o) => {
         checkKnownKeys(o, BOOTSTRAP_KEYS, "bootstrap", problems);
         checkNumber(o, "bootstrap.", "untilPlansDone", POSITIVE_INTEGER);
@@ -233,6 +243,9 @@ export function validateConfig(raw, label = "tumwater.json", rawFile = false) {
         // gateCommand is a string like command, but blank means off: falling back from it runs
         // the FULL check at the gate — the stronger check, never a silently weaker one.
         checkString(o, "check.", "gateCommand");
+        // mergeCommand likewise: an absent key falls back to the gate command (Fast merge
+        // "Defaults"), and a blank string means off, which runs the full check in the merge lock.
+        checkString(o, "check.", "mergeCommand");
         checkString(o, "check.", "cwd");
         checkNumber(o, "check.", "timeoutSeconds", DURATION_POSITIVE);
     });
@@ -246,6 +259,7 @@ export function validateConfig(raw, label = "tumwater.json", rawFile = false) {
         checkKnownKeys(o, REVIEW_KEYS, "review", problems);
         checkBoolean(o, "review.", "enabled");
         checkStringArray(o, "review.", "exemptPaths");
+        checkStringArray(o, "review.", "afterMerge");
         // An exemption pattern is matched against a repo-relative path (exemptions.ts), so a
         // pattern shaped like something git never emits can never match: the diff it was meant
         // to exempt gets a model review anyway, and the operator never learns the pattern was
@@ -269,117 +283,21 @@ export function validateConfig(raw, label = "tumwater.json", rawFile = false) {
         }
         checkModelTriple(o, "review.", "tier-name");
         checkSelectorHalves(o, "review.", "model", o.provider ?? r.provider, problems);
+        checkEntryBackend(o, "review", problems);
+        if ((o.provider ?? r.provider) === undefined)
+            checkRetiredSelector("review.model", o.model, typeof o.backend === "string" ? o.backend : topBackend, problems);
+        checkLegacyProvider(o.provider ?? r.provider, "review.", typeof o.backend === "string" ? o.backend : topBackend);
         checkNumber(o, "review.", "timeoutSeconds", DURATION_POSITIVE);
     });
-    // 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);
-                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 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);
-        }
-    }
-    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.");
-        if (!("provider" in o) && !("model" in o))
-            problems.push(`fallbackModel must name a provider or a model (got ${show(o)})`);
+    validateFallbackBlock(r, problems, {
+        checkModelTriple,
+        checkLegacyProvider,
+        tierBackend,
+        eachTierBackend,
     });
-    /** 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. */
-    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
-     * 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. */
-    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`);
-    }
-    // Custom loops (plans/user-defined-loops.md): names become worktree dirs and git refs, so
+    // Custom roles (plans/user-defined-loops.md): names become worktree dirs and git refs, so
     // 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
+    // (roleById wins in runPrompt), 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 customRoles name.
     const customNames = new Set();
@@ -395,7 +313,7 @@ export function validateConfig(raw, label = "tumwater.json", rawFile = false) {
                     problems.push(`${where} must be an object with keys name and task (got ${show(entry)})`);
                     return;
                 }
-                checkKnownKeys(entry, CUSTOM_LOOP_KEYS, where, problems);
+                checkKnownKeys(entry, CUSTOM_ROLE_KEYS, where, problems);
                 const name = entry.name;
                 if (typeof name !== "string") {
                     problems.push(`${where}.name must be a string matching /^[a-z0-9][a-z0-9_-]{0,31}$/ (got ${show(name)})`);
@@ -420,7 +338,7 @@ export function validateConfig(raw, label = "tumwater.json", rawFile = false) {
                 }
                 const task = entry.task;
                 // A whitespace-only task is as inert as an empty one — it rides into every one of
-                // this loop's tick prefills as blank text, so the loop has nothing to do and ticks
+                // this role's run prefills as blank text, so the role has nothing to do and runs
                 // no_change forever. Reject both shapes with the same message; the model-triple
                 // checkString rule uses the same trim-based emptiness test.
                 if (!isNonBlankString(task)) {
@@ -439,8 +357,8 @@ export function validateConfig(raw, label = "tumwater.json", rawFile = false) {
         }
         else {
             for (const [id, rc] of Object.entries(roles)) {
-                // An id outside the catalog and customRoles cannot work: tickPrompt has no prompt for
-                // it and the loop would error every tick forever (checkKnownRoleId).
+                // An id outside the catalog and customRoles cannot work: runPrompt has no prompt for
+                // it and the role would error every run forever (checkKnownRoleId).
                 if (!checkKnownRoleId("roles", id, customNames, problems))
                     continue;
                 if (!isJsonObject(rc)) {
@@ -450,16 +368,20 @@ export function validateConfig(raw, label = "tumwater.json", rawFile = false) {
                 const o = rc;
                 checkKnownKeys(o, ROLE_ENTRY_KEYS, `roles.${id}`, problems);
                 // Empty is a deliberate "no extra instructions". A non-empty value rides into every
-                // one of this role's tick prefills, so it is capped like a custom loop's task.
+                // one of this role's run prefills, so it is capped like a custom role's task.
                 checkString(o, `roles.${id}.`, "instructions");
                 const instructions = o.instructions;
                 if (typeof instructions === "string" && instructions.length > ROLE_INSTRUCTIONS_MAX_CHARS)
                     problems.push(tooLongMessage(`roles.${id}.instructions`, instructions.length, ROLE_INSTRUCTIONS_MAX_CHARS, PREFILL_REASON));
                 checkModelTriple(o, `roles.${id}.`, "tier-name");
                 checkSelectorHalves(o, `roles.${id}.`, "model", o.provider ?? r.provider, problems);
+                checkEntryBackend(o, `roles.${id}`, problems);
+                if ((o.provider ?? r.provider) === undefined)
+                    checkRetiredSelector(`roles.${id}.model`, o.model, typeof o.backend === "string" ? o.backend : topBackend, problems);
+                checkLegacyProvider(o.provider ?? r.provider, `roles.${id}.`, typeof o.backend === "string" ? o.backend : topBackend);
                 checkBoolean(o, `roles.${id}.`, "enabled");
                 checkNumber(o, `roles.${id}.`, "minRunIntervalSeconds", DURATION_NON_NEGATIVE);
-                // Only feature and bugfix may split (src/roles/loop-ids.ts INSTANCE_ROLES); an
+                // Only feature and bugfix may split (src/roles/runner-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.
                 if ("instances" in o && !INSTANCE_ROLES.has(id)) {
@@ -471,10 +393,22 @@ export function validateConfig(raw, label = "tumwater.json", rawFile = false) {
             }
         }
     }
+    // review.afterMerge names roles, so a typo'd id would silently keep that role reviewed before
+    // merging; the director is refused because its changes always merge on a review first.
+    if (isJsonObject(r.review) && Array.isArray(r.review.afterMerge)) {
+        r.review.afterMerge.forEach((id, i) => {
+            if (typeof id !== "string" || id.trim() === "")
+                return; // Already reported by checkStringArray.
+            if (id === DIRECTOR_ROLE)
+                problems.push(`review.afterMerge[${i}] must not be "${DIRECTOR_ROLE}" — its changes are always reviewed before merging`);
+            else
+                checkKnownRoleId("review.afterMerge", id, customNames, problems);
+        });
+    }
     // Per-role daily cost caps (src/gates/role-cap-gates.ts): each key must name a known role —
     // 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
+    // is fully collected by this point, so a custom role can be capped). Each value is a
     // spend threshold with the NON_NEGATIVE_OR_DISABLED semantics: 0 disables that role's cap.
     checkPerRoleMap(r, "maxDailyCostUsdPerRole", "USD caps", customNames, problems, (id) => {
         // Same MAX_SAFE_INTEGER bound as maxDailyCostUsd's DOLLAR_CAP rule (BUGS.md
@@ -536,6 +470,14 @@ export function validateConfig(raw, label = "tumwater.json", rawFile = false) {
             }
         }
     }
+    // The reserve's two spellings are mutually exclusive (plans/codex-backend.md part 2b/9): the
+    // nested key is the current one; `claudeWindowReserve` is kept as claude's older spelling. A
+    // file holding both is ambiguous about which drives the window, so it is rejected naming both.
+    if (r.claudeWindowReserve !== undefined &&
+        isJsonObject(r.backends) &&
+        isJsonObject(r.backends.claude) &&
+        r.backends.claude.windowReserve !== undefined)
+        problems.push("claudeWindowReserve and backends.claude.windowReserve set the same value — keep one (backends.claude.windowReserve is the current spelling; claudeWindowReserve is its old name)");
     // 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