tumwater 0.2.0 → 0.4.0

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,29 +122,36 @@ 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 });
 }
+/** The file-addressed prompt handlers' shared role prologue: validate the optional role
+ * (400 sent on a present-but-invalid one and null returned, so the caller stops) and default
+ * an absent role to the director's queue. The same optional-role rule handlePromptCancel,
+ * handlePromptEdit and handlePromptTop state once instead of a guard-plus-default pair. */
+function promptFileRole(body, res, root) {
+    if (body.role !== undefined && rejectBadRole(root, res, body.role))
+        return null;
+    return body.role === undefined ? DIRECTOR_ROLE : body.role;
+}
 /** Handle POST /api/prompt-cancel: retract one queued prompt addressed by its queue file —
  * the dashboard's per-row cancel affordance, the file-addressed twin of the CLI's
  * 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) {
     const body = await readPostBody(req, res, '{"role": "feature", "file": "<stamp>-<seq>-<pid>.md"}');
     if (!body)
         return;
-    if (body.role !== undefined && rejectBadRole(root, res, body.role))
+    const role = promptFileRole(body, res, root);
+    if (role === null)
         return;
-    const role = body.role === undefined ? DIRECTOR_ROLE : body.role;
     if (rejectBadQueueFileName(res, body.file))
         return;
     const outcome = cancelQueuedFile(root, role, body.file);
@@ -161,7 +167,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). */
@@ -169,9 +175,9 @@ export async function handlePromptEdit(req, res, root) {
     const body = await readPostBody(req, res, '{"role": "qa", "file": "<stamp>.md", "text": "..."}');
     if (!body)
         return;
-    if (body.role !== undefined && rejectBadRole(root, res, body.role))
+    const role = promptFileRole(body, res, root);
+    if (role === null)
         return;
-    const role = body.role === undefined ? DIRECTOR_ROLE : body.role;
     if (rejectBadQueueFileName(res, body.file))
         return;
     const fields = checkedPromptFields(res, body, role);
@@ -179,7 +185,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);
@@ -213,9 +219,9 @@ export async function handlePromptTop(req, res, root) {
     const body = await readPostBody(req, res, '{"role": "qa", "file": "<stamp>.md"}');
     if (!body)
         return;
-    if (body.role !== undefined && rejectBadRole(root, res, body.role))
+    const role = promptFileRole(body, res, root);
+    if (role === null)
         return;
-    const role = body.role === undefined ? DIRECTOR_ROLE : body.role;
     if (rejectBadQueueFileName(res, body.file))
         return;
     let outcome;

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

@@ -0,0 +1,97 @@
+/**
+ * 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 { loadQuarantine } from "../review/known-flakes.js";
+import { quarantineRows, renderQuarantineSection } from "../review/quarantine-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 response also carries `quarantine`, the
+ * Markdown section (renderQuarantineSection over the current loadQuarantine list, an empty
+ * string when it is empty) the Failures view paints below the digest — the read twin of the
+ * amber quarantine alert, current rather than window- or role-scoped. The digest's `markdown`
+ * is unchanged. 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;
+    const quarantine = renderQuarantineSection(quarantineRows(loadQuarantine(root)), Date.now());
+    if (scope.sinceMs !== undefined) {
+        sendJson(res, 200, { markdown: renderFailureMarkdown(collectFailureReportSince(root, scope.sinceMs, scope.roles, untilMs)), quarantine });
+        return;
+    }
+    sendJson(res, 200, { markdown: renderFailureMarkdown(collectFailureReport(root, windowDays(q), scope.roles)), quarantine });
+}

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

@@ -1,6 +1,8 @@
 /** The dashboard HTTP server: routing, the shared-token gate, the static page, /api/status, and the
  * self-reload watch. Every /api endpoint's handler lives in gui/gui-endpoints.ts (the GET data
- * endpoints) and gui/gui-endpoint-commands.ts (the POST operator endpoints) — this module owns
+ * endpoints, barrelled there from one module per family — gui-history-endpoints,
+ * gui-backlog-endpoints, gui-report-endpoints, gui-admin-endpoints) and
+ * gui/gui-endpoint-commands.ts (the POST operator endpoints) — this module owns
  * the socket, not the data. The `tumwater gui` CLI entry (cmdGui) lives in gui/gui-command.ts,
  * which imports startGui from here, so the server and the command that boots it stay adjacent. */
 import crypto from "node:crypto";
@@ -10,8 +12,8 @@ import { statusPayload } from "../ui/status-payload.js";
 import { captureStartupBuild, createReloadWatch, reexecSelf, watchReloadSupervisor, } from "../redeploy/self-reload.js";
 import { warnEvent, TUMWATER_SOURCE } from "../events/events.js";
 import { errorMessage } from "../text/text.js";
-import { handleBacklog, handleBrief, handleConfig, handleDiff, handleFailures, handleReport, handleHistory, handleLogs, handlePromptText, handleTick, handleRole, handleTranscript, handleDoctor, handleRetireList, } from "./gui-endpoints.js";
-import { handleAbort, handleBriefEdit, handleBudget, handleConfigSet, handleConfigUnset, handleRoleCap, handleRoleEnable, handleRoleDisable, handleRoleInstances, handleRoleInterval, handleRoleInstructions, handleRoleModel, handleRoleQuietHours, handleNotifyTest, handlePause, handlePauseRole, handlePrompt, handleBacklogFile, handleBacklogCancel, handleBacklogRelease, handleBacklogTop, handleBacklogEdit, handlePromptCancel, handlePromptEdit, handlePromptRole, handlePromptTop, handleQuestionAnswer, handleReclaim, handleRestart, handleStopSchedule, handleResetCounters, handleRoleNotes, handleRetire, handleWake, handleWakeCancel, } from "./gui-endpoint-commands.js";
+import { handleBacklog, handleBacklogMatch, handleBrief, handleConfig, handleDiff, handleFailures, handleReport, handleHistory, handleLogs, handlePromptText, handleRun, handleRole, handleTranscript, handleDoctor, handleRetireList, } from "./gui-endpoints.js";
+import { handleAbort, handleBriefEdit, handleBudget, handleConfigSet, handleConfigUnset, handleRoleCap, handleRoleReviewAfterMerge, handleRoleEnable, handleRoleDisable, handleRoleInstances, handleRoleInterval, handleRoleInstructions, handleRoleModel, handleRoleQuietHours, handleNotifyTest, handlePause, handlePauseRole, handlePrompt, handleBacklogFile, handleBacklogCancel, handleBacklogRelease, handleBacklogTop, handleBacklogEdit, handlePromptCancel, handlePromptEdit, handlePromptRole, handlePromptTop, handleQuestionAnswer, handleReclaim, handleKillOrphans, handleDropBrokenPins, handleCommitBacklog, handleResyncInstall, handleRetireLeftovers, handleDoctorReprobe, handleRestart, handleStopSchedule, handleResetCounters, handleRoleNotes, handleRetire, handleRevert, handleQueueCancel, handleQueueTop, handlePostReviewAccept, handleWake, handleWakeCancel, } from "./gui-endpoint-commands.js";
 import { sendJson } from "./http-body.js";
 /** Constant-time credential comparison for the shared-token gate: `timingSafeEqual` throws
  * on unequal lengths, so the length equality is the guard. A naive `===` string compare
@@ -148,10 +150,11 @@ export function startGui(root, port, allInterfaces = false, token = "", watch =
         "GET /api/logs": (_req, res, target) => handleLogs(target.searchParams, res, root),
         "GET /api/transcript": (_req, res, target) => handleTranscript(target.searchParams, res, root),
         "GET /api/prompt-text": (_req, res, target) => handlePromptText(target.searchParams, res, root),
-        "GET /api/run": (_req, res, target) => handleTick(target.searchParams, res, root),
+        "GET /api/run": (_req, res, target) => handleRun(target.searchParams, res, root),
         "GET /api/role": (_req, res, target) => handleRole(target.searchParams, res, root),
         "GET /api/diff": (_req, res, target) => handleDiff(target.searchParams, res, root),
         "GET /api/backlog": (_req, res, target) => handleBacklog(target.searchParams, res, root),
+        "GET /api/backlog-match": (_req, res, target) => handleBacklogMatch(target.searchParams, res, root),
         "GET /api/config": (_req, res) => handleConfig(res, root),
         "GET /api/brief": (_req, res) => handleBrief(res, root),
         "GET /api/doctor": (_req, res) => handleDoctor(res, root),
@@ -173,6 +176,7 @@ export function startGui(root, port, allInterfaces = false, token = "", watch =
         "POST /api/question-answer": (req, res) => handleQuestionAnswer(req, res, root),
         "POST /api/budget": (req, res) => handleBudget(req, res, root),
         "POST /api/role-cap": (req, res) => handleRoleCap(req, res, root),
+        "POST /api/role-review-after-merge": (req, res) => handleRoleReviewAfterMerge(req, res, root),
         "POST /api/role-enable": (req, res) => handleRoleEnable(req, res, root),
         "POST /api/role-disable": (req, res) => handleRoleDisable(req, res, root),
         "POST /api/role-interval": (req, res) => handleRoleInterval(req, res, root),
@@ -186,9 +190,19 @@ export function startGui(root, port, allInterfaces = false, token = "", watch =
         "POST /api/reset-counters": (req, res) => handleResetCounters(req, res, root),
         "POST /api/role-notes": (req, res) => handleRoleNotes(req, res, root),
         "POST /api/retire": (req, res) => handleRetire(req, res, root),
+        "POST /api/revert": (req, res) => handleRevert(req, res, root),
+        "POST /api/queue-cancel": (req, res) => handleQueueCancel(req, res, root),
+        "POST /api/queue-top": (req, res) => handleQueueTop(req, res, root),
+        "POST /api/post-review-accept": (req, res) => handlePostReviewAccept(req, res, root),
         "POST /api/restart": (req, res) => handleRestart(req, res, root),
         "POST /api/stop-schedule": (req, res) => handleStopSchedule(req, res, root),
         "POST /api/reclaim": (req, res) => handleReclaim(req, res, root),
+        "POST /api/kill-orphans": (req, res) => handleKillOrphans(req, res, root),
+        "POST /api/doctor-drop-broken-pins": (req, res) => handleDropBrokenPins(req, res, root),
+        "POST /api/doctor-commit-backlog": (req, res) => handleCommitBacklog(req, res, root),
+        "POST /api/doctor-resync-install": (req, res) => handleResyncInstall(req, res, root),
+        "POST /api/doctor-retire-leftovers": (req, res) => handleRetireLeftovers(req, res, root),
+        "POST /api/doctor-reprobe": (req, res) => handleDoctorReprobe(req, res, root),
         "POST /api/abort": (req, res) => handleAbort(req, res, root),
         "POST /api/pause-role": (req, res) => handlePauseRole(req, res, root),
     };
@@ -240,8 +254,15 @@ export function startGui(root, port, allInterfaces = false, token = "", watch =
             if (route)
                 await route(req, res, target);
             else {
+                // Unknown path: a bare "not found" hides which path failed, so name the offending
+                // target, JSON.stringify-quoted like every sibling error-answer (the quote-the-
+                // offending-value convention). Plain text, not sendJson's {error}, on purpose: this
+                // also answers non-/api requests (a stale /api route, a proxy's /favicon.ico), and the
+                // client's apiError treats a plain-text 404 body as a bare message. `pathname` is null
+                // only for a target the URL parser rejected, so fall back to the raw url. No "no such
+                // route" claim: a known path with a wrong method lands here too (GET /api/stop-schedule).
                 res.writeHead(404, { "content-type": "text/plain" });
-                res.end("not found");
+                res.end(`not found: ${JSON.stringify(pathname ?? req.url ?? "/")}`);
             }
         }
         catch (err) {

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

@@ -5,7 +5,7 @@
  * `wakeInSecondsMs` body rules they share. Each handler adapts HTTP onto the domain work one
  * layer down (team/team-state, operator-intent) and touches no socket beyond its own `res`.
  */
-import { baseRoleOf, INSTANCE_ROLES } from "../roles/loop-ids.js";
+import { baseRoleOf, INSTANCE_ROLES } from "../roles/runner-ids.js";
 import { normalizePauseReason, pauseTeam, pauseRole, resumeTeam, resumeRole } from "../team/team-state.js";
 import { cancelWakes, PAUSE_FOR_MAX_MS, requestWake } from "../operator/operator-intent.js";
 import { requirePausedFlag, validRoleIds } from "./gui-args.js";
@@ -127,13 +127,13 @@ export async function handleWakeCancel(req, res, root) {
     const body = await readRoleBody(req, res, '{"role": "feature"}', root, true);
     if (!body)
         return;
-    sendJson(res, 200, { ok: true, message: cancelWakes(root, body.role) });
+    sendJson(res, 200, { ok: true, message: cancelWakes(root, body.role === undefined ? undefined : [body.role]) });
 }
-/** Resume a row: lift every marker key that pauses this loop id (its own, its base role's, and
- * instance 1's `<role>-1`), since the row shows Resume whenever `loopPaused` holds and the key
+/** Resume a row: lift every marker key that pauses this role id (its own, its base role's, and
+ * instance 1's `<role>-1`), since the row shows Resume whenever `runnerPaused` holds and the key
  * actually in the marker may differ from the row's id. Reports whether any key was lifted. */
-function resumeLoopKeys(root, loopId) {
-    const keys = new Set([loopId, baseRoleOf(loopId), ...(INSTANCE_ROLES.has(loopId) ? [`${loopId}-1`] : [])]);
+function resumeRunnerKeys(root, runnerId) {
+    const keys = new Set([runnerId, baseRoleOf(runnerId), ...(INSTANCE_ROLES.has(runnerId) ? [`${runnerId}-1`] : [])]);
     let changed = false;
     for (const key of keys)
         changed = resumeRole(root, key) || changed;
@@ -159,6 +159,6 @@ export async function handlePauseRole(req, res, root) {
         return;
     const changed = value
         ? pauseRole(root, body.role, untilMs)
-        : resumeLoopKeys(root, body.role);
+        : resumeRunnerKeys(root, body.role);
     sendJson(res, 200, { ok: true, changed, paused: value, ...(untilMs === undefined ? {} : { until: untilMs }) });
 }

package/dist/src/gui/http-body.js

@@ -13,7 +13,7 @@ export function badRequest(res, message) {
     sendJson(res, 400, { error: message });
 }
 /** Send 200 with the {"ok":true,"status":"gone"} body every file-addressed handler that answers
- * for a vanished entry (the loop already dequeued it) replies with — data for the UI's flash
+ * for a vanished entry (the role already dequeued it) replies with — data for the UI's flash
  * line, not a server fault — so the status and the `{ ok, status }` wrapper live here instead
  * of being open-coded at each call site. */
 export function okGone(res) {