tumwater 0.4.2 → 0.4.4

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

@@ -87,6 +87,62 @@ export function handleBacklogMatch(q, res, root) {
         .map((row) => ({ role: row.role, file: row.file }));
     sendJson(res, 200, out);
 }
+/** Normalise an optional `?path=` query arg to `{ path }` (absent → `{ path: undefined }`),
+ * answering the shared 400 when the raw value does not name a repo-relative path. Shared by
+ * the `?overlaps` and `?role` arms; `null` means the 400 was sent, so the caller returns. */
+function diffPathParam(res, rawPath) {
+    if (rawPath === null)
+        return { path: undefined };
+    const path = normalizeDiffPath(rawPath);
+    if (path === null) {
+        badRequest(res, "path takes a repo-relative path such as src/cli.ts (as overlaps lists it)");
+        return null;
+    }
+    return { path };
+}
+/** The `?overlaps` view: refuse stat, normalise the path, resolve the comma-separated role
+ * list, collect the overlaps and scope them by roles then by path, then send. */
+async function handleDiffOverlaps(q, res, root, rawPath, stat) {
+    if (stat) {
+        badRequest(res, "overlaps lists paths, not patches; drop stat");
+        return;
+    }
+    const opath = diffPathParam(res, rawPath);
+    if (opath === null)
+        return;
+    const roles = roleListQuery(q, res, root);
+    if (roles === null)
+        return;
+    let view = await collectChangeOverlaps(root);
+    if (roles !== undefined)
+        view = scopeChangeOverlaps(view, roles);
+    if (opath.path !== undefined)
+        view = scopeChangeOverlapsToPath(view, opath.path);
+    sendJson(res, 200, view);
+}
+/** The role-less team roster: refuse stat and path with their own 400s, then send
+ * collectTeamChanges's document. */
+async function handleDiffTeam(res, root, rawPath, stat) {
+    if (stat) {
+        badRequest(res, "stat needs role (the team roster carries no patch)");
+        return;
+    }
+    if (rawPath !== null) {
+        badRequest(res, "path needs role (the team roster carries no patch)");
+        return;
+    }
+    sendJson(res, 200, await collectTeamChanges(root));
+}
+/** The `?role=<id>` per-role view: validate through rejectBadRole, normalise the shared path,
+ * then send collectRoleChange with its path and stat options. */
+async function handleDiffRole(res, root, role, rawPath, stat) {
+    if (rejectBadRole(root, res, role))
+        return;
+    const path = diffPathParam(res, rawPath);
+    if (path === null)
+        return;
+    sendJson(res, 200, await collectRoleChange(root, role, { ...(path.path === undefined ? {} : { path: path.path }), ...(stat ? { stat: true } : {}) }));
+}
 /** Handle GET /api/diff[?role=<id>]: the unmerged-change view the CLI prints from the same
  * collectors — no `role` → collectTeamChanges (exactly `tumwater diff --json`'s document:
  * `{ mainBranch, roles }`, no per-role patch halves); `?role=<id>` → collectRoleChange (the
@@ -105,46 +161,10 @@ export function handleBacklogMatch(q, res, root) {
 export async function handleDiff(q, res, root) {
     const rawPath = q.get("path");
     const stat = q.get("stat") !== null;
-    if (q.get("overlaps") !== null) {
-        if (stat) {
-            badRequest(res, "overlaps lists paths, not patches; drop stat");
-            return;
-        }
-        const opath = rawPath === null ? undefined : normalizeDiffPath(rawPath);
-        if (opath === null) {
-            badRequest(res, "path takes a repo-relative path such as src/cli.ts (as overlaps lists it)");
-            return;
-        }
-        const roles = roleListQuery(q, res, root);
-        if (roles === null)
-            return;
-        let view = await collectChangeOverlaps(root);
-        if (roles !== undefined)
-            view = scopeChangeOverlaps(view, roles);
-        if (opath !== undefined)
-            view = scopeChangeOverlapsToPath(view, opath);
-        sendJson(res, 200, view);
-        return;
-    }
+    if (q.get("overlaps") !== null)
+        return handleDiffOverlaps(q, res, root, rawPath, stat);
     const role = q.get("role");
-    if (role === null) {
-        if (stat) {
-            badRequest(res, "stat needs role (the team roster carries no patch)");
-            return;
-        }
-        if (rawPath !== null) {
-            badRequest(res, "path needs role (the team roster carries no patch)");
-            return;
-        }
-        sendJson(res, 200, await collectTeamChanges(root));
-        return;
-    }
-    if (rejectBadRole(root, res, role))
-        return;
-    const path = rawPath === null ? undefined : normalizeDiffPath(rawPath);
-    if (path === null) {
-        badRequest(res, "path takes a repo-relative path such as src/cli.ts (as overlaps lists it)");
-        return;
-    }
-    sendJson(res, 200, await collectRoleChange(root, role, { ...(path === undefined ? {} : { path }), ...(stat ? { stat: true } : {}) }));
+    if (role === null)
+        return handleDiffTeam(res, root, rawPath, stat);
+    return handleDiffRole(res, root, role, rawPath, stat);
 }

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

@@ -32,29 +32,19 @@ export function lanAddresses(interfaces = os.networkInterfaces()) {
  * /proc/<pid>/cmdline exposes to every local user and what a reload re-runs verbatim — so the
  * secret must travel by env, never argv. */
 export const GUI_TOKEN_ENV = "TUMWATER_GUI_TOKEN";
-/** The `tumwater gui` command: parse the --port/--all-interfaces/--token flags, start the
- * server, print the banner, and serve until Ctrl+C. Lives beside startGui (gui/gui-server.ts) so
- * the CLI's gui-specific policy (token validation, the listen-failure messages, the LAN
- * announcement) cannot drift from the server it drives. Flag-vocabulary rejection stays in
- * cli.ts with the other cases; everything gui-specific after that gate is this function's job.
- * A failed listen throws (cli.ts's main catch renders it as the same `tumwater: …` line and
- * exit 1 fail() would) so the listen-failure wordings stay assertable in-process. */
-export async function cmdGui(root, args, seams = {}) {
-    const start = seams.startGui ?? startGui;
-    const lan = seams.lanAddresses ?? lanAddresses;
-    const print = seams.say ?? say;
-    const serve = seams.serve ?? (() => new Promise(() => { }));
-    const portRaw = flagValue(args, "--port");
-    const port = portRaw !== null ? parsePortFlag(portRaw) : 7180;
-    const allInterfaces = args.includes("--all-interfaces");
-    // A valueless or empty --token is a CLI error, not an open server: an operator who
-    // asked for protection must never silently get none. The validation and its wording
-    // live in tokenValueProblem, shared with `start --gui` so the two callers cannot
-    // drift; its flag-looking-value case names `tumwater gui` here.
-    const problem = tokenValueProblem(args, "tumwater gui");
-    if (problem)
-        fail(problem);
-    const flagToken = flagValue(args, "--token");
+/** Resolve cmdGui's four injectable seams to their runnable forms: the server it starts, the
+ * LAN address source the banner names, the printer for the banner and warnings, and the
+ * serve-until-Ctrl+C wait. Production callers omit every seam and get the real server,
+ * interfaces, stdout, and wait. */
+function resolveGuiSeams(seams) {
+    return {
+        start: seams.startGui ?? startGui,
+        lan: seams.lanAddresses ?? lanAddresses,
+        print: seams.say ?? say,
+        serve: seams.serve ?? (() => new Promise(() => { })),
+    };
+}
+function adoptGuiToken(flagToken, print) {
     // A direct `tumwater gui --token` puts the secret on its own argv — readable by any local
     // user and re-run verbatim by reexecSelf onto every reloaded generation — so fold it into
     // the env and take it off the command line before a redeploy can re-expose it. A child
@@ -66,7 +56,10 @@ export async function cmdGui(root, args, seams = {}) {
         process.argv.splice(argvToken, 2);
         print(`--token is visible to every local user in this process's command line (\`ps\`, /proc/<pid>/cmdline) and is re-run onto each reloaded generation — prefer the ${GUI_TOKEN_ENV} env var`);
     }
-    const token = flagToken ?? process.env[GUI_TOKEN_ENV] ?? "";
+    return flagToken ?? process.env[GUI_TOKEN_ENV] ?? "";
+}
+/** Start the server and translate the two common listen failures into hints naming their fix. */
+async function startGuiOrExplain(start, root, port, allInterfaces, token) {
     try {
         await start(root, port, allInterfaces, token);
     }
@@ -83,6 +76,9 @@ export async function cmdGui(root, args, seams = {}) {
             throw new Error(`port ${port} could not be opened (permission denied) — ports below 1024 need root; pick an unprivileged port with \`tumwater gui --port <n>\``);
         throw err;
     }
+}
+/** Print the localhost banner and, under --all-interfaces, the LAN URLs and exposure wording. */
+function printGuiBanner(print, lan, port, allInterfaces, token) {
     const tokenSuffix = token ? `/?token=${encodeURIComponent(token)}` : "";
     print(`tumwater gui at http://127.0.0.1:${port}${tokenSuffix} — Ctrl+C to stop`);
     if (allInterfaces) {
@@ -95,5 +91,28 @@ export async function cmdGui(root, args, seams = {}) {
             ? "listening on ALL interfaces — token-protected; prompting the director requires the token"
             : "listening on ALL interfaces — no auth; anyone reaching it can prompt the director");
     }
+}
+/** The `tumwater gui` command: parse the --port/--all-interfaces/--token flags, start the
+ * server, print the banner, and serve until Ctrl+C. Lives beside startGui (gui/gui-server.ts) so
+ * the CLI's gui-specific policy (token validation, the listen-failure messages, the LAN
+ * announcement) cannot drift from the server it drives. Flag-vocabulary rejection stays in
+ * cli.ts with the other cases; everything gui-specific after that gate is this function's job.
+ * A failed listen throws (cli.ts's main catch renders it as the same `tumwater: …` line and
+ * exit 1 fail() would) so the listen-failure wordings stay assertable in-process. */
+export async function cmdGui(root, args, seams = {}) {
+    const { start, lan, print, serve } = resolveGuiSeams(seams);
+    const portRaw = flagValue(args, "--port");
+    const port = portRaw !== null ? parsePortFlag(portRaw) : 7180;
+    const allInterfaces = args.includes("--all-interfaces");
+    // A valueless or empty --token is a CLI error, not an open server: an operator who
+    // asked for protection must never silently get none. The validation and its wording
+    // live in tokenValueProblem, shared with `start --gui` so the two callers cannot
+    // drift; its flag-looking-value case names `tumwater gui` here.
+    const problem = tokenValueProblem(args, "tumwater gui");
+    if (problem)
+        fail(problem);
+    const token = adoptGuiToken(flagValue(args, "--token") ?? null, print);
+    await startGuiOrExplain(start, root, port, allInterfaces, token);
+    printGuiBanner(print, lan, port, allInterfaces, token);
     await serve(); // Serve until Ctrl+C.
 }

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

@@ -1,7 +1,7 @@
 /**
  * The dashboard's POST config/budget command handlers (barrelled into
  * gui/gui-endpoint-commands.ts, which routes to them from src/gui/gui-server.ts):
- * config-set, config-unset, budget, role-cap, role-review-after-merge, role-enable,
+ * config-set, config-unset, budget, role-cap, role-enable,
  * role-disable, and
  * notify-test — the
  * post-handler layer onto
@@ -9,9 +9,8 @@
  * own `res`.
  */
 import { setConfigKey, setDailyBudgetUsd, setRoleModelFields, unsetConfigKey } from "../config/config-write.js";
-import { loadConfigSafe } from "../config/config.js";
 import { checkDailyBudgetUsd, checkMinRunInterval } from "../config/config-keys.js";
-import { testNotifyHook } from "../cli/notify-command.js";
+import { testNotifyHook } from "../cli/cli-notify-command.js";
 import { rejectBadRole, requireConfigKey, requireRoleField, requireStringField } from "./gui-args.js";
 import { baseRoleOf } from "../roles/runner-ids.js";
 import { DIRECTOR_ROLE } from "../roles/roles.js";
@@ -88,67 +87,6 @@ export async function handleRoleCap(req, res, root) {
         return configKeyError(res, "maxDailyCostUsdPerRole." + baseRole, result);
     sendJson(res, 200, { ok: true, role: baseRole, maxDailyCostUsd: value, ...unchangedFlag(result) });
 }
-/** Handle POST /api/role-review-after-merge: the role drawer's Review row button moves one role
- * in or out of review.afterMerge — the browser twin of `tumwater role <id>
- * --review-after-merge`/`--clear-review-after-merge` (the CLI's just-landed write, the amber
- * role-cap alert's remedy on the surface the alert appears on). Same body discipline as
- * /api/role-cap (readPostBody → 400 malformed/non-object, 413 oversized); the body carries the
- * desired membership `afterMerge: true|false` (400 `afterMerge must be true or false`
- * otherwise), and the role id maps to its base role's membership (baseRoleOf) exactly as the
- * CLI's `--review-after-merge` branch does. An unknown id is refused up front (rejectBadRole
- * on the base id, the mirror of the CLI's requireKnownRole) because a no-op or clear write
- * skips validateConfig's known-role refusal — setConfigKey's section branch returns unchanged
- * and writes nothing when the candidate equals the resolved list, so without it a bogus id
- * would answer 200 on a clear. The whole-list value rides the same setConfigKey core `config
- * set review.afterMerge <json>` uses, so validateConfig owns the string-array shape and the
- * `review.afterMerge must not be "director"` refusal — no explicit director branch, matching
- * the CLI. A no-op write (already in the asked-for state) answers unchanged and leaves
- * tumwater.json byte-identical. */
-export async function handleRoleReviewAfterMerge(req, res, root) {
-    const body = await readPostBody(req, res, '{"role": "feature", "afterMerge": true}');
-    if (!body)
-        return;
-    const role = requireRoleField(res, body);
-    if (role === null)
-        return;
-    const want = body.afterMerge;
-    if (typeof want !== "boolean") {
-        badRequest(res, "afterMerge must be true or false");
-        return;
-    }
-    const base = baseRoleOf(role);
-    // An unknown base id is refused up front — the mirror of the CLI's requireKnownRole. A
-    // no-op or clear write returns the list unchanged and setConfigKey skips validateConfig
-    // (the known-role check a real write gets for free), so without this guard a bogus id
-    // would answer 200 on the clear path (same reason handleRoleQuietHours's clear arm carries
-    // rejectBadRole). The stored list holds base ids, so the base id is screened — as
-    // validateConfig's checkKnownRoleId screens the written list — letting an instance id
-    // like feature-2 map to its known base and pass.
-    if (rejectBadRole(root, res, base))
-        return;
-    // The CLI's own computation, list-for-list: the whole value lands through the same
-    // setConfigKey core so validateConfig owns the string-array shape and the director
-    // refusal, and the write is atomic.
-    const list = loadConfigSafe(root).config?.review.afterMerge ?? [];
-    const has = list.includes(base);
-    const next = has === want ? list : want ? [...list, base] : list.filter((r) => r !== base);
-    const result = setConfigKey(root, "review.afterMerge", JSON.stringify(next));
-    if (!result.ok)
-        return configKeyError(res, "review.afterMerge", result);
-    sendJson(res, 200, {
-        ok: true,
-        role: base,
-        afterMerge: want,
-        message: result.unchanged
-            ? want
-                ? `${base}: already in review.afterMerge, so tumwater.json was not written`
-                : `${base}: not in review.afterMerge, so nothing was cleared`
-            : want
-                ? `${base}: added to review.afterMerge`
-                : `${base}: removed from review.afterMerge`,
-        ...unchangedFlag(result),
-    });
-}
 /** Handle POST /api/role-interval: the role drawer's min run interval editor sets or clears
  * one role's override of the team-wide minRunIntervalSeconds — the knob that makes one role
  * act rarely, distinct from the team-wide value. Same body discipline as /api/role-cap

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

@@ -15,7 +15,7 @@
  */
 export { handlePrompt, handlePromptRole, handlePromptCancel, handlePromptEdit, handlePromptTop } from "./gui-prompt-commands.js";
 export { handleQuestionAnswer, handleBacklogFile, handleBacklogCancel, handleBacklogRelease, handleBacklogTop, handleBacklogEdit } from "./gui-backlog-commands.js";
-export { handleConfigSet, handleConfigUnset, handleBudget, handleRoleCap, handleRoleReviewAfterMerge, handleRoleEnable, handleRoleDisable, handleRoleInstances, handleRoleInterval, handleRoleInstructions, handleRoleModel, handleRoleQuietHours, handleNotifyTest } from "./gui-config-commands.js";
+export { handleConfigSet, handleConfigUnset, handleBudget, handleRoleCap, handleRoleEnable, handleRoleDisable, handleRoleInstances, handleRoleInterval, handleRoleInstructions, handleRoleModel, handleRoleQuietHours, handleNotifyTest } from "./gui-config-commands.js";
 export { handlePause, handlePauseRole, handleWake, handleWakeCancel } from "./gui-team-commands.js";
 export { handleResetCounters, handleRestart, handleReclaim, handleKillOrphans, handleDropBrokenPins, handleCommitBacklog, handleResyncInstall, handleRetireLeftovers, handleArchiveBacklog, handleAbort, handleAbortAll, handleStopSchedule, handleRoleNotes, handleRetire, handleRevert, handleQueueCancel, handleQueueTop, handlePostReviewAccept, handleBriefEdit } from "./gui-operator-commands.js";
 export { handleQuarantineRelease } from "./gui-quarantine-commands.js";

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

@@ -7,7 +7,7 @@
  * inputs with — and sendRequestResult, the shared boolean-claiming marker reply. The
  * per-domain `checked*` validators live with their domain's module, not here.
  */
-import { rejectBadRole } from "./gui-args.js";
+import { rejectBadRole, requireSha } from "./gui-args.js";
 import { readJsonObject, sendJson } from "./gui-http-body.js";
 /** Every POST handler's shared opening: readJsonObject reads the body and — when it is
  * oversized, malformed, or not a JSON object — has already written the 413/400 itself. Its
@@ -38,6 +38,24 @@ export async function readRoleBody(req, res, example, root, allowMissing = false
         return null; // 400 already sent
     return body;
 }
+/** The sha-addressed POST handlers' shared prologue: readPostBody (400/413 sent on a null
+ * return) plus requireSha's hex-commit-id validation (400 sent on a null return), so the
+ * queue-cancel/queue-top/post-review-accept/revert family states the body-discipline-and-sha
+ * check pair once instead of two guard lines per handler. Its null return means the response
+ * is already written and the handler must stop; callers keep their own `if (!read) return`
+ * bail. Exactly four call sites — handleRevert, handleQueueCancel, handleQueueTop, and
+ * handlePostReviewAccept — returning the body too so handleRevert can read its optional
+ * dryRun; the other three callers use only the sha. A caller that needs neither the body nor
+ * the example can read just `{ sha }` from the result. */
+export async function readShaBody(req, res) {
+    const body = await readPostBody(req, res, '{"sha": "1a2b3c4"}');
+    if (body === null)
+        return null; // 4xx already sent — oversized, malformed, or not an object
+    const sha = requireSha(res, body.sha);
+    if (sha === null)
+        return null; // 400 already sent
+    return { body, sha };
+}
 /** Reply for a boolean-claiming marker request (RequestResult): success maps to 200 with its
  * message, refusal to 409 — the request is valid but nothing can act on it, the same conflict
  * reading requestAbort's not-live error uses. /api/restart and /api/abort share it. */

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

@@ -14,7 +14,7 @@ import { eventRole, readEvents } from "../events/event-read.js";
 import { eventFeedItem, eventMatchesGrep } from "../events/event-format.js";
 import { readRunDetail, runCommitSha, runMergedSha } from "../run/run-detail-data.js";
 import { renderRunDetail, runDetailPatch, runDetailStat, runTranscriptLines } from "../run/run-detail-render.js";
-import { resolveRevertTarget } from "../operator/revert.js";
+import { resolveRevertTarget } from "../operator/operator-revert.js";
 import { rolePayload } from "../roles/role-view.js";
 import { clampCount, intQuery, rejectBadRole, sinceMsQuery, untilMsQuery } from "./gui-args.js";
 import { badRequest, sendJson } from "./gui-http-body.js";
@@ -124,36 +124,67 @@ function windowOrCount(q, res) {
     return { kind: "count" };
 }
 export function handleHistory(q, res, root) {
+    const req = historyRequest(q, res);
+    if (req === null)
+        return;
+    const ctl = req.windowCtl;
+    if (ctl.kind === "window")
+        serveHistoryWindow(res, root, req, ctl.sinceMs, ctl.untilMs);
+    else
+        serveHistoryCount(q, res, root, req);
+}
+/** Parse the request prefix `GET /api/history` shares across both shapes: the `role`/`grep`
+ * filters, the `result` class list (resultClassesQuery, a 400 on an unknown class), the `model`
+ * selector list, the `summary` flag's mere presence, and the rival `sinceMs`-vs-`n` shape
+ * (windowOrCount, a 400 on both or a bad cap). Any 400 is already sent and yields null. */
+function historyRequest(q, res) {
     const role = q.get("role") || null; // "" and absent both read all roles
     const grep = q.get("grep") || null; // "" and absent both filter nothing
     // `model` is a comma list of exact selectors (trimmed, deduplicated); "", absent and a list
     // with no non-empty piece all filter nothing, and an unknown selector keeps no rows.
     const classes = resultClassesQuery(q, res);
     if (classes === null)
-        return;
-    const inClasses = (rows) => (classes.length ? rows.filter((r) => classes.includes(historyClass(r.result))) : rows);
+        return null;
     const modelPieces = splitCommaListUnique(q.get("model") ?? "");
-    const onModels = (rows) => (modelPieces.length ? runRowsOnModels(rows, modelPieces) : rows);
     const summary = q.get("summary") !== null; // the flag's presence, whatever its value
     const windowCtl = windowOrCount(q, res);
     if (windowCtl === null)
-        return;
-    if (windowCtl.kind === "window") {
-        const { sinceMs, untilMs } = windowCtl;
-        const { rows, covered } = readRunRowsSince(root, sinceMs, role, untilMs ?? null);
-        const matched = onModels(inClasses(grep === null ? rows : runRowsMatchingGrep(rows, grep)));
-        sendJson(res, 200, { rows: matched, covered, note: covered ? "" : SPARSE_WINDOW_NOTE, ...(summary ? { summary: summarizeRunRows(matched), modelSummary: summarizeRunRowsByModel(matched) } : {}) });
-        return;
-    }
+        return null;
+    return { role, grep, classes, modelPieces, summary, windowCtl };
+}
+/** The shared filter chain both shapes apply to the served rows: grep first, then the `result`
+ * outcome classes, then the `model` selectors — the CLI's `history --grep`, `--result` and
+ * `--model` rules, in that order. */
+function historyRows(rows, req) {
+    const grepped = req.grep === null ? rows : runRowsMatchingGrep(rows, req.grep);
+    const classed = req.classes.length ? grepped.filter((r) => req.classes.includes(historyClass(r.result))) : grepped;
+    return req.modelPieces.length ? runRowsOnModels(classed, req.modelPieces) : classed;
+}
+/** The optional additive fold both answers share: when `summary` is present, `{ summary,
+ * modelSummary }` added to the 200 payload; absent, nothing (so the response is byte-for-byte
+ * today's). */
+function historySummaryFields(rows, summary) {
+    return summary ? { summary: summarizeRunRows(rows), modelSummary: summarizeRunRowsByModel(rows) } : {};
+}
+/** Answer the trailing-window shape ({ rows, covered, note }): rows read through readRunRowsSince
+ * from `sinceMs` (untilMs drops the rows newer than now − untilMs when present, exactly as the
+ * CLI's `history --since … --until` window reads), then the shared historyRows filter, then the
+ * optional summary fold — key order rows, covered, note, summary, modelSummary. */
+function serveHistoryWindow(res, root, req, sinceMs, untilMs) {
+    const { rows, covered } = readRunRowsSince(root, sinceMs, req.role, untilMs ?? null);
+    const matched = historyRows(rows, req);
+    sendJson(res, 200, { rows: matched, covered, note: covered ? "" : SPARSE_WINDOW_NOTE, ...historySummaryFields(matched, req.summary) });
+}
+/** Answer the newest-`n` count shape: `n` parses through intQuery (non-negative, default
+ * HISTORY_DEFAULT_RUNS) and is clamped to [1, HISTORY_MAX_RUNS] — the GUI clamps where the CLI
+ * fails fast — then rows read through readRunRows, filtered and answered through the shared
+ * historyRows/historySummaryFields, key order rows, summary, modelSummary. */
+function serveHistoryCount(q, res, root, req) {
     const parsed = intQuery(q, res, "n", "non-negative", HISTORY_DEFAULT_RUNS);
     if (parsed === null)
         return;
-    const n = clampCount(parsed, HISTORY_MAX_RUNS);
-    let rows = readRunRows(root, n, role);
-    if (grep !== null)
-        rows = runRowsMatchingGrep(rows, grep);
-    rows = onModels(inClasses(rows));
-    sendJson(res, 200, summary ? { rows, summary: summarizeRunRows(rows), modelSummary: summarizeRunRowsByModel(rows) } : { rows });
+    const rows = historyRows(readRunRows(root, clampCount(parsed, HISTORY_MAX_RUNS), req.role), req);
+    sendJson(res, 200, { rows, ...historySummaryFields(rows, req.summary) });
 }
 /** 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
@@ -245,47 +276,64 @@ function transcriptText(root, role, run, detail, includePrompts, grep) {
  * payload's `role` is that run's; `result`/`model` narrow it the same way, and a miss is a 404
  * worded for any role. */
 export async function handleRun(q, res, root) {
-    let role = q.get("role");
+    const target = runSelector(q, res, root);
+    if (target === null)
+        return;
+    const detail = readRunDetail(root, target.role, target.run);
+    if (detail === null) {
+        sendJson(res, 404, { error: runNotFoundMessage(target.role, target.run) });
+        return;
+    }
+    sendJson(res, 200, await runPayload(root, target.role, target.run, detail, q));
+}
+/** Resolve which run the request names — validating the role, then the numbered or `last` form. */
+function runSelector(q, res, root) {
+    const role = q.get("role");
     const bareLast = role === null && q.get("last") !== null;
     if (!bareLast && rejectBadRole(root, res, role))
-        return;
-    let run;
-    if (q.get("last") === null) {
-        if (q.get("result") !== null)
-            return badRequest(res, "result needs last");
-        if (q.get("model") !== null)
-            return badRequest(res, "model needs last");
-        run = intQuery(q, res, "run", "positive");
-        if (run === null)
-            return;
+        return null;
+    return q.get("last") !== null ? lastRunSelector(q, res, root, role) : numberedRunSelector(q, res, role);
+}
+/** Resolve the explicit `run=N` selector of /api/run (three 400s, the miss worded by intQuery). */
+function numberedRunSelector(q, res, role) {
+    if (q.get("result") !== null) {
+        badRequest(res, "result needs last");
+        return null;
     }
-    else {
-        if (q.get("run") !== null)
-            return badRequest(res, "last cannot be combined with run (a number and the newest run are rival selectors)");
-        const classes = resultClassesQuery(q, res);
-        if (classes === null)
-            return;
-        const models = splitCommaListUnique(q.get("model") ?? "");
-        const classFilter = classes.length ? classes : null;
-        const modelFilter = models.length ? models : null;
-        const row = newestRunRow(root, role, classFilter, modelFilter);
-        if (row !== null)
-            role = row.role;
-        run = row?.run ?? null;
-        if (run === null) {
-            sendJson(res, 404, { error: runNotFoundLastMessage(role, classFilter, modelFilter) });
-            return;
-        }
+    if (q.get("model") !== null) {
+        badRequest(res, "model needs last");
+        return null;
     }
-    const detail = readRunDetail(root, role, run);
-    if (detail === null) {
-        sendJson(res, 404, { error: runNotFoundMessage(role, run) });
-        return;
+    const run = intQuery(q, res, "run", "positive");
+    if (run === null)
+        return null;
+    return { role: role, run };
+}
+/** Resolve the `last` selector, narrowed by `result`/`model`, to the role's newest run. */
+function lastRunSelector(q, res, root, role) {
+    if (q.get("run") !== null) {
+        badRequest(res, "last cannot be combined with run (a number and the newest run are rival selectors)");
+        return null;
+    }
+    const classes = resultClassesQuery(q, res);
+    if (classes === null)
+        return null;
+    const models = splitCommaListUnique(q.get("model") ?? "");
+    const classFilter = classes.length ? classes : null;
+    const modelFilter = models.length ? models : null;
+    const row = newestRunRow(root, role, classFilter, modelFilter);
+    if (row === null) {
+        sendJson(res, 404, { error: runNotFoundLastMessage(role, classFilter, modelFilter) });
+        return null;
     }
+    return { role: row.role, run: row.run };
+}
+/** Assemble the 200 payload — the collector plus its rendered, stat and flag-gated fields. */
+async function runPayload(root, role, run, detail, q) {
     const grep = (q.get("grep") ?? "").trim();
     const mergedAs = runMergedSha(detail);
     const target = mergedAs === null ? null : await resolveRevertTarget(root, mergedAs);
-    sendJson(res, 200, {
+    return {
         ...detail,
         text: renderRunDetail(detail),
         stat: await runDetailStat(root, detail),
@@ -293,7 +341,7 @@ export async function handleRun(q, res, root) {
         hasCommit: runCommitSha(detail) !== null,
         ...(q.get("patch") !== null ? { patch: await runDetailPatch(root, detail) } : {}),
         ...(q.get("transcript") !== null ? { transcript: transcriptText(root, role, run, detail, q.get("prompt") !== null, grep === "" ? undefined : grep) } : {}),
-    });
+    };
 }
 /** Handle GET /api/role?role=<id>: one role's inspection payload — rolePayload's object,
  * the same collection behind `tumwater role <id>` — so the drawer's Notes and Next run