@uchibeke/gallivant 0.0.0-stage → 0.2.0

package/lib/time.mjs

@@ -0,0 +1,36 @@
+// Time helpers. The daemon and the tests both go through `clock` so a test can move time forward without sleeping.
+
+export const nowIso = (clock = Date) => new Date(clock.now()).toISOString();
+
+/** Filesystem-safe timestamp for run folder names: 2026-09-24T02-04-00-123 */
+export const stamp = (clock = Date) => new Date(clock.now()).toISOString().replace(/[:.]/g, "-").replace("Z", "");
+
+export const minutes = n => n * 60_000;
+export const hours = n => n * 3_600_000;
+
+export const isAfter = (iso, sinceIso) => !!iso && (!sinceIso || Date.parse(iso) > Date.parse(sinceIso));
+
+/**
+ * Inclusive of the boundary itself. GitHub stamps events to the second, so two that arrive in the same second
+ * carry the same timestamp; a cursor set to one of them would hide the other under a strict comparison. Callers
+ * that use this pair the cursor with a list of ids already handled at that instant.
+ */
+export const isAtOrAfter = (iso, sinceIso) => !!iso && (!sinceIso || Date.parse(iso) >= Date.parse(sinceIso));
+
+/** An ISO instant with its milliseconds dropped, so it never sorts after a GitHub timestamp in the same second. */
+export const floorSecond = iso => (iso ? new Date(Math.floor(Date.parse(iso) / 1000) * 1000).toISOString() : iso);
+
+export const later = (a, b) => (!a ? b : !b ? a : Date.parse(a) >= Date.parse(b) ? a : b);
+export const earlier = (a, b) => (!a ? b : !b ? a : Date.parse(a) <= Date.parse(b) ? a : b);
+
+/** "3m ago", "2h ago", "just now". */
+export function ago(iso, clock = Date) {
+  if (!iso) return "never";
+  const ms = clock.now() - Date.parse(iso);
+  if (ms < 45_000) return "just now";
+  const m = Math.round(ms / 60_000);
+  if (m < 60) return `${m}m ago`;
+  const h = Math.round(m / 60);
+  if (h < 48) return `${h}h ago`;
+  return `${Math.round(h / 24)}d ago`;
+}

package/lib/tracker/assets.mjs

@@ -0,0 +1,43 @@
+// The tracker's static files, read from templates/tracker/ once per start.
+//
+// They are files rather than strings in a module so that the CSS is CSS and the script is JavaScript: an editor
+// highlights them, and the CSP can be `script-src 'self'` and `style-src 'self'` with no nonce and no hash to keep
+// in step. Read once, because they cannot change under a running server and re-reading per request would be a file
+// system call on every page load.
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const DIR = join(HERE, "..", "..", "templates", "tracker");
+
+const load = name => readFileSync(join(DIR, name), "utf8");
+
+/**
+ * lib/harness_log.mjs, as a classic script the served file can carry.
+ *
+ * The per-harness event reader lives beside the adapters, because that is where knowing a harness's stream shape
+ * already lives. The browser needs the same reader, and a second copy of it in templates/ would drift: the reason
+ * there is one is that the five log panels command-center replaced were five copies of one parse. So the module's
+ * source is spliced in with its `export` keywords dropped, which is all that separates it from a script: it imports
+ * nothing, by design, and a test asserts the spliced copy behaves as the imported one does.
+ */
+const inlined = () => readFileSync(join(HERE, "..", "harness_log.mjs"), "utf8").replace(/^export (const|function) /gm, "$1 ");
+
+/** Path to content type, for the two files the pages ask for. Anything else is not an asset and is a 404. */
+export const ASSETS = Object.freeze({
+  "/tracker.css": { body: load("tracker.css"), type: "text/css; charset=utf-8" },
+  // Strict mode is asserted here rather than inside either file: a "use strict" directive only counts as the first
+  // statement of the script, and the spliced module goes in ahead of the script that used to carry it.
+  "/tracker.js": { body: `"use strict";\n${inlined()}\n${load("tracker.js")}`, type: "text/javascript; charset=utf-8" },
+});
+
+/**
+ * The palette a page should force, from `?theme=`.
+ *
+ * `prefers-color-scheme` inside an iframe follows the browser, not the page that framed it, so a dark parent gets a
+ * light frame and it looks broken. A parent that knows its own theme passes it on the iframe src and this stamps it
+ * on the root element, where the stylesheet's `[data-theme]` rules pick it up. Anything but dark or light is
+ * ignored rather than rejected: a bad value should fall back to the system setting, not fail the page.
+ */
+export const themeOf = value => (value === "dark" || value === "light" ? value : null);

package/lib/tracker/pages.mjs

@@ -0,0 +1,320 @@
+// The pages: plain semantic HTML, with the stylesheet and the script served as their own files.
+//
+// Everything interpolated goes through `esc`. PR titles, branch names, reasons, run names and log lines come from
+// GitHub or from an agent, and an agent that prints `<script>` into its log must not be able to run it in the
+// reader's browser. There is one escape function and every template uses it.
+import { ago } from "../time.mjs";
+import { contract } from "../fs.mjs";
+import { controlPending, CONTROL_LABELS, MAX_NOTE, lastMessage } from "../control.mjs";
+import { probeStatus } from "../probe.mjs";
+import { needsAgentResume, networkRecoveryDetail } from "../network_recovery.mjs";
+
+/** The five characters that matter in HTML text and in a double-quoted attribute. Nothing else is interpolated. */
+export const esc = s => String(s ?? "")
+  .replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;")
+  .replaceAll('"', "&quot;").replaceAll("'", "&#39;");
+
+/**
+ * The stylesheet and the script are served from their own routes rather than inlined, so `script-src 'self'` needs
+ * neither 'unsafe-inline' nor a per-response nonce. A nonce would mean the HTML could never be cached and every page
+ * would have to thread the value through; a hash would have to be recomputed whenever the file changes and would
+ * drift silently. Two files on two routes is the version that cannot rot.
+ */
+export const CSP = [
+  "default-src 'none'",
+  "script-src 'self'",
+  "style-src 'self'",
+  "connect-src 'self'",
+  "img-src 'self' data:",
+  "form-action 'self'",
+  "base-uri 'none'",
+  // Framing is the point: this is meant to sit in a dashboard. It is bound to 127.0.0.1, so the only page that can
+  // frame it is one already running on this machine.
+  "frame-ancestors 'self' http://localhost:* http://127.0.0.1:*",
+].join("; ");
+
+/**
+ * One page shell. `theme` is dark, light or null; null leaves the choice to `prefers-color-scheme`.
+ *
+ * `base` is the path this tracker is mounted at, empty when it owns the origin and something like `/gallivant` when
+ * a host server delegates a prefix to it. It is published on <body data-base> so the script can build its own URLs
+ * from it: the script is one static file served from one route, so it cannot be told at build time where it lives.
+ */
+export function page({ title, body, theme = null, base = "" }) {
+  return `<!doctype html>
+<html lang="en"${theme ? ` data-theme="${esc(theme)}"` : ""}><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${esc(title)}</title><link rel="stylesheet" href="${esc(base)}/tracker.css"></head>
+<body data-base="${esc(base)}">${body}<script src="${esc(base)}/tracker.js" defer></script></body></html>
+`;
+}
+
+/**
+ * Every internal URL goes through here: the mount path, then the page, then the query the reader is carrying.
+ *
+ * Emitting absolute paths (`/run?id=`) would work only when the tracker owns the origin, and would 404 the moment a
+ * host server mounted it under a prefix. One builder means a mount point is a parameter rather than a rewrite.
+ */
+const at = (base, path, params = {}, extra = {}) => {
+  const q = new URLSearchParams();
+  for (const [k, v] of Object.entries({ ...params, ...extra })) if (v) q.set(k, v);
+  const s = q.toString();
+  return `${base}${path}${s ? `?${s}` : ""}`;
+};
+
+/**
+ * `home` is a link back out to whatever is hosting the tracker, so a mounted tracker is not a one-way trip. The host
+ * passes its own label and URL; standalone there is nowhere to go back to and the link is simply absent.
+ */
+const header = (base, heading, here, ctxq, home) => `<header class="top"><h1>${esc(heading)}</h1>
+<nav class="views">${home ? `<a class="home" href="${esc(home.url)}">${esc(home.label)}</a>` : ""}
+<a href="${esc(at(base, "/", ctxq))}"${here === "dash" ? ' aria-current="page"' : ""}>entries</a>
+<a href="${esc(at(base, "/runs", ctxq))}"${here === "runs" ? ' aria-current="page"' : ""}>runs</a></nav></header>`;
+
+/** The filter box, the grouping switch and the match count. One row, the same on both views. */
+const controls = (by, groupings) => `<div class="controls">
+<input type="search" id="filter" placeholder="filter" aria-label="filter the list" autocomplete="off" spellcheck="false">
+${groupings.length > 1 ? `<label for="groupby">group by</label><select id="groupby" aria-label="group by">
+${groupings.map(g => `<option value="${esc(g)}"${g === by ? " selected" : ""}>${esc(g)}</option>`).join("")}</select>` : ""}
+</div><p class="hint" id="matches" aria-live="polite"></p>`;
+
+/**
+ * The sidebar: one collapsible group per key, each holding rows. `view` names the localStorage bucket the collapsed
+ * state lives in, so the two views remember their own groups. `hay` is the text a filter matches beyond what the row
+ * shows, so searching for a branch or a reason finds a row that displays neither in full.
+ */
+const sidebar = (view, groups, controlsHtml) => `<aside id="side" data-view="${esc(view)}">
+${controlsHtml}
+${groups.map(g => `<div class="group" data-group="${esc(g.key)}">
+<h3><i class="caret"></i><span class="n">${esc(g.label)}</span><small>${g.rows.length}</small></h3>
+<div class="rows">${g.rows.map(r => `<a class="row" href="${esc(r.href)}"${r.current ? ' aria-current="page"' : ""} data-hay="${esc(r.hay || "")}" title="${esc(r.title || r.label)}">
+<i class="dot ${esc(r.tone || "")}"></i><span class="n">${esc(r.label)}</span><small>${esc(r.badge || "")}</small></a>`).join("")}</div>
+</div>`).join("\n")}
+${groups.length ? "" : `<p class="empty">Nothing registered yet. <code>gallivant start</code> puts a PRD in the loop.</p>`}
+</aside>`;
+
+/** needs-you first, then running, then done: the order `gallivant status` prints, so the two agree on sight. */
+const SECTIONS = [["needs_you", "needs you"], ["running", "running"], ["done", "done"]];
+const TONE = { needs_you: "needs", running: "running", done: "" };
+
+/** How a state group's rows are built. `by=harness` regroups the same rows; nothing else about them changes. */
+function entryGroups(base, m, by, current, ctxq) {
+  const rows = SECTIONS.flatMap(([key]) => (m[key] || []).map(r => ({
+    section: key,
+    href: at(base, "/run", ctxq, { id: r.id }),
+    label: r.handle,
+    badge: r.label,
+    tone: r.section === "running" && r.run?.running ? "running" : TONE[key],
+    title: `${r.handle} ${r.label}${r.detail ? ` ${r.detail}` : ""}`,
+    // What a filter searches beyond the visible text: the id, the reason, the harness and the round.
+    hay: [r.id, r.detail, r.reason, r.harness, r.round].filter(Boolean).join(" "),
+    harness: r.harness || "unknown",
+    current: r.id === current,
+  })));
+  if (by === "harness") {
+    const names = [...new Set(rows.map(r => r.harness))].sort();
+    return names.map(h => ({ key: `harness:${h}`, label: h, rows: rows.filter(r => r.harness === h) }));
+  }
+  return SECTIONS.map(([key, label]) => ({ key, label, rows: rows.filter(r => r.section === key) })).filter(g => g.rows.length);
+}
+
+export const GROUPINGS = ["state", "harness"];
+
+/** The dashboard: the sidebar plus the same groups as a table, so a wide frame shows detail and a narrow one a list. */
+export function dashboard(m, { clock = Date, by = "state", theme = null, query = {}, base = "", home = null } = {}) {
+  const ctxq = { theme: query.theme, by: by === "state" ? "" : by };
+  const groups = entryGroups(base, m, by, null, ctxq);
+  const table = (title, rows) => `<h2>${esc(title)}</h2>` + (rows.length ? `<table>
+<thead><tr><th>entry</th><th>state</th><th>detail</th><th>round</th><th>since</th><th></th></tr></thead><tbody>
+${rows.map(r => `<tr><td><a href="${esc(at(base, "/run", ctxq, { id: r.id }))}">${esc(r.handle)}</a></td>
+<td><span class="tag${r.section === "needs_you" ? " bad" : r.run?.running ? " live" : ""}">${esc(r.label)}</span></td><td>${esc(r.detail)}</td><td class="dim">${esc(r.round)}</td>
+<td class="dim">${esc(ago(r.since, clock))}</td><td>${r.url ? `<a href="${esc(r.url)}">PR</a>` : ""}</td></tr>`).join("\n")}
+</tbody></table>` : `<p class="empty">(none)</p>`);
+  const d = m.daemon;
+  // A dead daemon is the first thing a reader needs, and "run gallivant up" on its own does not say how long it has
+  // been dead. daemon.json survives the process, so when it was last seen is on disk and worth showing.
+  const probes = Object.entries(d?.probes || {}).map(([k, p]) => `, ${k} ${probeStatus(p)}`).join("");
+  const state = d?.alive
+    ? `daemon up since ${ago(d.startedAt, clock)}, last tick ${ago(d.lastTick, clock)}${probes}`
+    : d
+      ? `daemon DOWN, last tick ${ago(d.lastTick, clock)}. Run: gallivant up`
+      : "daemon has never run here. Run: gallivant up";
+  return page({ title: "gallivant", theme, base, body: `${header(base, "gallivant", "dash", ctxq, home)}
+<div class="layout">${sidebar("entries", groups, controls(by, GROUPINGS))}
+<section class="main">
+<p class="${d?.alive ? "dim" : "warn"}">${esc(state)}</p>
+${m.latestError ? `<p class="warn mono">${esc(m.latestError)}</p>` : ""}
+${SECTIONS.map(([key, label]) => table(label, m[key] || [])).join("")}
+</section></div>` });
+}
+
+/**
+ * The log pane, with the control that reaches back into the log above it.
+ *
+ * The stream sends the last 400 lines on open and an `event: skipped` frame saying how many it did not send, because
+ * delivering thousands of lines as individual server-sent events stalls the browser until it drops the connection.
+ * The button is how the reader gets the rest: it fetches the window before what the pane holds, from
+ * `/api/run/history`, and keeps going back until the first line of the run.
+ *
+ * It is rendered disabled and says nothing, and the script fills in the count and enables it once the `skipped` frame
+ * arrives. A run whose whole log fitted in the tail has nothing older, so the control never appears for it; rendering
+ * it here rather than creating it in the script keeps the markup in the templates where the rest of it is.
+ */
+const logPane = attrs => `<p class="loadmore"><button type="button" id="earlier" disabled hidden>load earlier lines</button>
+<span class="hint" id="earlierstate"></span></p>
+<div id="log" ${attrs} aria-live="polite" aria-label="run log" tabindex="0"></div>
+<p class="note" id="logstate">connecting</p>`;
+
+/**
+ * The brief moved under this entry: above the facts, because it is the one thing on the page that says the work may be
+ * aimed at the wrong target, and a reader who scrolls past it has been told nothing useful by the rest. Every difference
+ * is listed rather than just the first, which is the whole reason this page has room the `status` row does not.
+ *
+ * Every field goes through `esc` like everything else here: the criteria text and the file path come from a markdown
+ * file the operator wrote, which is not hostile but is not this module's to trust either.
+ */
+const briefMoved = d => `<div class="warn">
+<p><strong>${esc(d.reason)}</strong>: ${esc(d.why)}</p>
+<ul>${d.diff.map(l => `<li>${esc(l)}</li>`).join("")}</ul>
+${d.verdict === "changed" ? `<p>The completion gate is judging neither brief. Resolve it: <code>gallivant resume ${esc(d.handle || "")} --resnapshot</code> makes the edited brief the one that counts, or put the brief back the way it was.</p>` : ""}
+${d.verdict === "illegal" ? `<p><code>${esc(d.path)}</code> would be refused by <code>gallivant start</code> as it stands. Fix it, then <code>gallivant ready</code> it again.</p>` : ""}
+${d.verdict === "gone" ? `<p>Restore the file, or <code>gallivant remove</code> the entry if the work is no longer wanted.</p>` : ""}
+</div>`;
+
+/** One entry: its facts, then the live log of the run it last dispatched, with the sidebar alongside. */
+export function runPage({ id, entry, handle, run, initialLaunch = false, maxIterations, model, divergence = null, controlToken = null, by = "state", theme = null, query = {}, base = "", home = null }) {
+  const canResume = !!entry.session || initialLaunch;
+  const canRecheck = !!entry.pr && !needsAgentResume(entry);
+  const recovering = entry.network_retry?.phase === "waiting" && !entry.dispatch_stopped;
+  const canMessage = canResume || !!(run?.running && run.id === entry.last?.run);
+  const savedMessage = lastMessage(entry);
+  const ctxq = { theme: query.theme, by: by === "state" ? "" : by };
+  const fact = (k, v) => (v ? `<dt>${esc(k)}</dt><dd>${v}</dd>` : "");
+  const facts = [
+    fact("state", `<span class="tag${recovering ? "" : entry.state === "needs-human" ? " bad" : run?.running ? " live" : ""}">${esc(recovering ? "retrying" : entry.state)}</span>${entry.reason ? ` <span class="dim">${esc(entry.reason)}</span>` : ""}`),
+    fact("network recovery", entry.network_retry ? esc(networkRecoveryDetail(entry.network_retry)) : ""),
+    fact("harness", esc(entry.harness)),
+    fact("round", esc(`round ${entry.iteration}/${maxIterations}`)),
+    fact("PR", entry.url ? `<a href="${esc(entry.url)}">${esc(entry.url)}</a>` : entry.pr ? esc(`#${entry.pr}`) : ""),
+    fact("branch", `<code>${esc(entry.branch)}</code>`),
+    fact("worktree", `<code>${esc(contract(entry.worktree))}</code>`),
+    fact("session", `<code>${esc(entry.session)}</code>`),
+    fact("provider state", esc(entry.execution?.providerState)),
+    fact("observed / reconciled", entry.execution ? esc(`${entry.execution.observedAt ?? "unknown"} / ${entry.execution.reconciledAt ?? "never"}`) : ""),
+    fact("recovery action", esc(entry.execution?.recoveryAction)),
+    fact("run", run ? `<code>${esc(run.id)}</code> ${run.running ? `<span class="live">running</span>` : `exit ${esc(String(run.exit ?? "not recorded yet"))}`}` : ""),
+    fact("runs", `<a href="${esc(at(base, "/runs", ctxq, { entry: id }))}">every run for this entry</a>`),
+    fact("result evidence", run ? `<a href="${esc(at(base, "/api/run/result", {}, { id, run: run.id }))}">saved result and verification</a>` : ""),
+  ].join("");
+  // The log pane is driven by tracker.js, which reads these attributes. Passing the ids through the DOM rather than
+  // through the script keeps the script one static file the CSP can allow by origin. `data-harness` is among them
+  // because a log line's shape is the harness's, so the script needs the name to pick the right stream reader; the
+  // registry is what knows it, and an entry with none renders every line as itself.
+  return page({
+    title: `${handle} - gallivant`,
+    theme,
+    base,
+    body: `${header(base, handle, "run", ctxq, home)}
+<div class="layout">${sidebar("entries", entryGroups(base, model, by, id, ctxq), controls(by, GROUPINGS))}
+<section class="main">
+${divergence ? briefMoved(divergence) : ""}
+<dl class="facts">${facts}</dl>
+${controlToken && entry.state !== "done" ? `<section id="run-controls" class="run-controls" aria-labelledby="control-heading" data-entry="${esc(id)}" data-token="${esc(controlToken)}" data-pending="${controlPending(entry.control)}">
+<h2 id="control-heading">Run actions</h2>
+<div class="run-actions">
+<div><button type="button" data-action="recheck" data-available="${canRecheck}" aria-describedby="recheck-help"${!canRecheck || controlPending(entry.control) ? " disabled" : ""}>Recheck PR</button>
+<p id="recheck-help" class="note">${needsAgentResume(entry) ? "An agent failure needs Resume agent, not PR recheck. Any scheduled recovery is shown above." : entry.pr ? "Read the latest checks and review. Keeps the round budget; does not rerun CI." : "Available once this task has a PR."}</p></div>
+<div><button type="button" data-action="resume" data-available="${canResume}" aria-describedby="resume-help"${!canResume || controlPending(entry.control) ? " disabled" : ""}>Resume agent</button>
+<p id="resume-help" class="note">${initialLaunch ? "Start the first run from the approved brief after repairing launch prerequisites." : entry.session ? "Continue the same session on its current instructions." : "Available once this task has an agent session."}</p></div>
+<div><button type="button" data-action="cancel" data-available="true" aria-describedby="cancel-help"${controlPending(entry.control) ? " disabled" : ""}>Cancel task</button>
+<p id="cancel-help" class="note">Stops further dispatch and requests cancellation. Remote execution may continue until the provider confirms.</p></div>
+</div>
+<form id="message-form" class="message-composer">
+<label for="run-note">Message agent</label>
+<textarea id="run-note" rows="3" maxlength="${MAX_NOTE}" required aria-describedby="message-help" placeholder="Share an update or give the agent direction…"${!canMessage ? " disabled" : ""}></textarea>
+${run?.running && entry.execution?.controls?.interrupt !== false ? `<label class="interrupt-option"><input id="interrupt-run" type="checkbox" aria-describedby="interrupt-help"><span>Interrupt the active run to apply this message</span></label><p id="interrupt-help" class="note">At the next daemon check, stops the current process, preserves files and resumes the same session. In-progress edits may need repair.</p>` : ""}
+<div class="message-footer"><p id="message-help" class="note">${initialLaunch ? "Start the first run from the approved brief with your clarification after repairing launch prerequisites." : canMessage ? `Continues the same session with your correction, even after it finished.${run?.running ? " Leave the option unchecked to queue until this run ends." : ""}` : "Available once this task starts an agent run."}</p>
+<button type="submit" data-action="message" data-available="${canMessage}" disabled>Send message</button></div>
+</form>
+<p class="note control-help">Resume and messages use your agent plan and keep the approved brief and guardrails. Requests need the daemon running.</p>
+<p id="control-status" role="status" aria-live="polite">${esc(entry.control ? `${CONTROL_LABELS[entry.control.action] || "Request"} — ${entry.control.status}: ${entry.control.message || "Waiting for the daemon and any active run."}` : "")}</p>
+<a id="control-refresh" href="${esc(at(base, "/run", ctxq, { id }))}" hidden>View updated run</a>
+<details id="last-message"${savedMessage ? "" : " hidden"}><summary>Last submitted message</summary><pre>${esc(savedMessage?.note || "")}</pre><button id="restore-message" type="button">Edit and resend</button></details>
+</section>` : entry.state === "done" ? `<p class="note">This PR is closed or merged. Start a follow-up PRD for further changes.</p>` : ""}
+<h2>Log</h2>
+${run ? logPane(`data-entry="${esc(id)}" data-run="${esc(run.id)}" data-harness="${esc(entry.harness || "")}"`) : `<p class="empty">No run has been dispatched for this entry yet.</p>`}
+</section></div>` });
+}
+
+/** The runs tab: every run folder on disk, newest first, grouped in the sidebar and listed in full beside it. */
+export function runsPage(rows, { entry = "", by = "state", theme = null, query = {}, base = "", home = null, open = null } = {}) {
+  const ctxq = { theme: query.theme, by: by === "state" ? "" : by, entry };
+  const groups = runGroups(base, rows, by, entry, ctxq, open);
+  const body = rows.length ? `<table>
+<thead><tr><th>started</th><th>entry</th><th>run</th><th>state</th><th class="num">duration</th><th></th></tr></thead><tbody>
+${rows.map(r => `<tr><td class="dim">${esc(when(r.startedAt))}</td>
+${/* A run from another tool has no registry entry, so there is nothing to link to: it is listed, not opened. */ ""}
+<td>${r.entry ? `<a href="${esc(at(base, "/run", ctxq, { id: r.entry }))}">${esc(r.handle)}</a>` : `${esc(r.handle)} <span class="tag">${esc(r.source || "")}</span>`}</td>
+<td class="mono">${esc(r.run)}</td>
+<td>${r.running ? `<span class="tag live">running</span>` : r.exit === 0 ? `<span class="tag">exit 0</span>` : `<span class="tag bad">exit ${esc(String(r.exit ?? "not recorded"))}</span>`}</td>
+<td class="num dim">${esc(duration(r))}</td>
+<td><a href="${esc(at(base, "/runs", ctxq, { open: r.run, source: r.entry ? "" : r.source }))}">log</a></td></tr>`).join("\n")}
+</tbody></table>` : `<p class="empty">${entry ? "No runs for that entry." : "No runs on disk yet."}</p>`;
+  return page({ title: "runs - gallivant", theme, base, body: `${header(base, "runs", "runs", ctxq, home)}
+<div class="layout">${sidebar("runs", groups, controls(by, GROUPINGS))}
+<section class="main">
+${entry ? `<p class="dim">Filtered to <code>${esc(entry)}</code>. <a href="${esc(at(base, "/runs", ctxq, { entry: "" }))}">every entry</a></p>` : ""}
+${open ? detail(base, open, ctxq) : ""}
+<h2>${esc(open ? "every run" : "runs")}</h2>
+${body}<p class="note">${esc(`${rows.length} run${rows.length === 1 ? "" : "s"}, newest first.`)}</p>
+</section></div>` });
+}
+
+/**
+ * The selected run, with its log tailing. The whole point of the sidebar: clicking a row fills this rather than
+ * navigating away to the entry page, which is a different view answering a different question.
+ */
+const detail = (base, r, ctxq) => `<h2>${esc(r.handle)}</h2>
+<dl class="facts">
+<dt>run</dt><dd><code>${esc(r.run)}</code></dd>
+<dt>${esc(r.entry ? "entry" : "source")}</dt><dd>${r.entry
+  ? `<a href="${esc(at(base, "/run", ctxq, { id: r.entry }))}">${esc(r.entry)}</a>`
+  : `<span class="tag">${esc(r.source || "")}</span>`}</dd>
+<dt>started</dt><dd>${esc(when(r.startedAt))}</dd>
+<dt>state</dt><dd>${r.running ? `<span class="tag live">running</span>` : r.exit === 0 ? `<span class="tag">exit 0</span>` : `<span class="tag bad">exit ${esc(String(r.exit ?? "not recorded"))}</span>`}${r.durationMs == null ? "" : ` <span class="dim">${esc(duration(r))}</span>`}</dd>
+</dl>
+${/* A foreign run's `harness` is its source label, which names no reader, so its lines render as themselves. That is
+      the right answer for them: command-center's own trees hold prose lines, which the renderer already reads. */ ""}
+${logPane(`data-entry="${esc(r.entry || "")}" data-source="${esc(r.source || "")}" data-run="${esc(r.run)}" data-harness="${esc(r.entry ? r.harness || "" : "")}"`)}`;
+
+/** Runs group by state (running, failed, done) or by harness, the same two choices the entries view offers. */
+function runGroups(base, rows, by, entry, ctxq, open = null) {
+  // A row opens the run here rather than navigating to the entry page: the sidebar and the pane beside it are one
+  // view. Every run can be opened this way, including one from another tool, which has no entry page to go to.
+  const row = r => ({
+    href: at(base, "/runs", ctxq, { open: r.run, source: r.entry ? "" : r.source }),
+    current: open ? open.run === r.run && (open.source || "") === (r.source || "") : false,
+    label: r.handle,
+    badge: r.running ? "running" : duration(r) || `exit ${r.exit ?? "?"}`,
+    tone: r.running ? "running" : r.exit === 0 ? "" : "failed",
+    title: `${r.handle} ${r.run}`,
+    hay: [r.entry, r.run, r.name, when(r.startedAt), r.harness, r.source].filter(Boolean).join(" "),
+  });
+  if (by === "harness") {
+    const names = [...new Set(rows.map(r => r.harness || "unknown"))].sort();
+    return names.map(h => ({ key: `harness:${h}`, label: h, rows: rows.filter(r => (r.harness || "unknown") === h).map(row) }));
+  }
+  const bucket = r => (r.running ? "running" : r.exit === 0 ? "done" : "failed");
+  return [["running", "running"], ["failed", "failed"], ["done", "done"]]
+    .map(([key, label]) => ({ key: `runs:${key}`, label, rows: rows.filter(r => bucket(r) === key).map(row) }))
+    .filter(g => g.rows.length);
+}
+
+const when = ms => (ms ? new Date(ms).toISOString().replace("T", " ").slice(0, 19) : "unknown");
+
+const duration = r => {
+  if (r.running) return "running";
+  if (r.durationMs == null) return "";
+  const s = Math.round(r.durationMs / 1000);
+  return s < 60 ? `${s}s` : s < 3600 ? `${Math.floor(s / 60)}m ${s % 60}s` : `${Math.floor(s / 3600)}h ${Math.round((s % 3600) / 60)}m`;
+};

package/lib/tracker/runs.mjs

@@ -0,0 +1,102 @@
+// Every run on disk, newest first. The history is already there: `~/.gallivant/runs/<entry slug>/<run id>/` holds
+// job.json and job.log for each dispatch the daemon ever made, and nothing deletes them. This module is the index
+// over that tree, plus the id validation every route goes through before it touches a path.
+//
+// Two shapes of tree, one reader. Gallivant nests runs under the entry that dispatched them, because one run per
+// entry is its lock. Command-center keeps them flat in `<project>/.content-pipeline/runs/`, because a run there
+// belongs to a project rather than to a row. The folder inside is identical either way (job.json, job.log, the same
+// field names), which is what `lib/run.mjs` was adapted from, so `readJob` and the row shape are shared and only
+// the walk differs.
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { idSlug, handleFor } from "../state.mjs";
+
+/** Run ids are stamp-plus-slug, the same character class `run.mjs`'s `dirOf` enforces. Anything else is not an id. */
+export const validRunId = id => typeof id === "string" && /^[A-Za-z0-9_-]+$/.test(id);
+
+/**
+ * Resolve `<entry id>/<run id>` to a directory, or null.
+ *
+ * Two separate checks, because the two ids have different shapes. A run id is validated by pattern. An entry id
+ * contains slashes, so a pattern is the wrong tool: it is checked against the registry instead, and only the slug
+ * of an id that is actually registered is ever joined to a path. A query string can therefore name no directory
+ * that the registry does not already name, whatever it contains.
+ */
+export function runDir(home, entries, entryId, runId) {
+  if (!validRunId(runId)) return null;
+  if (!entries.some(([id]) => id === entryId)) return null;
+  return join(home, "runs", idSlug(entryId), runId);
+}
+
+/**
+ * Resolve `<source label>/<run id>` to a directory in one of the configured flat trees, or null.
+ *
+ * The same two-part rule as `runDir`, for a tree that has no registry: the run id is validated by pattern, and the
+ * source is matched against the configured list rather than trusted, so only a directory the operator already named
+ * in config is ever joined to a path. A query string cannot reach a tree nobody configured.
+ */
+export function sourceRunDir(sources = [], label, runId) {
+  if (!validRunId(runId)) return null;
+  const source = sources.find(s => s.label === label);
+  return source ? join(source.dir, runId) : null;
+}
+
+const readJob = dir => { try { return JSON.parse(readFileSync(join(dir, "job.json"), "utf8")); } catch { return null; } };
+const ls = dir => { try { return readdirSync(dir, { withFileTypes: true }).filter(d => d.isDirectory()).map(d => d.name); } catch { return []; } };
+
+/** One run folder as a row. The same shape whichever tree it came from, so one table renders both. */
+const rowOf = (job, runId, { entry, handle, harness, running }) => ({
+  entry, handle, run: job.id || runId, name: job.name || "", harness,
+  startedAt: job.startedAt ?? null, endedAt: job.endedAt ?? null,
+  // A killed or crashed run whose exit was never recorded is not a success; it is unknown until something settles
+  // it, and saying so beats printing "0".
+  exit: running ? null : job.exit ?? null, running,
+  // A run still going has no duration yet; one whose end was never recorded has none either, and a made-up number
+  // would read as fact.
+  durationMs: job.startedAt && job.endedAt ? job.endedAt - job.startedAt : null,
+});
+
+/** Newest first. Run ids start with an ISO stamp, so the id is the tiebreak when startedAt is missing. */
+const newestFirst = (a, b) => (b.startedAt ?? 0) - (a.startedAt ?? 0) || b.run.localeCompare(a.run);
+
+/**
+ * A flat tree of run folders, as command-center writes under `<project>/.content-pipeline/runs/`. Same folder
+ * contents, no entry to key them by, so the source's name stands in for one and the rows are read-only: there is no
+ * registry here to validate an id against, so nothing addresses these by id and they are listed, not opened.
+ */
+export function listFlatRuns(dir, { source = "runs", isRunning = () => false, limit = 200 } = {}) {
+  const rows = [];
+  for (const runId of ls(dir)) {
+    const job = readJob(join(dir, runId));
+    if (!job) continue;
+    const running = job.exit === null && isRunning(job);
+    rows.push({ ...rowOf(job, runId, { entry: null, handle: job.name || runId, harness: source, running }), source });
+  }
+  return rows.sort(newestFirst).slice(0, limit);
+}
+
+/**
+ * Every run, newest first, with the entry it belongs to. The registry is the list of entries, so a run folder left
+ * behind by an entry that was removed is skipped rather than shown with no context: `runDir` would refuse to serve
+ * it anyway, and a row nothing can open is worse than no row.
+ *
+ * `isRunning` is the runner's liveness check, so a run whose daemon died is listed as ended rather than as live.
+ */
+export function listRuns(home, entries, { isRunning = () => false, entry: only = null, limit = 200 } = {}) {
+  const rows = [];
+  for (const [id, e] of entries) {
+    if (only && id !== only) continue;
+    const root = join(home, "runs", idSlug(id));
+    for (const runId of ls(root)) {
+      const job = readJob(join(root, runId));
+      if (!job) continue;
+      // The harness is the entry's, not the run's: job.json records the binary it spawned, and the registry is what
+      // says which adapter that was. A grouping by harness needs the name, not the path.
+      rows.push(rowOf(job, runId, { entry: id, handle: handleOf(id, e), harness: e?.harness || "unknown", running: job.exit === null && isRunning(job) }));
+    }
+  }
+  return rows.sort(newestFirst).slice(0, limit);
+}
+
+// The canonical handle, from state.mjs. An entry the index has no registry row for is `id` on its own.
+const handleOf = (id, e) => (e ? handleFor(id, e) : id);

package/lib/tracker/stream.mjs

@@ -0,0 +1,74 @@
+// SSE and history share the bounded public projection reader. Only the
+// coordinator reconciles providers; these routes read files and clean up on close.
+import { readFileSync, watch } from "node:fs";
+import { join } from "node:path";
+import { logWindow, LOG_LIMITS } from "../run_log.mjs";
+export const TAIL = LOG_LIMITS.lines;
+const jobOf = dir => { try { return JSON.parse(readFileSync(join(dir, "job.json"), "utf8")); } catch { return null; } };
+export function sliceRun(dir, { end = null, count = TAIL, meter } = {}) {
+  const tail = end === null ? logWindow(dir, { meter }) : null;
+  return logWindow(dir, { before: end === null ? tail.from : end, count, meter });
+}
+export function streamRun(res, dir, { isRunning, req = res.req, pollMs = 1000, beatMs = 20_000, meter } = {}) {
+  res.setTimeout?.(0);
+  req?.setTimeout?.(0); req?.socket?.setTimeout?.(0);
+  res.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-cache", connection: "keep-alive", "x-accel-buffering": "no" });
+  if (!jobOf(dir)) { res.write(`data: ${JSON.stringify("[no run]")}\n\n`); return res.end(); }
+  const initial = logWindow(dir, { meter });
+  const resume = Number(req?.headers?.["last-event-id"]);
+  const resuming = Number.isSafeInteger(resume) && resume >= 0;
+  let sent = resuming ? resume : Math.max(0, initial.from - 1);
+  let generation = initial.generation, blocked = false, closing = false, pending = [], buffered = 0;
+  let watcher, timer, beat;
+  const stop = () => {
+    closing = true; clearInterval(timer); clearInterval(beat); watcher?.close();
+    res.off?.("drain", drain); res.off?.("close", stop); res.off?.("error", stop);
+    pending = []; buffered = 0;
+  };
+  const write = frame => {
+    if (blocked) return false;
+    if (res.write(frame) === false) blocked = true;
+    return true;
+  };
+  const enqueue = frame => { pending.push(frame); buffered += Buffer.byteLength(frame); };
+  if (!resuming && sent > 0) enqueue(`event: skipped\ndata: ${sent}\n\n`);
+  if (initial.gap) enqueue(`event: gap\ndata: ${JSON.stringify(initial.gap)}\n\n`);
+  const drain = () => { if (closing) return; blocked = false; tick(); };
+  const flush = () => {
+    while (pending.length && !blocked) {
+      const frame = pending.shift(); buffered -= Buffer.byteLength(frame);
+      write(frame);
+    }
+  };
+  const tick = () => {
+    if (closing || blocked) return;
+    flush(); if (blocked) return;
+    const window = logWindow(dir, { after: sent, meter });
+    if (generation !== window.generation || (sent > window.total && !window.byteMode)) {
+      // Never renumber IDs after retention or rotate a reconnect to a new file.
+      write(`event: gap\ndata: ${JSON.stringify("log rotated; history unavailable after the recorded cursor")}\n\n`);
+      stop(); res.end(); return;
+    }
+    generation = window.generation;
+    if (window.gap && window.from > sent + 1) enqueue(`event: gap\ndata: ${JSON.stringify(window.gap)}\n\n`);
+    for (let i = 0; i < window.lines.length; i++) {
+      const frame = `id: ${window.ids[i]}\ndata: ${JSON.stringify(window.lines[i])}\n\n`;
+      if (buffered + Buffer.byteLength(frame) > LOG_LIMITS.bufferedBytes) break;
+      enqueue(frame); sent = window.ids[i];
+    }
+    flush();
+    if (blocked || pending.length || sent < window.total && window.lines.length) return;
+    const job = jobOf(dir);
+    if (!isRunning(job)) {
+      const message = job?.exit == null ? "[ended, waiting for the next tick to record the exit]" : `[exit ${job.exit}]`;
+      write(`data: ${JSON.stringify(message)}\n\n`);
+      if (!blocked) { stop(); res.end(); }
+    }
+  };
+  res.on("close", stop); res.on?.("error", stop); res.on?.("drain", drain);
+  timer = setInterval(tick, pollMs);
+  beat = setInterval(() => { if (!closing && !blocked && !pending.length) write(": keepalive\n\n"); }, beatMs);
+  try { watcher = watch(join(dir, "job.log"), { persistent: false }, tick); } catch { /* timer is the recovery path */ }
+  tick();
+  return { close: stop, bufferedBytes: () => buffered, blocked: () => blocked };
+}