tumwater 0.2.0 → 0.3.0

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

@@ -0,0 +1,96 @@
+/**
+ * The dashboard's GET settings/admin handlers (src/gui/gui-server.ts routes to them):
+ * prompt-text, doctor, config, retire-list, and brief. Each answers its request and touches no
+ * socket beyond its own `res`; the domain work lives one layer down (doctor/doctor.js,
+ * config/config.js, operator/retire.js), so this module only adapts HTTP onto it. Barrelled
+ * into gui/gui-endpoints.ts beside the other per-family GET endpoint modules.
+ */
+import { runDoctor } from "../doctor/doctor.js";
+import { knownRoleIds, loadConfigSafe } from "../config/config.js";
+import { runnerEnabled } from "../roles/runner-ids.js";
+import { artifactPhrase, previewRetire } from "../operator/retire.js";
+import { EDITABLE_CONFIG_KEYS } from "../config/config-editable-keys.js";
+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";
+/** 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
+ * address), so a stale poll's snapshot can never read the wrong entry; the not-before deferral
+ * marker and the `[image attached: …]` reference block are stripped, both plumbing the edit
+ * carries over unchanged. The role is optional (absent reads the director's queue) and
+ * validates exactly like /api/transcript; a file name failing the shared
+ * rejectBadQueueFileName guard is a user-input error answered 400 with nothing read. A
+ * vanished file answers 200 { ok: true, status: "gone" } — the role already dequeued
+ * it, which is data for the UI, not a server fault. Reads one file directly, so it works
+ * whether or not the team is running. */
+export function handlePromptText(q, res, root) {
+    const roleParam = q.get("role");
+    if (roleParam !== null && rejectBadRole(root, res, roleParam))
+        return;
+    const role = roleParam ?? DIRECTOR_ROLE;
+    const file = q.get("file");
+    if (rejectBadQueueFileName(res, file))
+        return;
+    const text = readQueuedPromptBody(root, role, file);
+    if (text === null) {
+        okGone(res);
+        return;
+    }
+    sendJson(res, 200, { ok: true, text });
+}
+/** 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")) {
+    sendJson(res, 200, await run(root));
+}
+/** Handle GET /api/config: the Settings view's resolved values for exactly
+ * EDITABLE_CONFIG_KEYS — read through the same load path `tumwater config get` uses
+ * (loadConfigSafe, defaults merged in), so the page shows what the team would actually
+ * load. A broken or invalid tumwater.json answers 500 with validateConfig's message instead
+ * of serving a half-empty panel. */
+export function handleConfig(res, root) {
+    const { config, error } = loadConfigSafe(root);
+    if (config === undefined) {
+        sendJson(res, 500, { error });
+        return;
+    }
+    const record = config;
+    const out = {};
+    for (const key of EDITABLE_CONFIG_KEYS)
+        out[key] = record[key] ?? null;
+    sendJson(res, 200, out);
+}
+/** Handle GET /api/retire: the Settings view's "Disabled roles" card — every configured,
+ * disabled, non-director role, with what `tumwater retire` would remove (previewRetire, so the
+ * rails and wording are the CLI's) and the rails' objections. `wouldRemove` is empty when there
+ * is nothing to retire (a role disabled with a clean checkout), so the card can also re-enable
+ * a role via POST /api/role-enable. Read-only (previewRetire's contract) and works whether or
+ * not the team runs; a throw reaches the server's outer 500, an unreadable tumwater.json
+ * answers 500 like /api/config. */
+export async function handleRetireList(res, root) {
+    const { config, error } = loadConfigSafe(root);
+    if (config === undefined) {
+        sendJson(res, 500, { error });
+        return;
+    }
+    const roles = [];
+    for (const role of knownRoleIds(config).filter((id) => id !== DIRECTOR_ROLE && !runnerEnabled(config, id))) {
+        const { wouldRemove, objections } = await previewRetire(root, role);
+        roles.push({ role, wouldRemove, phrases: wouldRemove.map((a) => artifactPhrase(a, role)), objections });
+    }
+    sendJson(res, 200, { roles });
+}
+/** Handle GET /api/brief: the brief file's name and the current brief text (what
+ * `tumwater brief --json` prints), or 404 when no brief carries a prompt block. */
+export function handleBrief(res, root) {
+    const brief = readBrief(root);
+    if (brief === null)
+        return sendJson(res, 404, { error: "no project brief with a prompt block found — run `tumwater init` first" });
+    sendJson(res, 200, { file: brief.file, prompt: brief.prompt });
+}

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

@@ -1,6 +1,6 @@
 /**
  * The request-argument validators behind the dashboard's /api endpoints (gui/gui-endpoints.ts's
- * GET handlers and gui/gui-endpoint-commands.ts's POST handlers call them): loop-targeting role
+ * GET handlers and gui/gui-endpoint-commands.ts's POST handlers call them): role-targeting role
  * validation, integer query parsing, the report
  * endpoints' days window, and the body-field checks the paired operator endpoints
  * (/api/prompt and /api/prompt-role, /api/pause and /api/pause-role) must answer with
@@ -14,10 +14,10 @@ import { REPORT_DEFAULT_DAYS, REPORT_MAX_DAYS } from "../events/event-window.js"
 import { promptLengthProblem } from "../inbox/inbox-submit.js";
 import { queueFileNameProblem } from "../inbox/inbox-cancel.js";
 import { DIRECTOR_ROLE } from "../roles/roles.js";
-import { gotSuffix, parseNonNegativeInt, parsePositiveInt } from "../text/text.js";
+import { gotSuffix, parseNonNegativeInt, parsePositiveInt, splitCommaListUnique } from "../text/text.js";
 import { typoSuffix } from "../text/suggest.js";
 import { badRequest, sendJson } from "./http-body.js";
-/** The role ids a loop-targeting endpoint accepts: when tumwater.json parses, catalog +
+/** 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
  * /api/transcript and the two operator endpoints so their validation and 400 wording cannot
@@ -25,7 +25,7 @@ import { badRequest, sendJson } from "./http-body.js";
 export function validRoleIds(root) {
     return knownRoleIdsCached(root);
 }
-/** Validate one request's loop-targeting role against validRoleIds, sending the shared 400 on
+/** Validate one request's role-targeting role against validRoleIds, sending the shared 400 on
  * a miss and reporting whether the request should stop: an absent id reads "role required
  * (valid ids: …)" — unless `allowMissing`, the wake endpoint's `{}` → all-roles default,
  * which only a truly absent `undefined` may ride; an explicit null is always rejected — and a
@@ -50,6 +50,24 @@ export function rejectBadRole(root, res, role, allowMissing = false) {
     }
     return false;
 }
+/** Parse the GET endpoints' `?role=` comma-separated list (each id trimmed, deduplicated, and
+ * validated by rejectBadRole; an empty list or unknown id → 400). Returns undefined when
+ * `role` is absent and null once a 400 is sent. Shared by /api/diff and the report endpoints'
+ * reportScope so the role-list rule cannot drift between them. */
+export function roleListQuery(q, res, root) {
+    const raw = q.get("role");
+    if (raw === null)
+        return undefined;
+    const roles = splitCommaListUnique(raw);
+    if (roles.length === 0) {
+        rejectBadRole(root, res, raw);
+        return null;
+    }
+    for (const r of roles)
+        if (rejectBadRole(root, res, r))
+            return null;
+    return roles;
+}
 /** Validate one request's file-addressed queue name (a queued prompt's basename) through
  * inbox-cancel.ts's queueFileNameProblem, sending its reason as the shared 400 and reporting
  * whether the request should stop — the file twin of rejectBadRole above. The three
@@ -87,6 +105,11 @@ export function intQuery(q, res, name, kind, fallback) {
     }
     return parsed;
 }
+/** Clamp a parsed count into 1..max: the bound every GUI count query (`n`, `days`) applies after
+ * its parse, so a request never asks for zero or more than the endpoint's cap. */
+export function clampCount(n, max) {
+    return Math.min(max, Math.max(1, n));
+}
 /** The window both report endpoints serve, from ?days=N on the request. One exact rule,
  * shared so /api/report and /api/failures cannot drift: missing or non-decimal →
  * REPORT_DEFAULT_DAYS, out-of-range clamped to 1..REPORT_MAX_DAYS (the same bounds the CLI's
@@ -97,7 +120,7 @@ export function intQuery(q, res, name, kind, fallback) {
  * coerced value — raw Number.parseInt would read "1e3" as 1, "0x10" as 0, and "-5" as -5. */
 export function windowDays(q) {
     const n = parseNonNegativeInt(q.get("days") ?? "");
-    return n === null ? REPORT_DEFAULT_DAYS : Math.min(REPORT_MAX_DAYS, Math.max(1, n));
+    return n === null ? REPORT_DEFAULT_DAYS : clampCount(n, REPORT_MAX_DAYS);
 }
 /** Pull the prompt text out of a prompt endpoint's body — the shared validator for
  * /api/prompt and /api/prompt-role, which must reject a non-string, blank, or over-long text
@@ -107,7 +130,7 @@ export function windowDays(q) {
 export function requirePromptText(res, body, role = DIRECTOR_ROLE) {
     const text = body.text;
     if (typeof text !== "string") {
-        sendJson(res, 400, { error: `text must be a string${text === undefined ? "" : gotSuffix(text)}` });
+        sendJson(res, 400, { error: `text must be a string${gotSuffix(text)}` });
         return null;
     }
     if (!text.trim()) {
@@ -140,6 +163,29 @@ export function sinceMsQuery(q, res, maxMs, overCap) {
     }
     return sinceMs;
 }
+/** Parse the report, failures, history and logs endpoints' optional `?untilMs=` window end — how
+ * long ago a `sinceMs` window stops, the twin of the CLI's `--until`. Absent → undefined (the
+ * window ends now). Present without a `sinceMs` → 400 (the CLI's "--until requires --since"),
+ * so the count and day shapes never ignore it silently; otherwise the value rides intQuery's
+ * positive-integer rule, and one not shorter than `sinceMs` is a 400 (the CLI's "must be
+ * shorter than --since"; sinceMs is already capped, so this bounds untilMs too). Returns the
+ * parsed length, undefined when absent, or null once the 400 is sent. */
+export function untilMsQuery(q, res, sinceMs) {
+    if (q.get("untilMs") === null)
+        return undefined;
+    if (sinceMs === undefined) {
+        badRequest(res, "untilMs requires sinceMs (it ends a sinceMs window that long ago)");
+        return null;
+    }
+    const untilMs = intQuery(q, res, "untilMs", "positive");
+    if (untilMs === null)
+        return null;
+    if (untilMs >= sinceMs) {
+        badRequest(res, `untilMs (${untilMs}) must be shorter than sinceMs (${sinceMs})`);
+        return null;
+    }
+    return untilMs;
+}
 /** Pull the required curated config key out of a config endpoint's body — the shared validator
  * for /api/config-set and /api/config-unset, which must reject a missing or uncurated key with
  * the same 400 wording: the panel's reach stays exactly EDITABLE_CONFIG_KEYS, and the browser and
@@ -149,11 +195,36 @@ export function sinceMsQuery(q, res, maxMs, overCap) {
 export function requireConfigKey(res, body) {
     const key = body.key;
     if (typeof key !== "string" || !EDITABLE_CONFIG_KEYS.includes(key)) {
-        badRequest(res, `key must be one of ${EDITABLE_CONFIG_KEYS.join(", ")}${key === undefined ? "" : gotSuffix(key)}${typeof key === "string" ? typoSuffix(key, EDITABLE_CONFIG_KEYS) : ""}`);
+        badRequest(res, `key must be one of ${EDITABLE_CONFIG_KEYS.join(", ")}${gotSuffix(key)}${typeof key === "string" ? typoSuffix(key, EDITABLE_CONFIG_KEYS) : ""}`);
         return null;
     }
     return key;
 }
+/** Pull the required, non-blank string `role` out of a config POST body — the shared 400
+ * (`role required`) for the role-cap, min-run-interval, instances, model, instructions,
+ * role-enable/disable, and quiet-hours handlers in gui-config-commands.ts. Returns the role
+ * as sent (untrimmed, not yet validated against the role list), or null once the 400 is sent. */
+export function requireRoleField(res, body) {
+    const role = body.role;
+    if (typeof role !== "string" || role.trim() === "") {
+        badRequest(res, "role required");
+        return null;
+    }
+    return role;
+}
+/** Pull a required string field out of a POST body — the shared 400 for the editors whose body
+ * carries a full replacement text that may be "" to clear it (role instructions, quiet-hours
+ * window, role notes, the brief, and the model handler's optional provider/model/thinking
+ * fields). `meaning` completes the message after the em dash. Returns the string as sent, or
+ * null once the 400 is sent. */
+export function requireStringField(res, body, key, meaning) {
+    const value = body[key];
+    if (typeof value !== "string") {
+        badRequest(res, `"${key}" must be a string — ${meaning}${gotSuffix(value)}`);
+        return null;
+    }
+    return value;
+}
 /** Pull the required `paused` boolean out of a pause endpoint's body — the shared validator
  * for /api/pause and /api/pause-role, which must reject a missing or non-boolean target state
  * with the same 400 wording: the target state is explicit (`paused: true|false`), so a retried
@@ -162,7 +233,7 @@ export function requireConfigKey(res, body) {
 export function requirePausedFlag(res, body) {
     const value = body.paused;
     if (typeof value !== "boolean") {
-        sendJson(res, 400, { error: `paused must be a boolean${value === undefined ? "" : gotSuffix(value)}` });
+        sendJson(res, 400, { error: `paused must be a boolean${gotSuffix(value)}` });
         return null;
     }
     return value;

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

@@ -1,4 +1,3 @@
-// vocabulary: plain
 /**
  * The dashboard's POST backlog/QUESTIONS command handlers (barrelled into
  * gui/gui-endpoint-commands.ts, which routes to them from src/gui/gui-server.ts):
@@ -8,9 +7,14 @@
  * HTTP onto the domain work one layer down (backlog-write, question-answer, backlog-commit)
  * and touches no socket beyond its own `res`.
  */
+import { backlogHolds, cancelledClaimNote, stillHeldNote } from "../backlog/backlog-eligibility.js";
+import { entryKey, plansReleasedBy, releasedPartsNote } from "../backlog/backlog-parts.js";
+import { plannedPlanEntries } from "../backlog/backlog.js";
+import { allLiveClaims } from "../runner/runner-state-load.js";
 import { commitOperatorBacklogEdit } from "../backlog/backlog-commit.js";
 import { stampedSubject } from "../git/commit-message.js";
-import { fileEntryWithBody, normalizeEntryBody, OPERATOR_FILE_KINDS, tryCancelEntry, tryEditEntry, tryMoveEntryToTop, tryReleaseEntry, bodyStructureProblem } from "../backlog/backlog-write.js";
+import { fileEntryWithBody, normalizeEntryBody, OPERATOR_FILE_KINDS, tryCancelEntry, tryEditEntry, bodyStructureProblem } from "../backlog/backlog-write.js";
+import { tryMoveEntryToTop, tryReleaseEntry } from "../backlog/backlog-release.js";
 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";
@@ -23,7 +27,7 @@ import { readPostBody } from "./gui-endpoint-common.js";
 function checkedBacklogKind(res, body) {
     const kind = body.kind;
     if (kind !== "bug" && kind !== "plan") {
-        badRequest(res, `kind must be "bug" or "plan"${kind === undefined ? "" : gotSuffix(kind)}`);
+        badRequest(res, `kind must be "bug" or "plan"${gotSuffix(kind)}`);
         return null;
     }
     return kind;
@@ -36,11 +40,11 @@ function checkedBacklogKind(res, body) {
 function checkedEntryPositionAndTitle(res, body) {
     const { position, title } = body;
     if (typeof position !== "number" || !Number.isInteger(position) || position < 1) {
-        badRequest(res, `position must be a positive integer${position === undefined ? "" : gotSuffix(position)}`);
+        badRequest(res, `position must be a positive integer${gotSuffix(position)}`);
         return null;
     }
     if (typeof title !== "string" || title === "") {
-        badRequest(res, `title must be a non-empty string${title === undefined ? "" : gotSuffix(title)}`);
+        badRequest(res, `title must be a non-empty string${gotSuffix(title)}`);
         return null;
     }
     return { position, title };
@@ -105,7 +109,7 @@ export async function handleQuestionAnswer(req, res, root) {
 }
 /** Handle POST /api/backlog-file: the Plans/Bugs tabs' New control — the same entry and wake
  * `tumwater bug`/`tumwater plan` produce (fileEntryWithBody, then the shared wake text to the
- * bugfix/feature loop). Body `{"kind": "bug"|"plan", "title": "...", "body": "optional
+ * bugfix/feature role). Body `{"kind": "bug"|"plan", "title": "...", "body": "optional
  * markdown"}`. The empty-title and wake-length checks run here, before anything is written:
  * the body is normalized and checked by bodyStructureProblem too, and an over-long wake
  * would throw after the entry merged. */
@@ -147,7 +151,8 @@ export async function handleBacklogFile(req, res, root) {
  * `tumwater plan|bug --cancel <n>` through the non-exiting tryCancelEntry. Body `{"kind":
  * "bug"|"plan", "position": <1-based>, "title": "<heading>"}`; a missing position or a
  * different heading there answers 200 { ok: true, status: "gone" } (the list moved since the
- * poll). No wake and no inbox prompt: removing work must not wake a loop. */
+ * poll). A cancelled plan that planned parts required adds `releasedNote` naming them, as
+ * `plan --cancel` prints. No wake and no inbox prompt: removing work must not wake a role. */
 export async function handleBacklogCancel(req, res, root) {
     const body = await readPostBody(req, res, '{"kind": "bug", "position": 1, "title": "<heading>"}');
     if (!body)
@@ -159,21 +164,30 @@ export async function handleBacklogCancel(req, res, root) {
     if (!pair)
         return;
     const { position, title } = pair;
+    const claims = allLiveClaims(root);
     const outcome = outcomeOrBadRequest(res, () => tryCancelEntry(root, kind, position, title));
     if (outcome === null)
         return;
     if (outcome.status === "cancelled") {
+        const workingNote = cancelledClaimNote(claims.get(entryKey(outcome.title)) ?? null);
+        const releasedNote = kind === "plan" ? releasedPartsNote(plansReleasedBy(plannedPlanEntries(root), outcome.title)) : "";
         const committed = await commitOperatorBacklogEdit(root, outcome.file, stampedSubject("operator", `Cancel ${kind}: ${outcome.title}`)); // vocabulary-ok: the commit prefix stays tumwater(operator):
-        sendJson(res, 200, { ok: true, status: "cancelled", file: outcome.file, title: outcome.title, committed });
+        sendJson(res, 200, { ok: true, status: "cancelled", file: outcome.file, title: outcome.title, committed, ...(workingNote === "" ? {} : { workingNote }), ...(releasedNote === "" ? {} : { releasedNote }) });
     }
     else {
         okGone(res);
     }
 }
+/** The hold on the kind's entry at a 1-based position (backlogHolds), `null` when eligible. */
+function heldAt(root, kind, position) {
+    const holds = backlogHolds(root);
+    return (kind === "bug" ? holds.bugs : holds.plans)[position - 1] ?? null;
+}
 /** 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 is newly eligible, so the kind's role is woken; `gone`
- * and `moved` answer okGone, and an entry with neither a Refused nor a Waiting-for-the-next-
+ * 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 neither a Refused nor a Waiting-for-the-next-
  * failure note 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>"}');
@@ -191,8 +205,10 @@ export async function handleBacklogRelease(req, res, root) {
         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):
-        requestWake(root, [OPERATOR_FILE_KINDS[kind].role]);
-        sendJson(res, 200, { ok: true, status: "released", file: outcome.file, title: outcome.title, committed });
+        const hold = heldAt(root, kind, position);
+        if (hold === null)
+            requestWake(root, [OPERATOR_FILE_KINDS[kind].role]);
+        sendJson(res, 200, { ok: true, status: "released", file: outcome.file, title: outcome.title, committed, ...(hold === null ? {} : { heldNote: stillHeldNote(hold) }) });
     }
     else if (outcome.status === "not_refused") {
         sendJson(res, 200, { ok: true, status: "not_refused", title: outcome.title });
@@ -203,8 +219,9 @@ export async function handleBacklogRelease(req, res, root) {
 }
 /** Handle POST /api/backlog-top: the entry drawer's Move to top — the same splice as
  * `tumwater plan|bug --top <n>` through the non-exiting tryMoveEntryToTop. Body as
- * backlog-cancel's. Reordering makes no entry newly eligible, so no role is woken; position 1
- * answers status "already_first" with no write, and `gone` and `moved` answer okGone. */
+ * backlog-cancel's. Reordering makes no entry newly eligible, so no role is woken (a held entry
+ * carries `heldNote`); position 1 answers status "already_first" with no write, and `gone` and
+ * `moved` answer okGone. */
 export async function handleBacklogTop(req, res, root) {
     const body = await readPostBody(req, res, '{"kind": "bug", "position": 2, "title": "<heading>"}');
     if (!body)
@@ -221,7 +238,8 @@ export async function handleBacklogTop(req, res, root) {
         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):
-        sendJson(res, 200, { ok: true, status: "moved_to_top", file: outcome.file, title: outcome.title, committed });
+        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) }) });
     }
     else if (outcome.status === "already_first") {
         sendJson(res, 200, { ok: true, status: "already_first", title: outcome.title });
@@ -233,8 +251,10 @@ export async function handleBacklogTop(req, res, root) {
 /** Handle POST /api/backlog-edit: the entry drawer's edit — tryEditEntry's title-checked,
  * in-place rewrite under the state lock. Body `{"kind", "position", "title", "newTitle",
  * "newBody"}`; a missing position or a different heading there answers 200 { ok: true, status:
- * "gone" }. The body keeps its line structure. No wake and no inbox prompt: whichever tick picks
- * the entry up refines it. */
+ * "gone" }; text identical to the entry's own answers 200 { ok: true, status: "unchanged", file,
+ * title } with nothing written or committed. An edited entry that is still held adds `heldNote`
+ * (stillHeldNote). The body keeps its line structure. No wake and no inbox prompt: whichever run
+ * picks the entry up refines it. */
 export async function handleBacklogEdit(req, res, root) {
     const body = await readPostBody(req, res, '{"kind": "bug", "position": 1, "title": "<heading>", "newTitle": "...", "newBody": "..."}');
     if (!body)
@@ -265,7 +285,11 @@ export async function handleBacklogEdit(req, res, root) {
         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):
-        sendJson(res, 200, { ok: true, status: "edited", file: outcome.file, title: outcome.title, committed });
+        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) }) });
+    }
+    else if (outcome.status === "unchanged") {
+        sendJson(res, 200, { ok: true, status: "unchanged", file: outcome.file, title: outcome.title });
     }
     else {
         okGone(res);

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

@@ -0,0 +1,155 @@
+/**
+ * The dashboard's GET backlog and unmerged-change handlers (src/gui/gui-server.ts routes to
+ * them): backlog, backlog-match, and diff. Each answers its request and touches no socket
+ * beyond its own `res`; the domain work lives one layer down (backlog/backlog.ts,
+ * 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 { 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 { 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,
+ * not an object literal, so no `file` spelling (`constructor`, `toString`, `__proto__`) can
+ * reach an inherited member through the lookup. Insertion order is the list order. */
+const BACKLOG_FILE_READERS = new Map([
+    ["plans", plannedPlanEntries],
+    ["bugs", openBugEntries],
+    ["questions", openQuestionEntries],
+    ["done", donePlanEntries],
+    ["fixed", fixedBugEntries],
+    ["answered", (root) => answeredQuestionEntries(root).reverse()],
+]);
+const BACKLOG_FILE_NAMES = [...BACKLOG_FILE_READERS.keys()];
+const BACKLOG_FILE_VALUES = BACKLOG_FILE_NAMES.join(", ");
+/** Handle GET /api/backlog?file=<plans|bugs|questions|done|fixed|answered>&index=N: one
+ * backlog entry's full text ({title, body}), fetched on demand so multi-KB bodies (long repros,
+ * whole plans) never ride the 1-second /api/status poll. index addresses the Nth entry of that
+ * file's section in the same order statusPayload lists its titles — plans: PLANS.md ## Planned,
+ * bugs: BUGS.md ## Open, questions: QUESTIONS.md ## Open, done: PLANS.md ## Done and fixed:
+ * BUGS.md ## Fixed (both newest first, the order of the dashboard's recent rows) and answered:
+ * QUESTIONS.md ## Answered, newest first (the file is appended to, so the reverse of file
+ * 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 plan (file === "plans" and the entry in
+ * operatorHeldEntries' selection), 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) {
+    const file = q.get("file");
+    if (file === null) {
+        badRequest(res, `file required (valid values: ${BACKLOG_FILE_VALUES})`);
+        return;
+    }
+    const reader = BACKLOG_FILE_READERS.get(file);
+    if (!reader) {
+        badRequest(res, `unknown file ${JSON.stringify(file)} (valid values: ${BACKLOG_FILE_VALUES})${typoSuffix(file, BACKLOG_FILE_NAMES)}`);
+        return;
+    }
+    const entries = reader(root);
+    const index = intQuery(q, res, "index", "non-negative");
+    if (index === null)
+        return;
+    const entry = entries[index];
+    if (!entry) {
+        badRequest(res, `index ${index} out of range (${file} has ${entries.length} entries)`);
+        return;
+    }
+    sendJson(res, 200, {
+        title: entry.title,
+        body: entry.body,
+        refused: refusalNote(entry.body) !== null,
+        waiting: waitingNote(entry.body) !== null,
+        ...(file === "plans" && operatorHeldEntries(root).some((e) => e.index === index) ? { heldForOperator: true } : {}),
+    });
+}
+/** Handle GET /api/backlog-match?grep=<text>: for each /api/backlog `file`, the ascending
+ * indexes (the ones /api/backlog?file=…&index=N addresses) whose entry heading or body contains
+ * the trimmed text, case-insensitively — the match `tumwater backlog --grep` and the TUI's `/`
+ * use — so the dashboard's Search can find text bodies hold without bodies riding the status
+ * poll. A `queued` key adds the queued messages whose full text (not only the 80-character
+ * preview) contains the text, as `{ role, file }` with the queue-file basename, director first —
+ * the match `tumwater prompt --list --grep` uses. Missing or blank grep → 400. */
+export function handleBacklogMatch(q, res, root) {
+    const needle = (q.get("grep") ?? "").trim();
+    if (!needle) {
+        badRequest(res, "grep required");
+        return;
+    }
+    const out = {};
+    for (const [file, reader] of BACKLOG_FILE_READERS) {
+        out[file] = reader(root).flatMap((entry, i) => (entryMatches(entry, needle) ? [i] : []));
+    }
+    const lower = needle.toLowerCase();
+    out.queued = queuedListRows(root, null, listWideScope(root))
+        .filter((row) => row.text.toLowerCase().includes(lower))
+        .map((row) => ({ role: row.role, file: row.file }));
+    sendJson(res, 200, out);
+}
+/** Handle GET /api/diff[?role=<id>]: the unmerged-change view the CLI prints from the same
+ * collectors — no `role` → collectTeamChanges (exactly `tumwater diff --json`'s document:
+ * `{ mainBranch, roles }`, no per-role patch halves); `?role=<id>` → collectRoleChange (the
+ * full per-role view with `diff`/`uncommittedDiff`, `tumwater diff --role <id> --json`). The
+ * role is a target, not a filter, so it validates through rejectBadRole exactly like
+ * /api/transcript and /api/run (unknown/missing → 400 naming the valid ids) — the same ids
+ * `parseRoleFlag` accepts on the CLI, including disabled and user-defined roles. The
+ * collectors degrade absent worktrees and missing base branches to their `state` instead of
+ * throwing, so a fresh or half-built repo still answers 200. Reads git plumbing directly, so
+ * it works whether or not the team is running. `?overlaps=1` serves collectChangeOverlaps
+ * (exactly `tumwater diff --overlaps --json`'s `{ mainBranch, state, overlaps }`); with `role` (a
+ * comma-separated list, each id validated) it keeps the files a listed role holds, exactly
+ * `tumwater diff --overlaps --role <ids> --json`; `&path=<path>` keeps the files at or under that
+ * path, exactly `tumwater diff --overlaps --path <path> --json`. `?role=<id>&stat=1` serves both
+ * halves as the `git diff --stat` summary, exactly `tumwater diff --role <id> --stat --json`. */
+export async function handleDiff(q, res, root) {
+    const rawPath = q.get("path");
+    const stat = q.get("stat") !== null;
+    if (q.get("overlaps") !== null) {
+        if (stat) {
+            badRequest(res, "overlaps lists paths, not patches; drop stat");
+            return;
+        }
+        const opath = rawPath === null ? undefined : normalizeDiffPath(rawPath);
+        if (opath === null) {
+            badRequest(res, "path takes a repo-relative path such as src/cli.ts (as overlaps lists it)");
+            return;
+        }
+        const roles = roleListQuery(q, res, root);
+        if (roles === null)
+            return;
+        let view = await collectChangeOverlaps(root);
+        if (roles !== undefined)
+            view = scopeChangeOverlaps(view, roles);
+        if (opath !== undefined)
+            view = scopeChangeOverlapsToPath(view, opath);
+        sendJson(res, 200, view);
+        return;
+    }
+    const role = q.get("role");
+    if (role === null) {
+        if (stat) {
+            badRequest(res, "stat needs role (the team roster carries no patch)");
+            return;
+        }
+        if (rawPath !== null) {
+            badRequest(res, "path needs role (the team roster carries no patch)");
+            return;
+        }
+        sendJson(res, 200, await collectTeamChanges(root));
+        return;
+    }
+    if (rejectBadRole(root, res, role))
+        return;
+    const path = rawPath === null ? undefined : normalizeDiffPath(rawPath);
+    if (path === null) {
+        badRequest(res, "path takes a repo-relative path such as src/cli.ts (as overlaps lists it)");
+        return;
+    }
+    sendJson(res, 200, await collectRoleChange(root, role, { ...(path === undefined ? {} : { path }), ...(stat ? { stat: true } : {}) }));
+}

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

@@ -6,8 +6,7 @@ import os from "node:os";
 import { startGui } from "./gui-server.js";
 import { errCode } from "../errno.js";
 import { fail, say } from "../cli/cli-output.js";
-import { flagValue, parsePortFlag } from "../cli/cli-args.js";
-import { TOKEN_VALUE_ERROR } from "../cli/cli-flag-specs.js";
+import { flagValue, parsePortFlag, tokenValueProblem } from "../cli/cli-args.js";
 /** External IPv4 addresses of this machine's network interfaces, for printing the URLs a
  * `gui --all-interfaces` server is reachable at. IPv6 and internal (loopback) addresses are
  * skipped: the loopback URL is printed separately, and bracketed IPv6 URLs are rarely what
@@ -43,17 +42,13 @@ export async function cmdGui(root, args, seams = {}) {
     const port = portRaw !== null ? parsePortFlag(portRaw) : 7180;
     const allInterfaces = args.includes("--all-interfaces");
     // A valueless or empty --token is a CLI error, not an open server: an operator who
-    // asked for protection must never silently get none. A flag-looking value is the
-    // same mistake in disguise — a valued flag claims the next token even when it is a
-    // known flag, so `--token --all-interfaces` would serve with the literal secret
-    // "--all-interfaces" (--all-interfaces still takes effect, since it is read straight
-    // from args) while the real secret sits unreached after another flag.
-    const tokenRaw = flagValue(args, "--token");
-    const token = tokenRaw ?? "";
-    if (tokenRaw !== null && !token)
-        fail(TOKEN_VALUE_ERROR);
-    if (tokenRaw !== null && token.startsWith("--"))
-        fail(`--token got the flag-looking value "${token}" instead of a secret — write the secret as its own argument (e.g. \`tumwater gui --token s3cret --all-interfaces\`)`);
+    // asked for protection must never silently get none. The validation and its wording
+    // live in tokenValueProblem, shared with `start --gui` so the two callers cannot
+    // drift; its flag-looking-value case names `tumwater gui` here.
+    const problem = tokenValueProblem(args, "tumwater gui");
+    if (problem)
+        fail(problem);
+    const token = flagValue(args, "--token") ?? "";
     try {
         await start(root, port, allInterfaces, token);
     }