tumwater 0.1.3 → 0.2.0

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

@@ -0,0 +1,234 @@
+// 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,
+ * prompt-role, prompt-cancel, prompt-edit, and prompt-top — the `checkedPromptImages` /
+ * `checkedPromptDefer` / `checkedPromptFields` validators they share ride with them. Each
+ * handler adapts HTTP onto the domain work one layer down (inbox-submit, inbox-cancel,
+ * inbox-edit, inbox-top, operator-intent) and touches no socket beyond its own `res`.
+ */
+import { submitPrompt } from "../inbox/inbox-submit.js";
+import { imagePromptGuidance } from "../inbox/inbox-submit.js";
+import { promptImagesProblem } from "../inbox/inbox-attachments.js";
+import { promptPreview } from "../inbox/inbox.js";
+import { cancelQueuedFile } from "../inbox/inbox-cancel.js";
+import { editQueuedFile } from "../inbox/inbox-edit.js";
+import { topQueuedFile } from "../inbox/inbox-top.js";
+import { parseDurationMs } from "../cli/cli-args.js";
+import { PAUSE_FOR_MAX_MS, submitRolePromptAndWake } from "../operator/operator-intent.js";
+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 { 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
+ * rule answers 400 — an unexpected submit failure (EACCES) still reaches the server's outer
+ * catch as the 500 its gui-server-transport test pins. An optional images array (the composer's
+ * dropped/pasted attachments) is validated before anything is queued: a bad image — wrong
+ * extension, too many, undecodable, oversized — answers 400 naming the rule, with no queue
+ * file and no image written. */
+export async function handlePrompt(req, res, root) {
+    const body = await readPostBody(req, res, '{"text": "..."}');
+    if (!body)
+        return;
+    const fields = checkedPromptFields(res, body);
+    if (!fields)
+        return;
+    submitPrompt(root, fields.text, fields.images, fields.notBeforeMs);
+    sendJson(res, 200, { ok: true });
+}
+/** The images field of a prompt endpoint's body, validated before anything touches the disk.
+ * Three outcomes, deliberately distinct: `undefined` — no images field, a text-only submit,
+ * continue without attachments; an array — the field was present and valid, attach it (a
+ * present-but-empty array is fine and saves nothing); `null` — the field was present and
+ * invalid, the 400 naming the rule is already sent, stop. The absent and invalid cases must
+ * not share a value: a text-only POST is the common path and must proceed. */
+function checkedPromptImages(res, body) {
+    if (body.images === undefined)
+        return undefined;
+    const problem = promptImagesProblem(body.images);
+    if (problem) {
+        badRequest(res, problem);
+        return null;
+    }
+    return body.images;
+}
+/** The defer field of a prompt endpoint's body, validated before anything touches the disk.
+ * Three outcomes, deliberately distinct like checkedPromptImages: `undefined` — no defer
+ * field, a prompt that runs as soon as its turn comes; a number — the epoch ms the prompt is
+ * deliverable from (`Date.now() + ms`); `null` — the field was present but not a duration
+ * this grammar accepts, or its duration is over the 90d cap, and the 400 naming the rule is
+ * already sent, so stop. The grammar is cli-args.ts's parseDurationMs — the same one
+ * `tumwater prompt --at` and `pause --for` accept — so a deferral spelled here computes the
+ * same `tumwater:not-before` marker the CLI writes. */
+function checkedPromptDefer(res, body) {
+    if (body.defer === undefined)
+        return undefined;
+    const ms = typeof body.defer === "string" ? parseDurationMs(body.defer) : null;
+    if (ms === null) {
+        badRequest(res, `defer needs a duration like 45s, 90m, 1h30m, or 2d${gotSuffix(body.defer)}`);
+        return null;
+    }
+    if (ms > PAUSE_FOR_MAX_MS) {
+        badRequest(res, `defer is capped at 90d${gotSuffix(body.defer)}`);
+        return null;
+    }
+    return Date.now() + ms;
+}
+/** The prompt endpoints' shared body tail: requirePromptText (400 on a null return) then
+ * checkedPromptImages then checkedPromptDefer (400 on a null return from either), so
+ * /api/prompt and /api/prompt-role read the same three fields in the same order and a body
+ * wrong in several still answers the text problem first. Null means a 400 is already sent;
+ * callers keep their own `if (!fields) return` bail. */
+function checkedPromptFields(res, body, role = DIRECTOR_ROLE) {
+    const text = requirePromptText(res, body, role);
+    if (text === null)
+        return null;
+    const images = checkedPromptImages(res, body);
+    if (images === null)
+        return null;
+    const notBeforeMs = checkedPromptDefer(res, body);
+    if (notBeforeMs === null)
+        return null;
+    return { text, images, notBeforeMs };
+}
+/** Handle POST /api/prompt-role: queue a prompt for one loop — 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).
+ * 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
+ * optional images array and its validate-before-anything-is-written discipline. */
+export async function handlePromptRole(req, res, root) {
+    const body = await readRoleBody(req, res, '{"role": "feature", "text": "..."}', root);
+    if (!body)
+        return;
+    const role = body.role;
+    const fields = checkedPromptFields(res, body, role);
+    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
+    // 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
+    // notice rides in the confirmation the composer flashes.
+    let notice = "";
+    if (fields.images && fields.images.length > 0) {
+        const guidance = imagePromptGuidance(root, role);
+        if (guidance.refusal) {
+            badRequest(res, guidance.refusal);
+            return;
+        }
+        notice = guidance.notice ?? "";
+    }
+    const message = [
+        submitRolePromptAndWake(root, role, fields.text, fields.images, fields.notBeforeMs),
+        notice,
+    ]
+        .filter(Boolean)
+        .join("\n");
+    sendJson(res, 200, { ok: true, message });
+}
+/** 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
+ * 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))
+        return;
+    const role = body.role === undefined ? DIRECTOR_ROLE : body.role;
+    if (rejectBadQueueFileName(res, body.file))
+        return;
+    const outcome = cancelQueuedFile(root, role, body.file);
+    sendJson(res, 200, outcome.status === "cancelled"
+        ? { ok: true, status: "cancelled", preview: promptPreview(outcome.text) }
+        : OK_GONE);
+}
+/** Handle POST /api/prompt-edit: rewrite one queued prompt addressed by its queue file — the
+ * dashboard's per-row edit affordance, the file-addressed twin of the CLI's position-addressed
+ * `prompt --edit`. The role is optional (absent edits the director's queue) and validates
+ * exactly like /api/prompt-cancel; a file name failing the shared rejectBadQueueFileName
+ * guard is a user-input error answered 400 with nothing touched on disk. Text
+ * 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
+ * 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). */
+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))
+        return;
+    const role = body.role === undefined ? DIRECTOR_ROLE : body.role;
+    if (rejectBadQueueFileName(res, body.file))
+        return;
+    const fields = checkedPromptFields(res, body, role);
+    if (!fields)
+        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
+    // submitRolePrompt enforces — before anything is written.
+    if (fields.images && fields.images.length > 0) {
+        const guidance = imagePromptGuidance(root, role);
+        if (guidance.refusal) {
+            badRequest(res, guidance.refusal);
+            return;
+        }
+    }
+    let outcome;
+    try {
+        outcome = editQueuedFile(root, role, body.file, fields.text, fields.images);
+    }
+    catch (err) {
+        badRequest(res, errorMessage(err));
+        return;
+    }
+    sendJson(res, 200, outcome.status === "edited"
+        ? { ok: true, status: "edited", oldText: outcome.oldText, newText: outcome.newText }
+        : OK_GONE);
+}
+/** Handle POST /api/prompt-top: move one queued prompt to the head of its role's queue,
+ * addressed by its queue file — the dashboard's per-row Move to top affordance, the
+ * file-addressed twin of the CLI's position-addressed `prompt --top`. The role is optional
+ * (absent moves in the director's queue) and validates exactly like /api/prompt-cancel; 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" } and the
+ * queue head answers 200 { status: "already_first" } — both data for the flash line, not
+ * server faults, so a stale poll can never reorder the wrong prompt. Same body discipline
+ * as /api/prompt (readJsonObject → 400 malformed/non-object, 413 oversized). */
+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))
+        return;
+    const role = body.role === undefined ? DIRECTOR_ROLE : body.role;
+    if (rejectBadQueueFileName(res, body.file))
+        return;
+    let outcome;
+    try {
+        outcome = topQueuedFile(root, role, body.file);
+    }
+    catch (err) {
+        badRequest(res, errorMessage(err));
+        return;
+    }
+    sendJson(res, 200, outcome.status === "topped"
+        ? { ok: true, status: "topped", preview: outcome.preview }
+        : outcome.status === "already_first"
+            ? { ok: true, status: "already_first" }
+            : OK_GONE);
+}

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

@@ -8,10 +8,10 @@ import http from "node:http";
 import { GUI_PAGE } from "../ui/gui/gui-page.js";
 import { statusPayload } from "../ui/status-payload.js";
 import { captureStartupBuild, createReloadWatch, reexecSelf, watchReloadSupervisor, } from "../redeploy/self-reload.js";
-import { warnEvent } from "../events/events.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, } from "./gui-endpoints.js";
-import { handleAbort, handleBriefEdit, handleBudget, handleConfigSet, handleConfigUnset, handlePause, handlePauseRole, handlePrompt, handleBacklogFile, handleBacklogCancel, handleBacklogEdit, handlePromptCancel, handlePromptEdit, handlePromptRole, handleQuestionAnswer, handleReclaim, handleRestart, handleStopSchedule, handleResetCounters, handleRoleNotes, handleWake, handleWakeCancel, } from "./gui-endpoint-commands.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 { 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
@@ -50,7 +50,10 @@ function crossOriginRequest(req) {
     const raw = req.headers.origin;
     if (raw === undefined)
         return false; // no Origin: not a browser — allow
-    const origin = Array.isArray(raw) ? raw[0] : raw;
+    // A `typeof` guard narrows to a concrete `string[]` (so `raw[0]` is `string | undefined`
+    // under noUncheckedIndexedAccess) instead of `Array.isArray`'s `any[]`, whose `[0]` is `any`;
+    // an empty array would be undefined either way, so `?? ""` only spells the first value out.
+    const origin = typeof raw === "string" ? raw : (raw[0] ?? "");
     if (origin === "null")
         return true;
     try {
@@ -99,7 +102,7 @@ export function loopbackHostAllowed(hostHeader) {
  * handler's purpose. The warning is best-effort, the same policy the cleanup warn sites apply. */
 function recordServerError(root, err) {
     try {
-        warnEvent(root, "harness", `dashboard server error: ${errorMessage(err)}`);
+        warnEvent(root, TUMWATER_SOURCE, `dashboard server error: ${errorMessage(err)}`);
     }
     catch {
         // The log is another process's to fix; the dashboard stays up either way.
@@ -107,7 +110,7 @@ function recordServerError(root, err) {
 }
 /** Start the dashboard server. Binds to 127.0.0.1 by default; with `allInterfaces` it
  * binds the unspecified address (every interface, IPv4 and IPv6), making the dashboard —
- * including the director prompt box, which anyone reaching it can use to steer the fleet —
+ * including the director prompt box, which anyone reaching it can use to steer the team —
  * available to the whole network. There is no authentication by default — exposing it is
  * the caller's deliberate choice — and an optional shared token (`gui --token <secret>`,
  * passed as `token`) gates every route: requests must carry it as `Authorization: Bearer
@@ -145,30 +148,44 @@ 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/tick": (_req, res, target) => handleTick(target.searchParams, res, root),
+        "GET /api/run": (_req, res, target) => handleTick(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/config": (_req, res) => handleConfig(res, root),
         "GET /api/brief": (_req, res) => handleBrief(res, root),
         "GET /api/doctor": (_req, res) => handleDoctor(res, root),
+        "GET /api/retire": (_req, res) => handleRetireList(res, root),
         "POST /api/brief": (req, res) => handleBriefEdit(req, res, root),
         "POST /api/config-set": (req, res) => handleConfigSet(req, res, root),
         "POST /api/config-unset": (req, res) => handleConfigUnset(req, res, root),
+        "POST /api/notify-test": (req, res) => handleNotifyTest(req, res, root),
         "POST /api/prompt": (req, res) => handlePrompt(req, res, root),
         "POST /api/prompt-role": (req, res) => handlePromptRole(req, res, root),
         "POST /api/backlog-file": (req, res) => handleBacklogFile(req, res, root),
         "POST /api/backlog-cancel": (req, res) => handleBacklogCancel(req, res, root),
+        "POST /api/backlog-release": (req, res) => handleBacklogRelease(req, res, root),
+        "POST /api/backlog-top": (req, res) => handleBacklogTop(req, res, root),
         "POST /api/backlog-edit": (req, res) => handleBacklogEdit(req, res, root),
         "POST /api/prompt-cancel": (req, res) => handlePromptCancel(req, res, root),
+        "POST /api/prompt-top": (req, res) => handlePromptTop(req, res, root),
         "POST /api/prompt-edit": (req, res) => handlePromptEdit(req, res, root),
         "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-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),
+        "POST /api/role-instances": (req, res) => handleRoleInstances(req, res, root),
+        "POST /api/role-instructions": (req, res) => handleRoleInstructions(req, res, root),
+        "POST /api/role-model": (req, res) => handleRoleModel(req, res, root),
+        "POST /api/role-quiet-hours": (req, res) => handleRoleQuietHours(req, res, root),
         "POST /api/pause": (req, res) => handlePause(req, res, root),
         "POST /api/wake": (req, res) => handleWake(req, res, root),
         "POST /api/wake-cancel": (req, res) => handleWakeCancel(req, res, root),
         "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/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),
@@ -210,7 +227,7 @@ export function startGui(root, port, allInterfaces = false, token = "", watch =
             // Cross-origin gate, ahead of every state-changing route: a hostile webpage can POST
             // to the open localhost server with a CORS-safelisted text/plain body (no preflight,
             // no readable response) and the side effect alone is the payload — a forged director
-            // prompt, a fleet pause, an abort. Browsers mark every cross-site POST with an Origin
+            // prompt, a team pause, an abort. Browsers mark every cross-site POST with an Origin
             // naming the hostile server, so one header check here refuses the forgery while the
             // dashboard's own POSTs (same-host Origin) and non-browser clients (no Origin) pass.
             if (req.method === "POST" && crossOriginRequest(req)) {

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

@@ -0,0 +1,164 @@
+/**
+ * The dashboard's POST team-pause/wake command handlers (barrelled into
+ * gui/gui-endpoint-commands.ts, which routes to them from src/gui/gui-server.ts): pause,
+ * pause-role, wake, and wake-cancel — with the `pauseForSecondsMs` / `pauseReasonField` /
+ * `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 { 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";
+import { badRequest, sendJson } from "./http-body.js";
+import { gotSuffix } from "../text/text.js";
+import { readPostBody, readRoleBody } from "./gui-endpoint-common.js";
+/** The shared optional-seconds rule behind the timed pause's `forSeconds` and the scheduled
+ * wake/stop's `inSeconds`: the field is absent (undefined) or a positive finite number of
+ * seconds within the CLI's 90-day cap — the two parallel validators used to restate this
+ * smell, one per field name. Its null return means the 400 is already sent and the caller must
+ * stop; its number return is the delay in milliseconds, which the timed-pause callers add
+ * their own clock to (the marker's `until` deadline) and the wake/stop-schedule callers use
+ * directly. `capHint` rides after the cap message for a field whose capped form earns an extra
+ * pointer (pause's standing-pause note); the messages name the field so pause (`forSeconds`)
+ * and wake/stop-schedule (`inSeconds`) each read correctly. */
+function boundedSecondsMs(res, body, field, capHint = "") {
+    const seconds = body[field];
+    if (seconds === undefined)
+        return undefined;
+    if (typeof seconds !== "number" || !Number.isFinite(seconds) || seconds <= 0) {
+        badRequest(res, `${field} must be a positive number of seconds${gotSuffix(seconds)}`);
+        return null;
+    }
+    if (seconds * 1000 > PAUSE_FOR_MAX_MS) {
+        badRequest(res, `${field} is capped at ${PAUSE_FOR_MAX_MS / 1000} seconds (90 days)${gotSuffix(seconds)}${capHint}`);
+        return null;
+    }
+    return Math.round(seconds * 1000);
+}
+/** The shared `forSeconds` rule of /api/pause and /api/pause-role: undefined when absent, the
+ * deadline in epoch milliseconds when valid, null after sending the 400 (only with
+ * `paused: true`, a positive finite number, within the CLI's 90-day cap — the numeric body
+ * rides boundedSecondsMs). */
+function pauseForSecondsMs(res, body, pausing) {
+    const forSeconds = body.forSeconds;
+    if (forSeconds === undefined)
+        return undefined;
+    if (!pausing) {
+        badRequest(res, "forSeconds only applies when pausing (paused: true)");
+        return null;
+    }
+    const ms = boundedSecondsMs(res, body, "forSeconds", " — pause without it for a standing pause");
+    return ms === null || ms === undefined ? ms : Date.now() + ms;
+}
+/** The optional `reason` of /api/pause: undefined when absent or blank, the raw string when
+ * given with `paused: true` (pauseTeam folds and caps it), null after sending the 400. */
+function pauseReasonField(res, body, pausing) {
+    const reason = body.reason;
+    if (reason === undefined)
+        return undefined;
+    if (!pausing) {
+        badRequest(res, "reason only applies when pausing (paused: true)");
+        return null;
+    }
+    if (typeof reason !== "string") {
+        badRequest(res, `reason must be a string${gotSuffix(reason)}`);
+        return null;
+    }
+    return reason.trim() === "" ? undefined : reason;
+}
+/** Handle POST /api/pause: the dashboard's pause control — the same operator gate
+ * `tumwater pause [--for <duration>]` and `resume` write, via team/team-state.ts's shared writers
+ * (pauseTeam/resumeTeam) so the CLI and the GUI cannot drift on the marker's format or
+ * idempotence. Same body discipline as /api/prompt and /api/budget (readJsonObject → 400
+ * malformed/non-object, 413 oversized); the target state is explicit (`paused: true|false`)
+ * rather than a toggle, so a retried request is idempotent. An optional `forSeconds` makes it
+ * a timed pause (the marker's `until`, capped like the CLI's `--for`); it only accompanies
+ * `paused: true`, as does an optional `reason` (the CLI's `pause --reason`, stored folded and
+ * capped by pauseTeam; the 200 body echoes what was stored). */
+export async function handlePause(req, res, root) {
+    const body = await readPostBody(req, res, '{"paused": true, "forSeconds": 3600}');
+    if (!body)
+        return;
+    const value = requirePausedFlag(res, body);
+    if (value === null)
+        return;
+    const untilMs = pauseForSecondsMs(res, body, value);
+    if (untilMs === null)
+        return;
+    const reason = pauseReasonField(res, body, value);
+    if (reason === null)
+        return;
+    if (value)
+        pauseTeam(root, untilMs, reason);
+    else
+        resumeTeam(root);
+    const stored = normalizePauseReason(reason);
+    sendJson(res, 200, { ok: true, paused: value, ...(untilMs === undefined ? {} : { until: untilMs }), ...(stored ? { reason: stored } : {}) });
+}
+/** The `inSeconds` rule of /api/wake: undefined when absent, the delay in milliseconds when
+ * valid, null after sending the 400 (a positive finite number within the CLI's 90-day cap).
+ * A duration, not a deadline: requestWake takes `inMs` and reads its own clock. */
+export function wakeInSecondsMs(res, body) {
+    return boundedSecondsMs(res, body, "inSeconds");
+}
+/** Handle POST /api/wake: the dashboard's per-row wake control — the same marker-writing
+ * core `tumwater wake` calls (requestWake), so the CLI and the GUI cannot drift on the
+ * state-file edits or the marker. `{}`/a missing role targets every configured role (the
+ * CLI's all-roles default); a given role validates exactly like /api/transcript. Same body
+ * discipline as /api/pause (readJsonObject → 400 malformed/non-object, 413 oversized). An
+ * optional `inSeconds` schedules the wake for later, like `tumwater wake --in` (same
+ * 90-day cap). */
+export async function handleWake(req, res, root) {
+    const body = await readRoleBody(req, res, '{"role": "feature"}', root, true);
+    if (!body)
+        return;
+    const inMs = wakeInSecondsMs(res, body);
+    if (inMs === null)
+        return;
+    sendJson(res, 200, {
+        ok: true,
+        message: requestWake(root, body.role === undefined ? validRoleIds(root) : [body.role], inMs),
+    });
+}
+/** Handle POST /api/wake-cancel: the dashboard's cancel of pending scheduled wakes — the same
+ * core `tumwater wake --cancel` calls (cancelWakes). A missing role cancels every pending wake;
+ * a given role validates like /api/wake and drops only its share. */
+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) });
+}
+/** 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
+ * 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`] : [])]);
+    let changed = false;
+    for (const key of keys)
+        changed = resumeRole(root, key) || changed;
+    return changed;
+}
+/** Handle POST /api/pause-role: the dashboard's per-row pause/resume control — the same
+ * marker-writing core `tumwater pause --role` / `resume --role` call (pauseRole/resumeRole),
+ * so the CLI and the GUI cannot drift on the marker's format or idempotence. The target state
+ * is explicit (`paused: true|false`) like /api/pause, so a retried request is idempotent; the
+ * team-wide pause composes freely — its gate is checked first at scheduling, and the role
+ * marker still records the operator's per-row intent. Same body discipline as /api/wake
+ * (readJsonObject → 400 malformed/non-object, 413 oversized; the role validates through the
+ * shared rejectBadRole wording). */
+export async function handlePauseRole(req, res, root) {
+    const body = await readRoleBody(req, res, '{"role": "feature", "paused": true}', root);
+    if (!body)
+        return;
+    const value = requirePausedFlag(res, body);
+    if (value === null)
+        return;
+    const untilMs = pauseForSecondsMs(res, body, value);
+    if (untilMs === null)
+        return;
+    const changed = value
+        ? pauseRole(root, body.role, untilMs)
+        : resumeLoopKeys(root, body.role);
+    sendJson(res, 200, { ok: true, changed, paused: value, ...(untilMs === undefined ? {} : { until: untilMs }) });
+}

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

@@ -6,6 +6,22 @@ export function sendJson(res, status, body) {
     res.writeHead(status, { "content-type": "application/json" });
     res.end(JSON.stringify(body));
 }
+/** Send a 400 Bad Request carrying a single client-error message — the one shape every /api
+ * handler's validation/authoring failure replies with ({ error: "..." }), so the status and
+ * the `{ error }` wrapper live here instead of being open-coded at each call site. */
+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
+ * 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) {
+    sendJson(res, 200, OK_GONE);
+}
+/** The {"ok":true,"status":"gone"} body okGone sends, also exposed for the couple of handlers
+ * that wrap it as one branch of a larger 200 reply (prompt-cancel/prompt-edit). */
+export const OK_GONE = { ok: true, status: "gone" };
 /** Max request body for the /api POST endpoints, in wire bytes. Sized for the prompt
  * endpoints' image attachments: 4 images × 5 MiB × 4/3 base64 expansion ≈ 27 MiB must fit one
  * POST, with headroom — the cap exists to bound memory on a local dashboard, not to be tight.
@@ -130,7 +146,7 @@ export async function readJsonObject(req, res, example) {
     // because it sends a different status.
     const parsed = parseJsonObject(body);
     if (!parsed) {
-        sendJson(res, 400, { error: `body must be a JSON object like ${example}` });
+        badRequest(res, `body must be a JSON object like ${example}`);
         return null;
     }
     return parsed;