tumwater 0.2.0 → 0.4.0

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

@@ -1,40 +1,43 @@
-// vocabulary: plain
 /** The budget/tier FALLBACK side of the config views, split out of config-views.ts: how the
  * team falls back at the daily spend cap — which free pair each tier runs on
  * (resolveTierFallbacks and its BORROW_ORDER), the per-role fallback config a model-failure
- * or cap episode hands a loop (fallbackRoleConfig, applyFallbackModel), and the surfaces
+ * or cap episode hands a role (fallbackRoleConfig, applyFallbackModel), and the surfaces
  * that name those pairs (seamsInUse, modelFallbackView, tierFallbackLabels). The per-seam
  * resolution these build on — how one role/reviewer/resolver provider/model/thinking resolves
  * (configForRole, reviewConfig, withModelOverrides, …) — stays in config-views.ts, so the
  * one-way dependency runs fallback → seam and never back. Pure, like its sibling: no I/O and
  * no caching. */
 import { MODEL_TIERS, } from "./config-schema.js";
-import { formatModelSelector, isAgentId, parseModelSelector } from "./model-selector.js";
+import { formatModelSelector, parseModelSelector, routeModel } from "./model-selector.js";
 import { modelPairName } from "../budget/budget.js";
 import { DIRECTOR_ROLE } from "../roles/roles.js";
-import { baseRoleOf } from "../roles/loop-ids.js";
+import { baseRoleOf } from "../roles/runner-ids.js";
 import { enabledRoleIds } from "./config.js";
-import { modelFallbackActive } from "../loop/model-fallback.js";
-import { FALLBACK_REVIEW_TIMEOUT_S, REVIEW_TIMEOUT_S, configForRole, isTierName, resolvedModelFields, resolverConfig, reviewConfig, reviewRunConfig, roleSeamTier, topTierSelector, withModelOverrides, } from "./config-views.js";
+import { modelFallbackActive } from "../runner/model-fallback.js";
+import { FALLBACK_REVIEW_TIMEOUT_S, REVIEW_TIMEOUT_S, configForRole, isTierName, pairOverrides, resolvedModelFields, resolverConfig, reviewConfig, reviewRunConfig, roleSeamTier, topTierBackend, topTierSelector, withModelOverrides, } from "./config-views.js";
+/** The resolved fields of one fallback step, keyed by the seam it routes to (PLANS.md "Mixed
+ * claude + pi fleets, part 2/4"): the backend is the step's own, else its tier primary's
+ * resolved backend (the tier entry's, else the top level's, else pi). A pair routed to a
+ * non-pi backend carries that backend as `backend` and its name as `provider` — the key the
+ * budget gate's handback (src/budget/budget-wiring.ts's runOnPair against the run's
+ * seamHoldKey capture, runner-run.ts's setRunPair) matches on — and the id passes to it as
+ * written (routeModel); a
+ * pi pair keeps its own provider (a bare pi selector keeps undefined). */
+function seamKeyedPairFields(config, tier, provider, model, thinking, stepBackend) {
+    const backend = stepBackend ?? topTierBackend(config, tier) ?? config.backend ?? "pi";
+    const routed = model === undefined ? undefined : routeModel(provider, model, "pi", tier, backend);
+    return {
+        ...resolvedModelFields(backend !== "pi" ? backend : provider, routed?.model, thinking),
+        ...(backend !== "pi" ? { backend } : {}),
+    };
+}
 /** The resolved model fields of a pure `fallback` selector string: parsed as a pure selector
  * (no legacy provider in scope), with the ambient top-level thinking when the selector
  * carries none. fallbackPair's map and string branches and tierOwnChain share this
  * assembly, so all three read one rule for how a `fallback` selector resolves. */
-function fallbackSelectorFields(selector, config) {
+function fallbackSelectorFields(selector, config, tier, backend) {
     const parsed = parseModelSelector(selector);
-    return resolvedModelFields(seamKeyedFallbackProvider(config, parsed.provider), parsed.model, parsed.thinking ?? config.thinking);
-}
-/** A fallback pair's provider keyed by the seam it routes to (PLANS.md "Mixed claude + pi
- * fleets, part 2/4"): a pair that routes to a non-pi backend carries that backend's name as
- * its provider — `claude/claude-sonnet-5-5` and a bare `claude-sonnet-5-5` on a claude
- * team both read `claude` — so the budget gate's handback (gate-polls.ts's tickOnPair
- * against the tick's seamHoldKey capture, loop-tick.ts's setTickPair) matches a tick on
- * either selector form. The same routing rule as routeModel: a provider naming an agent is
- * that agent, no provider runs on the config's `agent`, anything else is pi, which keeps
- * its own provider (a bare pi selector keeps undefined, exactly as before). */
-function seamKeyedFallbackProvider(config, provider) {
-    const agent = provider === undefined ? config.backend : isAgentId(provider) ? provider : "pi";
-    return agent !== "pi" ? agent : provider;
+    return seamKeyedPairFields(config, tier, parsed.provider, parsed.model, parsed.thinking ?? config.thinking, backend);
 }
 /** The team-level fallback pair: the `default` tier's resolved pair under
  * resolveTierFallbacks' borrow order, or null when the tier resolves to pause. The
@@ -61,10 +64,12 @@ function legacyFallbackPair(config) {
     // The top-level model is a selector too (parsed the same way withModelOverrides does), so a
     // fallback field that omits model borrows the parsed id, never the raw selector string.
     const topSel = topTierSelector(config, "default");
-    const provider = seamKeyedFallbackProvider(config, fbo.provider ?? topSel?.provider ?? config.provider);
+    const provider = fbo.provider ?? topSel?.provider ?? config.provider;
     const model = fbo.model ?? topSel?.model;
     const thinking = fbo.thinking ?? topSel?.thinking ?? config.thinking;
-    return resolvedModelFields(provider, model, thinking);
+    // The legacy object's own `provider` is a pi provider (claude takes none), so naming one
+    // keeps the pair on pi whatever the team's backend; without one it inherits like any step.
+    return seamKeyedPairFields(config, "default", provider, model, thinking, fbo.provider !== undefined ? "pi" : undefined);
 }
 /** The order a tier borrows other tiers' own fallbacks in, after trying its own: small
  * climbs (small → default → strong), default keeps near itself (default → strong → small),
@@ -77,7 +82,7 @@ const BORROW_ORDER = {
 };
 /** Exported for imageRerouteTarget (src/agent/image-input.ts), which walks a rerouting role's
  * tier through the same borrow order the budget fallback uses (skipping the tier itself), and
- * for the doctor's `image input` check naming the tier a text-only loop reroutes to. */
+ * for the doctor's `image input` check naming the tier a text-only role reroutes to. */
 export { BORROW_ORDER };
 /** A tier's OWN fallback chain, first step first — what the `fallback` key declares at that
  * tier's map entry (a selector or a list of them), or (default only) the string/list form of
@@ -104,7 +109,7 @@ function tierOwnChain(config, tier) {
         if (legacy === null)
             return [];
         const primaryClaude = withModelOverrides(config, tier, {}).agent === "claude";
-        return [legacy.provider === "claude" && primaryClaude ? { ...legacy, extraUsage: true } : legacy];
+        return [legacy.backend === "claude" && primaryClaude ? { ...legacy, extraUsage: true } : legacy];
     }
     if (raw === undefined || raw === "pause")
         return [];
@@ -115,9 +120,9 @@ function tierOwnChain(config, tier) {
         .filter((s) => s !== "pause")
         .map((s) => {
         const step = typeof s === "string" ? { model: s } : s;
-        const fields = fallbackSelectorFields(step.model, config);
-        const extraUsage = fields.provider === "claude" && claudeSeen;
-        if (fields.provider === "claude")
+        const fields = fallbackSelectorFields(step.model, config, tier, step.backend);
+        const extraUsage = fields.backend === "claude" && claudeSeen;
+        if (fields.backend === "claude")
             claudeSeen = true;
         return {
             ...fields,
@@ -162,7 +167,7 @@ export function resolveTierFallbacks(config, usable) {
     };
     return { small: resolve("small"), default: resolve("default"), strong: resolve("strong") };
 }
-/** The config a role's ticks run on while a model-fallback episode is active (PLANS.md "Model
+/** The config a role's runs use while a model-fallback episode is active (PLANS.md "Model
  * failure fallback, part 1/2"): the role's tier pair from resolveTierFallbacks (the tier's own
  * pair, else BORROW_ORDER's borrow), shaped like configForRole — provider/model/thinking over
  * the role's own and top-level values, plus the role's minRunIntervalSeconds. Null when the
@@ -174,11 +179,7 @@ export function fallbackRoleConfig(config, role) {
         return null;
     const rc = config.roles[baseRoleOf(role)];
     return {
-        ...withModelOverrides(config, tier, {
-            provider: pair.provider,
-            model: pair.model,
-            thinking: pair.thinking,
-        }),
+        ...withModelOverrides(config, tier, pairOverrides(pair)),
         minRunIntervalSeconds: rc?.minRunIntervalSeconds ?? config.minRunIntervalSeconds,
     };
 }
@@ -210,13 +211,13 @@ export function seamsInUse(config) {
     add("resolver", resolverConfig(config));
     add("director", configForRole(config, DIRECTOR_ROLE));
     for (const { tier, step, pair } of tierChainSteps(config)) {
-        add(step === 0 ? `fallback:${tier}` : `fallback:${tier}#${step}`, withModelOverrides(config, tier, { provider: pair.provider, model: pair.model, thinking: pair.thinking }));
+        add(step === 0 ? `fallback:${tier}` : `fallback:${tier}#${step}`, withModelOverrides(config, tier, pairOverrides(pair)));
     }
     return [...seams.values()];
 }
 /** Build a ModelFallbackView for an episode, or null while the episode is not running the
  * fallback (no episode, or a due probe on the primary). role-view.ts's
- * RoleViewPayload.modelFallback and status/status-data.ts's per-loop row both build this
+ * RoleViewPayload.modelFallback and status/status-data.ts's per-role row both build this
  * shape, so one function keeps the two surfaces from disagreeing about the pair, its start,
  * and its reason. `now` is the caller's clock (the status snapshot passes its own poll
  * clock), so a row and its poll agree on what "active" means. */
@@ -259,11 +260,17 @@ export function tiersResolveDistinctPairs(resolved) {
         .map((p) => modelPairName(p));
     return new Set(pairs).size >= 2;
 }
-/** Drop a model-override seam's provider/model/thinking fields — the one rule the fallback
+/** Drop a model-override seam's provider/model/backend/thinking fields — the one rule the fallback
  * view's role and reviewer strips share, so a field on that triple cannot be dropped from one
  * and left on the other (where it would reach a priced model after the cap). */
 function stripModel(o) {
-    const { provider: _p, model: _m, thinking: _t, ...rest } = o;
+    const { provider: _p, model: _m, backend: _b, thinking: _t, ...rest } = o;
+    return rest;
+}
+/** Drop only a seam's explicit backend, for a tier-name entry kept through the cap: the tier
+ * reference stays valid, but a paid `backend` pinned beside it must not outlive the cap. */
+function stripBackend(o) {
+    const { backend: _b, ...rest } = o;
     return rest;
 }
 /** The reviewer config as the fallback view sees it: model seam stripped, and its time budget
@@ -282,7 +289,7 @@ function fallbackReview(review) {
 function stripRoleModels(roles, keepTierNames) {
     return Object.fromEntries(Object.entries(roles).map(([id, rc]) => [
         id,
-        keepTierNames && isTierName(rc?.model) ? rc : stripModel(rc),
+        keepTierNames && isTierName(rc?.model) ? stripBackend(rc) : stripModel(rc),
     ]));
 }
 /** Every `roles.<id>` entry with its model seam stripped, except a seam `free` calls free — a
@@ -294,10 +301,10 @@ function freeRoleModels(config, free) {
     return Object.fromEntries(Object.entries(config.roles).map(([id, rc]) => {
         if (rc && free?.(withModelOverrides(config, roleSeamTier(config, id), rc)))
             return [id, rc];
-        return [id, isTierName(rc?.model) ? rc : stripModel(rc)];
+        return [id, isTierName(rc?.model) ? stripBackend(rc) : stripModel(rc)];
     }));
 }
-/** The config as seen by a role loop running on the free fallback model
+/** The config as seen by a role running on the free fallback model
  * (plans/fallback-model.md): the fallback's provider/model/thinking installed as the top-level
  * values AND every per-role and reviewer model override dropped, so that EVERY seam that could
  * otherwise reach a priced model — an author run, its reviewer, a conflict resolver — resolves
@@ -320,13 +327,26 @@ function freeRoleModels(config, free) {
  * model, while every priced seam still lands on its tier's fallback pair. */
 export function applyFallbackModel(config, resolved, free) {
     if (resolved) {
-        const selectorOf = (f) => f.pair
-            ? formatModelSelector({
-                provider: f.pair.provider,
-                model: f.pair.model ?? "",
-                thinking: f.pair.thinking,
-            })
-            : undefined;
+        // A pair's selector keeps pi's provider; a non-pi pair's model is already the whole id. On a
+        // team whose backend is not pi — or a pair routed off pi — the entry names the pair's
+        // backend, so the team's own backend cannot take a pi pair's id as its own.
+        const selectorOf = (f) => {
+            const pair = f.pair;
+            if (!pair)
+                return undefined;
+            const selector = formatModelSelector({
+                provider: pair.backend === undefined ? pair.provider : undefined,
+                model: pair.model ?? "",
+                thinking: pair.backend === undefined ? pair.thinking : undefined,
+            });
+            if (pair.backend === undefined && (config.backend ?? "pi") === "pi")
+                return formatModelSelector({ provider: pair.provider, model: pair.model ?? "", thinking: pair.thinking });
+            return {
+                backend: pair.backend ?? "pi",
+                model: selector,
+                ...(pair.thinking !== undefined ? { thinking: pair.thinking } : {}),
+            };
+        };
         const model = {};
         const stepCaps = {};
         for (const tier of MODEL_TIERS) {
@@ -336,16 +356,33 @@ export function applyFallbackModel(config, resolved, free) {
             const seam = withModelOverrides(config, tier, {});
             if (free?.(seam)) {
                 const own = topTierSelector(config, tier);
-                if (own !== undefined)
-                    model[tier] = formatModelSelector({ ...own, thinking: own.thinking ?? config.thinking });
+                // A tier entry that names a backend keeps it as an object entry: a bare selector string
+                // would route by namespace and drop the backend the entry chose.
+                const backend = topTierBackend(config, tier);
+                if (own !== undefined) {
+                    const thinking = own.thinking ?? config.thinking;
+                    if (backend !== undefined)
+                        model[tier] = {
+                            backend,
+                            model: formatModelSelector({ ...own, thinking: undefined }),
+                            ...(thinking !== undefined ? { thinking } : {}),
+                        };
+                    else
+                        model[tier] = formatModelSelector({ ...own, thinking });
+                }
                 // A tier with no top-level selector — `agent: "claude"` riding its agent default —
                 // has no own selector to carry the level, so name the routed default plus it.
-                else if (seam.model !== undefined)
-                    model[tier] = formatModelSelector({
-                        provider: seam.provider,
-                        model: seam.model,
-                        thinking: seam.thinking,
-                    });
+                else if (seam.model !== undefined) {
+                    const routed = { provider: seam.provider, model: seam.model };
+                    model[tier] =
+                        backend !== undefined
+                            ? {
+                                backend,
+                                model: formatModelSelector(routed),
+                                ...(seam.thinking !== undefined ? { thinking: seam.thinking } : {}),
+                            }
+                            : formatModelSelector({ ...routed, thinking: seam.thinking });
+                }
                 continue;
             }
             const sel = selectorOf(resolved[tier]);
@@ -370,7 +407,8 @@ export function applyFallbackModel(config, resolved, free) {
         return config;
     return {
         ...config,
-        provider: pair.provider,
+        ...(pair.backend !== undefined || config.backend !== undefined ? { backend: pair.backend ?? "pi" } : {}),
+        provider: pair.backend === undefined ? pair.provider : undefined,
         model: pair.model,
         thinking: pair.thinking,
         review: fallbackReview(config.review),

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

@@ -1,8 +1,7 @@
-// vocabulary: plain
 import { MODEL_TRIPLE_KEYS, MODEL_TIERS, TIER_MAP_KEYS, THINKING_LEVELS, } from "./config-schema.js";
 import { allRoleIds } from "../roles/roles.js";
 import { isJsonObject } from "../files/json-object.js";
-import { typoSuffix } from "../text/suggest.js";
+import { didYouMean, suggestClosest, typoSuffix } from "../text/suggest.js";
 import { truncate, isNonBlankString } from "../text/text.js";
 /** The generic field-check machinery behind validateConfig (config-validation.ts): error
  * message rendering (show, typeName), the unknown-key and known-role guards, the NumberRule
@@ -43,7 +42,7 @@ export function typeName(v) {
 export function checkKnownKeys(obj, known, where, problems) {
     for (const key of Object.keys(obj)) {
         if (!known.includes(key))
-            problems.push(`unknown key "${key}" in ${where} (valid keys: ${known.join(", ")})${typoSuffix(key, known)}`);
+            problems.push(`unknown key "${key}" in ${where} (valid keys: ${known.join(", ")})${typoSuffix(key, known)}${key === "agent" ? ' — "agent" is retired, write "backend"' : ""}`);
     }
 }
 /** Read an optional field once and hand it to `check` — the rule every per-field checker and
@@ -99,9 +98,9 @@ export const AT_LEAST_ONE = { ok: (n) => n >= 1, what: "a number of at least 1"
 export const MAX_DURATION_SECONDS = 2147483;
 /** Shared known-role guard for the per-role config sections (`roles.<id>` entries and
  * `maxDailyCostUsdPerRole.<id>` keys): an id outside the role catalog and customRoles cannot
- * work — a `roles` typo spawns a phantom loop that errors every tick forever; a caps typo
+ * work — a `roles` typo spawns a phantom role that errors every run forever; a caps typo
  * silently no-ops the cap — so both reject it here with the valid ids, the same message shape
- * `tumwater logs --role` uses for a bad flag value. Returns true when the id is known. */
+ * `tumwater logs --transcript` uses for a bad flag value. Returns true when the id is known. */
 export function checkKnownRoleId(section, id, customNames, problems) {
     if (allRoleIds().includes(id) || customNames.has(id))
         return true;
@@ -124,7 +123,7 @@ export function checkStringField(problems, obj, prefix, key, allowEmpty = true)
 /** Every model-override section validates the same provider/model/thinking triple the same
  * way: empty strings are rejected (see checkStringField) and thinking is value-checked —
  * pi only recognizes THINKING_LEVELS and silently drops anything else, so a typo would run
- * the loops at pi's default depth and never say so.
+ * the roles at pi's default depth and never say so.
  *
  * `modelShape` widens `model` per plans/model-tiers.md: "selector" (the default, for the
  * legacy `fallbackModel` object) keeps it a plain selector string; "tier-map" (top level)
@@ -132,9 +131,10 @@ export function checkStringField(problems, obj, prefix, key, allowEmpty = true)
  * selector strings — a map cannot coexist with a legacy provider in the same section, since
  * the provider's old meaning (the whole string is a bare id under it) has no per-tier
  * reading; "tier-name" (roles.<id>.model, review.model) also accepts a bare tier name as a
- * reference into the top-level map. Tier names are valid ONLY where a tier reference means
- * something: elsewhere (top level, fallbackModel) one is rejected with the two places that
- * accept it, so a misplaced `"model": "strong"` is an error naming its fix instead of a
+ * reference into the top-level map. A bare value within two edits of a tier name (ignoring
+ * case) is rejected as a misspelled tier reference. Tier names are valid ONLY where a tier
+ * reference means something: elsewhere (top level, fallbackModel) one is rejected with the two
+ * places that accept it, so a misplaced `"model": "strong"` is an error naming its fix instead of a
  * bare model pattern pi can never resolve. */
 export function checkModelTripleField(problems, obj, prefix, modelShape = "selector") {
     for (const key of MODEL_TRIPLE_KEYS)
@@ -151,7 +151,8 @@ export function checkModelTripleField(problems, obj, prefix, modelShape = "selec
         if (obj.provider !== undefined)
             problems.push(`${prefix}model as a map by tier cannot coexist with ${prefix ? prefix : "the legacy top-level "}provider — move the provider into each tier's model id (got provider ${show(obj.provider)})`);
         for (const [tier, v] of Object.entries(m))
-            if (!isNonBlankString(v))
+            // An object entry (`{ backend?, model?, thinking? }`) is validated by validateConfig.
+            if (!isNonBlankString(v) && !isJsonObject(v))
                 problems.push(`${prefix}model.${tier} must be a non-empty model id (got ${show(v)})`);
         return;
     }
@@ -172,6 +173,12 @@ export function checkModelTripleField(problems, obj, prefix, modelShape = "selec
         if (modelShape === "tier-name")
             return; // A valid tier reference.
         problems.push(`${prefix}model must name a model id — tier names are valid only as roles.<id>.model or review.model values (got ${show(m)})`);
+        return;
+    }
+    if (modelShape === "tier-name" && !m.includes("/") && obj.provider === undefined) {
+        const tier = suggestClosest(m, MODEL_TIERS);
+        if (tier !== null)
+            problems.push(`${prefix}model ${show(m)} is not a tier name or a model id pi can resolve${didYouMean(tier)}`);
     }
 }
 /** Validate one numeric field against a NumberRule when present. */
@@ -223,3 +230,26 @@ export function checkReservedArgs(problems, args, argsPath, whyFor) {
             problems.push(`${argsPath}[${i}] ${show(arg)} duplicates a flag tumwater sets — ${why}`);
     });
 }
+/** The config <key> a `-c <key>=…` / `--config <key>=…` / `-c<key>=…` / `-c=<key>=…` /
+ * `--config=<key>=…` argv element names, or undefined when the element is not a keyed codex
+ * config passthrough. Codex takes the key and value in one token (`-c key=value`), and accepts a
+ * joined `-c=<key>=<value>` identically to `-c <key>=<value>`; `-c` and `--config` alone are
+ * followed by the `<key>=<value>` token as the next element, so the scanner passes both. Kept
+ * here beside its one caller (the codex `backends.args` screen); the tokens actually split by
+ * checkReservedArgs cannot see this form, which is why the scan is its own loop. */
+export function codexConfigKey(arg, next) {
+    let rest;
+    if (arg === "-c" || arg === "--config")
+        rest = next;
+    else if (arg.startsWith("--config="))
+        rest = arg.slice("--config=".length);
+    else if (arg.startsWith("-c="))
+        rest = arg.slice(3);
+    else if (arg.startsWith("-c") && arg.length > 2 && !arg.startsWith("--"))
+        rest = arg.slice(2);
+    if (rest === undefined)
+        return undefined;
+    const eq = rest.indexOf("=");
+    const key = (eq === -1 ? rest : rest.slice(0, eq)).trim();
+    return key === "" ? undefined : key;
+}

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

@@ -1,14 +1,15 @@
-// vocabulary: plain
 /** The config KEY language — how `tumwater config get/set/unset` and the dashboard editors
  * name a config value and what makes one legitimate, apart from the writes that change it.
  * One family, in its own module because it serves both verbs AND the read side: `config get`,
  * shell completion, doctor's holds and the dashboard controllers all address keys and screen
  * per-key values without performing a write, so burying this in the config-write module made
  * read-side callers import from the "config WRITES" layer. The mutators (the load →
- * validate → atomic-write idiom, the cross-process lock) live in src/config/config-write.ts;
+ * validate → atomic-write idiom, the cross-process lock) live in src/config/config-write-core.ts
+ * (the operator-editor verbs in src/config/config-write.ts;
+ * the director's staged request in src/config/config-request.ts);
  * the per-key validators and key-shape parsing here are the one home of the wording both the
  * writers and the read side show. */
-import { AGENT_KEYS, CLAUDE_AGENT_KEYS, ROLE_ENTRY_KEYS, TIER_MAP_KEYS, TOP_LEVEL_KEYS } from "./config-schema.js";
+import { BACKEND_KEYS, BACKOFF_KEYS, BOOTSTRAP_KEYS, CHECK_KEYS, CLAUDE_AGENT_KEYS, CODEX_BACKEND_KEYS, REVIEW_KEYS, ROLE_ENTRY_KEYS, TIER_MAP_KEYS, TOP_LEVEL_KEYS } from "./config-schema.js";
 import { typoSuffix } from "../text/suggest.js";
 import { MAX_DURATION_SECONDS, POSITIVE_INTEGER, show } from "./config-field-checks.js";
 import { parseQuietHours } from "../scheduling/quiet-hours.js";
@@ -83,11 +84,19 @@ export const PER_KEY_VALIDATORS = {
  * check the per-role maps apply. The per-key value validator runs before the write, the same
  * screening a bare top-level key gets. */
 export const DOTTED_MAP_KEYS = ["maxDailyCostUsdPerRole", "quietHoursPerRole", "maxConcurrentPerProvider"];
+/** The fixed-shape top-level sections `config get/set/unset` reaches one field of with a
+ * two-segment key (`review.model`, `bootstrap.untilPlansDone`), each with its field list. */
+export const DOTTED_SECTION_FIELDS = {
+    review: REVIEW_KEYS,
+    check: CHECK_KEYS,
+    idleBackoff: BACKOFF_KEYS,
+    bootstrap: BOOTSTRAP_KEYS,
+};
 /** The valid first segments of a dotted config key — the per-role maps plus the `roles.` and
  * `model.` sections. The generic dotted-shape error suggests against these so a typo'd head
  * (`modle.small`, `maxDailyCostUsdPerRoll.feature`) gets the same did-you-mean the sibling
  * unknown-key errors attach. */
-const DOTTED_KEY_HEADS = [...DOTTED_MAP_KEYS, "roles", "model", "backends"];
+const DOTTED_KEY_HEADS = [...DOTTED_MAP_KEYS, "roles", "model", "backends", ...Object.keys(DOTTED_SECTION_FIELDS)];
 /** Split a config key into its write/get shape: `foo` is top-level,
  * `maxDailyCostUsdPerRole.feature` / `quietHoursPerRole.qa` name one map entry,
  * `roles.qa.model` names one role-entry field, and anything else dotted is an error
@@ -107,9 +116,10 @@ export function parseConfigKey(key) {
     // `roles.<id>.<field>` names one role field). The id is shape-checked only — routing owns
     // which agent ids exist (part 4b); a typo'd field is refused here with the valid ones named.
     if (parts.length === 3 && first === "backends" && second !== undefined && second !== "" && third !== undefined) {
-        // configDir is claude-only (CLAUDE_AGENT_KEYS): a config set backends.pi.configDir would
-        // write a key nothing reads, so it is refused everywhere but claude.
-        const validKeys = second === "claude" ? CLAUDE_AGENT_KEYS : AGENT_KEYS;
+        // configDir/windowReserve are claude/codex-only (CLAUDE_AGENT_KEYS / CODEX_BACKEND_KEYS):
+        // a config set backends.pi.configDir would write a key nothing reads, so it is refused
+        // everywhere but claude and codex.
+        const validKeys = second === "claude" ? CLAUDE_AGENT_KEYS : second === "codex" ? CODEX_BACKEND_KEYS : BACKEND_KEYS;
         if (validKeys.includes(third))
             return { kind: "agent", id: second, field: third };
         return {
@@ -129,6 +139,18 @@ export function parseConfigKey(key) {
             error: `unknown model tier "${second ?? ""}" — a dotted \`model.<tier>\` names one of ${TIER_MAP_KEYS.join(", ")} (e.g. \`config set model.strong huggingface/zai-org/GLM-5.3-Flash:together:low\`)${typoSuffix(second ?? "", TIER_MAP_KEYS)}`,
         };
     }
+    // `<section>.<field>` names one field of a fixed-shape section (review, check, idleBackoff,
+    // bootstrap); the field must be one the schema lists, or the write would be a dead key.
+    if (parts.length === 2 && Object.hasOwn(DOTTED_SECTION_FIELDS, first)) {
+        const section = first;
+        const fields = DOTTED_SECTION_FIELDS[section];
+        if (fields.includes(second ?? ""))
+            return { kind: "section", section, field: second ?? "" };
+        return {
+            kind: "error",
+            error: `unknown ${first} field "${second ?? ""}" (valid fields: ${fields.join(", ")})${typoSuffix(second ?? "", fields)}`,
+        };
+    }
     // A typo'd first segment is the common miss (`maxDailyCostUsdPerRoll.feature`,
     // `modle.small`); when the head is one of the valid ones the shape itself is wrong, so
     // suggesting that head back would mislead — the generic wording is the whole story there.
@@ -137,7 +159,7 @@ export function parseConfigKey(key) {
         : typoSuffix(first, DOTTED_KEY_HEADS);
     return {
         kind: "error",
-        error: `unknown config key "${key}" — dotted keys name one entry of a per-role map or one field of a role entry (e.g. \`maxDailyCostUsdPerRole.feature 1.5\`, \`roles.qa.model x\`); a bare key names a whole top-level value${headHint}`,
+        error: `unknown config key "${key}" — dotted keys name one entry of a per-role map or one field of a role entry (e.g. \`maxDailyCostUsdPerRole.feature 1.5\`, \`roles.qa.model x\`, \`review.model x\`); a bare key names a whole top-level value${headHint}`,
     };
 }
 /** The error `tumwater config get <key>` and `config set <key> <value>` both surface for a

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

@@ -1,12 +1,14 @@
 import { changedConfigKeys, loadConfigCached } from "./config.js";
-import { loopIds } from "../roles/loop-ids.js";
+import { runnerIds } from "../roles/runner-ids.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 { RoleRunner } from "../runner/runner.js";
 import { configPath } from "../paths.js";
+import { errorMessage } from "../text/text.js";
+import { backendsInUse, seedOpencodeCatalog } from "../gates/startup-gate.js";
 import { seedClaudeAccount } from "../agent/claude/claude-account.js";
-import { agentMissingMessage, findAgentBinary, resolveAgentBin } from "../pi/pi-bin.js";
+import { seedCodexAccount, readCodexAccount } from "../agent/codex/codex-account.js";
+import { backendMissingMessage, findBackendBinary, resolveBackendBin } 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) {
@@ -16,7 +18,7 @@ export function newLiveConfigReload(deps) {
     // transition warnings).
     let lastConfigError = null;
     let configMissing = false;
-    let prevEnabled = new Set(loopIds(deps.config));
+    let prevEnabled = new Set(runnerIds(deps.config));
     let live = deps.config;
     // The previous successful reload's config, for the one-shot config_changed event. Seeded from
     // the startup config, so the first poll of an unchanged file logs nothing.
@@ -32,6 +34,13 @@ export function newLiveConfigReload(deps) {
     // 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();
+    // Likewise for the codex-account seed: one `codex login status` per root per process.
+    const liveCodexSeedAttempted = new Set();
+    // Set while a live edit routing a codex seam is being refused for an API-key login, so the
+    // refusal warns once on the transition in (and once again when it re-enters after clearing).
+    let codexLiveRefused = false;
+    // Likewise for the opencode models catalog: one models.dev refresh per root per process.
+    const liveOpencodeSeedAttempted = 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 team — and, worse, skip
@@ -59,8 +68,32 @@ export function newLiveConfigReload(deps) {
                 configMissing = false;
             }
             if (reloaded.config) {
-                live = reloaded.config;
                 const nextConfig = reloaded.config;
+                // A live edit that routes a seam to a codex logged in with an API key is refused before
+                // the reload is applied: startup refuses the same codex seam (decision 5), and here a
+                // warn-only would let the running team spend per-token Codex the budget cap cannot see
+                // (review objection 1). Refusing keeps the last-known-good config, like a missing or
+                // broken file. The seed runs once per root (`codex login status` is a real probe); the
+                // persisted account file is the voice of the refusal on later polls, re-probing a stale
+                // api answer (codex-account.ts) so the operator's `codex login --device-auth` remedy
+                // clears it at the next seed. A subscription codex passes through to the backend loop.
+                const prevBackends = new Set(backendsInUse(prevLive));
+                const newlyRoutedCodex = !prevBackends.has("codex") && backendsInUse(nextConfig).includes("codex");
+                if (newlyRoutedCodex && !liveCodexSeedAttempted.has(deps.root)) {
+                    liveCodexSeedAttempted.add(deps.root);
+                    seedCodexAccount(deps.root, nextConfig);
+                }
+                if (newlyRoutedCodex && readCodexAccount(deps.root)?.billing === "api") {
+                    if (codexLiveRefused)
+                        return prevLive;
+                    codexLiveRefused = true;
+                    warn("refusing live edit: Codex is logged in with an API key; tumwater runs Codex on a ChatGPT subscription only — run `CODEX_HOME=<home> codex login --device-auth`");
+                    return prevLive;
+                }
+                // A poll that did not refuse clears the warn-once marker so a later re-entry into the
+                // refusal (the operator reverts, then re-adds the API-billed codex seam) warns again.
+                codexLiveRefused = false;
+                live = reloaded.config;
                 // A live edit that changes behavior elsewhere logs one event naming the settings that
                 // changed (maxConcurrent and sessionRetentionDays have their own events elsewhere).
                 const changedKeys = changedConfigKeys(prevLive, reloaded.config);
@@ -89,31 +122,37 @@ export function newLiveConfigReload(deps) {
                         });
                 }
                 // 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))
+                // team keeps running, but that backend must be verified and its account (claude) or
+                // models catalog (opencode) 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. (The codex seed moved to the refusal check at the top of
+                // this block, which also refuses an API-key-logged-in codex seam.)
+                for (const backend of backendsInUse(reloaded.config)) {
+                    if (prevBackends.has(backend))
                         continue;
-                    const resolved = resolveAgentBin(reloaded.config, agent);
-                    if (findAgentBinary(resolved)) {
-                        emit({ source: TUMWATER_SOURCE, type: "backend_binary", agent, found: true });
+                    const resolved = resolveBackendBin(reloaded.config, backend);
+                    if (findBackendBinary(resolved)) {
+                        emit({ source: TUMWATER_SOURCE, type: "backend_binary", agent: backend, found: true });
                     }
                     else {
-                        warn(`newly routed ${agent} backend: ${agentMissingMessage(resolved, agent)}`);
+                        warn(`newly routed ${backend} backend: ${backendMissingMessage(resolved, backend)}`);
                     }
-                    if (agent === "claude" && !liveClaudeSeedAttempted.has(deps.root)) {
+                    if (backend === "claude" && !liveClaudeSeedAttempted.has(deps.root)) {
                         liveClaudeSeedAttempted.add(deps.root);
                         seedClaudeAccount(deps.root, reloaded.config);
                     }
+                    if (backend === "opencode" && !liveOpencodeSeedAttempted.has(deps.root)) {
+                        liveOpencodeSeedAttempted.add(deps.root);
+                        // Not awaited: poll() is synchronous and a models.dev fetch must not stall the loop.
+                        void seedOpencodeCatalog(deps.root, reloaded.config, { ...deps.opencodeSeed, warn }).catch((err) => warn(`open code model catalog seed failed: ${errorMessage(err)}`));
+                    }
                 }
                 prevLive = reloaded.config;
                 for (const r of deps.runners)
                     r.config = reloaded.config;
                 // Live-resize the concurrency cap: a mid-run edit changes how many pi runs execute
-                // concurrently within this poll — no restart. Growing admits already-queued ticks;
+                // concurrently within this poll — no restart. Growing admits already-queued runs;
                 // shrinking never preempts in-flight work, it only caps future grants.
                 const newMaxConcurrent = Math.max(1, reloaded.config.maxConcurrent);
                 if (newMaxConcurrent !== lastMaxConcurrent) {
@@ -141,17 +180,17 @@ export function newLiveConfigReload(deps) {
                     }
                 }
                 lastKeyCaps = nextKeyCaps;
-                const nowEnabled = loopIds(reloaded.config);
+                const nowEnabled = runnerIds(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
-                // instance count keeps its runner; `loopEnabled` skips its future ticks. A scoped round
+                // runner for each newly present role id (its persisted state survives). A lowered
+                // instance count keeps its runner; `runnerEnabled` skips its future runs. A scoped round
                 // skips every other id: the enabling is logged (the warn loop below), but its runner
                 // waits for the next unscoped round.
                 for (const role of nowEnabled) {
-                    if (deps.roleFilter !== undefined && role !== deps.roleFilter)
+                    if (deps.roleFilter !== undefined && !deps.roleFilter.includes(role))
                         continue;
                     if (!deps.runners.some((r) => r.role === role))
-                        deps.runners.push(new LoopRunner(deps.root, role, reloaded.config, deps.mainBranch, deps.runnerSignal));
+                        deps.runners.push(new RoleRunner(deps.root, role, reloaded.config, deps.mainBranch, deps.runnerSignal));
                 }
                 for (const role of prevEnabled)
                     if (!nowEnabled.includes(role))