tumwater 0.1.2 → 0.2.0

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

@@ -0,0 +1,379 @@
+// 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
+ * 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 { modelPairName } from "../budget/budget.js";
+import { DIRECTOR_ROLE } from "../roles/roles.js";
+import { baseRoleOf } from "../roles/loop-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";
+/** 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) {
+    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;
+}
+/** The team-level fallback pair: the `default` tier's resolved pair under
+ * resolveTierFallbacks' borrow order, or null when the tier resolves to pause. The
+ * selector-string `fallback` (plans/model-tiers.md), the legacy `fallbackModel` object, and
+ * the map form all feed one resolution — a map with no `default` entry (or a `"pause"` one)
+ * borrows another tier's pair exactly as the budget gate does, so this view and the gate
+ * cannot disagree about which model the team would engage. `usable` filters the pairs that
+ * may supply the answer: the default predicate admits every declared pair (the config-only
+ * view), while a pricing predicate (src/pi/pi-models.ts's fallbackModelPair) yields the pair
+ * the gate would actually engage when a declared `default` pair is priced and a free pair
+ * exists at another tier. One definition so the freeness check, the dashboards' badge, the
+ * doctor, and applyFallbackModel below cannot disagree. */
+export function fallbackPair(config, usable = () => true) {
+    return resolveTierFallbacks(config, usable).default.pair;
+}
+/** The legacy `fallbackModel` object resolved to a pair: its own fields over the top-level
+ * values, the same precedence every other override section uses. Private — reached only
+ * through tierOwnChain (the default tier's own fallback) and so fallbackPair's resolution,
+ * which keeps the object and the string/map forms on one rule without recursing. */
+function legacyFallbackPair(config) {
+    const fbo = config.fallbackModel;
+    if (!fbo)
+        return null;
+    // 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 model = fbo.model ?? topSel?.model;
+    const thinking = fbo.thinking ?? topSel?.thinking ?? config.thinking;
+    return resolvedModelFields(provider, model, thinking);
+}
+/** 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),
+ * and strong never drops to a small model (strong → default → pause) — a weak reviewer or
+ * planner does more harm than a paused one. */
+const BORROW_ORDER = {
+    small: ["small", "default", "strong"],
+    default: ["default", "strong", "small"],
+    strong: ["strong", "default"],
+};
+/** 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. */
+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
+ * `fallback` or the legacy `fallbackModel` object (a one-element chain). Empty when the tier
+ * declares nothing or declares `"pause"` (an explicit opt-out, which also makes it
+ * unborrowable: a tier with no own fallback offers nothing to borrow). Each step is parsed
+ * like fallbackPair: a pure selector, with the ambient top-level thinking when the selector
+ * carries none. */
+function tierOwnChain(config, tier) {
+    const fb = config.fallback;
+    let raw;
+    if (fb !== undefined) {
+        // The top-level string/list form names the default tier's own chain; `"pause"` is rejected
+        // by validation but defensively names no model (matching the map entries below).
+        if (typeof fb === "string" || Array.isArray(fb))
+            raw = tier === "default" ? fb : undefined;
+        else
+            raw = fb[tier];
+    }
+    else if (tier === "default") {
+        // The legacy `fallbackModel` object is the default tier's own fallback, with its
+        // provider/thinking fields and the top-level borrow precedence.
+        const legacy = legacyFallbackPair(config);
+        if (legacy === null)
+            return [];
+        const primaryClaude = withModelOverrides(config, tier, {}).agent === "claude";
+        return [legacy.provider === "claude" && primaryClaude ? { ...legacy, extraUsage: true } : legacy];
+    }
+    if (raw === undefined || raw === "pause")
+        return [];
+    // A Claude step after an earlier Claude model — the tier's primary counts — may spend extra
+    // usage; the first Claude model stays on the subscription. Position alone decides.
+    let claudeSeen = withModelOverrides(config, tier, {}).agent === "claude";
+    return (Array.isArray(raw) ? raw : [raw])
+        .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")
+            claudeSeen = true;
+        return {
+            ...fields,
+            ...(step.maxDailyCostUsd !== undefined ? { maxDailyCostUsd: step.maxDailyCostUsd } : {}),
+            ...(extraUsage ? { extraUsage } : {}),
+        };
+    });
+}
+/** Every step of every tier's own chain, as the pair and its 0-based index in that chain — the
+ * enumeration the budget gate keys its breakers by and seamsInUse checks binaries over. */
+export function tierChainSteps(config) {
+    return MODEL_TIERS.flatMap((tier) => tierOwnChain(config, tier).map((pair, step) => ({ tier, step, pair })));
+}
+const stepField = (step) => (step > 0 ? { step } : {});
+/** Which free pair each tier runs on at the daily cap (plans/model-tiers.md "Budget fallback
+ * by tier", part 5a/8). A tier runs the first `usable(pair)` step of its own declared chain;
+ * otherwise it borrows the first usable step of another tier's OWN chain — never one that
+ * tier itself borrowed — in BORROW_ORDER's order; otherwise it pauses (`pair: null`). The
+ * engine is pure: the caller supplies `usable` (part 5b/8 wires it to pair pricing and the
+ * fallback breaker), so the same rules are testable with a stub and the gates cannot disagree
+ * with each other. A config with no fallback at all resolves every tier to pause, and a single
+ * `fallback: F` reads as default's own pair, which small and strong then borrow — today's
+ * behavior. */
+export function resolveTierFallbacks(config, usable) {
+    const firstUsable = (tier) => {
+        const chain = tierOwnChain(config, tier);
+        const step = chain.findIndex((p) => usable(p));
+        return step < 0 ? undefined : { pair: chain[step], step };
+    };
+    const resolve = (tier) => {
+        const mine = firstUsable(tier);
+        if (mine)
+            return { pair: mine.pair, from: null, ...stepField(mine.step) };
+        for (const t of BORROW_ORDER[tier]) {
+            if (t === tier)
+                continue;
+            const theirs = firstUsable(t);
+            if (theirs)
+                return { pair: theirs.pair, from: t, ...stepField(theirs.step) };
+        }
+        return { pair: null, from: null };
+    };
+    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
+ * 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
+ * tier resolves to pause (no fallback configured), so the feature stays off. Pure. */
+export function fallbackRoleConfig(config, role) {
+    const tier = roleSeamTier(config, role);
+    const pair = resolveTierFallbacks(config, () => true)[tier].pair;
+    if (pair === null)
+        return null;
+    const rc = config.roles[baseRoleOf(role)];
+    return {
+        ...withModelOverrides(config, tier, {
+            provider: pair.provider,
+            model: pair.model,
+            thinking: pair.thinking,
+        }),
+        minRunIntervalSeconds: rc?.minRunIntervalSeconds ?? config.minRunIntervalSeconds,
+    };
+}
+/** Every seam the team can spawn, each with its label: every enabled role's resolved config
+ * (configForRole), the review gate when it is on (reviewRunConfig), the conflict resolver
+ * (resolverConfig), the director (a catalog role, named explicitly so it is never missed), and
+ * each tier's budget fallback (resolveTierFallbacks) — the model-failure fallback
+ * (fallbackRoleConfig) runs the same tier pair, so one enumeration covers it. Deduplicated by
+ * label + routed pair so a seam reached through several surfaces is listed once. Read by the
+ * startup gate's agent list, doctor's pair sweep (and so its binary/credential/version checks
+ * and routing table), and the live-edit reload's newly-routed-backend check — no surface can
+ * miss a seam that exists only as a fallback. */
+export function seamsInUse(config) {
+    const seams = new Map();
+    const add = (label, cfg) => {
+        const key = `${label}\0${cfg.agent ?? ""}\0${cfg.provider ?? ""}\0${cfg.model ?? ""}\0${cfg.thinking ?? ""}`;
+        seams.set(key, {
+            label,
+            agent: cfg.agent,
+            provider: cfg.provider,
+            model: cfg.model,
+            thinking: cfg.thinking,
+        });
+    };
+    for (const role of enabledRoleIds(config))
+        add(role, configForRole(config, role));
+    if (config.review.enabled)
+        add("review", reviewRunConfig(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 }));
+    }
+    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
+ * 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. */
+export function modelFallbackView(episode, config, role, now = Date.now()) {
+    if (episode === undefined || !modelFallbackActive(episode, now))
+        return null;
+    const episodeConfig = fallbackRoleConfig(config, role);
+    if (episodeConfig === null)
+        return null;
+    return {
+        ...resolvedModelFields(episodeConfig.provider, episodeConfig.model, episodeConfig.thinking),
+        ...(episodeConfig.agent !== undefined && episodeConfig.agent !== "pi" ? { backend: episodeConfig.agent } : {}),
+        since: episode.since,
+        reason: episode.reason,
+    };
+}
+/** The per-tier fallback labels the observability surfaces render (part 7b/8): tier →
+ * `provider/model[ (from <tier>)]` for every tier the resolution gives a pair, in tier order.
+ * The `(from …)` suffix marks a borrowed pair — a strong-tier borrow is the fact an operator
+ * reading the feed or the badge can act on. Tiers resolved to pause are left out: the badge
+ * and the event name the pairs that RUN, the pause story lives on the pause events and the
+ * per-role rows. */
+export function tierFallbackLabels(resolved) {
+    const out = {};
+    for (const tier of MODEL_TIERS) {
+        const r = resolved[tier];
+        if (r.pair !== null)
+            out[tier] = modelPairName(r.pair) + (r.from !== null ? ` (from ${r.from})` : "");
+    }
+    return out;
+}
+/** True when the resolution hands out two or more DISTINCT pairs — the condition under which
+ * the tiered surfaces (the budget_fallback event, the header badge) switch from today's
+ * single-pair text to the tier list: a single fallback whose pair the other tiers borrow
+ * resolves every tier to the same pair, and that stays on the single-pair text, byte
+ * identical to the pre-tier surfaces. */
+export function tiersResolveDistinctPairs(resolved) {
+    const pairs = MODEL_TIERS.map((t) => resolved[t].pair)
+        .filter((p) => p !== null)
+        .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
+ * 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;
+    return rest;
+}
+/** The reviewer config as the fallback view sees it: model seam stripped, and its time budget
+ * raised to at least FALLBACK_REVIEW_TIMEOUT_S (a budget sized for the budgeted model's turns
+ * times out every review on a slower free one; a configured value above the floor stands). The
+ * one home of that rule, shared by both fallback branches. */
+function fallbackReview(review) {
+    return {
+        ...stripModel(review),
+        timeoutSeconds: Math.max(review.timeoutSeconds ?? REVIEW_TIMEOUT_S, FALLBACK_REVIEW_TIMEOUT_S),
+    };
+}
+/** Every `roles.<id>` entry with its model seam stripped. With `keepTierNames`, an entry whose
+ * model is a tier name is left untouched: the resolved tier map now serves that tier itself, so
+ * the reference stays valid (stripping it would lose the role's tier). */
+function stripRoleModels(roles, keepTierNames) {
+    return Object.fromEntries(Object.entries(roles).map(([id, rc]) => [
+        id,
+        keepTierNames && isTierName(rc?.model) ? rc : stripModel(rc),
+    ]));
+}
+/** Every `roles.<id>` entry with its model seam stripped, except a seam `free` calls free — a
+ * subscription claude role keeps its own model through the cap rather than moving to the
+ * fallback (plans/agent-backends.md "Free-ness"). With `keepTierNames`, an entry whose model is
+ * a tier name is left untouched: the resolved tier map now serves that tier itself, so the
+ * reference stays valid (stripping it would lose the role's tier). */
+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)];
+    }));
+}
+/** The config as seen by a role loop 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
+ * to the one free pair. Dropping the overrides is the point: a role pinned to a paid model in
+ * tumwater.json must not keep spending after the cap is reached. The one other change is the
+ * reviewer's time budget, raised to at least FALLBACK_REVIEW_TIMEOUT_S: a budget sized for the
+ * budgeted model's turns times out every review on a slower free one (a configured
+ * `review.timeoutSeconds` above the floor stands, and reviewRunConfig still caps it at
+ * runTimeoutSeconds). Everything else (intervals, thresholds, exempt paths, the cap itself) is
+ * unchanged when no fallback is configured. With a per-tier `resolved` map (resolveTierFallbacks,
+ * part 5a/8) the model map is rewritten to the resolved pairs instead — each seam keeps its
+ * tier: `model[tier]` becomes the tier's pair as a selector string, a tier resolved to pause
+ * is left out (it inherits default's entry, harmless because the gate holds its roles), raw
+ * per-role selector overrides are dropped so a paid pin cannot keep spending, and tier-name
+ * role overrides (`roles.<id>.model: "strong"`) are kept since the map now serves the tier
+ * itself. The director's exemption lives in the gates (roleForConfig), not here. A
+ * subscription claude seam is never moved (`free`): the gate passes one predicate over the
+ * resolved seam, so a free tier keeps its own primary in the map — with the ambient thinking
+ * level it resolved with — a free role keeps its own override, and a free reviewer keeps its own
+ * 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;
+        const model = {};
+        const stepCaps = {};
+        for (const tier of MODEL_TIERS) {
+            // A free seam keeps the tier's own primary selector — the backend namespace a resolved
+            // seam has cleared, plus the ambient thinking level `topTierSelector` alone omits. A moved
+            // seam gets its pair selector, which already carries that ambient level.
+            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 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,
+                    });
+                continue;
+            }
+            const sel = selectorOf(resolved[tier]);
+            if (sel !== undefined)
+                model[tier] = sel;
+            const cap = resolved[tier].pair?.maxDailyCostUsd;
+            if (cap !== undefined)
+                stepCaps[modelPairName(resolved[tier].pair)] = cap;
+        }
+        return {
+            ...config,
+            ...(Object.keys(stepCaps).length > 0 ? { fallbackStepCaps: stepCaps } : {}),
+            provider: undefined,
+            model,
+            thinking: undefined,
+            review: free?.(reviewConfig(config)) ? config.review : fallbackReview(config.review),
+            roles: freeRoleModels(config, free),
+        };
+    }
+    const pair = fallbackPair(config);
+    if (!pair)
+        return config;
+    return {
+        ...config,
+        provider: pair.provider,
+        model: pair.model,
+        thinking: pair.thinking,
+        review: fallbackReview(config.review),
+        roles: stripRoleModels(config.roles, false),
+    };
+}

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

@@ -1,3 +1,4 @@
+// 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";
@@ -88,8 +89,16 @@ export const POSITIVE_INTEGER = {
     what: "an integer of at least 1",
 };
 export const AT_LEAST_ONE = { ok: (n) => n >= 1, what: "a number of at least 1" };
+/** The upper bound every seconds field that feeds a ×1000 duration shares: 2147483 s
+ * × 1000 stays inside node's signed-32-bit setTimeout/setInterval range (2^31−1 ms,
+ * about 24.8 days). Above it node clamps the delay to 1ms — a one-zero typo like
+ * `"runTimeoutSeconds": 1e300` became Infinity ms, and every pi run died the moment it
+ * started (BUGS.md 2026-10-03). One home for the bound, shared by the config schema's
+ * duration rules (config-validation.ts) and checkMinRunInterval (config-keys.ts), so the
+ * dashboard's interval editor cannot drift from the schema's bound. */
+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 customLoops cannot
+ * `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
  * 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. */
@@ -102,7 +111,7 @@ export function checkKnownRoleId(section, id, customNames, problems) {
 }
 /** Validate one string field when present. `allowEmpty` defaults true; the model-triple fields
  * pass false — pi-args.ts skips an empty value when it builds its flags, so `"provider": ""`
- * would be silently ignored and the fleet would quietly fall back to pi's default — and an
+ * would be silently ignored and the team would quietly fall back to pi's default — and an
  * empty `fallbackModel` field makes fallbackPair drop it, so the fallback never engages. */
 export function checkStringField(problems, obj, prefix, key, allowEmpty = true) {
     whenPresent(obj, key, (v) => {
@@ -133,24 +142,24 @@ export function checkModelTripleField(problems, obj, prefix, modelShape = "selec
             checkStringField(problems, obj, prefix, key, false);
     const t = obj.thinking;
     if (isNonBlankString(t) && !THINKING_LEVELS.has(t))
-        problems.push(`${prefix}thinking must be one of ${[...THINKING_LEVELS].join(", ")} (got ${show(t)})`);
+        problems.push(`${prefix}thinking must be one of ${[...THINKING_LEVELS].join(", ")} (got ${show(t)})${typoSuffix(t, [...THINKING_LEVELS])}`);
     const m = obj.model;
     if (m === undefined)
         return;
     if (modelShape === "tier-map" && isJsonObject(m)) {
         checkKnownKeys(m, TIER_MAP_KEYS, `${prefix}model`, problems);
         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 selector (got provider ${show(obj.provider)})`);
+            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))
-                problems.push(`${prefix}model.${tier} must be a non-empty selector string (got ${show(v)})`);
+                problems.push(`${prefix}model.${tier} must be a non-empty model id (got ${show(v)})`);
         return;
     }
     if (typeof m !== "string") {
         const what = modelShape === "tier-map"
-            ? "a selector string or a map by tier (small, default, strong)"
+            ? "a model id or a map by tier (small, default, strong)"
             : modelShape === "tier-name"
-                ? "a selector string or a tier name (small, default, strong)"
+                ? "a model id or a tier name (small, default, strong)"
                 : "a string";
         problems.push(`${prefix}model must be ${what} (got ${show(m)})`);
         return;
@@ -162,7 +171,7 @@ export function checkModelTripleField(problems, obj, prefix, modelShape = "selec
     if (MODEL_TIERS.includes(m)) {
         if (modelShape === "tier-name")
             return; // A valid tier reference.
-        problems.push(`${prefix}model must name a selector — tier names are valid only as roles.<id>.model or review.model values (got ${show(m)})`);
+        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)})`);
     }
 }
 /** Validate one numeric field against a NumberRule when present. */
@@ -199,7 +208,7 @@ export function checkStringArrayField(problems, obj, prefix, key) {
 }
 /** Report every passthrough arg in `args` whose flag the harness sets itself — the one screen
  * behind both of validateConfig's reserved-flag checks (top-level `piArgs` and each
- * `agents.<id>.args`). `argsPath` names the array in the message (`piArgs`, `agents.pi.args`),
+ * `backends.<id>.args`). `argsPath` names the array in the message (`piArgs`, `backends.pi.args`),
  * and `whyFor` resolves the flag's reason against the reserved set it is screened against, or
  * undefined when the flag is not reserved. The flag is matched even when the arg carries its
  * value as `--flag=value` (split on the first `=`), so that joined spelling cannot slip past
@@ -211,6 +220,6 @@ export function checkReservedArgs(problems, args, argsPath, whyFor) {
             return;
         const why = whyFor(arg.split("=", 1)[0]);
         if (why)
-            problems.push(`${argsPath}[${i}] ${show(arg)} duplicates a flag the harness sets — ${why}`);
+            problems.push(`${argsPath}[${i}] ${show(arg)} duplicates a flag tumwater sets — ${why}`);
     });
 }

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

@@ -0,0 +1,160 @@
+// 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;
+ * 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 { typoSuffix } from "../text/suggest.js";
+import { MAX_DURATION_SECONDS, POSITIVE_INTEGER, show } from "./config-field-checks.js";
+import { parseQuietHours } from "../scheduling/quiet-hours.js";
+/** One definition of "a valid daily budget cap" (the TUI's Ctrl+B editor and the GUI's
+ * /api/budget endpoint both run their input through it): a finite number of 0 or more —
+ * 0 disables the gate, fractional dollars allowed (the badge renders cents). Returns an
+ * actionable error message for anything else so both surfaces can flash it without
+ * try/catch plumbing. A value past Number.MAX_SAFE_INTEGER is rejected too: it stays
+ * finite ("9"×25 → 1e24), so only this screen stands between a one-zero typo in the
+ * browser's budget editor and an effectively uncapped budget (BUGS.md 2026-10-02, the
+ * same rule the TUI's parseBudgetInput applies). `key` names the config key in the error,
+ * defaulting to the team-wide `maxDailyCostUsd`; the per-role map passes
+ * `maxDailyCostUsdPerRole.<id>` so a rejected entry names the key actually set. */
+export function checkDailyBudgetUsd(value, key = "maxDailyCostUsd") {
+    if (typeof value !== "number" ||
+        !Number.isFinite(value) ||
+        value < 0 ||
+        value > Number.MAX_SAFE_INTEGER)
+        return `${key} must be a number of 0 or more, at most ${Number.MAX_SAFE_INTEGER}, 0 disables (got ${show(value)})`;
+    return null;
+}
+/** One definition of "a valid per-provider concurrency cap" (plans/provider-concurrency.md
+ * §1): a positive integer, accepted for any (possibly unknown) provider name — a fallback's
+ * provider may only come into use later, so the key is not checked against a catalog. The one
+ * validation both `config set maxConcurrentPerProvider.<provider>` and validateConfig show,
+ * so they cannot drift apart on what a valid cap is. `key` names the config key in the error,
+ * defaulting to the map name; the dotted map passes `maxConcurrentPerProvider.<provider>`
+ * so a rejected entry names the key actually set. */
+export function checkProviderConcurrencyCap(value, key = "maxConcurrentPerProvider") {
+    if (typeof value !== "number" || !Number.isFinite(value) || !Number.isInteger(value) || value < 1)
+        return `${key} must be ${POSITIVE_INTEGER.what} (got ${show(value)})`;
+    return null;
+}
+/** One definition of "a valid quietHours window" (src/scheduling/quiet-hours.ts owns the format):
+ * "HH:MM-HH:MM" in local time, wrapping permitted, empty means off. parseQuietHours's
+ * message is the one wording every surface (validateConfig, `config set`, the TUI/GUI
+ * editors) shows, so they cannot drift apart on what a valid window is. `key` names the
+ * config key in the error, defaulting to the team-wide `quietHours`; the per-role map passes
+ * `quietHoursPerRole.<id>` so a rejected entry names the key actually set. */
+export function checkQuietHours(value, key = "quietHours") {
+    const parsed = parseQuietHours(value, key);
+    return parsed.ok ? null : parsed.error;
+}
+/** One definition of "a valid min run interval" — the seconds value the team-wide
+ * `minRunIntervalSeconds` and a per-role `roles.<id>.minRunIntervalSeconds` override hold:
+ * a finite number of 0 or more, at most MAX_DURATION_SECONDS (the ×1000 setTimeout bound the
+ * config schema's duration rules share). The dashboard's interval editor runs this before
+ * writing; `config set roles.<id>.minRunIntervalSeconds` leans on validateConfig's
+ * DURATION_NON_NEGATIVE for the CLI path instead, but the two cannot drift on the upper bound
+ * because both read the same MAX_DURATION_SECONDS constant. `key` names the config key in the
+ * error, defaulting to the team-wide `minRunIntervalSeconds`; the per-role path passes
+ * `roles.<id>.minRunIntervalSeconds` so a rejected entry names the key actually set. */
+export function checkMinRunInterval(value, key = "minRunIntervalSeconds") {
+    if (typeof value !== "number" ||
+        !Number.isFinite(value) ||
+        value < 0 ||
+        value > MAX_DURATION_SECONDS)
+        return `${key} must be a number of 0 or more, at most ${MAX_DURATION_SECONDS} (got ${show(value)})`;
+    return null;
+}
+/** Per-key value validators `config set` (and the dashboard editors that call it) run
+ * BEFORE the write, so a malformed value fails with its own actionable message instead of
+ * waiting for validateConfig's whole-file report. */
+export const PER_KEY_VALIDATORS = {
+    quietHours: checkQuietHours,
+};
+/** The per-role maps `config get/set` reaches with dotted keys: each names ONE entry
+ * (`maxDailyCostUsdPerRole.<role>`, `quietHoursPerRole.<role>`) that merges into the
+ * existing map, so raising one role's cap never requires re-typing another's. The
+ * `maxConcurrentPerProvider` map is dotted the same way (`maxConcurrentPerProvider.<provider>`);
+ * its keys are provider names, not role ids, so its per-key validation skips the role-catalog
+ * 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 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"];
+/** 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
+ * naming the supported dotted forms. */
+export function parseConfigKey(key) {
+    if (!key.includes("."))
+        return { kind: "top", key };
+    const parts = key.split(".");
+    const first = parts[0] ?? "";
+    const second = parts.length > 1 ? parts[1] ?? "" : undefined;
+    const third = parts.length > 2 ? parts[2] ?? "" : undefined;
+    if (third === undefined && second !== undefined && second !== "" && DOTTED_MAP_KEYS.includes(first))
+        return { kind: "map", map: first, role: second };
+    if (parts.length === 3 && first === "roles" && second !== undefined && second !== "" && third !== undefined && third !== "")
+        return { kind: "role", id: second, field: third };
+    // `backends.<id>.<field>` names one field of one agent backend's entry (the way
+    // `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;
+        if (validKeys.includes(third))
+            return { kind: "agent", id: second, field: third };
+        return {
+            kind: "error",
+            error: `unknown backend field "${third}" for backends.${second} (valid fields: ${validKeys.join(", ")})${typoSuffix(third, validKeys)}`,
+        };
+    }
+    // `model.<tier>` names one entry of the tier model map — the way `roles.<id>.model`
+    // names one role field, `maxDailyCostUsdPerRole.<role>` names one map entry. The tier
+    // must be a real tier: `config set model.turbo x` would otherwise write a dead map key
+    // the runtime (and doctor's checkKnownKeys) would silently never resolve.
+    if (parts.length === 2 && first === "model") {
+        if ((TIER_MAP_KEYS).includes(second ?? ""))
+            return { kind: "tier", map: "model", tier: second };
+        return {
+            kind: "error",
+            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)}`,
+        };
+    }
+    // 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.
+    const headHint = DOTTED_KEY_HEADS.includes(first)
+        ? ""
+        : 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}`,
+    };
+}
+/** The error `tumwater config get <key>` and `config set <key> <value>` both surface for a
+ * key outside TOP_LEVEL_KEYS — the valid-keys list plus text.ts's did-you-mean suggestion —
+ * or null when the key is known. One home for the phrasing so whichever verb misspells a
+ * key, the typo reads the same. */
+export function unknownConfigKeyError(key) {
+    if (TOP_LEVEL_KEYS.includes(key))
+        return null;
+    return `unknown config key "${key}" (valid top-level keys: ${TOP_LEVEL_KEYS.join(", ")})${typoSuffix(key, TOP_LEVEL_KEYS)}`;
+}
+/** The error for a dotted role key naming a field ROLE_ENTRY_KEYS does not hold — the one
+ * home of the wording `config set` and `config get` both surface, so a typo'd `roles.qa.colour`
+ * reads the same whichever verb names it (both refuse it; a silent `null` from get would look
+ * like a real unset value). Null when the field is a known role-entry key. */
+export function unknownRoleFieldError(id, field) {
+    if (ROLE_ENTRY_KEYS.includes(field))
+        return null;
+    return `unknown role field "${field}" for roles.${id} (valid fields: ${ROLE_ENTRY_KEYS.join(", ")})${typoSuffix(field, ROLE_ENTRY_KEYS)}`;
+}