tumwater 0.1.2 → 0.2.0

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

@@ -0,0 +1,49 @@
+/**
+ * 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 /
+ * 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";
+/** 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
+ * it again; each handler used to restate that contract in its own inline comment, and this is
+ * the one home for it. Handlers keep their own `if (!body) return` bail so the stop stays
+ * visible in their flow. */
+export async function readPostBody(req, res, example) {
+    const body = await readJsonObject(req, res, example);
+    if (body === null)
+        return null; // 4xx already sent — oversized or not a JSON object
+    return body;
+}
+/** The role-targeting POST handlers' shared prologue: readPostBody (400/413 sent on a null
+ * return) plus rejectBadRole's shared role validation (400 sent on a null return), so the
+ * wake/abort/prompt-role/pause-role family states the body-discipline-and-role-check pairing
+ * once instead of two guard lines per handler. Its null return means the response is already
+ * written and the handler must stop; callers keep their own `if (!body) return` bail. Exactly
+ * seven call sites — handlePromptRole, handleWake, handleWakeCancel and handleResetCounters
+ * (allowMissing, the {} → all-roles default), handleAbort, handlePauseRole, and
+ * handleRoleNotes; handlePromptCancel deliberately does not ride it, since its role is
+ * optional and validates only when present. */
+export async function readRoleBody(req, res, example, root, allowMissing = false) {
+    const body = await readPostBody(req, res, example);
+    if (body === null)
+        return null; // 4xx already sent — oversized, malformed, or not an object
+    if (rejectBadRole(root, res, body.role, allowMissing))
+        return null; // 400 already sent
+    return body;
+}
+/** Reply for a boolean-claiming marker request (RequestResult): success maps to 200 with its
+ * message, refusal to 409 — the request is valid but nothing can act on it, the same conflict
+ * reading requestAbort's not-live error uses. /api/restart and /api/abort share it. */
+export function sendRequestResult(res, result) {
+    if (!result.ok) {
+        sendJson(res, 409, { error: result.error });
+        return;
+    }
+    sendJson(res, 200, { ok: true, message: result.message });
+}

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

@@ -1,26 +1,42 @@
-import { openBugEntries, openQuestionEntries, plannedPlanEntries } from "../backlog/backlog.js";
+/**
+ * The dashboard's GET data endpoint handlers (src/gui/gui-server.ts routes to them): transcript,
+ * prompt-text, backlog, report, failures, history, tick, diff, config — the read-only surface.
+ * The POST
+ * operator endpoints (prompt, prompt-role, prompt-cancel, prompt-edit, budget, config-set, pause,
+ * wake, restart, abort, pause-role) and their body-discipline helpers live in
+ * gui/gui-endpoint-commands.ts. Each handler answers its request and touches no socket beyond
+ * its own `res`; server lifecycle, routing, the static page, and the token gate stay in
+ * gui/gui-server.ts. The domain work itself lives one layer down (transcript.ts, backlog.ts,
+ * report-data.ts, src/failure/failure-data.ts, history-data.ts, tick-detail-data.ts, config.ts)
+ * — this module only adapts HTTP onto it.
+ */
+import { refusalNote, waitingNote } from "../backlog/backlog-eligibility.js";
+import { answeredQuestionEntries, donePlanEntries, fixedBugEntries, openBugEntries, openQuestionEntries, plannedPlanEntries } from "../backlog/backlog.js";
 import { runDoctor } from "../doctor/doctor.js";
-import { loadConfigSafe } from "../config/config.js";
+import { knownRoleIds, loadConfigSafe } from "../config/config.js";
+import { loopEnabled } from "../roles/loop-ids.js";
+import { artifactPhrase, previewRetire } from "../operator/retire.js";
 import { EDITABLE_CONFIG_KEYS } from "../config/config-editable-keys.js";
 import { collectReport, collectReportSince } from "../report/report-data.js";
 import { collectFailureReport, collectFailureReportSince } from "../failure/failure-data.js";
 import { renderFailureMarkdown } from "../failure/failure-render.js";
 import { renderSinceReportMarkdown } from "../report/report-render.js";
-import { REPORT_SINCE_MAX_MS } from "../events/event-window.js";
+import { REPORT_SINCE_MAX_MS, reportSinceMsg } from "../events/event-window.js";
 import { humanSeconds } from "../text/datetime.js";
-import { collectFleetChanges, collectRoleChange } from "../change/change-data.js";
+import { collectTeamChanges, collectRoleChange } from "../change/change-data.js";
 import { readTranscript } from "../ui/transcript.js";
-import { HISTORY_DEFAULT_TICKS, HISTORY_MAX_TICKS, readTickRows, readTickRowsSince, tickRowsMatchingGrep } from "../history/history-data.js";
+import { HISTORY_DEFAULT_TICKS, HISTORY_MAX_TICKS, readTickRows, readTickRowsSince, summarizeTickRows, tickRowsMatchingGrep } from "../history/history-data.js";
 import { LOGS_SINCE_MAX_MS, SPARSE_WINDOW_NOTE } from "../events/event-window.js";
 import { eventRole, readEvents } from "../events/event-read.js";
 import { eventFeedItem, eventMatchesGrep } from "../events/event-format.js";
 import { readTickDetail } from "../tick/tick-detail-data.js";
-import { renderTickDetail, tickNotFoundMessage } from "../tick/tick-detail.js";
+import { renderTickDetail, tickDetailStat, tickNotFoundMessage } from "../tick/tick-detail.js";
 import { rolePayload } from "../roles/role-view.js";
 import { DIRECTOR_ROLE } from "../roles/roles.js";
 import { readQueuedPromptBody } from "../inbox/inbox-edit.js";
 import { intQuery, rejectBadQueueFileName, rejectBadRole, sinceMsQuery, windowDays } from "./gui-args.js";
-import { sendJson } from "./http-body.js";
+import { readBrief } from "../brief/brief.js";
+import { badRequest, okGone, sendJson } from "./http-body.js";
 import { typoSuffix } from "../text/suggest.js";
 /** Handle GET /api/transcript?role=<id>&n=N: rendered transcript lines for one loop's pi
  * log (same rendering as `tumwater logs --role <id>`). Unknown/missing role or a bad n → 400.
@@ -46,27 +62,33 @@ 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>&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 open
- * section in the same order statusPayload lists its titles — PLANS.md ## Planned,
- * BUGS.md ## Open, QUESTIONS.md ## Open — zero-based. Unknown/missing file, missing or bad
- * index, and out-of-range index → 400 JSON error via sendJson. The query arrives pre-parsed
- * (gui/gui-server.ts's parseRequestTarget), like every GET-data handler here. */
+/** 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.
+ * 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) {
-        sendJson(res, 400, { error: `file required (valid values: ${BACKLOG_FILE_VALUES})` });
+        badRequest(res, `file required (valid values: ${BACKLOG_FILE_VALUES})`);
         return;
     }
     const reader = BACKLOG_FILE_READERS.get(file);
     if (!reader) {
-        sendJson(res, 400, {
-            error: `unknown file ${JSON.stringify(file)} (valid values: ${BACKLOG_FILE_VALUES})${typoSuffix(file, BACKLOG_FILE_NAMES)}`,
-        });
+        badRequest(res, `unknown file ${JSON.stringify(file)} (valid values: ${BACKLOG_FILE_VALUES})${typoSuffix(file, BACKLOG_FILE_NAMES)}`);
         return;
     }
     const entries = reader(root);
@@ -75,25 +97,25 @@ export function handleBacklog(q, res, root) {
         return;
     const entry = entries[index];
     if (!entry) {
-        sendJson(res, 400, { error: `index ${index} out of range (${file} has ${entries.length} open entries)` });
+        badRequest(res, `index ${index} out of range (${file} has ${entries.length} entries)`);
         return;
     }
-    sendJson(res, 200, { title: entry.title, body: entry.body });
+    sendJson(res, 200, { title: entry.title, body: entry.body, refused: refusalNote(entry.body) !== null, waiting: waitingNote(entry.body) !== null });
 }
-/** Handle GET /api/diff[?role=<id>]: the unlanded-change view the CLI prints from the same
- * collectors — no `role` → collectFleetChanges (exactly `tumwater diff --json`'s document:
+/** 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/tick (unknown/missing → 400 naming the valid ids) — the same ids
+ * /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 loops. 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 fleet is running. */
+ * it works whether or not the team is running. */
 export async function handleDiff(q, res, root) {
     const role = q.get("role");
     if (role === null) {
-        sendJson(res, 200, await collectFleetChanges(root));
+        sendJson(res, 200, await collectTeamChanges(root));
         return;
     }
     if (rejectBadRole(root, res, role))
@@ -104,10 +126,10 @@ export async function handleDiff(q, res, root) {
  * usage report — the day series (collectReport's ReportData) as JSON the dashboard's report tab
  * charts, or, when sinceMs is set, the trailing-window totals rendered through
  * renderSinceReportMarkdown as { markdown } (the CLI's `report --since` shape), bounded by the
- * reportSinceMs helper. The day window follows windowDays. An absent role is the fleet-wide
+ * reportSinceMs helper. The day window follows windowDays. An absent role is the team-wide
  * report exactly as before; a present one is a filter, validated through rejectBadRole (unknown,
  * including the empty string → 400 naming the valid ids) and handed to the collector's role
- * scope. Reads files directly, so it works whether or not the fleet is running. */
+ * scope. Reads files directly, so it works whether or not the team is running. */
 export function handleReport(q, res, root) {
     const role = q.get("role");
     if (role !== null && rejectBadRole(root, res, role))
@@ -129,19 +151,19 @@ export function handleReport(q, res, root) {
  * null once the 400 is sent. */
 function reportSinceMs(q, res) {
     if (q.get("days") !== null) {
-        sendJson(res, 400, { error: "days and sinceMs are mutually exclusive; days counts whole local days, sinceMs totals a trailing window" });
+        badRequest(res, "days and sinceMs are mutually exclusive; days counts whole local days, sinceMs totals a trailing window");
         return null;
     }
-    return sinceMsQuery(q, res, REPORT_SINCE_MAX_MS, (sinceMs) => `sinceMs must be between 1 and ${humanSeconds(REPORT_SINCE_MAX_MS / 1000)} (got ${sinceMs})`);
+    return sinceMsQuery(q, res, REPORT_SINCE_MAX_MS, reportSinceMsg);
 }
 /** Handle GET /api/failures?days=N[&role=<id>] or /api/failures?sinceMs=<ms>[&role=<id>]: the
  * same bounded Markdown failure digest the telemetry loop feeds on and `tumwater report
  * --failures` prints, as JSON ({ markdown }) — the dashboard's failures tab renders it; with
  * sinceMs it is the trailing-window digest (collectFailureReportSince) through the same render,
  * the CLI's `report --failures --since` shape. The days window follows windowDays (so it can
- * never drift from /api/report's). role rides the same absent-fleet / present-filter rule as
- * handleReport: absent → the fleet digest, present → validated and scoped. Reads files
- * directly, so it works with no fleet running. */
+ * never drift from /api/report's). role rides the same absent-team / present-filter rule as
+ * handleReport: absent → the team digest, present → validated and scoped. Reads files
+ * directly, so it works with no team running. */
 export function handleFailures(q, res, root) {
     const role = q.get("role");
     if (role !== null && rejectBadRole(root, res, role))
@@ -158,16 +180,17 @@ export function handleFailures(q, res, root) {
 /** Handle GET /api/history?role=<id>&n=N[&grep=<text>] — or ?role=<id>&sinceMs=<ms> for a
  * trailing window: the per-tick rows the CLI's `tumwater history` derives from the event log,
  * the dashboard's history tab renders them. The count shape ({ rows }) rides readTickRows (the
- * shared scan, window growth included, so a role-filtered ask on a busy fleet cannot silently
+ * shared scan, window growth included, so a role-filtered ask on a busy team cannot silently
  * come back short); n is optional: absent → HISTORY_DEFAULT_TICKS; present but not a plain
  * non-negative integer → 400 (the handleBacklog index discipline — an explicit count that does
  * not parse is a client error, unlike the report's degrade-to-default typo rule); then clamped
  * to [1, HISTORY_MAX_TICKS] — the GUI clamps where the CLI fails fast, its established
  * convention. grep is optional: absent or empty filters nothing; present → the rows are
- * filtered through history-data.ts's shared tickRowsMatchingGrep rule, the same case-insensitive haystack rule
- * `tumwater history --grep` uses (shared, not re-implemented), after the n/role scan so n
- * bounds the scanned window and not the printed rows — the CLI's rule. The window shape
- * ({ rows, covered, note }) rides readTickRowsSince, the collector behind `history --since`,
+ * filtered through history-data.ts's shared tickRowsMatchingGrep rule, the same
+ * case-insensitive haystack rule `tumwater history --grep` uses (shared, not
+ * re-implemented), after the n/role scan so n bounds the scanned window and not the
+ * printed rows — the CLI's rule. The window shape ({ rows, covered, note }) rides
+ * readTickRowsSince, the collector behind `history --since`,
  * so the browser and the CLI cannot disagree about the window's rows; a simultaneous n is a
  * rival shape → 400 (the CLI's count-vs-window rule), sinceMs parses and is capped through
  * sinceMsQuery (gui-args.ts, LOGS_SINCE_MAX_MS — the shared `history --since` cap), and note is
@@ -175,13 +198,21 @@ export function handleFailures(q, res, root) {
  * loops; present → passed straight through as the role filter with no config validation (a
  * filter is not a target — an id with no ticks legitimately yields zero rows), so the endpoint
  * reads nothing but files, like /api/report and /api/failures. Reads files directly, so it
- * works whether or not the fleet is running. */
+ * present → passed straight through as the role filter with no config validation (a
+ * filter is not a target — an id with no ticks legitimately yields zero rows), so the endpoint
+ * reads nothing but files, like /api/report and /api/failures. summary is optional: absent /
+ * empty adds nothing (the response is byte-for-byte today's); present (any value — the flag's
+ * mere presence, a bad value ignored like a missing one) adds an additive `summary` folding the
+ * exact served rows through the shared summarizeTickRows collector, the same tally
+ * `tumwater history --summary` prints, so the dashboard Summary and the table cannot disagree
+ * about what a tick was. Reads files directly, so it works whether or not the team is running. */
 export function handleHistory(q, res, root) {
     const role = q.get("role") || null; // "" and absent both read all loops
     const grep = q.get("grep") || null; // "" and absent both filter nothing
+    const summary = q.get("summary") !== null; // the flag's presence, whatever its value
     if (q.get("sinceMs") !== null) {
         if (q.get("n") !== null) {
-            sendJson(res, 400, { error: "sinceMs cannot be combined with n (a count and a window are rival shapes)" });
+            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})`);
@@ -189,7 +220,7 @@ export function handleHistory(q, res, root) {
             return;
         const { rows, covered } = readTickRowsSince(root, sinceMs, role);
         const matched = grep === null ? rows : tickRowsMatchingGrep(rows, grep);
-        sendJson(res, 200, { rows: matched, covered, note: covered ? "" : SPARSE_WINDOW_NOTE });
+        sendJson(res, 200, { rows: matched, covered, note: covered ? "" : SPARSE_WINDOW_NOTE, ...(summary ? { summary: summarizeTickRows(matched) } : {}) });
         return;
     }
     const parsed = intQuery(q, res, "n", "non-negative", HISTORY_DEFAULT_TICKS);
@@ -199,7 +230,7 @@ export function handleHistory(q, res, root) {
     let rows = readTickRows(root, n, role);
     if (grep !== null)
         rows = tickRowsMatchingGrep(rows, grep);
-    sendJson(res, 200, { rows });
+    sendJson(res, 200, summary ? { rows, summary: summarizeTickRows(rows) } : { rows });
 }
 /** How many of the log's newest events `GET /api/logs` scans by default, and the most it will
  * scan however large `n` asks: the CLI's `-n` shape (n bounds the scanned tail, not the printed
@@ -220,7 +251,7 @@ const LOGS_SEARCH_MAX_EVENTS = 5000;
  * Reads the tail through readEvents' stat-keyed cache (no covered byte end, unlike the CLI's
  * follow), so a dashboard search that repeats on an unchanged log — the debounced filter fires
  * one per filter change — costs one stat instead of re-reading and re-parsing the scanned tail.
- * Reads files directly, so it works whether or not the fleet is running. */
+ * Reads files directly, so it works whether or not the team is running. */
 export function handleLogs(q, res, root) {
     const parsed = intQuery(q, res, "n", "non-negative", LOGS_SEARCH_EVENTS);
     if (parsed === null)
@@ -233,7 +264,7 @@ export function handleLogs(q, res, root) {
     const matched = events.filter((e) => (role === null || eventRole(e) === role) && (needle === null || eventMatchesGrep(e, needle)));
     sendJson(res, 200, { events: matched.map(eventFeedItem) });
 }
-/** Handle GET /api/tick?role=<id>&tick=N: one tick's full event trail — readTickDetail's
+/** Handle GET /api/run?role=<id>&run=N: one tick's full event trail — readTickDetail's
  * TickDetail, the collector `tumwater tick <role> <n>` prints from, plus `text`: the same
  * payload through renderTickDetail, pre-rendered server-side like /api/transcript's lines so
  * the browser shows the CLI's exact rendering instead of re-implementing the event formatting.
@@ -243,12 +274,12 @@ export function handleLogs(q, res, root) {
  * through intQuery (missing or not a positive integer → 400); and a tick the scanned window
  * does not hold — never ran, or rotation ate it — answers 404 with tickNotFoundMessage, the
  * CLI's exact not-found wording,
- * never a crash. Reads files directly, so it works whether or not the fleet is running. */
-export function handleTick(q, res, root) {
+ * never a crash. Reads files directly, so it works whether or not the team is running. */
+export async function handleTick(q, res, root) {
     const role = q.get("role");
     if (rejectBadRole(root, res, role))
         return;
-    const tick = intQuery(q, res, "tick", "positive");
+    const tick = intQuery(q, res, "run", "positive");
     if (tick === null)
         return;
     const detail = readTickDetail(root, role, tick);
@@ -256,15 +287,15 @@ export function handleTick(q, res, root) {
         sendJson(res, 404, { error: tickNotFoundMessage(role, tick) });
         return;
     }
-    sendJson(res, 200, { ...detail, text: renderTickDetail(detail) });
+    sendJson(res, 200, { ...detail, text: renderTickDetail(detail), stat: await tickDetailStat(root, detail) });
 }
 /** Handle GET /api/role?role=<id>: one loop's inspection payload — rolePayload's object,
  * the same collection behind `tumwater role <id>` — so the drawer's Notebook and Next tick
  * prompt sections render what the CLI shows without re-implementing the assembly. The role
  * is a target here, so it validates through rejectBadRole exactly like /api/transcript and
- * /api/tick (unknown/missing → the shared 400 naming the valid ids and correcting typos);
+ * /api/run (unknown/missing → the shared 400 naming the valid ids and correcting typos);
  * rolePayload is only reached with an id rejectBadRole accepted, so its own unknown-role
- * throw never fires. Reads files directly, so it works whether or not the fleet is running. */
+ * throw never fires. Reads files directly, so it works whether or not the team is running. */
 export function handleRole(q, res, root) {
     const role = q.get("role");
     if (rejectBadRole(root, res, role))
@@ -278,9 +309,10 @@ export function handleRole(q, res, root) {
  * 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 loop already dequeued it, which is data for the UI, not
- * a server fault. Reads one file directly, so it works whether or not the fleet is running. */
+ * rejectBadQueueFileName guard is a user-input error answered 400 with nothing read. A
+ * vanished file answers 200 { ok: true, status: "gone" } — the loop 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))
@@ -291,21 +323,21 @@ export function handlePromptText(q, res, root) {
         return;
     const text = readQueuedPromptBody(root, role, file);
     if (text === null) {
-        sendJson(res, 200, { ok: true, status: "gone" });
+        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 fleet is running. `run`
+ * nothing (runDoctor's own contract) — and it works whether or not the team is running. `run`
  * exists so tests can skip the host probes; a throw reaches the server's outer 500. */
-export async function handleDoctor(res, root, run = runDoctor) {
+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 fleet would actually
+ * (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) {
@@ -320,3 +352,31 @@ export function handleConfig(res, root) {
         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 && !loopEnabled(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 initial prompt (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-operator-commands.js

@@ -0,0 +1,145 @@
+// vocabulary: plain
+/**
+ * The dashboard's POST operator-lifecycle command handlers (barrelled into
+ * gui/gui-endpoint-commands.ts, which routes to them from src/gui/gui-server.ts): reset-counters,
+ * restart, reclaim, abort, stop-schedule, role-notes, retire, and brief-edit — every POST
+ * handler that is not prompt/backlog/config/team. Each handler adapts HTTP onto the domain work
+ * one layer down (operator-intent, role-notes-write, brief-edit) and touches no socket beyond
+ * its own `res`.
+ */
+import { cancelScheduledStopMessage, requestAbort, requestResetCounters, requestRestart, requestScheduledStop, runManualReclaim } from "../operator/operator-intent.js";
+import { saveRoleNote } from "../agent/role-notes-write.js";
+import { roleNotesPath } from "../paths.js";
+import { DIRECTOR_ROLE } from "../roles/roles.js";
+import { artifactPhrase, retireRole } from "../operator/retire.js";
+import { editInitialPrompt } from "../brief/brief-edit.js";
+import { validRoleIds } from "./gui-args.js";
+import { badRequest, sendJson } from "./http-body.js";
+import { errorMessage, gotSuffix } from "../text/text.js";
+import { readPostBody, readRoleBody, sendRequestResult } from "./gui-endpoint-common.js";
+import { wakeInSecondsMs } from "./gui-team-commands.js";
+/** Handle POST /api/reset-counters: the dashboard's counter reset — the same marker-writing
+ * core `tumwater reset-counters` calls (requestResetCounters). Same body discipline and
+ * `{}` → every configured role default as /api/wake. */
+export async function handleResetCounters(req, res, root) {
+    const body = await readRoleBody(req, res, '{"role": "feature"}', root, true);
+    if (!body)
+        return;
+    sendJson(res, 200, {
+        ok: true,
+        message: requestResetCounters(root, body.role === undefined ? validRoleIds(root) : [body.role]),
+    });
+}
+/** Handle POST /api/stop-schedule: the dashboard's "Stop the team later" control — the same
+ * cores `tumwater stop --in`/`--cancel` call (requestScheduledStop, cancelScheduledStopMessage).
+ * `{"cancel": true}` drops the marker (no live team needed, like the CLI); otherwise
+ * `inSeconds` is required and takes /api/wake's positive-finite-and-capped rule. A stopped
+ * team answers 409 with the not-running error. */
+export async function handleStopSchedule(req, res, root) {
+    const body = await readPostBody(req, res, '{"inSeconds": 7200}');
+    if (!body)
+        return;
+    if (body.cancel === true) {
+        if (body.inSeconds !== undefined) {
+            badRequest(res, "cancel and inSeconds cannot be combined");
+            return;
+        }
+        sendJson(res, 200, { ok: true, message: cancelScheduledStopMessage(root) });
+        return;
+    }
+    const inMs = wakeInSecondsMs(res, body);
+    if (inMs === null)
+        return;
+    if (inMs === undefined) {
+        badRequest(res, "inSeconds or cancel is required");
+        return;
+    }
+    sendRequestResult(res, requestScheduledStop(root, inMs));
+}
+/** Handle POST /api/restart: the dashboard's build-stale alert's refresh button — the same
+ * marker-writing core a CLI surface would call (requestRestart), so the wording and the
+ * not-pending refusal cannot drift. The not-pending error comes back 409 like /api/abort's
+ * not-live one: the request is valid but nothing can act on it. Same body discipline as
+ * /api/wake (readJsonObject → 400 malformed/non-object, 413 oversized; the body itself is
+ * ignored — there are no options to force a restart). */
+export async function handleRestart(req, res, root) {
+    const body = await readPostBody(req, res, "{}");
+    if (!body)
+        return;
+    sendRequestResult(res, requestRestart(root));
+}
+/** Handle POST /api/reclaim: the dashboard disk row's reclaim button — the same manual pass
+ * `tumwater reclaim` runs (runManualReclaim), answering its confirmation verbatim. Same body
+ * discipline as /api/restart (the body is ignored); a throw reaches the server's outer 500. */
+export async function handleReclaim(req, res, root) {
+    const body = await readPostBody(req, res, "{}");
+    if (!body)
+        return;
+    sendJson(res, 200, { ok: true, message: await runManualReclaim(root) });
+}
+/** Handle POST /api/abort: the dashboard's per-row abort control — the same marker-writing
+ * core `tumwater abort` calls (requestAbort). The role is required and validated like
+ * /api/transcript; requestAbort's not-live error comes back 409 — the marker is valid but
+ * nothing can consume it, a conflict rather than a client 400. The director variant's
+ * message (the discarded-prompt note) rides through verbatim. */
+export async function handleAbort(req, res, root) {
+    const body = await readRoleBody(req, res, '{"role": "feature"}', root);
+    if (!body)
+        return;
+    sendRequestResult(res, requestAbort(root, body.role));
+}
+/** Handle POST /api/role-notes: the loop drawer's notebook Edit/Clear — the same saveRoleNote
+ * `tumwater role <id> --notes-file` / `--clear-notes` call, so the 4 KB cap and its wording
+ * cannot drift. `"text": ""` clears. The director has no notes (400, the CLI's wording); a
+ * non-string text is a 400 before anything is written; an over-cap note is a 400 carrying
+ * saveRoleNote's byte-count message. */
+export async function handleRoleNotes(req, res, root) {
+    const body = await readRoleBody(req, res, '{"role": "feature", "text": "…"}', root);
+    if (!body)
+        return;
+    const role = body.role;
+    if (role === DIRECTOR_ROLE)
+        return badRequest(res, "the director has no notes");
+    if (typeof body.text !== "string")
+        return badRequest(res, `"text" must be a string — the full replacement note, or "" to clear it${gotSuffix(body.text)}`);
+    try {
+        sendJson(res, 200, { ok: true, message: saveRoleNote(roleNotesPath(root, role), body.text) });
+    }
+    catch (err) {
+        badRequest(res, errorMessage(err));
+    }
+}
+/** Handle POST /api/retire: the Settings view's Retire button — the same retireRole core
+ * `tumwater retire --role <id>` calls, never forced (a `force` key is a 400 naming the CLI
+ * override). A rail's refusal or an unreadable tumwater.json is a 409 carrying the core's
+ * message and removes nothing; success answers what was removed in the CLI's wording. */
+export async function handleRetire(req, res, root) {
+    const body = await readRoleBody(req, res, '{"role": "improve"}', root);
+    if (!body)
+        return;
+    const role = body.role;
+    if (body.force !== undefined)
+        return badRequest(res, "the dashboard never forces a retire — run `tumwater retire --role <id> --force` from the CLI");
+    try {
+        const { removed, skipped } = await retireRole(root, role, {});
+        const message = removed.length === 0 ? `nothing to remove for role ${role}` : removed.map((a) => `removed ${artifactPhrase(a, role)}`).join("; ");
+        sendJson(res, 200, { ok: true, removed, skipped, message });
+    }
+    catch (err) {
+        sendJson(res, 409, { error: errorMessage(err) });
+    }
+}
+/** Handle POST /api/brief: replace the initial prompt through editInitialPrompt — the same
+ * checks, locked write, and commit as `tumwater brief --file`. A non-string prompt or any
+ * refusal is a 400 and writes nothing. */
+export async function handleBriefEdit(req, res, root) {
+    const body = await readPostBody(req, res, '{"prompt": "…"}');
+    if (!body)
+        return;
+    if (typeof body.prompt !== "string")
+        return badRequest(res, `"prompt" must be a string — the full replacement brief${gotSuffix(body.prompt)}`);
+    const outcome = await editInitialPrompt(root, body.prompt);
+    if (!outcome.ok)
+        return badRequest(res, outcome.error);
+    sendJson(res, 200, { file: outcome.file, changed: outcome.changed, committed: outcome.committed });
+}