tumwater 0.2.0 → 0.3.0

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

@@ -0,0 +1,301 @@
+/**
+ * The dashboard's GET run/event-log drill-down handlers (src/gui/gui-server.ts routes to them):
+ * transcript, history, logs, run, and role. Each answers its request and touches no socket
+ * beyond its own `res`; the domain work lives one layer down (ui/transcript.ts,
+ * history/history-data.ts, run/run-detail-data.ts, events/event-read.ts), so this module only
+ * adapts HTTP onto it. Barrelled into gui/gui-endpoints.ts beside the other per-family GET
+ * endpoint modules.
+ */
+import { humanSeconds } from "../text/datetime.js";
+import { readTranscript } from "../ui/transcript.js";
+import { HISTORY_DEFAULT_RUNS, HISTORY_MAX_RUNS, HISTORY_RESULT_FLAG_NAMES, historyClass, parseHistoryResultClass, readRunRows, readRunRowsSince, summarizeRunRows, summarizeRunRowsByModel, runRowsMatchingGrep, runRowsOnModels, } from "../history/history-data.js";
+import { LOGS_SINCE_MAX_MS, SPARSE_WINDOW_NOTE, readEventsSince } from "../events/event-window.js";
+import { eventRole, readEvents } from "../events/event-read.js";
+import { eventFeedItem, eventMatchesGrep } from "../events/event-format.js";
+import { readRunDetail, runCommitSha, runMergedSha } from "../run/run-detail-data.js";
+import { renderRunDetail, runDetailPatch, runDetailStat, runTranscriptLines } from "../run/run-detail-render.js";
+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 { typoSuffix } from "../text/suggest.js";
+import { gotSuffix, splitCommaList, splitCommaListUnique } from "../text/text.js";
+import { newestRunRow, runNotFoundLastMessage, runNotFoundMessage } from "../run/run-detail.js";
+/** Handle GET /api/transcript?role=<id>&n=N[&grep=<text>]: rendered transcript lines for a role's
+ * pi log (same rendering as `tumwater logs --transcript <id>`). A present `prompt` flag also
+ * renders each agent run's prompt, the text `logs --transcript <id> --prompt` prints.
+ * Unknown/missing role
+ * or a bad n → 400. `grep` keeps only the entries containing the text, case-insensitively, each
+ * under its run's separator (the `logs --transcript <id> --grep` rule); `n` bounds the entries
+ * scanned.
+ * User-defined roles are valid targets too — the GUI marks them with an asterisk, so clicking
+ * one must open its transcript: ids validate through rejectBadRole. The 400 message lists
+ * exactly the ids accepted. The query arrives pre-parsed — the server parses the target
+ * once (gui/gui-server.ts's parseRequestTarget) and threads it down, so the parse idiom lives
+ * in one place and cannot disagree with the routing or the token gate about what the URL said. */
+export function handleTranscript(q, res, root) {
+    const role = q.get("role");
+    if (rejectBadRole(root, res, role))
+        return;
+    const n = intQuery(q, res, "n", "positive", 50);
+    if (n === null)
+        return;
+    const grep = (q.get("grep") ?? "").trim().toLowerCase();
+    const includePrompts = q.get("prompt") !== null;
+    sendJson(res, 200, {
+        lines: readTranscript(root, role, n, { includePrompts, grep: grep === "" ? undefined : grep }),
+    });
+}
+/** Parse `result=<class>[,...]` for /api/run?last and /api/history: the deduplicated classes in
+ * first-seen order (`[]` filters nothing), or null after sending the 400 for an unknown class. */
+function resultClassesQuery(q, res) {
+    const classes = [];
+    const names = Object.values(HISTORY_RESULT_FLAG_NAMES);
+    for (const piece of splitCommaList(q.get("result") ?? "")) {
+        const cls = parseHistoryResultClass(piece);
+        if (cls === null) {
+            badRequest(res, `result must be one of ${names.join(", ")}${gotSuffix(piece)}${typoSuffix(piece, names)}`);
+            return null;
+        }
+        if (!classes.includes(cls))
+            classes.push(cls);
+    }
+    return classes;
+}
+/** Handle GET /api/history?role=<id>&n=N[&grep=<text>] — or ?role=<id>&sinceMs=<ms>[&untilMs=<ms>]
+ * for a trailing window (untilMs ends it that long ago, via untilMsQuery; without sinceMs → 400):
+ * the per-run rows the CLI's `tumwater history` derives from the event log,
+ * the dashboard's history tab renders them. The count shape ({ rows }) rides readRunRows (the
+ * 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_RUNS; 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_RUNS] — 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 runRowsMatchingGrep 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
+ * readRunRowsSince, 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
+ * SPARSE_WINDOW_NOTE when covered is false, else "". role is optional: absent or empty → all
+ * roles; present → passed straight through as the role filter with no config validation (a
+ * filter is not a target — an id with no runs legitimately yields zero rows), so the endpoint
+ * reads nothing but files, like /api/report and /api/failures. Reads files directly, so it
+ * present → passed straight through as the role filter with no config validation (a
+ * filter is not a target — an id with no runs 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 summarizeRunRows collector, the same tally
+ * `tumwater history --summary` prints, so the dashboard Summary and the table cannot disagree
+ * about what a run was. It also adds `modelSummary`, `{ models, total }`, the
+ * `history --summary --by model` tally of the same rows. `model=<selector>[,...]` keeps only the
+ * runs that started on exactly one of those models (the `history --model` rule), after `grep` and
+ * before the summaries fold. `result=<class>[,...]` keeps only the runs in those outcome classes
+ * (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. */
+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
+    // `model` is a comma list of exact selectors (trimmed, deduplicated); "", absent and a list
+    // with no non-empty piece all filter nothing, and an unknown selector keeps no rows.
+    const classes = resultClassesQuery(q, res);
+    if (classes === null)
+        return;
+    const inClasses = (rows) => (classes.length ? rows.filter((r) => classes.includes(historyClass(r.result))) : rows);
+    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 { 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;
+    const n = clampCount(parsed, HISTORY_MAX_RUNS);
+    let rows = readRunRows(root, n, role);
+    if (grep !== null)
+        rows = runRowsMatchingGrep(rows, grep);
+    rows = onModels(inClasses(rows));
+    sendJson(res, 200, summary ? { rows, summary: summarizeRunRows(rows), modelSummary: summarizeRunRowsByModel(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
+ * rows), sized so the dashboard's search can reach well past the RECENT_EVENTS window the
+ * status poll carries. */
+const LOGS_SEARCH_EVENTS = 500;
+const LOGS_SEARCH_MAX_EVENTS = 5000;
+/** Handle GET /api/logs?n=N|sinceMs=S[&untilMs=U][&grep=<text>][&role=<id>]: a slice of the raw
+ * event log scanned from its newest end, filtered with the CLI's own rules and shaped as the
+ * activity feed's items. `n` is optional (absent → LOGS_SEARCH_EVENTS) and clamps to [1,
+ * LOGS_SEARCH_MAX_EVENTS] after intQuery's non-negative parse (an explicit count that does not
+ * parse is a 400, the handleHistory discipline); it bounds the scanned tail, so a matching event
+ * older than the last n events is absent — the same scan-then-filter rule `tumwater logs -n N
+ * --grep` applies. grep (absent or empty filters nothing) matches through eventMatchesGrep, and
+ * role is a filter, not a target: an id with no events legitimately yields an empty list, so it
+ * does not validate through rejectBadRole (the handleHistory rule). The matched events answer
+ * oldest-first as eventFeedItem objects — the same shape the status payload's eventItems carry.
+ * 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.
+ * With `sinceMs` instead of `n` it serves the trailing window's events (readEventsSince, the
+ * `logs --since` reader) as { events, covered, note }, the /api/history window shape: sinceMs
+ * with n is a 400 (rival shapes), sinceMs parses and is capped through sinceMsQuery at
+ * LOGS_SINCE_MAX_MS, the window is not row-capped, and note is SPARSE_WINDOW_NOTE when the log
+ * does not reach back that far; untilMs (untilMsQuery) drops the events newer than now −
+ * untilMs, and without sinceMs it is a 400.
+ * Reads files directly, so it works whether or not the team is running. */
+export function handleLogs(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
+    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 { cutoff, events: windowEvents, covered } = readEventsSince(root, sinceMs);
+        const events = untilMs === undefined ? windowEvents : windowEvents.filter((e) => e.ts < cutoff + sinceMs - untilMs);
+        sendJson(res, 200, {
+            events: events.filter(keep).map(eventFeedItem),
+            covered,
+            note: covered ? "" : SPARSE_WINDOW_NOTE,
+        });
+        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;
+    const n = clampCount(parsed, LOGS_SEARCH_MAX_EVENTS);
+    sendJson(res, 200, { events: readEvents(root, n).filter(keep).map(eventFeedItem) });
+}
+/** handleRun's `transcript` text: the run's transcript lines joined, else the miss note. */
+function transcriptText(root, role, run, detail, includePrompts, grep) {
+    const { found, note } = runTranscriptLines(root, role, run, detail, { includePrompts, grep });
+    return found.length > 0 ? found.join("\n") : note;
+}
+/** Handle GET /api/run?role=<id>&run=N: one run's full event trail — readRunDetail's
+ * RunDetail, the collector `tumwater history <role> <n>` prints from, plus `text`: the same
+ * payload through renderRunDetail, 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.
+ * Serving the shared collector is the point: the CLI and this endpoint cannot drift on what one
+ * run's block contains. The role is a target here, not a filter, so it validates through
+ * rejectBadRole (unknown/missing → 400 naming the valid ids); the run is an explicit count
+ * through intQuery (missing or not a positive integer → 400); and a run the scanned window
+ * does not hold — never ran, or rotation ate it — answers 404 with runNotFoundMessage, the
+ * CLI's exact not-found wording,
+ * never a crash. `revertSha` is the run's landed commit's full sha when it is on the base branch
+ * of a primary checkout that is on it (resolveRevertTarget, the revert cores' own check), else
+ * null — the drill-down offers its revert button only when it is set. `hasCommit` says whether
+ * the run pinned a commit (runCommitSha), for the "Show patch" button; `patch` — the same text
+ * `history --patch` prints — is added only when the `patch` flag is present, whatever its
+ * value, so the default expand costs no extra `git show`. `transcript`, likewise flag-gated, is
+ * the text `history --transcript` prints (runTranscriptLines: the found lines joined, else its
+ * note), so the default expand reads no pi log; a present `prompt` flag also renders each agent
+ * run's prompt, the text `history --transcript --prompt` prints. A non-blank `grep` (with
+ * `transcript`) keeps only the entries containing the text, case-insensitively, each under its
+ * agent run's separator, the text `history --transcript --grep` prints, or its miss note. Reads
+ * files directly, so it works whether or not the team is running.
+ *
+ * A present `last` flag replaces `run` with the role's newest completed run, the one
+ * `tumwater history <role> --last` opens (newestRunRow, shared): `result` (a comma list of
+ * outcome classes) and `model` (a comma list of selectors) narrow it to the newest run in those
+ * classes or on those models, an absent or empty value filtering nothing. `last` with `run`, and
+ * `result`/`model` without `last`, are 400s; a class that is not one is a 400 worded like the
+ * CLI's; no match answers 404 with runNotFoundLastMessage. The payload is the numbered form's,
+ * the resolved number in `run`. With no `role`, `last` opens the newest completed run of any role
+ * (newestRunRow with a null role, the run bare `tumwater history --last` opens), and the
+ * payload's `role` is that run's; `result`/`model` narrow it the same way, and a miss is a 404
+ * worded for any role. */
+export async function handleRun(q, res, root) {
+    let role = q.get("role");
+    const bareLast = role === null && q.get("last") !== null;
+    if (!bareLast && rejectBadRole(root, res, role))
+        return;
+    let run;
+    if (q.get("last") === null) {
+        if (q.get("result") !== null)
+            return badRequest(res, "result needs last");
+        if (q.get("model") !== null)
+            return badRequest(res, "model needs last");
+        run = intQuery(q, res, "run", "positive");
+        if (run === null)
+            return;
+    }
+    else {
+        if (q.get("run") !== null)
+            return badRequest(res, "last cannot be combined with run (a number and the newest run are rival selectors)");
+        const classes = resultClassesQuery(q, res);
+        if (classes === null)
+            return;
+        const models = splitCommaListUnique(q.get("model") ?? "");
+        const classFilter = classes.length ? classes : null;
+        const modelFilter = models.length ? models : null;
+        const row = newestRunRow(root, role, classFilter, modelFilter);
+        if (row !== null)
+            role = row.role;
+        run = row?.run ?? null;
+        if (run === null) {
+            sendJson(res, 404, { error: runNotFoundLastMessage(role, classFilter, modelFilter) });
+            return;
+        }
+    }
+    const detail = readRunDetail(root, role, run);
+    if (detail === null) {
+        sendJson(res, 404, { error: runNotFoundMessage(role, run) });
+        return;
+    }
+    const grep = (q.get("grep") ?? "").trim();
+    const mergedAs = runMergedSha(detail);
+    const target = mergedAs === null ? null : await resolveRevertTarget(root, mergedAs);
+    sendJson(res, 200, {
+        ...detail,
+        text: renderRunDetail(detail),
+        stat: await runDetailStat(root, detail),
+        revertSha: target?.ok ? target.full : null,
+        hasCommit: runCommitSha(detail) !== null,
+        ...(q.get("patch") !== null ? { patch: await runDetailPatch(root, detail) } : {}),
+        ...(q.get("transcript") !== null ? { transcript: transcriptText(root, role, run, detail, q.get("prompt") !== null, grep === "" ? undefined : grep) } : {}),
+    });
+}
+/** Handle GET /api/role?role=<id>: one role's inspection payload — rolePayload's object,
+ * the same collection behind `tumwater role <id>` — so the drawer's Notes and Next run
+ * 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/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 team is running. */
+export function handleRole(q, res, root) {
+    const role = q.get("role");
+    if (rejectBadRole(root, res, role))
+        return;
+    sendJson(res, 200, rolePayload(root, role));
+}

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

@@ -1,19 +1,28 @@
-// 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
+ * restart, reclaim, abort, stop-schedule, role-notes, retire, revert, brief-edit, and
+ * queue-cancel — 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 { runDoctor } from "../doctor/doctor.js";
+import { killOrphans, orphanKillLines } from "../doctor/doctor-orphans.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 { previewRevert, revertFollowUp, revertMergedCommit } from "../operator/revert.js";
+import { cancelQueuedMergeBySha } from "../merge/merge-cancel.js";
+import { readMergeQueue } from "../merge/merge-queue.js";
+import { mergeChanges } from "../merge/merge-slot.js";
+import { queueInFlight } from "../status/status-polls.js";
+import { orchestratorAlive } from "../team/orchestrator-info.js";
+import { shortSha } from "../text/format.js";
+import { editBriefText } from "../brief/brief-edit.js";
+import { requireStringField, 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";
@@ -77,6 +86,27 @@ export async function handleReclaim(req, res, root) {
         return;
     sendJson(res, 200, { ok: true, message: await runManualReclaim(root) });
 }
+/** Handle POST /api/kill-orphans: the dashboard Health card's Kill orphans button — the same
+ * killOrphans `tumwater doctor --kill-orphans` runs, answering its lines joined with "; ". Same
+ * body discipline as /api/reclaim; `ok` is false when the scan failed or a signal was refused. */
+export async function handleKillOrphans(req, res, root, kill = killOrphans) {
+    const body = await readPostBody(req, res, "{}");
+    if (!body)
+        return;
+    const report = await kill(root);
+    sendJson(res, 200, { ok: !("error" in report) && report.failed.length === 0, message: orphanKillLines(report).join("; ") });
+}
+/** Handle POST /api/doctor-reprobe: the dashboard Health card's Re-probe models button, the
+ * twin of `tumwater doctor --reprobe`. A POST because it spends one model call per claimed pi
+ * image-input model and rewrites `.tumwater/state/image-probes.json`; GET /api/doctor stays
+ * probe-free. Same body discipline as /api/kill-orphans; `run` takes the probe mode so a test
+ * can pin that the handler asks for "all" without spawning a probe. */
+export async function handleDoctorReprobe(req, res, root, run = (r, p) => runDoctor(r, undefined, undefined, p)) {
+    const body = await readPostBody(req, res, "{}");
+    if (!body)
+        return;
+    sendJson(res, 200, await run(root, "all"));
+}
 /** 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
@@ -88,7 +118,7 @@ export async function handleAbort(req, res, root) {
         return;
     sendRequestResult(res, requestAbort(root, body.role));
 }
-/** Handle POST /api/role-notes: the loop drawer's notebook Edit/Clear — the same saveRoleNote
+/** Handle POST /api/role-notes: the role drawer's notes 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
@@ -100,10 +130,11 @@ export async function handleRoleNotes(req, res, root) {
     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)}`);
+    const text = requireStringField(res, body, "text", `the full replacement note, or "" to clear it`);
+    if (text === null)
+        return;
     try {
-        sendJson(res, 200, { ok: true, message: saveRoleNote(roleNotesPath(root, role), body.text) });
+        sendJson(res, 200, { ok: true, message: saveRoleNote(roleNotesPath(root, role), text) });
     }
     catch (err) {
         badRequest(res, errorMessage(err));
@@ -129,16 +160,80 @@ export async function handleRetire(req, res, root) {
         sendJson(res, 409, { error: errorMessage(err) });
     }
 }
-/** Handle POST /api/brief: replace the initial prompt through editInitialPrompt — the same
+/** Handle POST /api/revert: the History drill-down's "Revert this change" button — the same
+ * cores `tumwater revert <sha> [--dry-run]` calls. A `sha` that is not 4-64 hex digits (so never
+ * a flag or a ref name) or a non-boolean `dryRun` is a 400 and runs nothing. `dryRun: true`
+ * answers `{ ok, preview }` (previewRevert, writing nothing); otherwise the revert commits and
+ * answers `{ ok, headSha, beforeSha, message }`. A core's refusal is a 409 with its wording. */
+export async function handleRevert(req, res, root) {
+    const body = await readPostBody(req, res, '{"sha": "1a2b3c4"}');
+    if (!body)
+        return;
+    if (typeof body.sha !== "string" || !/^[0-9a-f]{4,64}$/i.test(body.sha))
+        return badRequest(res, `"sha" must be a hex commit id of 4-64 digits${gotSuffix(body.sha)}`);
+    if (body.dryRun !== undefined && typeof body.dryRun !== "boolean")
+        return badRequest(res, `"dryRun" must be true or false${gotSuffix(body.dryRun)}`);
+    if (body.dryRun === true) {
+        const preview = await previewRevert(root, body.sha);
+        if (!preview.ok)
+            return sendJson(res, 409, { error: preview.error });
+        return sendJson(res, 200, { ok: true, preview });
+    }
+    const result = await revertMergedCommit(root, body.sha);
+    if (!result.ok)
+        return sendJson(res, 409, { error: result.error });
+    const followUp = revertFollowUp(result.subject);
+    sendJson(res, 200, {
+        ok: true,
+        headSha: result.headSha,
+        beforeSha: result.beforeSha,
+        subject: result.subject,
+        message: `main is now ${shortSha(result.headSha)}${followUp === null ? "" : ` — ${followUp}`}`,
+    });
+}
+/** Handle POST /api/queue-cancel: the Merge queue card row's two-click Cancel — the browser
+ * twin of `tumwater queue --cancel <n>`, resolving by pinned sha (the same removal
+ * `cancelQueuedMergeBySha` the CLI's position variant shares). A `sha` that is not 4-64 hex
+ * digits is a 400 and runs nothing. A sha a live merge marker names mid-merge is a 409 with the
+ * wait-then-revert wording and changes nothing; a sha no longer queued (a concurrent drain
+ * raced the click) is a 200 `{ status: "gone" }` data, not an error. Otherwise it answers the
+ * cancelled entry's role/commit/summary and removes the queue file and pin. */
+export async function handleQueueCancel(req, res, root) {
+    const body = await readPostBody(req, res, '{"sha": "1a2b3c4"}');
+    if (!body)
+        return;
+    if (typeof body.sha !== "string" || !/^[0-9a-f]{4,64}$/i.test(body.sha))
+        return badRequest(res, `"sha" must be a hex commit id of 4-64 digits${gotSuffix(body.sha)}`);
+    const view = readMergeQueue(root);
+    const sha = body.sha.toLowerCase();
+    const inFlight = queueInFlight(root, view.entries, orchestratorAlive(root));
+    if (inFlight && ((typeof inFlight.sha === "string" && inFlight.sha.toLowerCase() === sha) || mergeChanges(inFlight).some((c) => c.sha.toLowerCase() === sha)))
+        return sendJson(res, 409, { error: `this merge is being merged right now — wait for it to land, then \`tumwater revert ${shortSha(body.sha)}\`` });
+    const outcome = await cancelQueuedMergeBySha(root, body.sha);
+    if (outcome.status === "gone")
+        return sendJson(res, 200, { ok: true, status: "gone" });
+    if (outcome.status !== "cancelled")
+        return;
+    sendJson(res, 200, {
+        ok: true,
+        status: "cancelled",
+        role: outcome.role,
+        commit: outcome.sha,
+        summary: outcome.summary,
+        message: `cancelled the merge of ${shortSha(outcome.sha)} — ${outcome.summary}`,
+    });
+}
+/** Handle POST /api/brief: replace the brief text through editBriefText — 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);
+    const prompt = requireStringField(res, body, "prompt", "the full replacement brief");
+    if (prompt === null)
+        return;
+    const outcome = await editBriefText(root, prompt);
     if (!outcome.ok)
         return badRequest(res, outcome.error);
     sendJson(res, 200, { file: outcome.file, changed: outcome.changed, committed: outcome.committed });

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

@@ -1,4 +1,3 @@
-// vocabulary: plain
 /**
  * The dashboard's POST prompt-queueing command handlers (barrelled into
  * gui/gui-endpoint-commands.ts, which routes to them from src/gui/gui-server.ts): prompt,
@@ -19,7 +18,7 @@ import { PAUSE_FOR_MAX_MS, submitRolePromptAndWake } from "../operator/operator-
 import { DIRECTOR_ROLE } from "../roles/roles.js";
 import { rejectBadQueueFileName, rejectBadRole, requirePromptText } from "./gui-args.js";
 import { badRequest, OK_GONE, sendJson } from "./http-body.js";
-import { errorMessage, gotSuffix } from "../text/text.js";
+import { errorMessage, gotSuffix, joinParts } from "../text/text.js";
 import { readPostBody, readRoleBody } from "./gui-endpoint-common.js";
 /** Handle POST /api/prompt: queue a director prompt. An over-long prompt
  * (DIRECTOR_PROMPT_MAX_CHARS) is a user-input error, not a server fault: the shared length
@@ -93,10 +92,10 @@ function checkedPromptFields(res, body, role = DIRECTOR_ROLE) {
         return null;
     return { text, images, notBeforeMs };
 }
-/** Handle POST /api/prompt-role: queue a prompt for one loop — the dashboard's per-row
+/** Handle POST /api/prompt-role: queue a prompt for one role — the dashboard's per-row
  * prompt affordance submits here, calling the same path `tumwater prompt --role <id>` uses
- * (submitRolePrompt enqueues into that loop's own queue and logs under it, then a single-role
- * wake brings the live loop in within one poll; the wake message rides back for the flash).
+ * (submitRolePrompt enqueues into that role's own queue and logs under it, then a single-role
+ * wake brings the live role in within one poll; the wake message rides back for the flash).
  * The role validates exactly like /api/transcript (the shared rejectBadRole wording), and the
  * body discipline is /api/prompt's: readJsonObject → 400 malformed/non-object, 413 oversized,
  * text a non-empty string within the shared length rule → 400 otherwise — plus the same
@@ -110,9 +109,9 @@ export async function handlePromptRole(req, res, root) {
     if (!fields)
         return;
     // Image-input submit gate (plans/image-input.md "Attachments", part 5/5): an attachment the
-    // target loop cannot read (and that no tier reroutes) answers 400 naming the fix before
+    // target role cannot read (and that no tier reroutes) answers 400 naming the fix before
     // anything is queued — the same gate submitRolePrompt enforces, surfaced as a user-input
-    // error rather than the server's 500. A loop that reroutes a blind read is not refused; its
+    // error rather than the server's 500. A role that reroutes a blind read is not refused; its
     // notice rides in the confirmation the composer flashes.
     let notice = "";
     if (fields.images && fields.images.length > 0) {
@@ -123,12 +122,10 @@ export async function handlePromptRole(req, res, root) {
         }
         notice = guidance.notice ?? "";
     }
-    const message = [
+    const message = joinParts([
         submitRolePromptAndWake(root, role, fields.text, fields.images, fields.notBeforeMs),
         notice,
-    ]
-        .filter(Boolean)
-        .join("\n");
+    ], "\n");
     sendJson(res, 200, { ok: true, message });
 }
 /** Handle POST /api/prompt-cancel: retract one queued prompt addressed by its queue file —
@@ -136,7 +133,7 @@ export async function handlePromptRole(req, res, root) {
  * position-addressed `prompt --cancel`. The role is optional (absent cancels from 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 touched on disk. A vanished file answers 200 { status: "gone" } — the loop already
+ * nothing touched on disk. A vanished file answers 200 { status: "gone" } — the role already
  * dequeued the prompt, which is data for the flash line, not a server fault. Same body
  * discipline as /api/prompt (readJsonObject → 400 malformed/non-object, 413 oversized). */
 export async function handlePromptCancel(req, res, root) {
@@ -161,7 +158,7 @@ export async function handlePromptCancel(req, res, root) {
  * and images validate through the same checkedPromptFields /api/prompt and /api/prompt-role
  * use; editQueuedFile throws for a bad name or an over-cap text — both user-input errors
  * answered 400 (a filesystem failure reads as 400 like handleConfigSet's failed write). A
- * vanished file answers 200 { ok: true, status: "gone" } — the loop already dequeued the
+ * vanished file answers 200 { ok: true, status: "gone" } — the role already dequeued the
  * prompt, which is data for the flash line, not a server error; an edit answers 200 with the
  * old and new operator-facing text the client flashes. Same body discipline as /api/prompt
  * (readJsonObject → 400 malformed/non-object, 413 oversized). */
@@ -179,7 +176,7 @@ export async function handlePromptEdit(req, res, root) {
         return;
     // Image-input gate (plans/image-input.md "Attachments", part 5/5), the edit twin of
     // handlePromptRole's: an image edited into the queued prompt answers 400 naming the fix
-    // when the target loop cannot read it (and no tier reroutes it) — the same gate
+    // when the target role cannot read it (and no tier reroutes it) — the same gate
     // submitRolePrompt enforces — before anything is written.
     if (fields.images && fields.images.length > 0) {
         const guidance = imagePromptGuidance(root, role);

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

@@ -0,0 +1,90 @@
+/**
+ * The dashboard's GET report and failures handlers (src/gui/gui-server.ts routes to them):
+ * report and failures. Each answers its request and touches no socket beyond its own `res`;
+ * the domain work lives one layer down (report/report-data.ts, failure/failure-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 { 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, reportSinceMsg } from "../events/event-window.js";
+import { roleListQuery, sinceMsQuery, untilMsQuery, windowDays } from "./gui-args.js";
+import { badRequest, sendJson } from "./http-body.js";
+/** Parse and validate the role-scoped, sinceMs-or-days query the report and failures endpoints
+ * both take: the `?role=` filter, a comma-separated list (each id trimmed, deduplicated, and
+ * validated by rejectBadRole — an unknown id or an empty list → 400 naming it) and, when
+ * `?sinceMs=` is present, the trailing-window length (reportSinceMs, which 400s a simultaneous
+ * `?days=`). Returns null once a 400 is sent. `sinceMs` is defined exactly when the caller
+ * should use the since shape; otherwise it falls through to the days shape with `windowDays(q)`.
+ * The one home of that shared scaffolding, so the two endpoints cannot drift on the role rule or
+ * the days-vs-sinceMs mutual exclusion (the server twin of reportEndpoint on the GUI client). */
+function reportScope(q, res, root) {
+    const roles = roleListQuery(q, res, root);
+    if (roles === null)
+        return null;
+    if (q.get("sinceMs") !== null) {
+        const sinceMs = reportSinceMs(q, res);
+        if (sinceMs === null)
+            return null;
+        return { roles, sinceMs };
+    }
+    return { roles };
+}
+/** Parse and bound the report endpoints' `?sinceMs=` trailing-window length: a simultaneous
+ * `?days=` is the CLI's rival shape (whole local days vs a trailing window) → 400 naming both;
+ * otherwise the length rides sinceMsQuery (gui-args.ts) — positive-integer parse, then a 400
+ * naming the cap rather than a silent clamp (an explicit window typo must not shrink to some
+ * other window) — with the "must be between 1 and …" wording. Returns the parsed length, or
+ * null once the 400 is sent. */
+function reportSinceMs(q, res) {
+    if (q.get("days") !== null) {
+        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, reportSinceMsg);
+}
+/** Handle GET /api/report?days=N[&role=<id>[,<id>...]] or
+ * /api/report?sinceMs=<ms>[&untilMs=<ms>][&role=<id>[,<id>...]]: the
+ * 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). The day window
+ * follows windowDays. An absent role is the team-wide report; the listed roles, summed
+ * (each id validated by reportScope). Reads files directly, so it works whether or not the team
+ * is running. */
+export function handleReport(q, res, root) {
+    const scope = reportScope(q, res, root);
+    if (scope === null)
+        return;
+    const untilMs = untilMsQuery(q, res, scope.sinceMs);
+    if (untilMs === null)
+        return;
+    if (scope.sinceMs !== undefined) {
+        sendJson(res, 200, { markdown: renderSinceReportMarkdown(collectReportSince(root, scope.sinceMs, scope.roles, untilMs)) });
+        return;
+    }
+    sendJson(res, 200, collectReport(root, windowDays(q), scope.roles));
+}
+/** Handle GET /api/failures?days=N[&role=<id>[,<id>...]] or
+ * /api/failures?sinceMs=<ms>[&untilMs=<ms>][&role=<id>[,<id>...]]: the
+ * same bounded Markdown failure digest the selfcheck role 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 rule as
+ * handleReport: absent → the team digest, present → the validated listed roles, summed. Reads files
+ * directly, so it works with no team running. */
+export function handleFailures(q, res, root) {
+    const scope = reportScope(q, res, root);
+    if (scope === null)
+        return;
+    const untilMs = untilMsQuery(q, res, scope.sinceMs);
+    if (untilMs === null)
+        return;
+    if (scope.sinceMs !== undefined) {
+        sendJson(res, 200, { markdown: renderFailureMarkdown(collectFailureReportSince(root, scope.sinceMs, scope.roles, untilMs)) });
+        return;
+    }
+    sendJson(res, 200, { markdown: renderFailureMarkdown(collectFailureReport(root, windowDays(q), scope.roles)) });
+}