tumwater 0.1.2 → 0.2.0

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

@@ -1,57 +1,27 @@
+// vocabulary: plain
 /** Harness-mediated config WRITES — the mutators behind the operator surfaces (the TUI's
  * Ctrl+B editor, the GUI's /api/budget endpoint) and the director's config requests. Each
  * one loads fresh (bypassing config.ts's stat cache), validates before writing, and writes
  * atomically, because readers poll tumwater.json every ~2 s. The read side — defaults,
- * loading, saving, and the role-selection helpers — lives in config.ts, and the per-run
- * model derivations in config-views.ts. */
+ * loading, saving, and the role-selection helpers — lives in config.ts, the per-run
+ * model derivations in config-views.ts, and the config KEY language — how keys are parsed,
+ * addressed and given per-key value screeners — lives in config-keys.ts (both the write
+ * verbs here and the read side / doctor share it). */
 import fs from "node:fs";
-import { AGENT_KEYS, modelTierMap, ROLE_ENTRY_KEYS, TIER_MAP_KEYS, TOP_LEVEL_KEYS, } from "./config-schema.js";
+import { modelTierMap } from "./config-schema.js";
 import { configPath, configLockPath, configRequestPath, CONFIG_BASENAME } from "../paths.js";
 import { errorMessage } from "../text/text.js";
-import { typoSuffix } from "../text/suggest.js";
 import { writeJsonAtomic } from "../files/json-files.js";
 import { isJsonObject, objectOrEmpty } from "../files/json-object.js";
 import { withStateLock } from "../concurrency/lock.js";
 import { show } from "./config-field-checks.js";
 import { validateConfig } from "./config-validation.js";
-import { loadConfig, parseJsonConfig, collapseAgentAliases } from "./config.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 fleet-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 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 fleet-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;
-}
-/** 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. */
-const PER_KEY_VALIDATORS = {
-    quietHours: checkQuietHours,
-};
+import { canonicalConfigKey, normalizeConfigKeys } from "./config-aliases.js";
+import { unknownRoleMessage } from "../roles/roles.js";
+import { loadConfig, parseJsonConfig, collapseAgentAliases, knownRoleIdsCached } from "./config.js";
+import { checkDailyBudgetUsd, checkProviderConcurrencyCap, checkQuietHours, parseConfigKey, PER_KEY_VALIDATORS, unknownConfigKeyError, unknownRoleFieldError, } from "./config-keys.js";
 /** Serialize a config write through the cross-process lock (paths.ts's configLockPath): the
- * CLI, a standalone dashboard's server, and the running fleet are separate processes, so an
+ * CLI, a standalone dashboard's server, and the running team are separate processes, so an
  * unguarded read-modify-write lets one writer's whole-file write silently drop another's change
  * (the same lost update paused-roles.json already guards against). A lock that cannot be
  * acquired within the budget throws rather than writing unlocked — a silently lost config edit
@@ -62,6 +32,12 @@ function withConfigLock(root, fn) {
     // file).
     return withStateLock(configLockPath(root), fn, CONFIG_LOCK_TIMEOUT_MS);
 }
+/** The error arm of the shared write-result union — one home for the `{ ok: false, error }`
+ * constructor every writer's failure path returns (a broken on-disk file, a validation
+ * problem, a failed write, a lost lock), so the shape cannot drift between callers. */
+function fail(error) {
+    return { ok: false, error };
+}
 /** The one load → mutate → validate → atomic-write idiom every top-level config writer
  * shares (setDailyBudgetUsd, setConfigKey): a fresh loadConfig that bypasses config.ts's
  * stat cache (a writer must see the latest file), the caller's mutation applied in memory,
@@ -80,7 +56,7 @@ function writeConfigMutation(root, mutate) {
                 cfg = loadConfig(root); // fresh — bypasses the stat cache on purpose
             }
             catch (err) {
-                return { ok: false, error: errorMessage(err) }; // broken file: never overwrite it with defaults
+                return fail(errorMessage(err)); // broken file: never overwrite it with defaults
             }
             const mutated = mutate(cfg);
             // An unset that finds nothing to remove returns the loaded config unchanged. Write nothing:
@@ -96,20 +72,20 @@ function writeConfigMutation(root, mutate) {
                 validateConfig(candidate); // throws listing every problem — nothing is written on failure
             }
             catch (err) {
-                return { ok: false, error: errorMessage(err) };
+                return fail(errorMessage(err));
             }
             try {
                 // The trailing newline is tumwater.json's convention (POSIX text file).
                 writeJsonAtomic(configPath(root), candidate, true);
             }
             catch (err) {
-                return { ok: false, error: errorMessage(err) };
+                return fail(errorMessage(err));
             }
             return { ok: true };
         });
     }
     catch (err) {
-        return { ok: false, error: errorMessage(err) }; // lock acquire timeout/failure — nothing written
+        return fail(errorMessage(err)); // lock acquire timeout/failure — nothing written
     }
 }
 /** Set the daily cost budget cap in tumwater.json through the shared writer idiom (see
@@ -118,7 +94,7 @@ function writeConfigMutation(root, mutate) {
 export function setDailyBudgetUsd(root, value) {
     const problem = checkDailyBudgetUsd(value);
     if (problem)
-        return { ok: false, error: problem };
+        return fail(problem);
     return writeConfigMutation(root, (cfg) => {
         const next = { ...cfg, maxDailyCostUsd: value };
         // A whole-config write: keep the file's own roles section (see preserveFileRoles).
@@ -126,83 +102,6 @@ export function setDailyBudgetUsd(root, value) {
         return next;
     });
 }
-/** 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 per-key
- * value validator runs before the write, the same screening a bare top-level key gets. */
-const DOTTED_MAP_KEYS = ["maxDailyCostUsdPerRole", "quietHoursPerRole"];
-/** 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", "agents"];
-/** 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 };
-    // `agents.<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 === "agents" && second !== undefined && second !== "" && third !== undefined) {
-        if (AGENT_KEYS.includes(third))
-            return { kind: "agent", id: second, field: third };
-        return {
-            kind: "error",
-            error: `unknown agent field "${third}" for agents.${second} (valid fields: ${AGENT_KEYS.join(", ")})${typoSuffix(third, AGENT_KEYS)}`,
-        };
-    }
-    // `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)}`;
-}
 /** Set ONE top-level key of tumwater.json from its raw CLI text (`tumwater config set`'s
  * engine): the key must be a member of TOP_LEVEL_KEYS — the same protection checkKnownKeys
  * gives the file itself, so `config set modle x` cannot write a dead key the runtime would
@@ -219,9 +118,10 @@ export function unknownRoleFieldError(id, field) {
  * actionable message. Returns the parsed value and the previous one so the caller can
  * confirm the change; on any failure the file is untouched (see writeConfigMutation). */
 export function setConfigKey(root, key, rawValue) {
+    key = canonicalConfigKey(key);
     const parsed = parseConfigKey(key);
     if (parsed.kind === "error")
-        return { ok: false, error: parsed.error };
+        return fail(parsed.error);
     let value;
     try {
         value = JSON.parse(rawValue);
@@ -232,21 +132,22 @@ export function setConfigKey(root, key, rawValue) {
     if (parsed.kind !== "top") {
         const fieldError = parsed.kind === "role" ? unknownRoleFieldError(parsed.id, parsed.field) : null;
         if (fieldError)
-            return { ok: false, error: fieldError };
+            return fail(fieldError);
         if (parsed.kind === "map") {
             // Name the key the operator actually typed (`maxDailyCostUsdPerRole.qa`), not the
-            // fleet-wide field the shared validator's message would otherwise default to.
+            // team-wide field the shared validator's message would otherwise default to.
             const label = `${parsed.map}.${parsed.role}`;
-            const validator = parsed.map === "maxDailyCostUsdPerRole" ? checkDailyBudgetUsd : checkQuietHours;
+            const validator = parsed.map === "maxDailyCostUsdPerRole"
+                ? checkDailyBudgetUsd
+                : parsed.map === "maxConcurrentPerProvider"
+                    ? checkProviderConcurrencyCap
+                    : checkQuietHours;
             const problem = validator(value, label);
             if (problem)
-                return { ok: false, error: problem };
+                return fail(problem);
         }
         if (parsed.kind === "tier" && (typeof value !== "string" || value === "")) {
-            return {
-                ok: false,
-                error: `model.${parsed.tier} must be a model selector string (e.g. \`config set model.strong huggingface/zai-org/GLM-5.3-Flash:together:low\`) — got ${show(value)}`,
-            };
+            return fail(`model.${parsed.tier} must be a model id (e.g. \`config set model.strong huggingface/zai-org/GLM-5.3-Flash:together:low\`) — got ${show(value)}`);
         }
         let oldValue;
         const result = writeConfigMutation(root, (cfg) => {
@@ -272,12 +173,12 @@ export function setConfigKey(root, key, rawValue) {
                 // Merge one field of one backend's entry, preserving the other field and the other
                 // backends. validateConfig in writeConfigMutation owns the value type, so a bad
                 // value fails there and nothing is written.
-                const agents = { ...record.agents };
+                const agents = { ...record.backends };
                 const entry = { ...(agents[parsed.id] ?? {}) };
                 oldValue = entry[parsed.field];
                 entry[parsed.field] = value;
                 agents[parsed.id] = entry;
-                const next = { ...cfg, agents };
+                const next = { ...cfg, backends: agents };
                 // Writers keep one spelling: the new pi form drops its legacy alias so the file can
                 // never hold both (validateConfig's raw pass rejects a file that does).
                 if (parsed.id === "pi") {
@@ -313,7 +214,7 @@ export function setConfigKey(root, key, rawValue) {
     }
     const unknown = unknownConfigKeyError(key);
     if (unknown)
-        return { ok: false, error: unknown };
+        return fail(unknown);
     // Legacy `provider` / `fallbackModel` are accepted to FIX an existing value (a config
     // that already has one keeps the old meaning), but `config set` never adds them to a
     // config that lacks them — the new-form writers emit `model` and `fallback` only.
@@ -328,16 +229,13 @@ export function setConfigKey(root, key, rawValue) {
             }
         })();
         if (absent)
-            return {
-                ok: false,
-                error: `config set ${key}: this config has no ${key}, and a writer never adds legacy ${key} — set \`${key === "provider" ? "model" : "fallback"}\` instead`,
-            };
+            return fail(`config set ${key}: this config has no ${key}, and a writer never adds legacy ${key} — set \`${key === "provider" ? "model" : "fallback"}\` instead`);
     }
     const perKeyValidator = PER_KEY_VALIDATORS[key];
     if (perKeyValidator) {
         const problem = perKeyValidator(value);
         if (problem)
-            return { ok: false, error: problem };
+            return fail(problem);
     }
     let oldValue;
     const result = writeConfigMutation(root, (cfg) => {
@@ -349,29 +247,26 @@ export function setConfigKey(root, key, rawValue) {
         // When the key IS `roles` the value is the replacement, so it is left alone.
         if (key !== "roles")
             preserveFileRoles(root, next);
-        // Writers keep one spelling: a whole-section `agents` set (the GUI Save path) drops the
+        // Writers keep one spelling: a whole-section `backends` set (the GUI Save path) drops the
         // legacy aliases the new pi form now carries, so the file can never hold both.
-        if (key === "agents" && isJsonObject(value)) {
-            const pi = isJsonObject(value.pi) ? value.pi : undefined;
-            const record = next;
-            if (pi?.bin !== undefined)
-                delete record.agentBin;
-            if (pi?.args !== undefined)
-                delete record.piArgs;
-            return next;
-        }
-        // Writers keep one spelling: a legacy top-level set drops the matching agents.pi field, so
+        // Writers keep one spelling: a whole-section `backends` set (the GUI Save path) drops the
+        // legacy agentBin/piArgs aliases the new pi form now carries, so the file can never hold
+        // both — the same collapseAgentAliases rule the whole-config writers (above and in
+        // config.ts) use, so the alias policy cannot drift between the per-key arm and the others.
+        if (key === "backends")
+            return collapseAgentAliases(next);
+        // Writers keep one spelling: a legacy top-level set drops the matching backends.pi field, so
         // the file can never hold both (validateConfig's raw pass rejects a file that does).
         if (key === "agentBin" || key === "piArgs") {
             const record = next;
-            const agents = { ...(record.agents ?? {}) };
+            const agents = { ...(record.backends ?? {}) };
             const entry = { ...(agents.pi ?? {}) };
             delete entry[key === "agentBin" ? "bin" : "args"];
             if (Object.keys(entry).length === 0)
                 delete agents.pi;
             else
                 agents.pi = entry;
-            return { ...next, agents };
+            return { ...next, backends: agents };
         }
         return next;
     });
@@ -379,6 +274,66 @@ export function setConfigKey(root, key, rawValue) {
         return result;
     return { ok: true, value, oldValue };
 }
+/** Set a role's provider/model/thinking override triple in tumwater.json (`roles.<base>`),
+ * the write behind the dashboard role drawer's Model overrides editor: one writeConfigMutation
+ * rebuilds `roles.<base>` from the FILE's own `roles` section (the `rawConfigObject(root).roles` /
+ * `objectOrEmpty` idiom setConfigKey's role branch uses, so the write never re-expands the
+ * operator's partial section), and validateConfig's `roles.<id>` check (checkModelTriple,
+ * modelShape "tier-name") owns the whole candidate, so a bad `thinking` level writes nothing.
+ * An unknown base id writes nothing too — refused up front, because validateConfig is skipped
+ * on the no-op path (a clear of fields a role the file never held changes nothing) and the
+ * writer must not answer a phantom role "updated". `undefined` leaves that field as the file
+ * has it; `""` deletes it (never stores an empty string, which checkStringField rejects), and
+ * clearing the entry's last override removes `roles.<base>` entirely rather than leaving an
+ * empty object (the file-wide no-empty-object invariant unsetConfigKey's `without` keeps).
+ * An all-no-op call (every named field already absent-or-equal) returns the loaded config
+ * unchanged and writeConfigMutation skips the write, so clearing keys the file never held
+ * leaves its bytes identical. */
+export function setRoleModelFields(root, base, fields) {
+    // An unknown base id writes nothing. validateConfig owns the refusal when the write changes
+    // the candidate, but it is skipped on the no-op path (clearing fields a role the file never
+    // held changes nothing), so refuse the phantom role up front — the same knownRoleIds guard
+    // the CLI's unsetConfigKey clear paths and the GUI's rejectBadRole use — rather than answer
+    // a bogus id "updated".
+    if (!knownRoleIdsCached(root).includes(base))
+        return fail(unknownRoleMessage(base, knownRoleIdsCached(root)));
+    return writeConfigMutation(root, (cfg) => {
+        const rawRolesCandidate = rawConfigObject(root).roles;
+        const rawRoles = objectOrEmpty(rawRolesCandidate);
+        const rawEntryCandidate = rawRoles[base];
+        const rawEntry = objectOrEmpty(rawEntryCandidate);
+        const nextEntry = { ...rawEntry };
+        let changed = false;
+        for (const [key, value] of Object.entries(fields)) {
+            if (value === undefined)
+                continue; // leave that field as the file has it
+            if (value === "") {
+                if (Object.prototype.hasOwnProperty.call(nextEntry, key)) {
+                    delete nextEntry[key];
+                    changed = true;
+                }
+            }
+            else if (nextEntry[key] !== value) {
+                nextEntry[key] = value;
+                changed = true;
+            }
+        }
+        if (!changed)
+            return cfg; // writeConfigMutation skips the write — file bytes identical
+        const nextRoles = { ...rawRoles };
+        // Clearing the entry's last override empties it — never leave an empty `roles.<base>: {}`
+        // (the file-wide no-empty-object invariant unsetConfigKey's `without` keeps); an emptied
+        // entry falls back to the catalog's defaults at load. When the section empties entirely,
+        // drop the `roles` key too, exactly as unsetConfigKey's role branch does.
+        if (Object.keys(nextEntry).length === 0)
+            delete nextRoles[base];
+        else
+            nextRoles[base] = nextEntry;
+        if (Object.keys(nextRoles).length === 0)
+            return without(cfg, "roles");
+        return { ...cfg, roles: nextRoles };
+    });
+}
 /** A shallow copy of `obj` without `key` — the copy each `unsetConfigKey` branch edits
  * before it decides whether the removal emptied its container, and the shape the branch then
  * returns when it did (an emptied map, the last field of a `roles.<id>` entry, an emptied
@@ -390,7 +345,7 @@ function without(obj, key) {
 }
 /** The raw parsed tumwater.json as a plain object — the pre-defaults view `unsetConfigKey`'s
  * presence check needs, because the merged config always carries defaults a top-level key or a
- * `roles.<id>.<field>` (e.g. the seeded `minTickIntervalSeconds`) may never have been set to.
+ * `roles.<id>.<field>` (e.g. the seeded `minRunIntervalSeconds`) may never have been set to.
  * Read inside writeConfigMutation's lock; a missing or unparsable file is `{}` (loadConfig has
  * already rejected a broken file before a mutation runs, and an absent file is the bare
  * defaults — there is nothing to retract). */
@@ -418,7 +373,7 @@ function preservingFileRoles(root, candidate) {
     return candidate;
 }
 /** The config with top-level `key` set to `section`, or removed when `section` is empty — the
- * unset shape for the per-role maps, `model` tiers and `agents`, which never leave an empty
+ * unset shape for the per-role maps, `model` tiers and `backends`, which never leave an empty
  * object in the file. A whole-config write, so the file's own roles section is kept. */
 function withSectionOrDropped(root, cfg, key, section) {
     const next = Object.keys(section).length === 0 ? without(cfg, key) : { ...cfg, [key]: section };
@@ -431,9 +386,9 @@ function withSectionOrDropped(root, cfg, key, section) {
  * preserving its siblings, so an operator retracts one role's override without re-typing the
  * rest. The containing map/`model` key is dropped when it empties, so the file never keeps an
  * empty object (a `roles.<id>` entry cannot empty through the CLI: loadConfig always seeds
- * `enabled`/`minTickIntervalSeconds`). Presence is judged against the raw FILE, not the merged
+ * `enabled`/`minRunIntervalSeconds`). Presence is judged against the raw FILE, not the merged
  * config: a key the file never set but the defaults fill in (a top-level `quietHours`/
- * `maxConcurrent`, a seeded `roles.<id>.minTickIntervalSeconds`) is nothing to remove, so the
+ * `maxConcurrent`, a seeded `roles.<id>.minRunIntervalSeconds`) is nothing to remove, so the
  * mutation returns the loaded config unchanged and writeConfigMutation skips the write — the
  * file's bytes stay identical rather than being re-serialized with the defaults expanded.
  * Legacy `provider`/`fallbackModel` unset normally — only
@@ -442,18 +397,19 @@ function withSectionOrDropped(root, cfg, key, section) {
  * still own truth, so a rejected candidate leaves the file byte-identical. oldValue is the
  * file's own value removed, or `undefined` when the file never held it. */
 export function unsetConfigKey(root, key) {
+    key = canonicalConfigKey(key);
     const parsed = parseConfigKey(key);
     if (parsed.kind === "error")
-        return { ok: false, error: parsed.error };
+        return fail(parsed.error);
     if (parsed.kind === "role") {
         const fieldError = unknownRoleFieldError(parsed.id, parsed.field);
         if (fieldError)
-            return { ok: false, error: fieldError };
+            return fail(fieldError);
     }
     if (parsed.kind === "top") {
         const unknown = unknownConfigKeyError(key);
         if (unknown)
-            return { ok: false, error: unknown };
+            return fail(unknown);
     }
     let oldValue;
     const result = writeConfigMutation(root, (cfg) => {
@@ -493,22 +449,22 @@ export function unsetConfigKey(root, key) {
         }
         if (parsed.kind === "agent") {
             // Presence is judged against the FILE, so unsetting a field only the default (or the
-            // legacy alias's resolved view) carries is a no-op success. The entry and the `agents`
+            // legacy alias's resolved view) carries is a no-op success. The entry and the `backends`
             // section are dropped when they empty, so the file never keeps an empty object.
-            const rawAgents = objectOrEmpty(raw.agents);
+            const rawAgents = objectOrEmpty(raw.backends);
             const rawEntryCandidate = rawAgents[parsed.id];
             const rawEntry = objectOrEmpty(rawEntryCandidate);
             if (!Object.hasOwn(rawEntry, parsed.field))
                 return cfg; // absent file field: a no-op success
             oldValue = rawEntry[parsed.field];
-            const agents = { ...record.agents };
+            const agents = { ...record.backends };
             const entry = { ...(agents[parsed.id] ?? {}) };
             delete entry[parsed.field];
             if (Object.keys(entry).length === 0)
                 delete agents[parsed.id];
             else
                 agents[parsed.id] = entry;
-            return withSectionOrDropped(root, cfg, "agents", agents);
+            return withSectionOrDropped(root, cfg, "backends", agents);
         }
         const rawRolesCandidate = raw.roles;
         const rawRoles = objectOrEmpty(rawRolesCandidate);
@@ -535,13 +491,13 @@ export function unsetConfigKey(root, key) {
 }
 /** Consume the director's config-write request file (plans/portability.md §3/7). After its pi
  * run the director may leave `.tumwater-config-request.json` at its worktree root:
- * `{ "customLoops": [ { "name", "task" }, … ] }` — the whole array, replacing the current one.
+ * `{ "customRoles": [ { "name", "task" }, … ] }` — the whole array, replacing the current one.
  * Applied atomically to the live config with setDailyBudgetUsd's idiom (fresh loadConfig that
  * bypasses the stat cache, validateConfig, then writeJsonAtomic — readers poll every ~2 s), so
  * the orchestrator's live reload starts the new loop with no commit, no review gate, and no
  * merge, and the request file never enters a diff.
  *
- * The permitted key set is enforced here, not in prose: `customLoops` is accepted and every
+ * The permitted key set is enforced here, not in prose: `customRoles` is accepted and every
  * other top-level key is collected into `ignored` and dropped (the caller logs the warning that
  * names them). Validation runs BEFORE any write and nothing here dereferences a request entry
  * first — a structurally malformed entry (`[null]`, a non-string name) is left for
@@ -574,16 +530,21 @@ export function applyConfigRequest(root, wt) {
     let applied = [];
     let error;
     try {
-        const parsed = JSON.parse(raw);
-        if (!isJsonObject(parsed))
-            throw new Error(`config request must be a JSON object (got ${show(parsed)})`);
+        const unnormalized = JSON.parse(raw);
+        if (!isJsonObject(unnormalized))
+            throw new Error(`config request must be a JSON object (got ${show(unnormalized)})`);
+        // Old key spellings read as the new ones; a request setting both fails with the pair named.
+        const normalized = normalizeConfigKeys(unnormalized);
+        if (normalized.problems.length > 0)
+            throw new Error(normalized.problems.join("; "));
+        const parsed = normalized.raw;
         for (const key of Object.keys(parsed)) {
-            if (key !== "customLoops")
+            if (key !== "customRoles")
                 ignored.push(key);
         }
-        const loops = parsed.customLoops;
+        const loops = parsed.customRoles;
         if (!Array.isArray(loops))
-            throw new Error(`config request's customLoops must be an array (got ${show(loops)})`);
+            throw new Error(`config request's customRoles must be an array (got ${show(loops)})`);
         // The load-to-write sequence is one critical section under withConfigLock: a concurrent
         // `config set`/dashboard write between the load and this write must not be dropped by the
         // whole-file overwrite (see writeConfigMutation).
@@ -603,13 +564,13 @@ export function applyConfigRequest(root, wt) {
             // only from what the file actually holds.
             const rawRolesCandidate = rawConfigObject(root).roles;
             const roles = isJsonObject(rawRolesCandidate)
-                ? { ...rawRolesCandidate }
+                ? { ...(rawRolesCandidate) }
                 : {};
-            for (const c of current.customLoops) {
+            for (const c of current.customRoles) {
                 if (!requestedNames.has(c.name))
                     delete roles[c.name];
             }
-            const candidate = { ...current, customLoops: loops };
+            const candidate = { ...current, customRoles: loops };
             const candidateRecord = candidate;
             if (rawRolesCandidate === undefined)
                 delete candidateRecord.roles;
@@ -617,11 +578,11 @@ export function applyConfigRequest(root, wt) {
                 candidateRecord.roles = roles;
             // Collapse legacy/new pi spellings before writing so a merged config (which always
             // carries the default piArgs) never lands both forms in the file — the next load's raw
-            // pass rejects a file holding both `piArgs` and `agents.pi.args`.
+            // pass rejects a file holding both `piArgs` and `backends.pi.args`.
             const collapsed = collapseAgentAliases(candidate);
             validateConfig(collapsed); // throws listing every problem — nothing is written on failure
             writeJsonAtomic(configPath(root), collapsed, true);
-            applied = collapsed.customLoops.map((c) => c.name);
+            applied = collapsed.customRoles.map((c) => c.name);
         });
     }
     catch (err) {