tumwater 0.1.0 → 0.1.2

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

@@ -0,0 +1,322 @@
+import { openBugEntries, openQuestionEntries, plannedPlanEntries } from "../backlog/backlog.js";
+import { runDoctor } from "../doctor/doctor.js";
+import { loadConfigSafe } from "../config/config.js";
+import { EDITABLE_CONFIG_KEYS } from "../config/config-editable-keys.js";
+import { collectReport, collectReportSince } from "../report/report-data.js";
+import { collectFailureReport, collectFailureReportSince } from "../failure/failure-data.js";
+import { renderFailureMarkdown } from "../failure/failure-render.js";
+import { renderSinceReportMarkdown } from "../report/report-render.js";
+import { REPORT_SINCE_MAX_MS } from "../events/event-window.js";
+import { humanSeconds } from "../text/datetime.js";
+import { collectFleetChanges, collectRoleChange } from "../change/change-data.js";
+import { readTranscript } from "../ui/transcript.js";
+import { HISTORY_DEFAULT_TICKS, HISTORY_MAX_TICKS, readTickRows, readTickRowsSince, tickRowsMatchingGrep } from "../history/history-data.js";
+import { LOGS_SINCE_MAX_MS, SPARSE_WINDOW_NOTE } from "../events/event-window.js";
+import { eventRole, readEvents } from "../events/event-read.js";
+import { eventFeedItem, eventMatchesGrep } from "../events/event-format.js";
+import { readTickDetail } from "../tick/tick-detail-data.js";
+import { renderTickDetail, tickNotFoundMessage } from "../tick/tick-detail.js";
+import { rolePayload } from "../roles/role-view.js";
+import { DIRECTOR_ROLE } from "../roles/roles.js";
+import { readQueuedPromptBody } from "../inbox/inbox-edit.js";
+import { intQuery, rejectBadQueueFileName, rejectBadRole, sinceMsQuery, windowDays } from "./gui-args.js";
+import { sendJson } from "./http-body.js";
+import { typoSuffix } from "../text/suggest.js";
+/** Handle GET /api/transcript?role=<id>&n=N: rendered transcript lines for one loop's pi
+ * log (same rendering as `tumwater logs --role <id>`). Unknown/missing role or a bad n → 400.
+ * User-defined loops 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;
+    sendJson(res, 200, { lines: readTranscript(root, role, n) });
+}
+/** The /api/backlog `file` values and the open-section reader each addresses — one table so
+ * the on-demand dispatch and the "valid values" list in both 400s cannot drift apart. A Map,
+ * not an object literal, so no `file` spelling (`constructor`, `toString`, `__proto__`) can
+ * reach an inherited member through the lookup. Insertion order is the list order. */
+const BACKLOG_FILE_READERS = new Map([
+    ["plans", plannedPlanEntries],
+    ["bugs", openBugEntries],
+    ["questions", openQuestionEntries],
+]);
+const BACKLOG_FILE_NAMES = [...BACKLOG_FILE_READERS.keys()];
+const BACKLOG_FILE_VALUES = BACKLOG_FILE_NAMES.join(", ");
+/** Handle GET /api/backlog?file=<plans|bugs|questions>&index=N: one backlog entry's full
+ * text ({title, body}), fetched on demand so multi-KB bodies (long repros, whole plans) never
+ * ride the 1-second /api/status poll. index addresses the Nth entry of that file's open
+ * section in the same order statusPayload lists its titles — PLANS.md ## Planned,
+ * BUGS.md ## Open, QUESTIONS.md ## Open — zero-based. Unknown/missing file, missing or bad
+ * index, and out-of-range index → 400 JSON error via sendJson. The query arrives pre-parsed
+ * (gui/gui-server.ts's parseRequestTarget), like every GET-data handler here. */
+export function handleBacklog(q, res, root) {
+    const file = q.get("file");
+    if (file === null) {
+        sendJson(res, 400, { error: `file required (valid values: ${BACKLOG_FILE_VALUES})` });
+        return;
+    }
+    const reader = BACKLOG_FILE_READERS.get(file);
+    if (!reader) {
+        sendJson(res, 400, {
+            error: `unknown file ${JSON.stringify(file)} (valid values: ${BACKLOG_FILE_VALUES})${typoSuffix(file, BACKLOG_FILE_NAMES)}`,
+        });
+        return;
+    }
+    const entries = reader(root);
+    const index = intQuery(q, res, "index", "non-negative");
+    if (index === null)
+        return;
+    const entry = entries[index];
+    if (!entry) {
+        sendJson(res, 400, { error: `index ${index} out of range (${file} has ${entries.length} open entries)` });
+        return;
+    }
+    sendJson(res, 200, { title: entry.title, body: entry.body });
+}
+/** Handle GET /api/diff[?role=<id>]: the unlanded-change view the CLI prints from the same
+ * collectors — no `role` → collectFleetChanges (exactly `tumwater diff --json`'s document:
+ * `{ mainBranch, roles }`, no per-role patch halves); `?role=<id>` → collectRoleChange (the
+ * full per-role view with `diff`/`uncommittedDiff`, `tumwater diff --role <id> --json`). The
+ * role is a target, not a filter, so it validates through rejectBadRole exactly like
+ * /api/transcript and /api/tick (unknown/missing → 400 naming the valid ids) — the same ids
+ * `parseRoleFlag` accepts on the CLI, including disabled and user-defined loops. The
+ * collectors degrade absent worktrees and missing base branches to their `state` instead of
+ * throwing, so a fresh or half-built repo still answers 200. Reads git plumbing directly, so
+ * it works whether or not the fleet is running. */
+export async function handleDiff(q, res, root) {
+    const role = q.get("role");
+    if (role === null) {
+        sendJson(res, 200, await collectFleetChanges(root));
+        return;
+    }
+    if (rejectBadRole(root, res, role))
+        return;
+    sendJson(res, 200, await collectRoleChange(root, role));
+}
+/** Handle GET /api/report?days=N[&role=<id>] or /api/report?sinceMs=<ms>[&role=<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), bounded by the
+ * reportSinceMs helper. The day window follows windowDays. An absent role is the fleet-wide
+ * report exactly as before; a present one is a filter, validated through rejectBadRole (unknown,
+ * including the empty string → 400 naming the valid ids) and handed to the collector's role
+ * scope. Reads files directly, so it works whether or not the fleet is running. */
+export function handleReport(q, res, root) {
+    const role = q.get("role");
+    if (role !== null && rejectBadRole(root, res, role))
+        return;
+    if (q.get("sinceMs") !== null) {
+        const sinceMs = reportSinceMs(q, res);
+        if (sinceMs === null)
+            return;
+        sendJson(res, 200, { markdown: renderSinceReportMarkdown(collectReportSince(root, sinceMs, role ?? undefined)) });
+        return;
+    }
+    sendJson(res, 200, collectReport(root, windowDays(q), role ?? undefined));
+}
+/** 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) {
+        sendJson(res, 400, { error: "days and sinceMs are mutually exclusive; days counts whole local days, sinceMs totals a trailing window" });
+        return null;
+    }
+    return sinceMsQuery(q, res, REPORT_SINCE_MAX_MS, (sinceMs) => `sinceMs must be between 1 and ${humanSeconds(REPORT_SINCE_MAX_MS / 1000)} (got ${sinceMs})`);
+}
+/** Handle GET /api/failures?days=N[&role=<id>] or /api/failures?sinceMs=<ms>[&role=<id>]: the
+ * same bounded Markdown failure digest the telemetry loop feeds on and `tumwater report
+ * --failures` prints, as JSON ({ markdown }) — the dashboard's failures tab renders it; with
+ * sinceMs it is the trailing-window digest (collectFailureReportSince) through the same render,
+ * the CLI's `report --failures --since` shape. The days window follows windowDays (so it can
+ * never drift from /api/report's). role rides the same absent-fleet / present-filter rule as
+ * handleReport: absent → the fleet digest, present → validated and scoped. Reads files
+ * directly, so it works with no fleet running. */
+export function handleFailures(q, res, root) {
+    const role = q.get("role");
+    if (role !== null && rejectBadRole(root, res, role))
+        return;
+    if (q.get("sinceMs") !== null) {
+        const sinceMs = reportSinceMs(q, res);
+        if (sinceMs === null)
+            return;
+        sendJson(res, 200, { markdown: renderFailureMarkdown(collectFailureReportSince(root, sinceMs, role ?? undefined)) });
+        return;
+    }
+    sendJson(res, 200, { markdown: renderFailureMarkdown(collectFailureReport(root, windowDays(q), role ?? undefined)) });
+}
+/** Handle GET /api/history?role=<id>&n=N[&grep=<text>] — or ?role=<id>&sinceMs=<ms> for a
+ * trailing window: the per-tick rows the CLI's `tumwater history` derives from the event log,
+ * the dashboard's history tab renders them. The count shape ({ rows }) rides readTickRows (the
+ * shared scan, window growth included, so a role-filtered ask on a busy fleet cannot silently
+ * come back short); n is optional: absent → HISTORY_DEFAULT_TICKS; present but not a plain
+ * non-negative integer → 400 (the handleBacklog index discipline — an explicit count that does
+ * not parse is a client error, unlike the report's degrade-to-default typo rule); then clamped
+ * to [1, HISTORY_MAX_TICKS] — the GUI clamps where the CLI fails fast, its established
+ * convention. grep is optional: absent or empty filters nothing; present → the rows are
+ * filtered through history-data.ts's shared tickRowsMatchingGrep rule, the same case-insensitive haystack rule
+ * `tumwater history --grep` uses (shared, not re-implemented), after the n/role scan so n
+ * bounds the scanned window and not the printed rows — the CLI's rule. The window shape
+ * ({ rows, covered, note }) rides readTickRowsSince, the collector behind `history --since`,
+ * 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
+ * loops; present → passed straight through as the role filter with no config validation (a
+ * filter is not a target — an id with no ticks legitimately yields zero rows), so the endpoint
+ * reads nothing but files, like /api/report and /api/failures. Reads files directly, so it
+ * works whether or not the fleet is running. */
+export function handleHistory(q, res, root) {
+    const role = q.get("role") || null; // "" and absent both read all loops
+    const grep = q.get("grep") || null; // "" and absent both filter nothing
+    if (q.get("sinceMs") !== null) {
+        if (q.get("n") !== null) {
+            sendJson(res, 400, { error: "sinceMs cannot be combined with n (a count and a window are rival shapes)" });
+            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 { rows, covered } = readTickRowsSince(root, sinceMs, role);
+        const matched = grep === null ? rows : tickRowsMatchingGrep(rows, grep);
+        sendJson(res, 200, { rows: matched, covered, note: covered ? "" : SPARSE_WINDOW_NOTE });
+        return;
+    }
+    const parsed = intQuery(q, res, "n", "non-negative", HISTORY_DEFAULT_TICKS);
+    if (parsed === null)
+        return;
+    const n = Math.min(HISTORY_MAX_TICKS, Math.max(1, parsed));
+    let rows = readTickRows(root, n, role);
+    if (grep !== null)
+        rows = tickRowsMatchingGrep(rows, grep);
+    sendJson(res, 200, { 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[&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.
+ * Reads files directly, so it works whether or not the fleet is running. */
+export function handleLogs(q, res, root) {
+    const parsed = intQuery(q, res, "n", "non-negative", LOGS_SEARCH_EVENTS);
+    if (parsed === null)
+        return;
+    const n = Math.min(LOGS_SEARCH_MAX_EVENTS, Math.max(1, parsed));
+    const role = q.get("role") || null; // "" and absent both read all loops
+    const grep = q.get("grep") || null; // "" and absent both filter nothing
+    const needle = grep === null ? null : grep.toLowerCase();
+    const events = readEvents(root, n);
+    const matched = events.filter((e) => (role === null || eventRole(e) === role) && (needle === null || eventMatchesGrep(e, needle)));
+    sendJson(res, 200, { events: matched.map(eventFeedItem) });
+}
+/** Handle GET /api/tick?role=<id>&tick=N: one tick's full event trail — readTickDetail's
+ * TickDetail, the collector `tumwater tick <role> <n>` prints from, plus `text`: the same
+ * payload through renderTickDetail, pre-rendered server-side like /api/transcript's lines so
+ * the browser shows the CLI's exact rendering instead of re-implementing the event formatting.
+ * Serving the shared collector is the point: the CLI and this endpoint cannot drift on what one
+ * tick'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 tick is an explicit count
+ * through intQuery (missing or not a positive integer → 400); and a tick the scanned window
+ * does not hold — never ran, or rotation ate it — answers 404 with tickNotFoundMessage, the
+ * CLI's exact not-found wording,
+ * never a crash. Reads files directly, so it works whether or not the fleet is running. */
+export function handleTick(q, res, root) {
+    const role = q.get("role");
+    if (rejectBadRole(root, res, role))
+        return;
+    const tick = intQuery(q, res, "tick", "positive");
+    if (tick === null)
+        return;
+    const detail = readTickDetail(root, role, tick);
+    if (detail === null) {
+        sendJson(res, 404, { error: tickNotFoundMessage(role, tick) });
+        return;
+    }
+    sendJson(res, 200, { ...detail, text: renderTickDetail(detail) });
+}
+/** Handle GET /api/role?role=<id>: one loop's inspection payload — rolePayload's object,
+ * the same collection behind `tumwater role <id>` — so the drawer's Notebook and Next tick
+ * prompt sections render what the CLI shows without re-implementing the assembly. The role
+ * is a target here, so it validates through rejectBadRole exactly like /api/transcript and
+ * /api/tick (unknown/missing → the shared 400 naming the valid ids and correcting typos);
+ * rolePayload is only reached with an id rejectBadRole accepted, so its own unknown-role
+ * throw never fires. Reads files directly, so it works whether or not the fleet is running. */
+export function handleRole(q, res, root) {
+    const role = q.get("role");
+    if (rejectBadRole(root, res, role))
+        return;
+    sendJson(res, 200, rolePayload(root, role));
+}
+/** Handle GET /api/prompt-text?file=<name>[&role=<id>]: one queued prompt's editable body —
+ * the text an edit replaces, for the dashboard's per-row edit affordance (PLANS.md
+ * 2026-10-11). The prompt is addressed by its queue-file basename (the /api/prompt-cancel
+ * address), so a stale poll's snapshot can never read the wrong entry; the not-before deferral
+ * marker and the `[image attached: …]` reference block are stripped, both plumbing the edit
+ * carries over unchanged. The role is optional (absent reads the director's queue) and
+ * validates exactly like /api/transcript; a file name failing the shared
+ * rejectBadQueueFileName guard is a user-input error answered 400 with nothing read. A vanished file answers 200
+ * { ok: true, status: "gone" } — the loop already dequeued it, which is data for the UI, not
+ * a server fault. Reads one file directly, so it works whether or not the fleet is running. */
+export function handlePromptText(q, res, root) {
+    const roleParam = q.get("role");
+    if (roleParam !== null && rejectBadRole(root, res, roleParam))
+        return;
+    const role = roleParam ?? DIRECTOR_ROLE;
+    const file = q.get("file");
+    if (rejectBadQueueFileName(res, file))
+        return;
+    const text = readQueuedPromptBody(root, role, file);
+    if (text === null) {
+        sendJson(res, 200, { ok: true, status: "gone" });
+        return;
+    }
+    sendJson(res, 200, { ok: true, text });
+}
+/** Handle GET /api/doctor: the same DoctorReport `tumwater doctor --json` prints, so the
+ * Settings view's Health check card and the CLI cannot disagree. Read-only — the checks write
+ * nothing (runDoctor's own contract) — and it works whether or not the fleet is running. `run`
+ * exists so tests can skip the host probes; a throw reaches the server's outer 500. */
+export async function handleDoctor(res, root, run = runDoctor) {
+    sendJson(res, 200, await run(root));
+}
+/** Handle GET /api/config: the Settings view's resolved values for exactly
+ * EDITABLE_CONFIG_KEYS — read through the same load path `tumwater config get` uses
+ * (loadConfigSafe, defaults merged in), so the page shows what the fleet would actually
+ * load. A broken or invalid tumwater.json answers 500 with validateConfig's message instead
+ * of serving a half-empty panel. */
+export function handleConfig(res, root) {
+    const { config, error } = loadConfigSafe(root);
+    if (config === undefined) {
+        sendJson(res, 500, { error });
+        return;
+    }
+    const record = config;
+    const out = {};
+    for (const key of EDITABLE_CONFIG_KEYS)
+        out[key] = record[key] ?? null;
+    sendJson(res, 200, out);
+}

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

@@ -0,0 +1,270 @@
+/** 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
+ * 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";
+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 { errorMessage } from "../text/text.js";
+import { handleBacklog, handleConfig, handleDiff, handleFailures, handleReport, handleHistory, handleLogs, handlePromptText, handleTick, handleRole, handleTranscript, handleDoctor, } from "./gui-endpoints.js";
+import { handleAbort, handleBudget, handleConfigSet, handleConfigUnset, handlePause, handlePauseRole, handlePrompt, handleBacklogFile, handleBacklogCancel, handleBacklogEdit, handlePromptCancel, handlePromptEdit, handlePromptRole, handleQuestionAnswer, handleReclaim, handleRestart, handleResetCounters, handleRoleNotes, 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
+ * would leak the token's length and prefix byte by byte. */
+function tokenMatches(expected, provided) {
+    const a = Buffer.from(expected, "utf8");
+    const b = Buffer.from(provided, "utf8");
+    if (a.length !== b.length)
+        return false;
+    return crypto.timingSafeEqual(a, b);
+}
+/** The request target parsed once (path, query, and the token gate all read the same
+ * object), or null when `req.url` is not a parseable URL — such requests fall through to
+ * 404 instead of throwing into the handler's 500 catch, token gate included: the gate reads
+ * the same parsed target rather than re-parsing, so a malformed target answers 401 there
+ * like the 404 it earns on the token-less server, never a 500 for a bad request.
+ * Routing compares the exact pathname, never the raw target: a startsWith on req.url
+ * answered ANY path prefixing a route (e.g. /api/transcripts?role=… returned 200 transcript
+ * data), and an equality check on the raw target would miss query strings on exact routes
+ * (/api/status?x → 404). */
+function parseRequestTarget(req) {
+    try {
+        return new URL(req.url ?? "", "http://localhost");
+    }
+    catch {
+        return null; // Unparseable target — not a route.
+    }
+}
+/** True when a request's Origin header names a server other than this one — the browser's
+ * cross-origin signal. Browsers attach Origin to every cross-site POST (fetch and form
+ * alike) and to same-origin POSTs too, so a POST from the dashboard carries this server's
+ * own Host authority, while curl and scripts send no Origin at all. `Origin: null`
+ * (sandboxed frames, data: redirects) is the hostile shape and is refused too. Pure header
+ * reading, so the router can gate every POST route through it in one place. */
+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;
+    if (origin === "null")
+        return true;
+    try {
+        return new URL(origin).host.toLowerCase() !== (req.headers.host ?? "").toLowerCase();
+    }
+    catch {
+        return true; // unparseable Origin — refuse a signal we cannot verify
+    }
+}
+/** The address `startGui` binds for a given `allInterfaces` choice: loopback-only by default,
+ * the unspecified address (`undefined` — every interface, IPv4 and IPv6) on request. Pure and
+ * host-independent, so the mapping is testable without a live socket or this host's address
+ * family. */
+export function guiBindHost(allInterfaces) {
+    return allInterfaces ? undefined : "127.0.0.1";
+}
+/** Whether a request's `Host` header names the loopback-bound server itself — `localhost`,
+ * `127.0.0.1`, or `::1`, each with or without its port (`[::1]:7180` bracketed). The check
+ * exists for a loopback-bound server only (see startGui): a browser that resolves an
+ * attacker-controlled name to 127.0.0.1 (DNS rebinding) reaches a loopback socket while its
+ * page's origin and the request's Host both name the attacker's domain, so crossOriginRequest's
+ * Origin/Host comparison calls the forged request same-origin. The Host is the one header the
+ * rebinding browser must set to that domain, so refusing a non-loopback Host closes both the
+ * read endpoints and the state-changing POSTs to a server reachable only from this machine.
+ * A non-bracketed IPv6 literal is malformed per RFC 7230 and is not accepted. Pure, so the
+ * parsing is testable without a socket. */
+export function loopbackHostAllowed(hostHeader) {
+    let host = hostHeader.trim().toLowerCase();
+    if (host.startsWith("[")) {
+        const end = host.indexOf("]");
+        if (end === -1)
+            return false;
+        host = host.slice(1, end);
+    }
+    else {
+        const colon = host.lastIndexOf(":");
+        if (colon !== -1)
+            host = host.slice(0, colon);
+    }
+    return host === "localhost" || host === "127.0.0.1" || host === "::1";
+}
+/** Record a post-listen dashboard server error without letting the recording itself take the
+ * dashboard down. warnEvent appends to the event log, which can fail (ENOSPC, EACCES under
+ * disk pressure); a throw out of a Node 'error' listener is an uncaught exception that kills
+ * the process, turning a recoverable socket error into a dead dashboard — the opposite of this
+ * 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)}`);
+    }
+    catch {
+        // The log is another process's to fix; the dashboard stays up either way.
+    }
+}
+/** 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 —
+ * 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
+ * <token>` or `?token=`, anything else gets a 401 JSON error. An empty token means no
+ * check — byte-for-byte the open server. Resolves once it is listening.
+ *
+ * `watch` overrides the self-reload watch's seams (self-reload.ts's injectables) plus the
+ * re-exec itself, and the supervised child's supervisor watch plus its exit; production
+ * callers omit it and get the real disk-stamp poll, reexecSelf and process.exit — tests
+ * inject fakes so the wiring (close, then re-exec, at most once; close, then exit, once the
+ * reload supervisor is gone) is assertable without launching a process or touching this
+ * dist's own stamp. */
+export function startGui(root, port, allInterfaces = false, token = "", watch = {}) {
+    // The serving process's own startup stamp: added to every /api/status payload so the page can
+    // notice a newer server (a redeploy or manual build re-execs this process) and reload itself.
+    const startupBuild = captureStartupBuild();
+    // The routes as one table, keyed by `METHOD path`: dispatch is a single lookup where the
+    // previous twenty-branch if/else chain restated `req.method === … && pathname === …` on
+    // every arm. Each path appears once (the page's two spellings share servePage), so lookup
+    // order carries no meaning. A handler that needs the query reads the one parsed target
+    // (parseRequestTarget) — routing matched its exact pathname, so the target is non-null.
+    const servePage = (_req, res) => {
+        res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+        res.end(GUI_PAGE);
+    };
+    const guiRoutes = {
+        "GET /": servePage,
+        "GET /index.html": servePage,
+        "GET /api/status": (_req, res) => {
+            sendJson(res, 200, { ...statusPayload(root), serverBuildSha: startupBuild?.sha ?? null });
+        },
+        "GET /api/report": (_req, res, target) => handleReport(target.searchParams, res, root),
+        "GET /api/failures": (_req, res, target) => handleFailures(target.searchParams, res, root),
+        "GET /api/history": (_req, res, target) => handleHistory(target.searchParams, res, root),
+        "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/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/doctor": (_req, res) => handleDoctor(res, root),
+        "POST /api/config-set": (req, res) => handleConfigSet(req, res, root),
+        "POST /api/config-unset": (req, res) => handleConfigUnset(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-edit": (req, res) => handleBacklogEdit(req, res, root),
+        "POST /api/prompt-cancel": (req, res) => handlePromptCancel(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/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/restart": (req, res) => handleRestart(req, res, root),
+        "POST /api/reclaim": (req, res) => handleReclaim(req, res, root),
+        "POST /api/abort": (req, res) => handleAbort(req, res, root),
+        "POST /api/pause-role": (req, res) => handlePauseRole(req, res, root),
+    };
+    const server = http.createServer(async (req, res) => {
+        try {
+            const target = parseRequestTarget(req);
+            const pathname = target?.pathname ?? null;
+            // DNS-rebinding gate, ahead of every route on a loopback-bound server: a hostile page
+            // whose domain resolves to 127.0.0.1 is same-origin with this server, so the
+            // cross-origin gate below cannot tell its requests from the dashboard's — but its
+            // Host header must name the attacker's domain, which a request to the loopback
+            // dashboard never legitimately does. Refusing that Host blocks the read endpoints
+            // (status, config, transcripts) and the state-changing POSTs together. An
+            // all-interfaces server is deliberately network-facing, so it keeps accepting every
+            // Host (the operator's exposure choice); a token, if set, still gates it.
+            if (!allInterfaces && !loopbackHostAllowed(req.headers.host ?? "")) {
+                sendJson(res, 403, {
+                    error: "request Host is not this loopback dashboard's — a rebinding name is refused",
+                });
+                return;
+            }
+            // Opt-in shared-token gate, ahead of every route: with a token set, the page and all
+            // /api endpoints require it as `Authorization: Bearer <token>` or `?token=`; anything
+            // else — including `GET /` — gets the same JSON 401 every handler uses, deliberately
+            // no HTML login form: the CLI prints the token-bearing URL, and a bare 401 body is the
+            // honest signal that the URL needs `?token=`.
+            if (token) {
+                const auth = req.headers.authorization ?? "";
+                const bearer = auth.startsWith("Bearer ") ? auth.slice("Bearer ".length) : "";
+                const provided = bearer || target?.searchParams.get("token") || "";
+                if (!tokenMatches(token, provided)) {
+                    sendJson(res, 401, { error: "token required" });
+                    return;
+                }
+            }
+            // 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
+            // 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)) {
+                sendJson(res, 403, {
+                    error: "cross-origin request rejected — dashboard POSTs must come from this dashboard's own origin",
+                });
+                return;
+            }
+            const route = guiRoutes[`${req.method ?? ""} ${pathname ?? ""}`];
+            if (route)
+                await route(req, res, target);
+            else {
+                res.writeHead(404, { "content-type": "text/plain" });
+                res.end("not found");
+            }
+        }
+        catch (err) {
+            sendJson(res, 500, { error: errorMessage(err) });
+        }
+    });
+    // Reload onto a newer compiled tree: close the server, then re-exec. The page's own poll sees
+    // the new process's changed serverBuildSha and reloads; failed polls while the port is down
+    // are swallowed by its existing catch.
+    const reloadWatch = createReloadWatch({
+        root,
+        startupInfo: startupBuild,
+        ...watch,
+        onTrigger: () => {
+            server.close();
+            (watch.reexec ?? reexecSelf)();
+        },
+    });
+    void reloadWatch.start();
+    // A reloaded child whose reload supervisor died outright: nothing will respawn or stop it,
+    // so it frees the port and exits instead of serving on at PPID 1.
+    const stopSupervisorWatch = watchReloadSupervisor(() => {
+        reloadWatch.stop();
+        server.close();
+        (watch.exit ?? process.exit)(0);
+    }, watch.supervisor);
+    server.once("close", stopSupervisorWatch);
+    return new Promise((resolve, reject) => {
+        const onListenError = (err) => reject(err);
+        server.once("error", onListenError);
+        const onListening = () => {
+            // The listen-time listener must not outlive the listen: an 'error' after this point
+            // would call reject on a settled promise and be swallowed. Replace it with a handler
+            // that records the failure, so a post-listen socket error (EMFILE on accept, …) is
+            // visible in the event feed instead of silently leaving a dead dashboard.
+            server.removeListener("error", onListenError);
+            server.on("error", (err) => recordServerError(root, err));
+            resolve(server);
+        };
+        const host = guiBindHost(allInterfaces);
+        if (host === undefined)
+            server.listen(port, onListening);
+        else
+            server.listen(port, host, onListening);
+    });
+}