omp-conductor 0.18.2 → 0.19.0

package/src/dashboard/server.ts

@@ -32,9 +32,32 @@ import { classifyDaemonProjectHealth, fleetLayers } from "../fleet.ts";
 import type { FleetLayers } from "../status-render.ts";
 import { statusSnapshot, type StatusSnapshot } from "../daemon.ts";
 import { boardJson, boardSnapshotOnce } from "../board.ts";
+import { computeStats, parseStatsWindow, type StatsReport } from "../stats.ts";
 import { dbPath, openStore } from "../store.ts";
 import type { ProjectConfig } from "../types.ts";
-import type { BaseHealth, DigestBacklog, HeldNotice, ReportRecord, RunRecord, TurnOverride, VerbLedgerEntry } from "../types.ts";
+import {
+  dashboardAnswerDecision,
+  dashboardDisarm,
+  dashboardExtend,
+  dashboardHold,
+  dashboardPause,
+  dashboardResume,
+  dashboardUnblock,
+  dashboardWorkerControl,
+  type ControlDeps,
+  type ControlOutcome,
+} from "./controls.ts";
+import { transcriptStreamResponse } from "./transcript.ts";
+import type {
+  BaseHealth,
+  DecisionRecord,
+  DigestBacklog,
+  HeldNotice,
+  ReportRecord,
+  RunRecord,
+  TurnOverride,
+  VerbLedgerEntry,
+} from "../types.ts";
 
 /** The dashboard's default bind address — loopback, like the daemon port. */
 export const DASHBOARD_HOST = "127.0.0.1";
@@ -259,13 +282,22 @@ async function ledgerProducer(
  *  open reports, the digest backlog, and the held notices awaiting a digest. */
 async function reportsProducer(
   name: string,
-): Promise<{ openReports: ReportRecord[]; digestBacklog: DigestBacklog; heldNotices: HeldNotice[] }> {
+): Promise<{
+  openReports: ReportRecord[];
+  digestBacklog: DigestBacklog;
+  heldNotices: HeldNotice[];
+  openDecisions: DecisionRecord[];
+}> {
   const store = openStore(dbPath());
   try {
     return {
       openReports: store.openReports(name),
       digestBacklog: store.digestBacklog(name),
       heldNotices: store.undigestedNotices(name),
+      // The questions waiting on an operator. Carried here so the answer verb
+      // #295 added has something to answer: an endpoint with no surface that
+      // lists what it can act on is an endpoint nobody uses.
+      openDecisions: store.openDecisions(name),
     };
   } finally {
     store.close();
@@ -274,6 +306,37 @@ async function reportsProducer(
 
 /** `/api/projects/:name/runs/:issue` — every run row for the issue: attempts,
  *  states, spend, failure classes, PR URLs. */
+/**
+ * The analytics payload (#297): byte-for-byte what `stats --json` prints.
+ *
+ * One aggregation, two consumers — `computeStats` and `parseStatsWindow` are the
+ * same functions the CLI runs, fed by the same read-only store queries. That is
+ * the whole of the slice's first acceptance criterion ("numbers on the page equal
+ * `stats --json` for the same window"): it holds because there is nothing else
+ * here that could compute a different number.
+ *
+ * Store-only by construction, which is the second criterion: `statsRuns` and
+ * `ghCallsBetween` are local reads, and no GitHub client exists in this module.
+ */
+async function statsProducer(name: string, since: string): Promise<StatsReport | undefined> {
+  const window = parseStatsWindow(since, Date.now());
+  // An unparseable window is the caller's error, and the caller turns this into
+  // a 400. Defaulting it would measure a different week and say nothing — the
+  // exact failure the shared parser exists to prevent.
+  if (window === undefined) return undefined;
+  const store = openStore(dbPath());
+  try {
+    return computeStats({
+      project: name,
+      window,
+      ghCalls: store.ghCallsBetween(window.sinceDay, window.untilDay),
+      runs: store.statsRuns(name, window.sinceEpochMs),
+    });
+  } finally {
+    store.close();
+  }
+}
+
 async function runsProducer(name: string, issue: number): Promise<{ runs: RunRecord[] }> {
   const store = openStore(dbPath());
   try {
@@ -302,8 +365,27 @@ export interface DashboardHttpDeps {
   ): Promise<{ verb: VerbLedgerEntry[]; turnOverrides: TurnOverride[] }>;
   reports(
     name: string,
-  ): Promise<{ openReports: ReportRecord[]; digestBacklog: DigestBacklog; heldNotices: HeldNotice[] }>;
+  ): Promise<{
+    openReports: ReportRecord[];
+    digestBacklog: DigestBacklog;
+    heldNotices: HeldNotice[];
+    openDecisions: DecisionRecord[];
+  }>;
   runs(name: string, issue: number): Promise<{ runs: RunRecord[] }>;
+  /** The analytics payload (#297); `undefined` for an unparseable window. */
+  stats(name: string, since: string): Promise<StatsReport | undefined>;
+  /**
+   * The live transcript stream (#296). Returns the SSE response itself rather
+   * than data, because the whole point is a connection that stays open — a
+   * producer returning a value would have to buffer the run to completion first.
+   */
+  transcript?: (name: string, issue: number, req: Request) => Response;
+  /**
+   * The mutating half (#295). Held as one injected object rather than eight
+   * function fields so a test overrides exactly the action it drives, and so the
+   * read surface above stays visibly read-only.
+   */
+  controls?: Partial<ControlDeps>;
 }
 
 /** The deps bound to the real producers — what `startDashboard` serves with. */
@@ -317,6 +399,7 @@ export function defaultDashboardDeps(token: string): DashboardHttpDeps {
     ledger: ledgerProducer,
     reports: reportsProducer,
     runs: runsProducer,
+    stats: statsProducer,
   };
 }
 
@@ -341,6 +424,32 @@ function bearerToken(req: Request): string | undefined {
   return header.startsWith(prefix) ? header.slice(prefix.length).trim() : undefined;
 }
 
+/**
+ * The token from `?token=`, accepted on the SSE stream path and nowhere else
+ * (#296).
+ *
+ * `EventSource` is the browser API for Server-Sent Events and it cannot set an
+ * `Authorization` header — that is a documented limitation of the API, not
+ * something the UI is choosing. The two honest alternatives are a cookie or a
+ * query parameter, and a cookie is strictly worse here: it would ride on every
+ * request including the unauthenticated static ones, and it would need SameSite
+ * and expiry policy this product has no other use for.
+ *
+ * So the exposure is accepted, narrowed, and stated: a URL can reach a server
+ * log or a browser history entry, and this endpoint is the only place that can
+ * happen. It is scoped to the exact stream path so no other route can ever be
+ * reached with a URL-borne credential, and the dashboard binds loopback by
+ * default — the `--host` opt-in already carries its own warning about the token
+ * being the only thing between the network and the fleet.
+ */
+function streamQueryToken(url: URL): string | undefined {
+  if (!/^\/api\/projects\/[^/]+\/runs\/\d+\/transcript\/stream$/.test(url.pathname)) {
+    return undefined;
+  }
+  const token = url.searchParams.get("token");
+  return token === null || token === "" ? undefined : token;
+}
+
 /**
  * The ledger's query params. `limit` defaults to 50 — the CLI's own default —
  * so the endpoint and `omp-conductor ledger` cannot disagree. An explicit
@@ -361,6 +470,109 @@ function parseLedgerParams(url: URL): { issue?: number; limit: number } | null {
   return { ...(issue === undefined ? {} : { issue }), limit };
 }
 
+/**
+ * The configured project a `/api/projects/:name/...` path names, or undefined.
+ *
+ * One resolver for reads and mutations both: an unknown name is a 404 rather
+ * than a producer's throw, and — the part that matters for #295 — an action can
+ * never be applied to a project this host does not configure.
+ */
+function projectFromPath(path: string): ProjectConfig | undefined {
+  const match = /^\/api\/projects\/([^/]+)(?:\/|$)/.exec(path);
+  if (match === null) return undefined;
+  let name: string;
+  try {
+    name = decodeURIComponent(match[1]!);
+  } catch {
+    return undefined;
+  }
+  return loadConfig().projects.find((p) => p.name === name);
+}
+
+/**
+ * The JSON body of a mutating request, or the 400 that says why not.
+ *
+ * An absent body is `{}` rather than an error: `resume` and `disarm` take no
+ * arguments, and requiring an empty object from them would be ceremony. A body
+ * that is present and unparseable is always an error — that is a client bug, and
+ * treating it as "no arguments" is how a `stop` arrives with no reason.
+ */
+async function mutationBody(req: Request): Promise<unknown | { __malformed: true }> {
+  const raw = await req.text();
+  if (raw.trim() === "") return {};
+  try {
+    return JSON.parse(raw) as unknown;
+  } catch {
+    return { __malformed: true };
+  }
+}
+
+/**
+ * The mutating surface (#295). Every branch delegates to `controls.ts`, which
+ * delegates to the CLI's own code or the owning daemon's own endpoint — there is
+ * no fleet logic in this function, only routing.
+ */
+async function mutatingResponse(
+  req: Request,
+  path: string,
+  project: ProjectConfig,
+  d: DashboardHttpDeps,
+): Promise<Response> {
+  const body = await mutationBody(req);
+  if (body !== null && typeof body === "object" && Reflect.get(body, "__malformed") === true) {
+    return Response.json({ error: "request body must be valid JSON" }, { status: 400 });
+  }
+  const deps: ControlDeps = { project, ...d.controls };
+  const answer = async (): Promise<ControlOutcome | undefined> => {
+    const fleet = /^\/api\/projects\/[^/]+\/(pause|resume|hold|disarm)$/.exec(path);
+    if (fleet !== null) {
+      switch (fleet[1]) {
+        case "pause":
+          return dashboardPause(body, deps);
+        case "resume":
+          return dashboardResume(deps);
+        case "hold":
+          return dashboardHold(body, deps);
+        case "disarm":
+          return dashboardDisarm(deps);
+      }
+    }
+    const run = /^\/api\/projects\/[^/]+\/runs\/(\d+)\/(extend|unblock)$/.exec(path);
+    if (run !== null) {
+      const issue = Number.parseInt(run[1]!, 10);
+      if (!Number.isSafeInteger(issue)) return undefined;
+      return run[2] === "extend"
+        ? await dashboardExtend(issue, body, deps)
+        : await dashboardUnblock(issue, body, deps);
+    }
+    const worker = /^\/api\/projects\/[^/]+\/runs\/(\d+)\/worker\/(pause|resume|stop)$/.exec(path);
+    if (worker !== null) {
+      const issue = Number.parseInt(worker[1]!, 10);
+      if (!Number.isSafeInteger(issue)) return undefined;
+      return await dashboardWorkerControl(
+        issue,
+        worker[2] as "pause" | "resume" | "stop",
+        body,
+        deps,
+      );
+    }
+    const decision = /^\/api\/projects\/[^/]+\/decisions\/([^/]+)\/answer$/.exec(path);
+    if (decision !== null) {
+      let id: string;
+      try {
+        id = decodeURIComponent(decision[1]!);
+      } catch {
+        return undefined;
+      }
+      return dashboardAnswerDecision(id, body, deps);
+    }
+    return undefined;
+  };
+  const outcome = await answer();
+  if (outcome === undefined) return new Response("", { status: 404 });
+  return Response.json(outcome.body, { status: outcome.status });
+}
+
 /**
  * The dashboard's whole HTTP surface, separated from the socket exactly like
  * `daemonHttpResponse` so a test can drive it without binding a port. The UI
@@ -370,58 +582,79 @@ export async function dashboardResponse(req: Request, d: DashboardHttpDeps): Pro
   const url = new URL(req.url);
   const path = url.pathname;
   if (path.startsWith("/api/")) {
-    const presented = bearerToken(req);
+    const presented = bearerToken(req) ?? streamQueryToken(url);
     if (presented === undefined || !verifyDashboardToken(presented, d.token)) {
       // Bare 401: no body, no scheme hint — nothing about the token leaks.
       return new Response("", { status: 401 });
     }
-    // Read-only surface: every /api route is a GET. Everything else stays
-    // 404 (after the auth check, so the surface cannot be probed).
-    if (req.method !== "GET") return new Response("", { status: 404 });
+    // Two methods now (#295): GET reads, POST mutates. Anything else stays 404
+    // — after the auth check, so the surface cannot be probed unauthenticated.
+    if (req.method !== "GET" && req.method !== "POST") {
+      return new Response("", { status: 404 });
+    }
+
+    // The mutating routes first (#295), so a read route can never answer a POST.
+    // Reads are then explicitly GET-gated below: without that, `POST .../board`
+    // would have fallen through and returned the board, which is a mutating
+    // method quietly served by a read handler.
+    const project = projectFromPath(path);
+    if (req.method === "POST") {
+      if (project === undefined) return new Response("", { status: 404 });
+      return mutatingResponse(req, path, project, d);
+    }
 
     if (path === "/api/projects") return Response.json(await d.projects());
     if (path === "/api/overview") return Response.json(await d.overview());
 
-    // `/api/projects/:name/{board,status,ledger,reports}` and
-    // `/api/projects/:name/runs/:issue`. Project names are matched against the
-    // configured set so an unknown name is a 404, never the producer's throw.
-    const name = (m: RegExpExecArray): string | undefined => {
-      try {
-        return decodeURIComponent(m[1]!);
-      } catch {
-        return undefined;
-      }
-    };
-    const known = (project: string | undefined): project is string =>
-      project !== undefined && loadConfig().projects.some((p) => p.name === project);
-
-    const proj = /^\/api\/projects\/([^/]+)\/(board|status|ledger|reports)$/.exec(path);
+    const proj = /^\/api\/projects\/([^/]+)\/(board|status|ledger|reports|stats)$/.exec(path);
     if (proj !== null) {
-      const project = name(proj);
-      if (!known(project)) return new Response("", { status: 404 });
+      if (project === undefined) return new Response("", { status: 404 });
       switch (proj[2]) {
         case "board":
-          return Response.json(await d.board(project!));
+          return Response.json(await d.board(project.name));
         case "status":
-          return Response.json(await d.status(project!));
+          return Response.json(await d.status(project.name));
         case "ledger": {
           const opts = parseLedgerParams(url);
           if (opts === null) return new Response("", { status: 400 });
-          return Response.json(await d.ledger(project!, opts));
+          return Response.json(await d.ledger(project.name, opts));
         }
         case "reports":
-          return Response.json(await d.reports(project!));
+          return Response.json(await d.reports(project.name));
+        case "stats": {
+          // `7d` is the CLI's own default, so an unqualified page and an
+          // unqualified `stats` describe the same window.
+          const report = await d.stats(project.name, url.searchParams.get("since") ?? "7d");
+          if (report === undefined) {
+            return Response.json(
+              { error: "since must be 7d, 30d, any Nd, or YYYY-MM-DD" },
+              { status: 400 },
+            );
+          }
+          return Response.json(report);
+        }
+      }
+    }
+
+    // The transcript stream (#296) is matched before the run-detail route so
+    // `/runs/42/transcript/stream` cannot be read as an issue named
+    // "42/transcript".
+    const stream = /^\/api\/projects\/([^/]+)\/runs\/(\d+)\/transcript\/stream$/.exec(path);
+    if (stream !== null) {
+      const issue = Number.parseInt(stream[2]!, 10);
+      if (project === undefined || !Number.isSafeInteger(issue)) {
+        return new Response("", { status: 404 });
       }
+      return (d.transcript ?? transcriptStreamResponse)(project.name, issue, req);
     }
 
     const runs = /^\/api\/projects\/([^/]+)\/runs\/(\d+)$/.exec(path);
     if (runs !== null) {
-      const project = name(runs);
       const issue = Number.parseInt(runs[2]!, 10);
-      if (!known(project) || !Number.isSafeInteger(issue)) {
+      if (project === undefined || !Number.isSafeInteger(issue)) {
         return new Response("", { status: 404 });
       }
-      return Response.json(await d.runs(project!, issue));
+      return Response.json(await d.runs(project.name, issue));
     }
 
     return new Response("", { status: 404 });
@@ -461,6 +694,14 @@ export async function startDashboard(opts: DashboardStartOpts = {}): Promise<voi
   const server = Bun.serve({
     hostname: host,
     port: opts.port ?? DASHBOARD_PORT,
+    // Long-lived by necessity (#296). `Bun.serve` defaults to a 10s idle
+    // timeout, which closes a transcript stream mid-run — a quiet worker is
+    // exactly the case where watching matters most, and no keepalive interval
+    // short enough to beat that default would be sane. Disabled here rather
+    // than tuned, because the streams are the only long connections this server
+    // has and each one already ends on its own: the follow returns when the run
+    // goes terminal, and the client vanishing aborts it.
+    idleTimeout: 0,
     fetch: (req) => dashboardResponse(req, defaultDashboardDeps(token)),
   });
   // An IPv6 literal needs brackets to be a clickable URL.

package/src/dashboard/style.css

@@ -346,3 +346,119 @@ ul.reports li {
     --down: #ff8a80;
   }
 }
+
+/* The control surface (#295). Destructive actions are visually distinct because
+   the confirm dialog is the second line of defence, not the first. */
+.controls {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.5rem;
+  align-items: center;
+  margin: 0.75rem 0;
+}
+
+.controls button {
+  background: #1b1f27;
+  color: #d7dae0;
+  border: 1px solid #2f3542;
+  border-radius: 4px;
+  padding: 0.35rem 0.7rem;
+  font: inherit;
+  cursor: pointer;
+}
+
+.controls button:hover {
+  border-color: #4a5568;
+}
+
+.controls button.destructive {
+  border-color: #6b2f2f;
+  color: #e8b4b4;
+}
+
+.controls button.destructive:hover {
+  background: #2a1b1b;
+}
+
+.controls #control-result,
+.controls > p.state {
+  flex-basis: 100%;
+  margin: 0.25rem 0 0;
+}
+
+/* Live transcript (#296). Fixed height with its own scroll so a long run does
+   not push the run controls off the page. */
+.transcript-head {
+  display: flex;
+  gap: 0.75rem;
+  align-items: center;
+  flex-wrap: wrap;
+  margin: 0.75rem 0 0.25rem;
+}
+
+.transcript-head label {
+  font-size: 0.85rem;
+  color: #9aa0aa;
+}
+
+.transcript {
+  max-height: 26rem;
+  overflow-y: auto;
+  margin: 0;
+  padding: 0.6rem 0.75rem;
+  background: #0f1115;
+  border: 1px solid #2f3542;
+  border-radius: 4px;
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 0.8rem;
+  line-height: 1.45;
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+
+/* Analytics (#297). Hand-rolled SVG, per the epic's no-dependency constraint. */
+.chart {
+  margin: 1rem 0;
+}
+
+.chart h4 {
+  margin: 0 0 0.4rem;
+  font-size: 0.9rem;
+  font-weight: 600;
+  color: #c8ccd4;
+}
+
+.chart .bars {
+  width: 100%;
+  max-width: 40rem;
+  height: auto;
+}
+
+.chart .bar {
+  fill: #3d6ea8;
+}
+
+.chart .bar-label,
+.chart .bar-value {
+  fill: #9aa0aa;
+  font-size: 11px;
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+}
+
+.stat {
+  display: flex;
+  justify-content: space-between;
+  gap: 1rem;
+  padding: 0.2rem 0;
+  border-bottom: 1px solid #1e222a;
+  font-size: 0.85rem;
+}
+
+.stat-label {
+  color: #9aa0aa;
+}
+
+.stat-value {
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  color: #d7dae0;
+}

package/src/dashboard/transcript.ts

@@ -0,0 +1,173 @@
+/**
+ * Live transcript streaming for the dashboard (epic #292, slice 4/5 — #296).
+ *
+ * The run detail view could show what a run *did*; this makes it possible to
+ * watch one happening, which is the difference between reading a postmortem and
+ * noticing a worker is stuck at turn eight.
+ *
+ * ## It follows the file, not the daemon
+ *
+ * `tailRun` is the follow — the same function `omp-conductor tail` runs, with
+ * the same 1s re-stat cadence, the same read-from-byte-zero behaviour (attaching
+ * to a run ten turns in and showing nothing until turn eleven is not watching
+ * it), and the same advisor-transcript discovery. This module only turns its
+ * lines into Server-Sent Events.
+ *
+ * That is what makes the acceptance criterion "neither blocks the daemon" true by
+ * construction rather than by measurement: nothing here talks to the daemon at
+ * all. Two browsers on one run are two read-only file follows, and the daemon
+ * does not know either of them exists.
+ *
+ * ## Why SSE and not a websocket
+ *
+ * The data is one-directional, text, and append-only, which is exactly what SSE
+ * is. A websocket would add a handshake, a framing layer and a dependency for a
+ * feature whose whole payload is lines of text — and the epic's constraint is no
+ * runtime dependencies. `EventSource` is in every browser and reconnects on its
+ * own.
+ */
+
+import { tailRun } from "../commands/tail.ts";
+import type { Store } from "../types.ts";
+
+/** How often a comment frame is written when nothing else is. */
+export const KEEPALIVE_MS = 15_000;
+
+/** Injected so a test drives the whole stream with no file and no clock. */
+export interface TranscriptStreamDeps {
+  /**
+   * The follow itself. Defaults to `tailRun`, and a test replaces it — the point
+   * of the seam is that this module owns the *framing*, not the following.
+   */
+  follow?: (
+    project: string,
+    issue: number,
+    opts: { write: (line: string) => void; signal: AbortSignal; store?: Store },
+  ) => Promise<void>;
+  /**
+   * A store for the follow to read the run row through. Optional, and NOT closed
+   * here: `tailRun` closes whatever store it is given, so opening one in this
+   * module would double-close it. Production passes none and the follow opens
+   * (and closes) its own, exactly as `omp-conductor tail` does.
+   */
+  store?: Store;
+  keepaliveMs?: number;
+}
+
+/**
+ * One SSE frame.
+ *
+ * Exported because the framing is the contract a browser parses, and a test that
+ * asserts on assembled frames is asserting on the thing `EventSource` sees. Data
+ * is split per line so a payload containing a newline cannot terminate the frame
+ * early — the one way a text stream corrupts an SSE connection.
+ */
+export function sseFrame(event: string | undefined, data: string): string {
+  const lines = data.split("\n").map((line) => `data: ${line}`);
+  return `${event === undefined ? "" : `event: ${event}\n`}${lines.join("\n")}\n\n`;
+}
+
+/**
+ * Stream one run's transcript as Server-Sent Events.
+ *
+ * Three terminal shapes, and each is said out loud rather than inferred from a
+ * closed connection:
+ *
+ *  - **`error`** — there is no transcript to follow (no run, or a claimed run
+ *    whose session never opened one). `tail` throws in exactly that case, and
+ *    the message is its message. A silent empty stream would read as "a quiet
+ *    worker", which is the wrong conclusion to invite.
+ *  - **`end`** — the follow returned, which `tailRun` does once the run row has
+ *    left the live states and stayed quiet. Its last written line is
+ *    `run ended: <state>`, so the terminal state is already in the stream.
+ *  - **the client vanishing** — the request's signal aborts the follow, which is
+ *    why `tailRun` takes one: a closed tab must not leave a poll loop holding
+ *    file descriptors until the run happens to finish.
+ */
+export function transcriptStreamResponse(
+  project: string,
+  issue: number,
+  req: Request,
+  deps: TranscriptStreamDeps = {},
+): Response {
+  const follow = deps.follow ?? defaultFollow;
+  const keepaliveMs = deps.keepaliveMs ?? KEEPALIVE_MS;
+  const controller = new AbortController();
+  // Both directions matter: the client going away aborts the follow, and the
+  // follow finishing means nobody is waiting on the client any more.
+  req.signal.addEventListener("abort", () => controller.abort(), { once: true });
+
+  const encoder = new TextEncoder();
+  const body = new ReadableStream<Uint8Array>({
+    start(sink) {
+      let closed = false;
+      const send = (frame: string): void => {
+        if (closed) return;
+        try {
+          sink.enqueue(encoder.encode(frame));
+        } catch {
+          // The client hung up between our abort check and this write. Stop
+          // following rather than throwing inside a stream nobody reads.
+          closed = true;
+          controller.abort();
+        }
+      };
+      // A comment frame — `EventSource` ignores it, proxies and load balancers
+      // do not, which is the whole reason it exists.
+      const keepalive = setInterval(() => send(": keepalive\n\n"), keepaliveMs);
+      const finish = (): void => {
+        if (closed) return;
+        closed = true;
+        clearInterval(keepalive);
+        try {
+          sink.close();
+        } catch {
+          // Already closed by the client; nothing to do.
+        }
+      };
+
+      void (async () => {
+        try {
+          await follow(project, issue, {
+            write: (line) => send(sseFrame(undefined, line)),
+            signal: controller.signal,
+            ...(deps.store === undefined ? {} : { store: deps.store }),
+          });
+          if (!controller.signal.aborted) send(sseFrame("end", "stream closed"));
+        } catch (err) {
+          // `tail`'s own wording: "no run recorded for #N", or
+          // "no transcript yet (state: claimed)". Both are answers, not faults.
+          send(sseFrame("error", err instanceof Error ? err.message : String(err)));
+        } finally {
+          finish();
+        }
+      })();
+    },
+    cancel() {
+      controller.abort();
+    },
+  });
+
+  return new Response(body, {
+    headers: {
+      "content-type": "text/event-stream; charset=utf-8",
+      // No buffering anywhere in between, or the 1s cadence becomes minutes.
+      "cache-control": "no-cache, no-transform",
+      connection: "keep-alive",
+      "x-accel-buffering": "no",
+    },
+  });
+}
+
+/** `tailRun` with the stream's store, so one connection opens one reader. */
+async function defaultFollow(
+  project: string,
+  issue: number,
+  opts: { write: (line: string) => void; signal: AbortSignal; store?: Store },
+): Promise<void> {
+  await tailRun(project, issue, {
+    write: opts.write,
+    signal: opts.signal,
+    ...(opts.store === undefined ? {} : { store: opts.store }),
+  });
+}