tumwater 0.4.0 → 0.4.2

package/dist/src/git/worktree-pool.js

@@ -12,16 +12,13 @@
  * which re-decide; `signal` aborts a waiter. */
 import path from "node:path";
 import { loadConfig, slotCount } from "../config/config.js";
-import { worktreesDir, slotWorktreePath } from "../paths.js";
-import { loadRunnerState } from "../runner/runner-state-load.js";
-import { DIRECTOR_ROLE } from "../roles/roles.js";
+import { slotWorktreePath, isCanonicalSlotDir } from "../paths.js";
 import { readSlotsState, slotForDir, updateSlotsState } from "./slots-state.js";
 import { salvageSlotLeftovers } from "./slot-salvage.js";
 import { beginWorktreeUse } from "./worktree-use.js";
 import { ensureDetachedWorktree, removeWorktreeDir } from "./worktree.js";
 import { logEventBestEffort, warnEventBestEffort, tryOrWarn, TUMWATER_SOURCE } from "../events/events.js";
 import { errorMessage } from "../text/text.js";
-import { subdirectoryNames } from "../files/files.js";
 import { dropProviderLeaseKey } from "../concurrency/provider-lease.js";
 /** In-process waiters per root, woken when any slot is released. Keyed by resolved root so two
  * roots never wake each other. */
@@ -229,12 +226,6 @@ function liveCount(root) {
         return Number.MAX_SAFE_INTEGER;
     }
 }
-/** A slot dir is canonical when it is exactly a `_slot-<n>` checkout under the worktrees dir.
- * A migrated legacy `<role>` dir is not, which marks it for retirement once its resume finishes
- * (retireLegacyRoleWorktrees and releaseSlot). */
-function isCanonicalSlotDir(dir) {
-    return /^_slot-\d+$/.test(path.basename(dir));
-}
 /** Slot dirs per root whose release write to slots.json failed in this process; the next claim
  * clears their stale lease. */
 const unsavedReleases = new Map();
@@ -316,116 +307,6 @@ export async function removeDroppedSlots(root, dirs, remove = removeWorktreeDir)
         }
     }
 }
-/** One-time startup migration (plans/worktree-pool.md "Legacy role worktrees", part 4c/5):
- * retire the pre-pool `.tumwater/worktrees/<role>` checkouts now that runs lease pooled slots.
- * A resumable enabled role keeps its legacy dir as a pinned slot so its pending resume runs in
- * the same cwd; every other legacy dir is removed (its branch keeps any commit), and pins for
- * roles outside `configured` are cleared. `configured` is every role id the config's roles
- * enable (`runnerIds`), never a `--once --role` filter: a scoped run must leave the other roles'
- * legacy dirs and pins alone, or it silently loses their pending resumes. It runs after
- * `runOrchestrator` constructs every
- * `RoleRunner` but before any run can call `leaseSlot`: the constructor infers `resumePending`
- * from the on-disk `running` flag only in memory (it does not save it), so `loadRunnerState` here
- * still reports the on-disk flags. *Removing* a dir is best-effort and logged: the slot records
- * are already updated, so a leaked directory is only a leak the next prune collects. */
-export async function retireLegacyRoleWorktrees(root, configured) {
-    const dir = worktreesDir(root);
-    // A missing worktrees dir (a team that has not started) yields no names to migrate; the pin
-    // retirement pass below still runs over whatever slots.json holds.
-    const names = subdirectoryNames(dir, (name) => name !== DIRECTOR_ROLE && !name.startsWith("_"));
-    const configuredSet = new Set(configured);
-    const toRemove = new Set();
-    updateSlotsState(root, (state) => {
-        for (const role of names) {
-            const legacyDir = path.join(dir, role);
-            const legacy = loadRunnerState(root, role);
-            const resumable = legacy.resumePending === true || legacy.running === true;
-            const ownRecord = state.slots.find((slot) => slot.dir === legacyDir);
-            if (resumable && configuredSet.has(role)) {
-                const owned = state.slots.find((slot) => slot.pinnedFor === role ||
-                    (slot.lease?.role === role && slot.lease.purpose === "run"));
-                if (owned !== undefined) {
-                    // The resume happens in the owned slot: drop the legacy record and remove its dir.
-                    if (owned.dir !== legacyDir) {
-                        state.slots = state.slots.filter((slot) => slot.dir !== legacyDir);
-                        toRemove.add(legacyDir);
-                    }
-                    if (owned.pinnedFor !== role)
-                        owned.pinnedAt = Date.now();
-                    owned.pinnedFor = role;
-                }
-                else if (ownRecord !== undefined) {
-                    // Already migrated (a restart before the resume ran): keep it pinned and inert,
-                    // preserving the pin's original age for the doctor's stuck-pin warning.
-                    ownRecord.lease = null;
-                    if (ownRecord.pinnedFor !== role)
-                        ownRecord.pinnedAt = Date.now();
-                    ownRecord.pinnedFor = role;
-                    ownRecord.lastRole = null;
-                    ownRecord.lastReleasedAt = null;
-                }
-                else {
-                    state.slots.push({
-                        dir: legacyDir,
-                        lease: null,
-                        pinnedFor: role,
-                        pinnedAt: Date.now(),
-                        lastRole: null,
-                        lastReleasedAt: null,
-                    });
-                }
-            }
-            else {
-                state.slots = state.slots.filter((slot) => slot.dir !== legacyDir);
-                toRemove.add(legacyDir);
-            }
-        }
-        // A paused or removed role must not leak a permanently pinned checkout.
-        for (const slot of [...state.slots]) {
-            if (slot.pinnedFor === null || configuredSet.has(slot.pinnedFor))
-                continue;
-            slot.pinnedFor = null;
-            slot.pinnedAt = null;
-            if (!isCanonicalSlotDir(slot.dir)) {
-                state.slots = state.slots.filter((s) => s !== slot);
-                toRemove.add(slot.dir);
-            }
-        }
-    });
-    for (const victim of toRemove) {
-        try {
-            await removeWorktreeDir(root, victim);
-        }
-        catch (err) {
-            warnEventBestEffort(root, TUMWATER_SOURCE, `could not remove legacy role workspace ${victim}: ${errorMessage(err)}`);
-        }
-    }
-}
-/** Startup pass for runs the previous process died in (crash, kill -9, power loss): such a run's
- * lease is still in slots.json with the dead pid, and its RoleRunner reads the persisted
- * `running` flag as a resume that must run in the same checkout, the cwd its session used. Pin
- * each such slot for its role, as the graceful shutdown's abort pin would have, unless the role
- * already holds a pin; the next claim then clears the dead lease (marking the run unsettled) and
- * the resume leases the pinned slot with its edits in place. Only configured roles count, as in
- * retireLegacyRoleWorktrees, so a removed role never leaks a pin. Like that pass, it runs before
- * any run can lease, while loadRunnerState still reports the on-disk flags. */
-export function pinCrashedRuns(root, configured) {
-    const configuredSet = new Set(configured);
-    updateSlotsState(root, (state) => {
-        for (const slot of state.slots) {
-            const lease = slot.lease;
-            if (lease === null || lease.pid === process.pid || lease.purpose !== "run")
-                continue;
-            if (!configuredSet.has(lease.role) || state.slots.some((s) => s.pinnedFor === lease.role))
-                continue;
-            const runner = loadRunnerState(root, lease.role);
-            if (runner.running !== true && runner.resumePending !== true)
-                continue;
-            slot.pinnedFor = lease.role;
-            slot.pinnedAt = Date.now();
-        }
-    });
-}
 /** Lease a pooled slot for `role`, prepared at `ref`. Resolves once a slot is held and reset to
  * `ref`, any uncommitted edits its last holder left saved first (salvageSlotLeftovers), as work
  * to hand back when that holder was a run that never settled them; rejects on a `signal` abort

package/dist/src/gui/gui-admin-endpoints.js

@@ -14,7 +14,7 @@ import { readBrief } from "../brief/brief.js";
 import { readQueuedPromptBody } from "../inbox/inbox-edit.js";
 import { rejectBadQueueFileName, rejectBadRole } from "./gui-args.js";
 import { DIRECTOR_ROLE } from "../roles/roles.js";
-import { okGone, sendJson } from "./http-body.js";
+import { okGone, sendJson } from "./gui-http-body.js";
 /** Handle GET /api/prompt-text?file=<name>[&role=<id>]: one queued prompt's editable body —
  * the text an edit replaces, for the dashboard's per-row edit affordance (PLANS.md
  * 2026-10-11). The prompt is addressed by its queue-file basename (the /api/prompt-cancel
@@ -44,9 +44,8 @@ export function handlePromptText(q, res, root) {
 /** Handle GET /api/doctor: the same DoctorReport `tumwater doctor --json` prints, so the
  * Settings view's Health check card and the CLI cannot disagree. Read-only — the checks write
  * nothing (runDoctor's own contract) — and it works whether or not the team is running. `run`
- * exists so tests can skip the host probes; it never probes images ("never") — the explicit
- * re-probe is POST /api/doctor-reprobe; a throw reaches the server's outer 500. */
-export async function handleDoctor(res, root, run = (r) => runDoctor(r, undefined, undefined, "never")) {
+ * exists so tests can skip the host probes; a throw reaches the server's outer 500. */
+export async function handleDoctor(res, root, run = (r) => runDoctor(r)) {
     sendJson(res, 200, await run(root));
 }
 /** Handle GET /api/config: the Settings view's resolved values for exactly

package/dist/src/gui/gui-args.js

@@ -16,7 +16,7 @@ import { queueFileNameProblem } from "../inbox/inbox-cancel.js";
 import { DIRECTOR_ROLE } from "../roles/roles.js";
 import { gotSuffix, parseNonNegativeInt, parsePositiveInt, splitCommaListUnique } from "../text/text.js";
 import { typoSuffix } from "../text/suggest.js";
-import { badRequest, sendJson } from "./http-body.js";
+import { badRequest, sendJson } from "./gui-http-body.js";
 /** The role ids a role-targeting endpoint accepts: when tumwater.json parses, catalog +
  * customRoles (knownRoleIds); a transiently broken file falls back to the built-in catalog
  * rather than refusing every id — the rule config.knownRoleIdsCached owns. Shared by

package/dist/src/gui/gui-backlog-commands.js

@@ -18,7 +18,7 @@ import { tryMoveEntryToTop, tryReleaseEntry } from "../backlog/backlog-release.j
 import { tryAnswerQuestion, UNCLOSED_FENCE_MESSAGE } from "../backlog/question-answer.js";
 import { promptLengthProblem } from "../inbox/inbox-submit.js";
 import { requestWake, submitRolePromptAndWake, wakeQuestionAsker } from "../operator/operator-intent.js";
-import { badRequest, okGone, sendJson } from "./http-body.js";
+import { badRequest, okGone, sendJson } from "./gui-http-body.js";
 import { collapseWhitespace, errorMessage, gotSuffix } from "../text/text.js";
 import { readPostBody } from "./gui-endpoint-common.js";
 /** Shared 400-validation for an entry-target body's `kind` — "bug" or "plan" — the one field
@@ -183,11 +183,26 @@ function heldAt(root, kind, position) {
     const holds = backlogHolds(root);
     return (kind === "bug" ? holds.bugs : holds.plans)[position - 1] ?? null;
 }
+/** Commit a successful backlog write and send the drawer's success response — the same
+ * post-write tail the release, move-to-top, and edit handlers repeat: commit the file change on
+ * main, re-read the entry's hold (its position may have moved), and send the 200 with the
+ * commit and a `heldNote` naming the hold when one still applies (a held entry is not newly
+ * eligible, so the caller must not wake a role — the release handler reads the returned hold
+ * to decide). `verb` names the action in the commit subject (`Release`/`Prioritize`/`Edit`),
+ * `status` is the response's status, and `extra` carries the success body fields only one
+ * handler has (release's `lifted`), spread before `committed` so that body's key order stays
+ * intact. Returns the hold it read. */
+async function respondBacklogWrite(res, root, kind, position, outcome, verb, status, extra = {}) {
+    const committed = await commitOperatorBacklogEdit(root, outcome.file, stampedSubject("operator", `${verb} ${kind}: ${outcome.title}`)); // vocabulary-ok: the commit prefix stays tumwater(operator):
+    const hold = heldAt(root, kind, position);
+    sendJson(res, 200, { ok: true, status, file: outcome.file, title: outcome.title, ...extra, committed, ...(hold === null ? {} : { heldNote: stillHeldNote(hold) }) });
+    return hold;
+}
 /** Handle POST /api/backlog-release: the entry drawer's release — the same lock and splice as
  * `tumwater plan|bug --release <n>` through the non-exiting tryReleaseEntry. Body as
  * backlog-cancel's. A released entry that is not still held is newly eligible, so the kind's
  * role is woken (a held one wakes no role and carries `heldNote`); `gone` and `moved` answer
- * okGone, and an entry with none of the Refused, Waiting-for-the-next-failure, or
+ * okGone, and an entry with none of the Refused or
  * held-for-operator notes answers status "not_refused" with no write and no wake. */
 export async function handleBacklogRelease(req, res, root) {
     const body = await readPostBody(req, res, '{"kind": "bug", "position": 1, "title": "<heading>"}');
@@ -204,11 +219,9 @@ export async function handleBacklogRelease(req, res, root) {
     if (outcome === null)
         return;
     if (outcome.status === "released") {
-        const committed = await commitOperatorBacklogEdit(root, outcome.file, stampedSubject("operator", `Release ${kind}: ${outcome.title}`)); // vocabulary-ok: the commit prefix stays tumwater(operator):
-        const hold = heldAt(root, kind, position);
+        const hold = await respondBacklogWrite(res, root, kind, position, outcome, "Release", "released", { lifted: outcome.lifted });
         if (hold === null)
             requestWake(root, [OPERATOR_FILE_KINDS[kind].role]);
-        sendJson(res, 200, { ok: true, status: "released", file: outcome.file, title: outcome.title, lifted: outcome.lifted, committed, ...(hold === null ? {} : { heldNote: stillHeldNote(hold) }) });
     }
     else if (outcome.status === "not_refused") {
         sendJson(res, 200, { ok: true, status: "not_refused", title: outcome.title });
@@ -237,9 +250,7 @@ export async function handleBacklogTop(req, res, root) {
     if (outcome === null)
         return;
     if (outcome.status === "moved_to_top") {
-        const committed = await commitOperatorBacklogEdit(root, outcome.file, stampedSubject("operator", `Prioritize ${kind}: ${outcome.title}`)); // vocabulary-ok: the commit prefix stays tumwater(operator):
-        const hold = heldAt(root, kind, 1);
-        sendJson(res, 200, { ok: true, status: "moved_to_top", file: outcome.file, title: outcome.title, committed, ...(hold === null ? {} : { heldNote: stillHeldNote(hold) }) });
+        await respondBacklogWrite(res, root, kind, 1, outcome, "Prioritize", "moved_to_top");
     }
     else if (outcome.status === "already_first") {
         sendJson(res, 200, { ok: true, status: "already_first", title: outcome.title });
@@ -284,9 +295,7 @@ export async function handleBacklogEdit(req, res, root) {
     if (outcome === null)
         return;
     if (outcome.status === "edited") {
-        const committed = await commitOperatorBacklogEdit(root, outcome.file, stampedSubject("operator", `Edit ${kind}: ${outcome.title}`)); // vocabulary-ok: the commit prefix stays tumwater(operator):
-        const hold = heldAt(root, kind, position);
-        sendJson(res, 200, { ok: true, status: "edited", file: outcome.file, title: outcome.title, committed, ...(hold === null ? {} : { heldNote: stillHeldNote(hold) }) });
+        await respondBacklogWrite(res, root, kind, position, outcome, "Edit", "edited");
     }
     else if (outcome.status === "unchanged") {
         sendJson(res, 200, { ok: true, status: "unchanged", file: outcome.file, title: outcome.title });

package/dist/src/gui/gui-backlog-endpoints.js

@@ -5,12 +5,12 @@
  * inbox/inbox.ts, change/change-data.ts), so this module only adapts HTTP onto it. Barrelled
  * into gui/gui-endpoints.ts beside the other per-family GET endpoint modules.
  */
-import { operatorHeldEntries, refusalNote, waitingNote } from "../backlog/backlog-eligibility.js";
+import { refusalNote } from "../backlog/backlog-eligibility.js";
 import { answeredQuestionEntries, entryMatches, donePlanEntries, fixedBugEntries, openBugEntries, openQuestionEntries, plannedPlanEntries } from "../backlog/backlog.js";
 import { collectChangeOverlaps, scopeChangeOverlaps, scopeChangeOverlapsToPath, collectTeamChanges, collectRoleChange, normalizeDiffPath } from "../change/change-data.js";
 import { listWideScope, queuedListRows } from "../inbox/inbox.js";
 import { intQuery, rejectBadRole, roleListQuery } from "./gui-args.js";
-import { badRequest, sendJson } from "./http-body.js";
+import { badRequest, sendJson } from "./gui-http-body.js";
 import { typoSuffix } from "../text/suggest.js";
 /** The /api/backlog `file` values and the open-section reader each addresses — one table so
  * the on-demand dispatch and the "valid values" list in both 400s cannot drift apart. A Map,
@@ -36,10 +36,6 @@ const BACKLOG_FILE_VALUES = BACKLOG_FILE_NAMES.join(", ");
  * order, unlike done/fixed) — zero-based.
  * Unknown/missing file, missing or bad index, and out-of-range index
  * → 400 JSON error via sendJson.
- * On a held-for-operator entry (the entry in
- * operatorHeldEntries' selection, file and index both matching), the 200 payload adds
- * `heldForOperator: true` so the drawer shows its Release button there too; every other
- * entry's payload carries no such key.
  * The query arrives pre-parsed (gui/gui-server.ts's parseRequestTarget), like every
  * GET-data handler here. */
 export function handleBacklog(q, res, root) {
@@ -66,8 +62,6 @@ export function handleBacklog(q, res, root) {
         title: entry.title,
         body: entry.body,
         refused: refusalNote(entry.body) !== null,
-        waiting: waitingNote(entry.body) !== null,
-        ...(operatorHeldEntries(root).some((e) => e.file === file && e.index === index) ? { heldForOperator: true } : {}),
     });
 }
 /** Handle GET /api/backlog-match?grep=<text>: for each /api/backlog `file`, the ascending

package/dist/src/gui/gui-config-commands.js

@@ -15,7 +15,7 @@ import { testNotifyHook } from "../cli/notify-command.js";
 import { rejectBadRole, requireConfigKey, requireRoleField, requireStringField } from "./gui-args.js";
 import { baseRoleOf } from "../roles/runner-ids.js";
 import { DIRECTOR_ROLE } from "../roles/roles.js";
-import { badRequest, sendJson } from "./http-body.js";
+import { badRequest, sendJson } from "./gui-http-body.js";
 import { readPostBody } from "./gui-endpoint-common.js";
 /** Handle POST /api/budget: the dashboard's budget-badge editor saves the daily cost cap —
  * same body discipline as /api/prompt (readJsonObject), and the same shared validation rule +
@@ -173,40 +173,28 @@ export async function handleRoleInterval(req, res, root) {
         return;
     }
     const base = baseRoleOf(role);
-    // A null, empty or whitespace-only value clears the override, so the role falls back to the
-    // team-wide minRunIntervalSeconds (unsetConfigKey, like the CLI's config unset of the key).
-    if (value === null || (typeof value === "string" && value.trim() === "")) {
-        // unsetConfigKey's no-op map path (a role the file never holds, an unknown id included)
-        // skips validateConfig, so without this the set branch's unknown-role refusal would never
-        // fire on a clear and a bogus id would answer 200 "cleared" — the explicit check mirrors
-        // the CLI's knownRoleIds guard and the role-quiet-hours clear branch.
-        if (rejectBadRole(root, res, role))
+    // A non-null, non-blank value must pass the shared per-key screen (the finite
+    // 0..MAX_DURATION_SECONDS rule, naming the per-role dotted key so a rejected write tells the
+    // operator which key the drawer would set) before the write; a null/blank value is the clear
+    // path (writeRoleJsonKey), so the role falls back to the team-wide interval.
+    if (value !== null && !(typeof value === "string" && value.trim() === "")) {
+        const problem = checkMinRunInterval(value, `roles.${base}.minRunIntervalSeconds`);
+        if (problem) {
+            badRequest(res, problem);
             return;
-        const clearResult = unsetConfigKey(root, `roles.${base}.minRunIntervalSeconds`);
-        if (!clearResult.ok)
-            return configKeyError(res, `roles.${base}.minRunIntervalSeconds`, clearResult);
-        const message = clearResult.oldValue === undefined
-            ? `${base}: min run interval is not set in tumwater.json, so nothing was cleared`
-            : `${base}: min run interval cleared`;
-        sendJson(res, 200, { ok: true, role: base, message });
-        return;
-    }
-    // The shared rule (finite 0..MAX_DURATION_SECONDS), naming the per-role dotted key so a
-    // rejected write tells the operator which key the drawer would set.
-    const problem = checkMinRunInterval(value, `roles.${base}.minRunIntervalSeconds`);
-    if (problem) {
-        badRequest(res, problem);
-        return;
+        }
     }
-    // setConfigKey takes the raw CLI text; a JSON round-trip of an already-parsed value is
-    // exact, so the shared per-key validator + whole-config validateConfig apply unchanged.
-    const result = setConfigKey(root, `roles.${base}.minRunIntervalSeconds`, JSON.stringify(value));
-    if (!result.ok)
-        return configKeyError(res, `roles.${base}.minRunIntervalSeconds`, result);
-    const message = result.unchanged
-        ? `${base}: min run interval is already ${value}s, so tumwater.json was not written`
-        : `${base}: min run interval set to ${value}s`;
-    sendJson(res, 200, { ok: true, role: base, minRunIntervalSeconds: value, message });
+    // The set-or-clear tail shared with the other role JSON-key handlers: clears through
+    // unsetConfigKey and sets through the CLI's own setConfigKey dotted path, so the shared
+    // per-key validator (above) and whole-config validateConfig (which rejects an unknown role
+    // id) own the final truth. The clear arm carries rejectBadRole because unsetConfigKey's
+    // no-op map path skips validateConfig — the guard the set branch gets free from
+    // setConfigKey's unknown-role refusal (mirrors the CLI's knownRoleIds guard).
+    writeRoleJsonKey(res, root, base, `roles.${base}.minRunIntervalSeconds`, "min run interval", value, (v) => `${base}: min run interval set to ${v}s`, {
+        unchangedMessage: (v) => `${base}: min run interval is already ${v}s, so tumwater.json was not written`,
+        guardClear: () => rejectBadRole(root, res, role),
+        extra: { minRunIntervalSeconds: value },
+    });
 }
 /** Handle POST /api/role-instances: the role drawer's instance-count editor sets or clears one
  * role's parallel-runner count — the count that lets `feature-2`…`feature-N` run. Same body
@@ -233,34 +221,17 @@ export async function handleRoleInstances(req, res, root) {
         return;
     }
     const base = baseRoleOf(role);
-    // A null, empty or whitespace-only value clears the key, so the role falls back to the
-    // default 1 (unsetConfigKey, like the CLI's config unset of the key).
-    if (value === null || (typeof value === "string" && value.trim() === "")) {
-        // unsetConfigKey's no-op map path (a role the file never holds, an unknown id included)
-        // skips validateConfig, so without this the set branch's unknown-role refusal would never
-        // fire on a clear and a bogus id would answer 200 "cleared" — the explicit check mirrors
-        // the CLI's knownRoleIds guard and the role-interval clear branch.
-        if (rejectBadRole(root, res, role))
-            return;
-        const clearResult = unsetConfigKey(root, `roles.${base}.instances`);
-        if (!clearResult.ok)
-            return configKeyError(res, `roles.${base}.instances`, clearResult);
-        const message = clearResult.oldValue === undefined
-            ? `${base}: instances is not set in tumwater.json, so nothing was cleared`
-            : `${base}: instances cleared`;
-        sendJson(res, 200, { ok: true, role: base, message });
-        return;
-    }
-    // setConfigKey takes the raw CLI text; a JSON round-trip of an already-parsed value is
-    // exact, so the shared per-key validator + whole-config validateConfig (which owns which
-    // roles may split and the 1–8 integer bound) apply unchanged.
-    const result = setConfigKey(root, `roles.${base}.instances`, JSON.stringify(value));
-    if (!result.ok)
-        return configKeyError(res, `roles.${base}.instances`, result);
-    const message = result.unchanged
-        ? `${base}: instances is already ${value}, so tumwater.json was not written`
-        : `${base}: instances set to ${value}`;
-    sendJson(res, 200, { ok: true, role: base, instances: value, message });
+    // The set-or-clear tail shared with the other role JSON-key handlers: clears through
+    // unsetConfigKey and sets through the CLI's own setConfigKey dotted path, so whole-candidate
+    // validateConfig owns the final truth (the INSTANCE_COUNT bound and which roles may split;
+    // an unknown id is refused there). The clear arm carries rejectBadRole because
+    // unsetConfigKey's no-op map path skips validateConfig — the guard the set branch gets free
+    // from setConfigKey's unknown-role refusal (mirrors the CLI's knownRoleIds guard).
+    writeRoleJsonKey(res, root, base, `roles.${base}.instances`, "instances", value, (v) => `${base}: instances set to ${v}`, {
+        unchangedMessage: (v) => `${base}: instances is already ${v}, so tumwater.json was not written`,
+        guardClear: () => rejectBadRole(root, res, role),
+        extra: { instances: value },
+    });
 }
 /** Handle POST /api/role-model: the role drawer's Model overrides editor sets or clears one
  * role's provider/model/thinking/backend set (roles.<base>.provider/.model/.thinking/
@@ -337,7 +308,7 @@ export async function handleRoleInstructions(req, res, root) {
     // 4096-char cap and the unknown-role check in writeConfigMutation. Unlike quiet hours the
     // clear arm carries no role guard (the director may clear, and the unknown-role clear gap is
     // pre-existing).
-    writeRoleJsonKey(res, root, base, `roles.${base}.instructions`, "instructions", text, (v) => JSON.stringify(v), (v) => `${base}: instructions saved (${v.length} chars)`);
+    writeRoleJsonKey(res, root, base, `roles.${base}.instructions`, "instructions", text, (v) => `${base}: instructions saved (${String(v).length} chars)`);
 }
 /** The shared write behind POST /api/role-enable and POST /api/role-disable: the Settings
  * card's Enable button and the role drawer's two-click Disable both write
@@ -416,7 +387,7 @@ export async function handleRoleQuietHours(req, res, root) {
     // branch's unknown-role refusal would never fire on a clear and a bogus id would answer 200
     // "cleared" (mirrors the CLI's knownRoleIds guard). The set arm runs setConfigKey raw, its
     // map branch checking the dotted key as the label and validateConfig owning the unknown role.
-    writeRoleJsonKey(res, root, base, `quietHoursPerRole.${base}`, "quiet hours", window, (v) => JSON.stringify(v), (v) => `${base}: quiet hours set to ${v}`, () => rejectBadRole(root, res, role));
+    writeRoleJsonKey(res, root, base, `quietHoursPerRole.${base}`, "quiet hours", window, (v) => `${base}: quiet hours set to ${v}`, { guardClear: () => rejectBadRole(root, res, role) });
 }
 /** The shared 400 for a failed config mutation — the set and unset write paths both nest the
  * write's error under the key it names, so the Settings view can tell which field failed and a
@@ -431,16 +402,18 @@ function configKeyError(res, key, result) {
 function unchangedFlag(result) {
     return result.unchanged ? { unchanged: true } : {};
 }
-/** The set-or-clear write the two per-role JSON-config-key handlers (quiet hours, standing
- * instructions) share: an empty/whitespace `raw` unsets `key` (after `guardClear`, a per-call
- * check the clear arm runs first — quiet hours' unknown-role guard; instructions has none),
- * else sets it via setConfigKey (which JSON-encodes nothing, so `serialize` shapes the stored
- * value). `noun` names the hold in the "cleared" 200 and `setMessage` is the exact set-arm 200
- * message, threaded so each handler keeps its own wording. Always writes the response, so the
- * caller never falls through to further output. */
-function writeRoleJsonKey(res, root, base, key, noun, raw, serialize, setMessage, guardClear) {
-    if (raw.trim() === "") {
-        if (guardClear?.())
+/** The set-or-clear write every per-role JSON-config-key handler (quiet hours, standing
+ * instructions, min run interval, instance count) shares: an empty/whitespace/`null` `raw`
+ * unsets `key` (after `guardClear`, a per-call check the clear arm runs first — the numeric
+ * keys' and quiet hours' unknown-role guard; instructions has none), else sets it via
+ * setConfigKey (which JSON-encodes nothing, so the JSON.stringify below shapes the stored
+ * value). `noun` names the hold in the "cleared" 200, `setMessage` is the exact set-arm 200
+ * message, and `unchangedMessage` overrides the default unchanged wording — threaded so each
+ * handler keeps its own wording. Always writes the response, so the caller never falls
+ * through. */
+function writeRoleJsonKey(res, root, base, key, noun, raw, setMessage, options = {}) {
+    if (raw === null || (typeof raw === "string" && raw.trim() === "")) {
+        if (options.guardClear?.())
             return;
         const result = unsetConfigKey(root, key);
         if (!result.ok)
@@ -453,12 +426,14 @@ function writeRoleJsonKey(res, root, base, key, noun, raw, serialize, setMessage
         }
         return;
     }
-    const result = setConfigKey(root, key, serialize(raw));
+    const result = setConfigKey(root, key, JSON.stringify(raw));
     if (!result.ok)
         configKeyError(res, key, result);
     else {
-        const message = result.unchanged ? `${base}: ${noun} unchanged, so tumwater.json was not written` : setMessage(raw);
-        sendJson(res, 200, { ok: true, role: base, message });
+        const message = result.unchanged
+            ? (options.unchangedMessage ?? (() => `${base}: ${noun} unchanged, so tumwater.json was not written`))(raw)
+            : setMessage(raw);
+        sendJson(res, 200, { ok: true, role: base, message, ...options.extra });
     }
 }
 /** Handle POST /api/config-set: the Settings view's per-key Save — one curated key set to

package/dist/src/gui/gui-endpoint-commands.js

@@ -10,10 +10,12 @@
  * question-answer (gui/gui-backlog-commands), config set/unset + budget + notify-test
  * (gui/gui-config-commands), team pause/role-pause/wake (gui/gui-team-commands),
  * and operator lifecycle restart/reclaim/abort/reset-counters/stop-schedule/role-notes/
- * retire/brief-edit (gui/gui-operator-commands).
+ * retire/brief-edit (gui/gui-operator-commands), and flake-quarantine release
+ * (gui/gui-quarantine-commands).
  */
 export { handlePrompt, handlePromptRole, handlePromptCancel, handlePromptEdit, handlePromptTop } from "./gui-prompt-commands.js";
 export { handleQuestionAnswer, handleBacklogFile, handleBacklogCancel, handleBacklogRelease, handleBacklogTop, handleBacklogEdit } from "./gui-backlog-commands.js";
 export { handleConfigSet, handleConfigUnset, handleBudget, handleRoleCap, handleRoleReviewAfterMerge, handleRoleEnable, handleRoleDisable, handleRoleInstances, handleRoleInterval, handleRoleInstructions, handleRoleModel, handleRoleQuietHours, handleNotifyTest } from "./gui-config-commands.js";
 export { handlePause, handlePauseRole, handleWake, handleWakeCancel } from "./gui-team-commands.js";
-export { handleResetCounters, handleRestart, handleReclaim, handleKillOrphans, handleDropBrokenPins, handleCommitBacklog, handleResyncInstall, handleRetireLeftovers, handleDoctorReprobe, handleAbort, handleStopSchedule, handleRoleNotes, handleRetire, handleRevert, handleQueueCancel, handleQueueTop, handlePostReviewAccept, handleBriefEdit } from "./gui-operator-commands.js";
+export { handleResetCounters, handleRestart, handleReclaim, handleKillOrphans, handleDropBrokenPins, handleCommitBacklog, handleResyncInstall, handleRetireLeftovers, handleArchiveBacklog, handleAbort, handleAbortAll, handleStopSchedule, handleRoleNotes, handleRetire, handleRevert, handleQueueCancel, handleQueueTop, handlePostReviewAccept, handleBriefEdit } from "./gui-operator-commands.js";
+export { handleQuarantineRelease } from "./gui-quarantine-commands.js";

package/dist/src/gui/gui-endpoint-common.js

@@ -1,13 +1,14 @@
 /**
  * The request-body helpers shared by the dashboard's per-domain POST command modules
- * (gui-prompt-commands, gui-backlog-commands, gui-config-commands, gui-team-commands, and
- * gui-operator-commands, all barrelled into gui/gui-endpoint-commands.ts): readPostBody /
+ * (gui-prompt-commands, gui-backlog-commands, gui-config-commands, gui-team-commands,
+ * gui-operator-commands, and gui-quarantine-commands, all barrelled into
+ * gui/gui-endpoint-commands.ts): readPostBody /
  * readRoleBody — the body-discipline-and-role-check pair each mutating handler guards its
  * inputs with — and sendRequestResult, the shared boolean-claiming marker reply. The
  * per-domain `checked*` validators live with their domain's module, not here.
  */
 import { rejectBadRole } from "./gui-args.js";
-import { readJsonObject, sendJson } from "./http-body.js";
+import { readJsonObject, sendJson } from "./gui-http-body.js";
 /** Every POST handler's shared opening: readJsonObject reads the body and — when it is
  * oversized, malformed, or not a JSON object — has already written the 413/400 itself. Its
  * null return therefore means the response is sent and the handler must stop without touching

package/dist/src/gui/gui-history-endpoints.js

@@ -17,7 +17,7 @@ import { renderRunDetail, runDetailPatch, runDetailStat, runTranscriptLines } fr
 import { resolveRevertTarget } from "../operator/revert.js";
 import { rolePayload } from "../roles/role-view.js";
 import { clampCount, intQuery, rejectBadRole, sinceMsQuery, untilMsQuery } from "./gui-args.js";
-import { badRequest, sendJson } from "./http-body.js";
+import { badRequest, sendJson } from "./gui-http-body.js";
 import { typoSuffix } from "../text/suggest.js";
 import { gotSuffix, splitCommaList, splitCommaListUnique } from "../text/text.js";
 import { newestRunRow, runNotFoundLastMessage, runNotFoundMessage } from "../run/run-detail.js";
@@ -98,6 +98,31 @@ function resultClassesQuery(q, res) {
  * (the `history --result` rule, parsed by resultClassesQuery like /api/run's), after `grep` and
  * before `model`; an unknown class is a 400. Reads files directly, so it works whether
  * or not the team is running. */
+/** Parse the `sinceMs`-window prologue the two history endpoints share. A present `sinceMs`
+ * (with no rival `n`) yields `{ kind: "window", sinceMs, untilMs }`; an absent `sinceMs`
+ * yields `{ kind: "count" }`. Any 400 — the rival-shapes rejection when both `sinceMs` and
+ * `n` are present, or a `sinceMs`/`untilMs` that fails to parse or caps (sinceMsQuery,
+ * untilMsQuery) — is already sent and yields null, so the caller returns early. Shared by
+ * handleHistory and handleLogs so the rival-shapes message and the parse-and-cap discipline
+ * cannot drift. */
+function windowOrCount(q, res) {
+    if (q.get("sinceMs") !== null) {
+        if (q.get("n") !== null) {
+            badRequest(res, "sinceMs cannot be combined with n (a count and a window are rival shapes)");
+            return null;
+        }
+        const sinceMs = sinceMsQuery(q, res, LOGS_SINCE_MAX_MS, (ms) => `sinceMs is capped at ${humanSeconds(LOGS_SINCE_MAX_MS / 1000)} (got ${ms})`);
+        if (sinceMs === null)
+            return null;
+        const untilMs = untilMsQuery(q, res, sinceMs);
+        if (untilMs === null)
+            return null;
+        return { kind: "window", sinceMs, untilMs };
+    }
+    if (untilMsQuery(q, res, undefined) === null)
+        return null; // a count has no window end to move
+    return { kind: "count" };
+}
 export function handleHistory(q, res, root) {
     const role = q.get("role") || null; // "" and absent both read all roles
     const grep = q.get("grep") || null; // "" and absent both filter nothing
@@ -110,24 +135,16 @@ export function handleHistory(q, res, root) {
     const modelPieces = splitCommaListUnique(q.get("model") ?? "");
     const onModels = (rows) => (modelPieces.length ? runRowsOnModels(rows, modelPieces) : rows);
     const summary = q.get("summary") !== null; // the flag's presence, whatever its value
-    if (q.get("sinceMs") !== null) {
-        if (q.get("n") !== null) {
-            badRequest(res, "sinceMs cannot be combined with n (a count and a window are rival shapes)");
-            return;
-        }
-        const sinceMs = sinceMsQuery(q, res, LOGS_SINCE_MAX_MS, (ms) => `sinceMs is capped at ${humanSeconds(LOGS_SINCE_MAX_MS / 1000)} (got ${ms})`);
-        if (sinceMs === null)
-            return;
-        const untilMs = untilMsQuery(q, res, sinceMs);
-        if (untilMs === null)
-            return;
+    const windowCtl = windowOrCount(q, res);
+    if (windowCtl === null)
+        return;
+    if (windowCtl.kind === "window") {
+        const { sinceMs, untilMs } = windowCtl;
         const { rows, covered } = readRunRowsSince(root, sinceMs, role, untilMs ?? null);
         const matched = onModels(inClasses(grep === null ? rows : runRowsMatchingGrep(rows, grep)));
         sendJson(res, 200, { rows: matched, covered, note: covered ? "" : SPARSE_WINDOW_NOTE, ...(summary ? { summary: summarizeRunRows(matched), modelSummary: summarizeRunRowsByModel(matched) } : {}) });
         return;
     }
-    if (untilMsQuery(q, res, undefined) === null)
-        return; // a count has no window end to move
     const parsed = intQuery(q, res, "n", "non-negative", HISTORY_DEFAULT_RUNS);
     if (parsed === null)
         return;
@@ -169,17 +186,11 @@ export function handleLogs(q, res, root) {
     const grep = q.get("grep") || null; // "" and absent both filter nothing
     const needle = grep === null ? null : grep.toLowerCase();
     const keep = (e) => (role === null || eventRole(e) === role) && (needle === null || eventMatchesGrep(e, needle));
-    if (q.get("sinceMs") !== null) {
-        if (q.get("n") !== null) {
-            badRequest(res, "sinceMs cannot be combined with n (a count and a window are rival shapes)");
-            return;
-        }
-        const sinceMs = sinceMsQuery(q, res, LOGS_SINCE_MAX_MS, (ms) => `sinceMs is capped at ${humanSeconds(LOGS_SINCE_MAX_MS / 1000)} (got ${ms})`);
-        if (sinceMs === null)
-            return;
-        const untilMs = untilMsQuery(q, res, sinceMs);
-        if (untilMs === null)
-            return;
+    const windowCtl = windowOrCount(q, res);
+    if (windowCtl === null)
+        return;
+    if (windowCtl.kind === "window") {
+        const { sinceMs, untilMs } = windowCtl;
         const { cutoff, events: windowEvents, covered } = readEventsSince(root, sinceMs);
         const events = untilMs === undefined ? windowEvents : windowEvents.filter((e) => e.ts < cutoff + sinceMs - untilMs);
         sendJson(res, 200, {
@@ -189,8 +200,6 @@ export function handleLogs(q, res, root) {
         });
         return;
     }
-    if (untilMsQuery(q, res, undefined) === null)
-        return; // a count has no window end to move
     const parsed = intQuery(q, res, "n", "non-negative", LOGS_SEARCH_EVENTS);
     if (parsed === null)
         return;