tumwater 0.2.0 → 0.4.0

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

@@ -1,107 +1,59 @@
-// 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, 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";
+/** Harness-mediated config WRITES — the four operator-editor mutators behind the operator
+ * surfaces (the TUI's Ctrl+B editor, the GUI's /api/budget endpoint, `tumwater config
+ * set`/`unset`), addressed by key through config-keys.ts. The shared write MACHINERY these
+ * verbs run on — the load → validate → atomic-write idiom, the cross-process lock, and the
+ * raw/preserve-role helpers — lives in config-write-core.ts, which the director's staged
+ * request (config-request.ts) also consumes; every writer here 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, 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 { isDeepStrictEqual } from "node:util";
 import { modelTierMap } from "./config-schema.js";
-import { configPath, configLockPath, configRequestPath, CONFIG_BASENAME } from "../paths.js";
-import { errorMessage } from "../text/text.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 { canonicalConfigKey, normalizeConfigKeys } from "./config-aliases.js";
+import { canonicalConfigKey } from "./config-aliases.js";
 import { unknownRoleMessage } from "../roles/roles.js";
-import { loadConfig, parseJsonConfig, collapseAgentAliases, knownRoleIdsCached } from "./config.js";
+import { loadConfig, collapseBackendAliases, 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 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;
-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. */
-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,
- * 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. */
-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 = collapseAgentAliases(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
-    }
-}
+import { writeConfigMutation, fail, rawConfigObject, without, preservingFileRoles, preserveFileRoles, withSectionOrDropped, } from "./config-write-core.js";
 /** Set the daily cost budget cap in tumwater.json through the shared writer idiom (see
  * writeConfigMutation), after checkDailyBudgetUsd has screened the value with its own
- * actionable message — the one both dashboards flash. */
+ * actionable message — the one both dashboards flash. A cap the config already resolves to
+ * (an omitted key resolves to the default) returns `unchanged: true` and writes nothing. */
 export function setDailyBudgetUsd(root, value) {
     const problem = checkDailyBudgetUsd(value);
     if (problem)
         return fail(problem);
-    return writeConfigMutation(root, (cfg) => {
+    let unchanged = false;
+    const result = writeConfigMutation(root, (cfg) => {
+        if (cfg.maxDailyCostUsd === value) {
+            unchanged = true;
+            return cfg; // the loaded config itself: writeConfigMutation skips the write
+        }
         const next = { ...cfg, maxDailyCostUsd: value };
         // A whole-config write: keep the file's own roles section (see preserveFileRoles).
         preserveFileRoles(root, next);
         return next;
     });
+    return result.ok && unchanged ? { ok: true, unchanged: true } : result;
 }
+/** The top-level team keys whose value is a plain positive integer (validateConfig's
+ * POSITIVE_INTEGER checks, config-validation.ts): the run-concurrency knobs plus the legacy
+ * merge batch cap. For these, an exponent spelling like "4e1" is itself a JSON number (40)
+ * that setConfigKey's JSON.parse would read past validateConfig's integer check and silently
+ * write — the same silent misread the per-role instances/interval guards, the TUI team-key
+ * editors, and the GUI Settings rows refuse — so setConfigKey refuses it, naming the key and
+ * writing nothing. The per-provider map (maxConcurrentPerProvider.<provider>) has its own
+ * checkProviderConcurrencyCap screen and is not in this set. */
+const PLAIN_INTEGER_TOP_LEVEL_KEYS = new Set([
+    "maxConcurrent",
+    "mergeBatchMax",
+    "maxConcurrentChecks",
+    "worktreeSlots",
+]);
 /** 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
@@ -116,12 +68,33 @@ export function setDailyBudgetUsd(root, value) {
  * ROLE_ENTRY_KEYS (a did-you-mean suggestion otherwise, via text/suggest.ts's typoSuffix); a
  * typo'd role id and a type-invalid value are left for validateConfig to reject with its own
  * 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). */
+ * confirm the change; on any failure the file is untouched
+ * (see writeConfigMutation). A value equal to the resolved one is a no-op: nothing is written and
+ * the result carries `unchanged`. */
 export function setConfigKey(root, key, rawValue) {
     key = canonicalConfigKey(key);
     const parsed = parseConfigKey(key);
     if (parsed.kind === "error")
         return fail(parsed.error);
+    // Shape, before the JSON.parse, for every plain-positive-integer key this verb can write —
+    // the top-level run-concurrency knobs and legacy merge batch cap, plus the integer-bound
+    // team-scope keys that arrive as a dotted key (`maxConcurrentPerProvider.<provider>`,
+    // `roles.<id>.instances`, the `bootstrap.untilPlansDone` section field): refuse an exponent
+    // spelling ("4e1" → 40) that JSON.parse would read past validateConfig's integer check and
+    // silently write, naming the key and writing nothing — the twin of the per-role guards, the
+    // TUI team-key editors, and the GUI Settings rows. A non-exponent invalid falls through for
+    // validateConfig (whose message names the key). Empty clears the key below.
+    const trimmed = rawValue.trim();
+    const isPlainIntegerKey = (parsed.kind === "top" && PLAIN_INTEGER_TOP_LEVEL_KEYS.has(key)) ||
+        (parsed.kind === "map" && parsed.map === "maxConcurrentPerProvider") ||
+        (parsed.kind === "role" && parsed.field === "instances") ||
+        (parsed.kind === "section" && parsed.section === "bootstrap" && parsed.field === "untilPlansDone");
+    if (isPlainIntegerKey &&
+        trimmed !== "" &&
+        !/^\d*\.?\d+$/.test(trimmed) &&
+        /^\d+(\.\d+)?[eE][+-]?\d+$/.test(trimmed))
+        return fail(`${key} must be a plain integer — no exponent notation`);
+    let unchanged; // set by a mutation callback when value equals the resolved one
     let value;
     try {
         value = JSON.parse(rawValue);
@@ -155,6 +128,10 @@ export function setConfigKey(root, key, rawValue) {
             if (parsed.kind === "map") {
                 const existing = record[parsed.map] ?? {};
                 oldValue = existing[parsed.role];
+                if (isDeepStrictEqual(oldValue, value)) {
+                    unchanged = true;
+                    return cfg;
+                }
                 const next = { ...cfg, [parsed.map]: { ...existing, [parsed.role]: value } };
                 return preservingFileRoles(root, next);
             }
@@ -166,19 +143,39 @@ export function setConfigKey(root, key, rawValue) {
                 // there and nothing is written.
                 const existing = modelTierMap(record.model);
                 oldValue = existing[parsed.tier];
+                if (isDeepStrictEqual(oldValue, value)) {
+                    unchanged = true;
+                    return cfg;
+                }
                 const next = { ...cfg, model: { ...existing, [parsed.tier]: value } };
                 return preservingFileRoles(root, next);
             }
+            if (parsed.kind === "section") {
+                // Merge one field into the loaded section, keeping its other fields; validateConfig in
+                // writeConfigMutation owns the value type, so a bad value fails there and writes nothing.
+                const existing = record[parsed.section] ?? {};
+                oldValue = existing[parsed.field];
+                if (isDeepStrictEqual(oldValue, value)) {
+                    unchanged = true;
+                    return cfg;
+                }
+                const next = { ...cfg, [parsed.section]: { ...existing, [parsed.field]: value } };
+                return preservingFileRoles(root, next);
+            }
             if (parsed.kind === "agent") {
                 // 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.backends };
-                const entry = { ...(agents[parsed.id] ?? {}) };
+                const backends = { ...record.backends };
+                const entry = { ...(backends[parsed.id] ?? {}) };
                 oldValue = entry[parsed.field];
+                if (isDeepStrictEqual(oldValue, value)) {
+                    unchanged = true;
+                    return cfg;
+                }
                 entry[parsed.field] = value;
-                agents[parsed.id] = entry;
-                const next = { ...cfg, backends: agents };
+                backends[parsed.id] = entry;
+                const next = { ...cfg, backends: backends };
                 // 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") {
@@ -188,6 +185,12 @@ export function setConfigKey(root, key, rawValue) {
                     else
                         delete nextRecord.piArgs;
                 }
+                // Setting the nested claude reserve drops the top-level spelling, so the file can never
+                // hold both (validateConfig rejects a file that does, mirroring the agentBin/piArgs pair).
+                if (parsed.id === "claude" && parsed.field === "windowReserve") {
+                    const nextRecord = next;
+                    delete nextRecord.claudeWindowReserve;
+                }
                 return preservingFileRoles(root, next);
             }
             // Base the merge on the FILE's own roles, not the loaded (catalog-merged) map: an
@@ -199,6 +202,10 @@ export function setConfigKey(root, key, rawValue) {
             const rawEntryCandidate = rawRoles[parsed.id];
             const rawEntry = objectOrEmpty(rawEntryCandidate);
             oldValue = record.roles?.[parsed.id]?.[parsed.field];
+            if (isDeepStrictEqual(oldValue, value)) {
+                unchanged = true;
+                return cfg;
+            }
             const roles = {
                 ...rawRoles,
                 [parsed.id]: { ...rawEntry, [parsed.field]: value },
@@ -210,6 +217,18 @@ export function setConfigKey(root, key, rawValue) {
         });
         if (!result.ok)
             return result;
+        if (unchanged)
+            return { ok: true, value, oldValue, unchanged: true };
+        // A string replaces a whole object tier entry, so its `backend` goes with it.
+        if (parsed.kind === "tier" && isJsonObject(oldValue)) {
+            const dropped = typeof oldValue.backend === "string" ? `backend ${show(oldValue.backend)}` : "its other keys";
+            return {
+                ok: true,
+                value,
+                oldValue,
+                note: `model.${parsed.tier} was an object entry — the string replaces it, dropping ${dropped}`,
+            };
+        }
         return { ok: true, value, oldValue };
     }
     const unknown = unknownConfigKeyError(key);
@@ -240,6 +259,10 @@ export function setConfigKey(root, key, rawValue) {
     let oldValue;
     const result = writeConfigMutation(root, (cfg) => {
         oldValue = cfg[key];
+        if (isDeepStrictEqual(oldValue, value)) {
+            unchanged = true;
+            return cfg;
+        }
         const next = { ...cfg, [key]: value };
         // `roles` merges per-entry at load (overlayDefaults seeds the catalog and lets the file
         // override one entry), so an unrelated whole-config write must not re-expand the file's
@@ -251,30 +274,46 @@ export function setConfigKey(root, key, rawValue) {
         // legacy aliases the new pi form now carries, so the file can never hold both.
         // 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
+        // both — the same collapseBackendAliases 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);
+            return collapseBackendAliases(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.backends ?? {}) };
-            const entry = { ...(agents.pi ?? {}) };
+            const backends = { ...(record.backends ?? {}) };
+            const entry = { ...(backends.pi ?? {}) };
             delete entry[key === "agentBin" ? "bin" : "args"];
             if (Object.keys(entry).length === 0)
-                delete agents.pi;
+                delete backends.pi;
             else
-                agents.pi = entry;
-            return { ...next, backends: agents };
+                backends.pi = entry;
+            return { ...next, backends: backends };
+        }
+        // Writers keep one spelling: setting the top-level `claudeWindowReserve` drops the nested
+        // `backends.claude.windowReserve`, so a supported `config set` never writes the rejected pair
+        // (validateConfig still refuses a hand-edited file holding both).
+        if (key === "claudeWindowReserve") {
+            const record = next;
+            const backends = { ...(record.backends ?? {}) };
+            const entry = { ...(backends.claude ?? {}) };
+            delete entry.windowReserve;
+            if (Object.keys(entry).length === 0)
+                delete backends.claude;
+            else
+                backends.claude = entry;
+            return { ...next, backends: backends };
         }
         return next;
     });
     if (!result.ok)
         return result;
+    if (unchanged)
+        return { ok: true, value, oldValue, unchanged: true };
     return { ok: true, value, oldValue };
 }
-/** Set a role's provider/model/thinking override triple in tumwater.json (`roles.<base>`),
+/** Set a role's provider/model/thinking/backend override set 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
@@ -297,7 +336,8 @@ export function setRoleModelFields(root, base, fields) {
     // a bogus id "updated".
     if (!knownRoleIdsCached(root).includes(base))
         return fail(unknownRoleMessage(base, knownRoleIdsCached(root)));
-    return writeConfigMutation(root, (cfg) => {
+    let unchanged; // set when no field differs from the file
+    const result = writeConfigMutation(root, (cfg) => {
         const rawRolesCandidate = rawConfigObject(root).roles;
         const rawRoles = objectOrEmpty(rawRolesCandidate);
         const rawEntryCandidate = rawRoles[base];
@@ -318,8 +358,10 @@ export function setRoleModelFields(root, base, fields) {
                 changed = true;
             }
         }
-        if (!changed)
+        if (!changed) {
+            unchanged = true;
             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
@@ -333,51 +375,9 @@ export function setRoleModelFields(root, base, fields) {
             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
- * `model` map), so tumwater.json never keeps an empty object. */
-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). */
-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. */
-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. */
-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. */
-function withSectionOrDropped(root, cfg, key, section) {
-    const next = Object.keys(section).length === 0 ? without(cfg, key) : { ...cfg, [key]: section };
-    return preservingFileRoles(root, next);
+    if (result.ok && unchanged)
+        return { ok: true, unchanged: true };
+    return result;
 }
 /** Remove ONE value of tumwater.json from its raw CLI text (`tumwater config unset <key>`):
  * the inverse of setConfigKey. A bare top-level key is deleted (reverting to its default or
@@ -447,24 +447,34 @@ export function unsetConfigKey(root, key) {
             const next = without(existing, parsed.tier);
             return withSectionOrDropped(root, cfg, "model", next);
         }
+        if (parsed.kind === "section") {
+            // Presence is judged against the FILE: a field only the default carries is a no-op
+            // success, and an emptied section leaves the file.
+            const rawSection = objectOrEmpty(raw[parsed.section]);
+            if (!Object.hasOwn(rawSection, parsed.field))
+                return cfg;
+            oldValue = rawSection[parsed.field];
+            const existing = record[parsed.section] ?? {};
+            return withSectionOrDropped(root, cfg, parsed.section, without(existing, parsed.field));
+        }
         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 `backends`
             // section are dropped when they empty, so the file never keeps an empty object.
-            const rawAgents = objectOrEmpty(raw.backends);
-            const rawEntryCandidate = rawAgents[parsed.id];
+            const rawBackends = objectOrEmpty(raw.backends);
+            const rawEntryCandidate = rawBackends[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.backends };
-            const entry = { ...(agents[parsed.id] ?? {}) };
+            const backends = { ...record.backends };
+            const entry = { ...(backends[parsed.id] ?? {}) };
             delete entry[parsed.field];
             if (Object.keys(entry).length === 0)
-                delete agents[parsed.id];
+                delete backends[parsed.id];
             else
-                agents[parsed.id] = entry;
-            return withSectionOrDropped(root, cfg, "backends", agents);
+                backends[parsed.id] = entry;
+            return withSectionOrDropped(root, cfg, "backends", backends);
         }
         const rawRolesCandidate = raw.roles;
         const rawRoles = objectOrEmpty(rawRolesCandidate);
@@ -489,114 +499,3 @@ export function unsetConfigKey(root, key) {
         return result;
     return { ok: true, oldValue };
 }
-/** 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:
- * `{ "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: `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
- * validateConfig to reject, so on failure nothing is written and the previous config stays
- * live. The request file is deleted on EVERY path (including every failure), so a malformed
- * request cannot retry forever and the file cannot survive into `git add -A`.
- *
- * Roles entries for custom loops the request removes are stripped before validation, from the
- * FILE's own `roles` section rather than the catalog-merged map (the rule every other
- * whole-config write follows, see preserveFileRoles): loadConfig seeds one `roles.<name>` per
- * current custom loop and validateConfig rejects an id that is neither a catalog role nor a
- * requested custom-loop name, so without the strip a removal would never apply. Only
- * structurally valid names feed the strip — a malformed entry stays in the array for
- * validateConfig to reject.
- *
- * Returns null when no request file exists. `applied` names the custom loops now live (empty
- * unless the write happened); `ignored` lists the discarded top-level keys; `error`, when set,
- * names why nothing (or only part of the work) was done — the caller turns it and `ignored`
- * into warning events. */
-export function applyConfigRequest(root, wt) {
-    const requestFile = configRequestPath(wt);
-    let raw;
-    try {
-        raw = fs.readFileSync(requestFile, "utf8");
-    }
-    catch {
-        return null; // no request this tick
-    }
-    const ignored = [];
-    let applied = [];
-    let error;
-    try {
-        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 !== "customRoles")
-                ignored.push(key);
-        }
-        const loops = parsed.customRoles;
-        if (!Array.isArray(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).
-        withConfigLock(root, () => {
-            const current = loadConfig(root); // fresh — bypasses the stat cache: a writer sees the latest file
-            // Strip roles.<id> entries for custom loops this request removes (see docstring).
-            // Structurally valid names only; anything else stays for validateConfig to reject — never
-            // dereference a request entry before validation.
-            const requestedNames = new Set();
-            for (const entry of loops) {
-                if (isJsonObject(entry) && typeof entry.name === "string")
-                    requestedNames.add(entry.name);
-            }
-            // Base the roles rewrite on the FILE's own section, not the loaded (catalog-merged)
-            // map: this whole-config write must not re-expand a partial section to every built-in
-            // (preserveFileRoles' rule). Only the removed custom loops' entries are stripped, and
-            // only from what the file actually holds.
-            const rawRolesCandidate = rawConfigObject(root).roles;
-            const roles = isJsonObject(rawRolesCandidate)
-                ? { ...(rawRolesCandidate) }
-                : {};
-            for (const c of current.customRoles) {
-                if (!requestedNames.has(c.name))
-                    delete roles[c.name];
-            }
-            const candidate = { ...current, customRoles: loops };
-            const candidateRecord = candidate;
-            if (rawRolesCandidate === undefined)
-                delete candidateRecord.roles;
-            else
-                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 `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.customRoles.map((c) => c.name);
-        });
-    }
-    catch (err) {
-        applied = []; // no write happened, or it must not be reported as applied
-        error = errorMessage(err);
-    }
-    // Delete the request on EVERY path — success, rejection, malformed JSON — so it can never be
-    // staged by commitAll, reach a review gate, or retry forever. A failed unlink is surfaced as
-    // an error so the caller logs it (the file would otherwise survive into the diff).
-    try {
-        fs.unlinkSync(requestFile);
-    }
-    catch (err) {
-        error ??= `config request file could not be deleted: ${errorMessage(err)}`;
-    }
-    return { applied, ignored, error };
-}