tumwater 0.2.0 → 0.4.0

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

@@ -1,25 +1,25 @@
-// vocabulary: plain
 /** The config AS SEEN BY A RUN — the per-seam resolution half of the config views, split out
  * of config.ts: which provider/model/thinking a role, the reviewer, or the conflict resolver
  * resolves to, and which timeout a reviewer run gets. The budget/tier fallback side — which
  * free pair the team runs on at the daily cap, and the per-role fallback config (fallbackPair,
  * resolveTierFallbacks, applyFallbackModel, …) — lives in config-fallbacks.ts, which builds on
  * this module one-way. No I/O and no caching — the persistence side (defaults, loading,
- * saving, the role-selection helpers) lives in config.ts, the write side in config-write.ts. */
+ * saving, the role-selection helpers) lives in config.ts, the write side in config-write.ts
+ * (editor verbs) and config-request.ts (the director's staged request). */
 import { MODEL_TIERS } from "./config-schema.js";
-import { formatModelSelector, isAgentId, parseModelSelector, routeModel } from "./model-selector.js";
+import { formatModelSelector, parseModelSelector, routeModel } from "./model-selector.js";
 import { modelPairName } from "../budget/budget.js";
 import { isJsonObject } from "../files/json-object.js";
 import { DIRECTOR_ROLE, roleById } from "../roles/roles.js";
-import { baseRoleOf } from "../roles/loop-ids.js";
+import { baseRoleOf } from "../roles/runner-ids.js";
 /** The effective `backends.<id>` entry as a run sees it (plans/agent-backends.md "Back-compat"):
  * the file's own entry, with the legacy top-level `agentBin`/`piArgs` read as the pi backend's
  * `bin`/`args` when the new form leaves a field absent. Pure — it never writes those legacy
  * values back into `config.backends`, so a config write that re-serializes the merged config
  * cannot leak a second spelling into the file (which validateConfig would then reject).
- * pi-backend.ts and claude-backend.ts read `.bin` through resolveAgentBin (pi-bin.ts);
+ * pi-backend.ts and claude-backend.ts read `.bin` through resolveBackendBin (pi-bin.ts);
  * claude-backend.ts reads `.args` for passthrough argv. */
-export function resolvedAgentConfig(config, id) {
+export function resolvedBackendConfig(config, id) {
     const entry = config.backends?.[id];
     // A view must own its array: returning the config's own `args` reference would let a caller
     // that appends passthrough argv silently mutate the loaded config, breaking the
@@ -31,6 +31,20 @@ export function resolvedAgentConfig(config, id) {
     }
     return { bin: entry?.bin ?? config.agentBin, args: (entry?.args ?? config.piArgs ?? []).slice() };
 }
+/** A backend's subscription-window reserve (plans/codex-backend.md part 2b/9): the nested
+ * `backends[backend].windowReserve` when the backend has one, else the top-level
+ * `claudeWindowReserve` for claude (its older spelling), else undefined. The two spellings are
+ * mutually exclusive in a loaded file (validateConfig rejects one holding both), so the
+ * fallback only ever answers for a config written before the rename. Pure: it never writes a
+ * spelling back into the file. */
+export function windowReserveFor(config, backend) {
+    const nested = config.backends?.[backend]?.windowReserve;
+    if (nested !== undefined)
+        return nested;
+    if (backend === "claude")
+        return config.claudeWindowReserve;
+    return undefined;
+}
 /** True when `s` names one of the three tiers — the form `roles.<id>.model` /
  * `review.model` may take to point at that tier of the top-level `model` map. */
 export function isTierName(s) {
@@ -43,13 +57,40 @@ export function isTierName(s) {
  * leaves pi's own default in charge. Map-form + legacy provider is a validation error, so
  * no legacy provider is in scope for a map's entries. */
 export function topTierSelector(config, tier) {
+    return resolveTopTier(config, tier).sel;
+}
+function resolveTopTier(config, tier) {
     if (typeof config.model === "string")
-        return parseModelSelector(config.model, config.provider);
-    if (isJsonObject(config.model)) {
-        const sel = config.model[tier] ?? config.model.default;
-        return sel !== undefined ? parseModelSelector(sel) : undefined;
+        return { sel: parseModelSelector(config.model, config.provider) };
+    if (!isJsonObject(config.model))
+        return {};
+    const raw = config.model[tier] ?? config.model.default;
+    if (raw === undefined)
+        return {};
+    if (typeof raw === "string")
+        return { sel: parseModelSelector(raw) };
+    const withThinking = (t) => {
+        if (raw.thinking === undefined)
+            return t;
+        return t.sel ? { ...t, sel: { ...t.sel, thinking: raw.thinking } } : { ...t, thinking: raw.thinking };
+    };
+    if (raw.model !== undefined) {
+        const sel = parseModelSelector(raw.model);
+        return withThinking({ sel, ...(raw.backend !== undefined ? { backend: raw.backend } : {}) });
     }
-    return undefined;
+    // No model of its own: take `default`'s, but an explicit backend only when `default` routes
+    // there already (the inherited model then routes by its own spelling, exactly as `default` does).
+    const dflt = tier === "default" ? {} : resolveTopTier(config, "default");
+    if (raw.backend !== undefined &&
+        (tier === "default" || withModelOverrides(config, "default", {}).agent !== raw.backend))
+        return withThinking({ backend: raw.backend });
+    return withThinking(dflt);
+}
+/** The explicit `backend` a tier's entry names — undefined for a string entry or an object entry
+ * without one, or when the entry names a backend `default`'s model does not route to and so
+ * inherits nothing (the backend then rides only its own tier default). */
+export function topTierBackend(config, tier) {
+    return resolveTopTier(config, tier).backend;
 }
 /** The selector one seam's tier resolves to at the top level — the tier's own map entry,
  * else `default`'s, else none (pi's own default). The pricing view (teamModelsFree) and
@@ -77,21 +118,43 @@ export function tierModel(config, tier) {
 export function withModelOverrides(config, tier, o) {
     // The top-level model resolves at the seam's tier: a string form is the default tier's
     // selector; a map form takes the tier's entry, else `default`'s.
-    const topSel = topTierSelector(config, tier);
+    const top = resolveTopTier(config, tier);
     const ownSel = o.model !== undefined ? parseModelSelector(o.model, o.provider ?? config.provider) : undefined;
+    const configBackend = config.backend ?? "pi";
+    // A role's own `backend` binds only to its own model; alone it inherits the tier's model only
+    // when the tier already routes there, else the backend's tier default fills in. A role's
+    // `model` without `backend` routes by the legacy rules, never by the tier entry's backend.
+    const inherit = o.model === undefined &&
+        (o.backend === undefined ||
+            routeModel(top.sel?.provider, top.sel?.model, configBackend, tier, top.backend).agent === o.backend);
+    // The tier's thinking level rides every path but a backend-only role whose tier routes elsewhere.
+    const topThinking = o.model === undefined && !inherit ? undefined : (top.sel?.thinking ?? top.thinking);
+    const topSel = inherit ? top.sel : undefined;
+    const backend = o.model !== undefined ? o.backend : inherit ? top.backend : o.backend;
     const provider = ownSel ? ownSel.provider : (o.provider ?? topSel?.provider ?? config.provider);
     const model = ownSel ? ownSel.model : topSel?.model;
     // The routed backend decides whether the provider half survives: a pi provider name is kept,
     // a backend namespace such as `claude` is dropped (that backend takes no provider).
-    const routed = routeModel(provider, model, config.backend ?? "pi", tier);
+    const routed = routeModel(provider, model, configBackend, tier, backend);
     return {
         ...config,
         provider: routed.agent === "pi" ? provider : undefined,
         model: routed.model,
-        thinking: o.thinking ?? ownSel?.thinking ?? topSel?.thinking ?? config.thinking,
+        thinking: o.thinking ?? ownSel?.thinking ?? topThinking ?? config.thinking,
         agent: routed.agent,
     };
 }
+/** A fallback pair as withModelOverrides' overrides: always an explicit backend (a pi pair is pi
+ * even on a claude team), a non-pi pair dropping the seam-key provider (its model already
+ * carries the whole id), a pi pair keeping its provider. */
+export function pairOverrides(pair) {
+    return {
+        provider: pair.backend === undefined ? pair.provider : undefined,
+        model: pair.model,
+        backend: pair.backend ?? "pi",
+        thinking: pair.thinking,
+    };
+}
 /** The provider/model/thinking overrides a config section (a role entry or `review`) carries
  * into withModelOverrides: a tier-name `model` already chose the seam's tier, so it is not a
  * selector and drops out here. Shared by configForRole and reviewConfig. */
@@ -99,12 +162,13 @@ function seamOverrides(s) {
     return {
         provider: s.provider,
         model: isTierName(s.model) ? undefined : s.model,
+        backend: s.backend,
         thinking: s.thinking,
     };
 }
 /** The tier a role's model resolves at: a tier-name `roles.<id>.model` names it directly, and
  * every other role rides the model catalog's assignment. Exported for the per-tier budget gate's
- * pause set (src/gates/gate-polls.ts, part 5c/8) and the dashboards' per-role budget pause
+ * pause set (src/budget/budget-wiring.ts, part 5c/8) and the dashboards' per-role budget pause
  * (src/status/status-data.ts), which must resolve the SAME tier the seams resolve — the hold an
  * operator sees is the hold the scheduler enforces. */
 export function roleSeamTier(config, role) {
@@ -115,6 +179,14 @@ export function roleSeamTier(config, role) {
         return "strong";
     return roleById(role)?.tier ?? "default";
 }
+/** Whether the review gate reviews this role's commits AFTER they merge (review.afterMerge
+ * lists the role's base id). One home for the membership test the review gate (review.ts's
+ * reviewAttempt), the runner's `already_queued` recovery arm (runner-run.ts) and the role
+ * view (`tumwater role <id>` / the dashboard role drawer) all share, so an operator reading
+ * one surface sees the same answer every consumer enforces. Pure, no I/O. */
+export function reviewedAfterMerge(config, role) {
+    return (config.review.afterMerge ?? []).includes(baseRoleOf(role));
+}
 /** The config as seen by one role: role-level provider/model/thinking overrides applied
  * over the top-level values, plus the per-role minRunIntervalSeconds (a slow clock for
  * roles that should act rarely) falling back to the global value when unset. The role's
@@ -130,25 +202,22 @@ export function configForRole(config, role) {
         minRunIntervalSeconds: rc.minRunIntervalSeconds ?? config.minRunIntervalSeconds,
     };
 }
-/** The config a role's ticks SCHEDULE from: configForRole, except that while the new-project
- * bootstrap is active (plans/work-ratio.md, part 2/2) the plan role schedules on the GLOBAL
- * minRunIntervalSeconds rather than its per-role 3600 s slow clock, so a young project gets a
- * steady stream of plans for feature; and while the brief still carries the placeholder status
- * (descriptionIncomplete) the plan role schedules with a ZERO min gap, so a fresh project plans
- * back-to-back until a run changes nothing — the zero gap is tighter than bootstrap. One home
- * for the rule: isEligible enforces the same gap when it decides whether plan may start, and
- * loop-tick.ts hands this config to applyTickOutcome so nextRunAt is scheduled from the same
- * figure instead of the role default. `descriptionIncomplete` means the brief's status section
- * is still the placeholder; the initial prompt half is always present (init rejects an empty
- * one), so the placeholder status is the machine-detectable "description not yet complete". */
-export function scheduleConfigForRole(config, role, bootstrapActive, descriptionIncomplete = false) {
+/** The config a role's runs SCHEDULE from: configForRole, except that while PLANS.md still
+ * has planning room (planBacklogOpen — below the plan role's eligible-plan target, or holding
+ * a plan that needs review/needs replan) the plan role schedules with a ZERO min gap, so a
+ * productive plan run reruns on the next poll and an unproductive one drops to the idle
+ * backoff. The plan role's own machine signal is `planBacklogFull` (src/scheduling/claims.ts):
+ * a fresh project's empty backlog is not full, so this subsumes the old placeholder-status
+ * trigger. One home for the rule: isEligible enforces the same gap when it decides whether
+ * plan may start, and runner-run.ts hands this config to applyRunOutcome so nextRunAt is
+ * scheduled from the same figure instead of the role default. Every other role, and the plan
+ * role once the target is met (which already holds the run via the plans-full deferral),
+ * schedule configForRole unchanged. */
+export function scheduleConfigForRole(config, role, planBacklogOpen = false) {
     const resolved = configForRole(config, role);
-    if (descriptionIncomplete && baseRoleOf(role) === "plan") {
+    if (planBacklogOpen && baseRoleOf(role) === "plan") {
         return { ...resolved, minRunIntervalSeconds: 0 };
     }
-    if (bootstrapActive && baseRoleOf(role) === "plan") {
-        return { ...resolved, minRunIntervalSeconds: config.minRunIntervalSeconds };
-    }
     return resolved;
 }
 /** The config as seen by the review gate's pi runs: the top-level `review` section's
@@ -173,10 +242,10 @@ export function resolverConfig(config) {
     return withModelOverrides(config, "strong", {});
 }
 /** Default wall-clock budget for one reviewer run (`review.timeoutSeconds`). The reviewer holds
- * the merge slot the whole queue waits on, and its only other limits were the tick's budget
+ * the merge slot the whole queue waits on, and its only other limits were the run's budget
  * and the quiet watchdog: reviews measured 2026-09-22/23 ran 2.3 min median, 9.2 min p90 and
  * 24.6 min max, while earlier days had 1.5–3.5 h reviews. 15 min clears the ordinary review and
- * kills a wedged one in minutes instead of the tick's hours. */
+ * kills a wedged one in minutes instead of the run's hours. */
 export const REVIEW_TIMEOUT_S = 900;
 /** The reviewer's wall-clock floor while the budget fallback carries the team. The free model
  * is typically local and far slower per turn than the budgeted one it replaces, but a review
@@ -189,7 +258,7 @@ export const REVIEW_TIMEOUT_S = 900;
 export const FALLBACK_REVIEW_TIMEOUT_S = 3600;
 /** The config as seen by the gate's reviewer run: the reviewer's model wiring (reviewConfig)
  * with its own time budget — `review.timeoutSeconds`, default REVIEW_TIMEOUT_S — overriding
- * the tick's. A smaller runTimeoutSeconds still wins. A still-progressing gate run gets one
+ * the run's. A smaller runTimeoutSeconds still wins. A still-progressing gate run gets one
  * extension of the same length (src/pi/pi-watchdogs.ts), so the effective ceiling on a large
  * diff's review is twice this budget. */
 export function reviewRunConfig(config) {
@@ -221,21 +290,21 @@ export function resolvedModelFields(provider, model, thinking) {
  * provider/model/thinking triple formatted as one selector string, or an empty object when
  * no model id is resolved (pi's own default) — the key stays absent rather than empty, the
  * same empty-means-unset rule resolvedModelFields applies to the raw halves. One home of
- * that assembly and guard, shared by the two run-start event writers (loop-tick.ts's run_start,
- * review.ts's review_start) and the per-loop status snapshot (status-data.ts) so the three
- * observability surfaces cannot disagree about which model a run starts on. A non-pi agent is
- * named as the selector's provider namespace (agentQualifiedSelector), so a claude run reads
+ * that assembly and guard, shared by the two run-start event writers (runner-run.ts's run_start,
+ * review-run.ts's review_start) and the per-role status snapshot (status-data.ts) so the three
+ * observability surfaces cannot disagree about which model a run starts on. A non-pi backend is
+ * named as the selector's provider namespace (backendQualifiedSelector), so a claude run reads
  * `claude/claude-sonnet-5-5` in every surface instead of a bare model id. */
 export function modelSelectorField(cfg) {
     const { model } = cfg;
-    return model ? { model: agentQualifiedSelector({ ...cfg, model }) } : {};
+    return model ? { model: backendQualifiedSelector({ ...cfg, model }) } : {};
 }
-/** The resolved seam as one selector string, agent-qualified: a non-pi backend id is the
+/** The resolved seam as one selector string, backend-qualified: a non-pi backend id is the
  * selector's provider namespace (`claude/claude-sonnet-5-5`), the form routeModel parses back
- * into that agent; a pi seam keeps `provider/model[:thinking]` byte-identical to before, since
+ * into that backend; a pi seam keeps `provider/model[:thinking]` byte-identical to before, since
  * pi's providers are real model providers, not a backend namespace. `model` is required — the
  * caller has already guarded that a model resolved (modelSelectorField). */
-export function agentQualifiedSelector(cfg) {
+export function backendQualifiedSelector(cfg) {
     const base = formatModelSelector({ provider: cfg.provider, model: cfg.model, thinking: cfg.thinking });
     return cfg.agent && cfg.agent !== "pi" ? `${cfg.agent}/${base}` : base;
 }
@@ -246,9 +315,9 @@ export function agentQualifiedSelector(cfg) {
 export function seamHoldKey(cfg) {
     return cfg.agent !== undefined && cfg.agent !== "pi" ? cfg.agent : cfg.provider;
 }
-/** The `modelPairName` a resolved seam's run is charged under (LoopState.dayCostByPair): the
+/** The `modelPairName` a resolved seam's run is charged under (RunnerState.dayCostByPair): the
  * routed backend's id stands in for the provider on a non-pi seam, exactly as the fallback
- * pairs carry it (config-fallbacks.ts's seamKeyedFallbackProvider), so a run and the chain
+ * pairs carry it (config-fallbacks.ts's seamKeyedPairFields), so a run and the chain
  * step it ran on name one key. */
 export function seamPairName(cfg) {
     return modelPairName({ provider: seamHoldKey(cfg), model: cfg.model });
@@ -273,18 +342,31 @@ export function seamConcurrencyKey(cfg, piDefault) {
  * event: null when no tier resolves to a model (pi's own default), the single selector when
  * every set tier agrees (the string-form `model`), and the `small=…, default=…, strong=…`
  * list when the tiers differ. Reading EVERY tier makes an edit to any tier's entry change the
- * label. Each tier's label is agent-qualified (agentQualifiedSelector), so flipping the
+ * label. Each tier's label is agent-qualified (backendQualifiedSelector), so flipping the
  * top-level `agent` over a bare-id model relabels every tier and the reload now emits
  * `model_changed` — a team's backend is part of what it runs (PLANS.md "Mixed claude + pi
  * fleets, part 3/4"), and an edit that moves a bare id to another backend must not read as
  * "nothing changed". */
 export function teamModelLabel(config) {
     const entries = MODEL_TIERS.map((tier) => {
-        const sel = tierModel(config, tier);
-        if (!sel)
+        const { sel, backend, thinking } = resolveTopTier(config, tier);
+        if (!sel && backend === undefined)
+            return null;
+        const routed = routeModel(sel?.provider, sel?.model, config.backend ?? "pi", tier, backend);
+        if (routed.model === undefined)
             return null;
-        const { agent } = routeModel(sel.provider, sel.model, config.backend ?? "pi", tier);
-        return { tier, label: agentQualifiedSelector({ ...sel, agent }) };
+        // routeModel consumed an agent-naming provider (or an explicit backend) as the agent; keep
+        // the provider only for a pi seam so the label doesn't prefix the agent twice.
+        const provider = routed.agent === "pi" ? sel?.provider : undefined;
+        return {
+            tier,
+            label: backendQualifiedSelector({
+                provider,
+                model: routed.model,
+                thinking: sel?.thinking ?? thinking,
+                agent: routed.agent,
+            }),
+        };
     }).filter((e) => e !== null);
     if (entries.length === 0)
         return null;
@@ -293,18 +375,18 @@ export function teamModelLabel(config) {
     return entries.map((e) => `${e.tier}=${e.label}`).join(", ");
 }
 /** One fallback pair rendered for display, agent-qualified (PLANS.md "Mixed claude + pi
- * fleets, part 3/4" gap 7): a pair routed to a non-pi backend — its `provider` is that
- * backend's id, per seamKeyedFallbackProvider, so `claude` — renders as `claude/claude-sonnet-5-5`,
+ * fleets, part 3/4" gap 7): a pair routed to a non-pi backend — its `backend`, per
+ * seamKeyedPairFields, so `claude` — renders as `claude/claude-sonnet-5-5`,
  * the same agent-qualified form every other surface carries; a pi pair keeps the bare model
  * byte-identical to before (the badge, the team alert and `tumwater role` all name the
  * model a pi fallback runs, never its provider). Falls back through the provider to the
  * caller's `<agent> default` label when both halves are absent. One home so the three display
  * surfaces cannot render one fallback two ways. */
-export function fallbackDisplayPair(pair, agentDefault) {
+export function fallbackDisplayPair(pair, backendDefault) {
     const p = pair ?? {};
     if (p.model !== undefined)
-        return p.provider !== undefined && isAgentId(p.provider) ? `${p.provider}/${p.model}` : p.model;
+        return p.backend !== undefined && p.backend !== "pi" ? `${p.backend}/${p.model}` : p.model;
     if (p.provider !== undefined)
         return p.provider;
-    return agentDefault;
+    return backendDefault;
 }

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

@@ -0,0 +1,135 @@
+/** The shared write MACHINERY for tumwater.json — the one home for the load →
+ * validate → atomic-write idiom, the cross-process lock, and the raw/preserve-role
+ * helpers that every writer shares. The operator-editor verbs (config-write.ts's
+ * setConfigKey/unsetConfigKey/setRoleModelFields/setDailyBudgetUsd) are whole-config writes
+ * with the
+ * same traps — a fresh loadConfig that bypasses config.ts's stat cache, validateConfig over
+ * the merged candidate, an atomic write because readers poll tumwater.json every ~2 s, a lock
+ * that serializes separate-process writers, and a roles section that must never be re-expanded
+ * from the catalog — so the idiom lives here, apart from the editor module.
+ * (config-request.ts's applyConfigRequest hits the same traps but inlines its own load →
+ * validate → write; it imports only withConfigLock and rawConfigObject from this module.)
+ * The read side — defaults, loading, saving,
+ * and the role-selection helpers — lives in config.ts, the per-run model derivations in
+ * config-views.ts, the config KEY language in config-keys.ts, and the operator-editor verbs
+ * in config-write.ts. */
+import { configPath, configLockPath, CONFIG_BASENAME } from "../paths.js";
+import { errorMessage } from "../text/text.js";
+import { writeJsonAtomic } from "../files/json-files.js";
+import { objectOrEmpty } from "../files/json-object.js";
+import { withStateLock } from "../concurrency/lock.js";
+import { validateConfig } from "./config-validation.js";
+import { loadConfig, parseJsonConfig, collapseBackendAliases } from "./config.js";
+/** Serialize a config write through the cross-process lock (paths.ts's configLockPath): the
+ * 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
+ * is worse than a write that reports an error. */
+const CONFIG_LOCK_TIMEOUT_MS = 10_000;
+export function withConfigLock(root, fn) {
+    // withStateLock creates the state dir the lock sits in (a CLI write may run before any state
+    // 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. */
+export function fail(error) {
+    return { ok: false, error };
+}
+/** The one load → mutate → validate → atomic-write idiom the operator-editor verbs share
+ * (setDailyBudgetUsd, setConfigKey, unsetConfigKey, setRoleModelFields): a fresh loadConfig that
+ * bypasses config.ts's stat cache (a writer must see the latest file), the caller's mutation
+ * applied in memory, validateConfig over the whole merged candidate, then writeJsonAtomic
+ * (tmp file + rename) because readers poll tumwater.json every ~2 s. The whole load-to-write
+ * sequence runs under withConfigLock, so two processes racing different keys cannot each write
+ * from the same pre-race snapshot and lose one update. On any failure — a broken on-disk file,
+ * a type-invalid candidate, a failed write, or a lock that cannot be acquired — the file is
+ * left untouched (and no tmp remnant is left behind); the error surfaces as a string so
+ * callers (both dashboards, the CLI) can print it without try/catch plumbing. */
+export function writeConfigMutation(root, mutate) {
+    try {
+        return withConfigLock(root, () => {
+            let cfg;
+            try {
+                cfg = loadConfig(root); // fresh — bypasses the stat cache on purpose
+            }
+            catch (err) {
+                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:
+            // re-serializing the merged config would reformat tumwater.json (defaults expanded) and
+            // break the no-op's "changes nothing" contract. The bytes stay identical; validation of an
+            // already-validated config is unnecessary.
+            if (mutated === cfg)
+                return { ok: true };
+            // Collapse legacy/new pi spellings before writing so a merged config (which always
+            // carries the default piArgs) never lands both forms in the file.
+            const candidate = collapseBackendAliases(mutated);
+            try {
+                validateConfig(candidate); // throws listing every problem — nothing is written on failure
+            }
+            catch (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 fail(errorMessage(err));
+            }
+            return { ok: true };
+        });
+    }
+    catch (err) {
+        return fail(errorMessage(err)); // lock acquire timeout/failure — nothing written
+    }
+}
+/** 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
+ * `model` map), so tumwater.json never keeps an empty object. */
+export function without(obj, key) {
+    const copy = { ...obj };
+    delete copy[key];
+    return copy;
+}
+/** 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 `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). */
+export function rawConfigObject(root) {
+    const { raw } = parseJsonConfig(configPath(root), CONFIG_BASENAME);
+    return objectOrEmpty(raw);
+}
+/** Reinstall the raw tumwater.json's `roles` section onto a whole-config write candidate (or
+ * drop it when the file had none), so a bare `config set`/`unset` of an unrelated key never
+ * re-expands the file's roles to the built-in catalog. `roles` merges per-entry at load, so
+ * this is about the bytes the operator can read and edit, not the resolved view: omission
+ * still cannot disable a role, and a partial section stays exactly as written. */
+export function preserveFileRoles(root, candidate) {
+    const record = candidate;
+    const rawRoles = rawConfigObject(root).roles;
+    if (rawRoles === undefined)
+        delete record.roles;
+    else
+        record.roles = rawRoles;
+}
+/** preserveFileRoles, returning the candidate so a whole-config write branch can
+ * `return preservingFileRoles(root, next)` after building it. */
+export function preservingFileRoles(root, candidate) {
+    preserveFileRoles(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 `backends`, which never leave an empty
+ * object in the file. A whole-config write, so the file's own roles section is kept. */
+export function withSectionOrDropped(root, cfg, key, section) {
+    const next = Object.keys(section).length === 0 ? without(cfg, key) : { ...cfg, [key]: section };
+    return preservingFileRoles(root, next);
+}