@nanobpm/nano-workforce 0.69.1 → 0.70.0

package/operations/listAgenticTranscripts.test.ts

@@ -0,0 +1,169 @@
+// Tests for GET /app/api/agentic/transcripts → operation `listAgenticTranscripts` (H3 read path, #222).
+//
+// Covers: the empty list when no relay/transcript family is mounted; the shared-secret guard; the
+// end-to-end projection of a mounted TranscriptStore's rows into the list (byteLength, chunkCount,
+// lifecycle/status, jobKey decoded from the stream id); correlation enrichment (process instance /
+// plan) when the H6 correlation family is mounted; and the jobKey / plan / time filters.
+import { DatabaseSync } from "node:sqlite";
+import { test } from "node:test";
+import type { ConnectionRegistry } from "@nanobpm/agentic/channel";
+import type { Frame } from "@nanobpm/agentic/protocol";
+import type { SqliteDb } from "@nanobpm/agentic/transcript";
+import type { AppApi, DataLayer } from "@nanobpm/urban";
+import { assert, assertEquals } from "#test-assert";
+import { currentCorrelation } from "../app/agentic/correlation.ts";
+import { family as correlationFamily } from "../app/agentic/families/correlation.family.ts";
+import { createRelayFamily, currentRelayTranscriptService } from "../app/agentic/families/relay.family.ts";
+import type { AgenticContext } from "../app/agentic/registry.ts";
+import { noopLog } from "../test/log.ts";
+import handler from "./listAgenticTranscripts.ts";
+
+function memSqlite(): SqliteDb {
+  const db = new DatabaseSync(":memory:");
+  return {
+    exec: (sql) => db.exec(sql),
+    run: (sql, params = []) => {
+      const r = db.prepare(sql).run(...(params as never[]));
+      return { changes: Number(r.changes), lastInsertRowid: Number(r.lastInsertRowid) };
+    },
+    all: <T = Record<string, unknown>>(sql: string, params: unknown[] = []) =>
+      db.prepare(sql).all(...(params as never[])) as T[],
+  };
+}
+
+function memData(db: SqliteDb): DataLayer {
+  return { source: () => ({ db }) } as unknown as DataLayer;
+}
+
+/** A hub double that just captures the relay family handler (unused here — we seed the store directly). */
+function fakeHub() {
+  return {
+    registerFamilyHandler(_family: string, _handler: (frame: Frame, conn: never) => void) {},
+    registry: { has: () => false, list: () => [] },
+  };
+}
+
+function mountCtx(db: SqliteDb): AgenticContext {
+  const hub = fakeHub();
+  return {
+    hub: hub as never,
+    registry: hub.registry as unknown as ConnectionRegistry,
+    transport: undefined as never,
+    data: memData(db),
+    log: noopLog(),
+  };
+}
+
+function input(query: Record<string, unknown> = {}, headers: Record<string, string> = {}) {
+  return {
+    req: { method: "GET", path: "/app/api/agentic/transcripts", query: new URLSearchParams(), headers: new Headers(headers), text: async () => "" } as never,
+    params: {},
+    query,
+    body: undefined,
+  };
+}
+
+const app = { log: noopLog() } as unknown as AppApi;
+const relayFamily = createRelayFamily();
+
+test("returns an empty list when no relay/transcript family is mounted", async () => {
+  relayFamily.teardown?.();
+  const res = (await handler(input(), app)) as { status: number; body: { count: number; transcripts: unknown[] } };
+  assertEquals(res.status, 200);
+  assertEquals(res.body.count, 0);
+  assertEquals(res.body.transcripts.length, 0);
+});
+
+test("projects the TranscriptStore rows into the list (byteLength, chunkCount, lifecycle, jobKey)", async () => {
+  relayFamily.mount(mountCtx(memSqlite()));
+  const store = currentRelayTranscriptService()?.store;
+  assert(store !== undefined, "the relay family installs a persisted store");
+  // Seed one completed ephemeral session on a jobKey-scoped stream.
+  store.flush("job:6494", { since: () => ({ entries: [{ offset: 0, chunk: "hello " }, { offset: 1, chunk: "world" }] }), nextOffset: 2 }, "ephemeral");
+  try {
+    const res = (await handler(input(), app)) as {
+      status: number;
+      body: { count: number; retentionMs?: number; transcripts: Array<Record<string, unknown>> };
+    };
+    assertEquals(res.status, 200);
+    assertEquals(res.body.count, 1);
+    assert(typeof res.body.retentionMs === "number", "the list surfaces the retention window");
+    const t = res.body.transcripts[0];
+    assertEquals(t.stream, "job:6494");
+    assertEquals(t.jobKey, "6494", "the jobKey is decoded from the job: stream id");
+    assertEquals(t.lifecycle, "ephemeral");
+    assertEquals(t.status, "completed");
+    assertEquals(t.chunkCount, 2);
+    assertEquals(t.byteLength, "hello world".length);
+    assertEquals(t.nextOffset, 2);
+  } finally {
+    relayFamily.teardown?.();
+  }
+});
+
+test("enriches with the H6 correlation (process instance / plan) when it is still live", async () => {
+  relayFamily.mount(mountCtx(memSqlite()));
+  const store = currentRelayTranscriptService()?.store;
+  assert(store !== undefined);
+  store.flush("job:6494", { since: () => ({ entries: [{ offset: 0, chunk: "x" }] }), nextOffset: 1 }, "ephemeral");
+  correlationFamily.mount({ hub: undefined as never, registry: undefined as never, transport: undefined as never, data: undefined, log: noopLog() });
+  currentCorrelation()?.link("wk-a", "6494", { processInstanceKey: "4612", bpmnProcessId: "plan-fanout", planKey: "o/r#142" });
+  try {
+    const res = (await handler(input(), app)) as { body: { transcripts: Array<Record<string, unknown>> } };
+    const t = res.body.transcripts[0];
+    assertEquals(t.processInstanceKey, "4612");
+    assertEquals(t.bpmnProcessId, "plan-fanout");
+    assertEquals(t.planKey, "o/r#142");
+  } finally {
+    correlationFamily.teardown?.();
+    relayFamily.teardown?.();
+  }
+});
+
+test("filters by jobKey and plan", async () => {
+  relayFamily.mount(mountCtx(memSqlite()));
+  const store = currentRelayTranscriptService()?.store;
+  assert(store !== undefined);
+  store.flush("job:1", { since: () => ({ entries: [{ offset: 0, chunk: "a" }] }), nextOffset: 1 }, "ephemeral");
+  store.flush("job:2", { since: () => ({ entries: [{ offset: 0, chunk: "b" }] }), nextOffset: 1 }, "ephemeral");
+  correlationFamily.mount({ hub: undefined as never, registry: undefined as never, transport: undefined as never, data: undefined, log: noopLog() });
+  currentCorrelation()?.link("wk", "2", { planKey: "o/r#9" });
+  try {
+    const byJob = (await handler(input({ jobKey: "1" }), app)) as { body: { count: number; transcripts: Array<Record<string, unknown>> } };
+    assertEquals(byJob.body.count, 1);
+    assertEquals(byJob.body.transcripts[0]?.stream, "job:1");
+
+    const byPlan = (await handler(input({ planKey: "o/r#9" }), app)) as { body: { count: number; transcripts: Array<Record<string, unknown>> } };
+    assertEquals(byPlan.body.count, 1);
+    assertEquals(byPlan.body.transcripts[0]?.stream, "job:2");
+  } finally {
+    correlationFamily.teardown?.();
+    relayFamily.teardown?.();
+  }
+});
+
+test("rejects a malformed since/until with a 400", async () => {
+  relayFamily.mount(mountCtx(memSqlite()));
+  try {
+    const res = (await handler(input({ since: "not-a-date" }), app)) as { status: number };
+    assertEquals(res.status, 400);
+  } finally {
+    relayFamily.teardown?.();
+  }
+});
+
+test("shared-secret guard rejects a missing secret when configured", async () => {
+  const prev = process.env["NANO_PR_WEBHOOK_SECRET"];
+  process.env["NANO_PR_WEBHOOK_SECRET"] = "s3cr3t";
+  try {
+    const mod = await import(`./listAgenticTranscripts.ts?guard=${Date.now()}`);
+    const guarded = mod.default as typeof handler;
+    const bad = (await guarded(input(), app)) as { status: number };
+    assertEquals(bad.status, 401);
+    const ok = (await guarded(input({}, { "x-hook-secret": "s3cr3t" }), app)) as { status: number };
+    assertEquals(ok.status, 200);
+  } finally {
+    if (prev === undefined) delete process.env["NANO_PR_WEBHOOK_SECRET"];
+    else process.env["NANO_PR_WEBHOOK_SECRET"] = prev;
+  }
+});

package/operations/listAgenticTranscripts.ts

@@ -0,0 +1,61 @@
+// GET /app/api/agentic/transcripts → operationId `listAgenticTranscripts` (ADR 0056, H3 read path #222).
+//
+// The READ counterpart to the write-only transcript store (H3 #146): it lists the durable transcripts an
+// ephemeral agent flushed on job completion, so an operator can review "what did that agent do" AFTER it
+// is gone. Sourced from the mounted relay/transcript service's TranscriptStore (over `app.data`) and
+// correlated via `app/agentic/correlation.ts` (best-effort — jobKey is always recovered from the stream
+// id, engine context only while the job is still live). Feeds the cockpit "past sessions" view.
+//
+// Advisory read-only (ADR 0056): it NEVER gates a BPMN sequence flow. Optional filters (jobKey / process
+// instance / plan / time) narrow the feed. The optional shared-secret guard mirrors getAgenticSupply:
+// when NANO_PR_WEBHOOK_SECRET is set, callers must present it via the x-hook-secret header; unset -> open.
+
+import { currentCorrelation } from "../app/agentic/correlation.ts";
+import { currentRelayTranscriptService } from "../app/agentic/families/relay.family.ts";
+import { listTranscripts, type TranscriptFilter } from "../app/agentic/transcript-read.ts";
+import { envVar } from "../app/version.ts";
+import type { AgenticTranscriptList } from "../nano-generated/api-io.d.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
+
+const SECRET = envVar("NANO_PR_WEBHOOK_SECRET") ?? "";
+
+/** Reject an ISO-8601 filter that does not parse (a malformed since/until is a 400, not a silent no-op). */
+function badInstant(value: string | undefined): boolean {
+  return value !== undefined && !Number.isFinite(Date.parse(value));
+}
+
+export default defineOperation("listAgenticTranscripts", async ({ query, req }, app) => {
+  if (SECRET && req.headers.get("x-hook-secret") !== SECRET) {
+    app.log.warn("listAgenticTranscripts rejected: missing/invalid shared secret");
+    return { status: 401, body: { error: "unauthorized" } };
+  }
+
+  if (badInstant(query.since) || badInstant(query.until)) {
+    return { status: 400, body: { error: "invalid since/until: expected an ISO-8601 instant" } };
+  }
+
+  const service = currentRelayTranscriptService();
+  const store = service?.store;
+  if (!store) {
+    // The relay family has not mounted, or is running unpersisted (no DataLayer) - no transcripts to
+    // report, not an error (advisory).
+    const empty: AgenticTranscriptList = { count: 0, generatedAt: new Date().toISOString(), transcripts: [] };
+    return { status: 200, body: empty };
+  }
+
+  const filter: TranscriptFilter = {
+    ...(query.jobKey !== undefined ? { jobKey: query.jobKey } : {}),
+    ...(query.processInstanceKey !== undefined ? { processInstanceKey: query.processInstanceKey } : {}),
+    ...(query.planKey !== undefined ? { planKey: query.planKey } : {}),
+    ...(query.since !== undefined ? { since: query.since } : {}),
+    ...(query.until !== undefined ? { until: query.until } : {}),
+  };
+  const transcripts = listTranscripts(store, currentCorrelation(), filter);
+  const body: AgenticTranscriptList = {
+    count: transcripts.length,
+    generatedAt: new Date().toISOString(),
+    retentionMs: store.ephemeralRetentionMs,
+    transcripts,
+  };
+  return { status: 200, body };
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.69.1",
+  "version": "0.70.0",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",

package/pages/cockpit/cockpit.css

@@ -42,6 +42,7 @@
 }
 
 .cockpit-supply-region,
+.cockpit-past-region,
 .cockpit-terminal {
   background: var(--cockpit-panel);
   border: 1px solid var(--cockpit-edge);
@@ -160,3 +161,72 @@
   background: #05080b;
   border-radius: 6px;
 }
+
+/* ── Past sessions (H3 read path / #222): the captured-session history + replay. ──────────────── */
+
+.cockpit-past-header {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: 8px;
+  margin-bottom: 8px;
+}
+
+.cockpit-past-title {
+  font-size: 13px;
+  margin: 0;
+  color: var(--cockpit-muted);
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+}
+
+.cockpit-past-summary {
+  color: var(--cockpit-muted);
+  font-size: 12px;
+  font-variant-numeric: tabular-nums;
+}
+
+.cockpit-past-table {
+  width: 100%;
+  border-collapse: collapse;
+  font-variant-numeric: tabular-nums;
+}
+
+.cockpit-past-replay {
+  background: none;
+  border: none;
+  color: var(--cockpit-text);
+  cursor: pointer;
+  font: inherit;
+  padding: 0;
+  text-align: left;
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}
+
+.cockpit-past-replay:hover { color: #58a6ff; }
+
+.cockpit-past-session[data-active="true"] {
+  background: rgba(88, 166, 255, 0.12);
+}
+
+.cockpit-past-status { color: var(--cockpit-muted); }
+.cockpit-past-size { color: var(--cockpit-muted); }
+.cockpit-past-captured { color: var(--cockpit-muted); font-size: 12px; }
+
+.cockpit-past-empty {
+  color: var(--cockpit-muted);
+  padding: 8px 0;
+}
+
+/* Distinguish a live terminal from a replayed (static) past session at a glance. */
+.cockpit-terminal[data-terminal-mode="replay"] {
+  border-color: #8957e5;
+}
+.cockpit-terminal[data-terminal-mode="replay"] .cockpit-panel-title {
+  color: #b392f0;
+}
+.cockpit-terminal[data-terminal-mode="live"] .cockpit-panel-title {
+  color: var(--cockpit-green);
+}

package/pages/cockpit/mount.js

@@ -21,6 +21,7 @@ import { Terminal } from "@xterm/xterm";
 
 const DEFAULT_REFRESH_MS = 2000;
 const DEFAULT_STALE_AFTER_MS = 15_000;
+const DEFAULT_PAST_FETCH_TIMEOUT_MS = 15_000;
 
 function isPosInt(value) {
   return Number.isSafeInteger(value) && value > 0;
@@ -181,6 +182,113 @@ function renderSupply(host, doc, view, onDrill) {
   host.appendChild(root);
 }
 
+// ── past-sessions projection + render (mirrors app/agentic/cockpit/transcript-view.ts + -render.ts) ──
+
+function humanBytes(bytes) {
+  if (!Number.isFinite(bytes) || bytes < 0) return "0 B";
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+function humanDuration(ms) {
+  if (ms == null || !Number.isFinite(ms) || ms <= 0) return undefined;
+  const s = Math.round(ms / 1000);
+  if (s < 60) return `${s}s`;
+  const m = Math.round(s / 60);
+  if (m < 60) return `${m}m`;
+  const h = Math.round(m / 60);
+  if (h < 48) return `${h}h`;
+  return `${Math.round(h / 24)}d`;
+}
+
+function sessionLabel(t) {
+  const parts = [];
+  if (t.bpmnProcessId != null) parts.push(t.bpmnProcessId);
+  if (t.elementId != null) parts.push(t.elementId);
+  if (t.processInstanceKey != null) parts.push(`inst ${t.processInstanceKey}`);
+  if (t.planKey != null) parts.push(t.planKey);
+  if (parts.length > 0) return parts.join(" \u00b7 ");
+  if (t.jobKey != null) return `job ${t.jobKey}`;
+  return t.stream;
+}
+
+function transcriptsView(report) {
+  const sessions = (report.transcripts ?? [])
+    .map((t) => ({
+      stream: t.stream,
+      label: sessionLabel(t),
+      jobKey: t.jobKey,
+      status: t.status,
+      lifecycle: t.lifecycle,
+      size: humanBytes(t.byteLength),
+      byteLength: t.byteLength,
+      capturedAt: t.completedAt ?? t.createdAt,
+    }))
+    .sort((a, b) => {
+      const byTime = String(b.capturedAt).localeCompare(String(a.capturedAt));
+      return byTime !== 0 ? byTime : a.stream.localeCompare(b.stream);
+    });
+  return { sessions, count: sessions.length, retention: humanDuration(report.retentionMs) };
+}
+
+function sessionRow(doc, session, onReplay, activeStream) {
+  const row = el(doc, "tr", "cockpit-past-session");
+  row.setAttribute("data-stream", session.stream);
+  row.setAttribute("data-status", session.status);
+  if (session.jobKey != null) row.setAttribute("data-job-key", session.jobKey);
+  if (activeStream === session.stream) row.setAttribute("data-active", "true");
+  const nameCell = el(doc, "td", "cockpit-td cockpit-past-name");
+  const button = el(doc, "button", "cockpit-past-replay", session.label);
+  button.setAttribute("type", "button");
+  button.setAttribute("data-stream", session.stream);
+  if (onReplay) button.addEventListener("click", () => onReplay(session.stream));
+  nameCell.appendChild(button);
+  row.appendChild(nameCell);
+  row.appendChild(el(doc, "td", "cockpit-td cockpit-past-status", session.status));
+  row.appendChild(el(doc, "td", "cockpit-td cockpit-past-size", session.size));
+  row.appendChild(el(doc, "td", "cockpit-td cockpit-past-captured", session.capturedAt));
+  return row;
+}
+
+function renderTranscripts(host, doc, view, onReplay, activeStream) {
+  host.replaceChildren();
+  const root = el(doc, "div", "cockpit-past");
+  root.setAttribute("data-session-count", String(view.count));
+  const header = el(doc, "header", "cockpit-past-header");
+  header.appendChild(el(doc, "h2", "cockpit-past-title", "Past sessions"));
+  const summary = el(doc, "span", "cockpit-past-summary", view.retention != null ? `${view.count} \u00b7 kept ${view.retention}` : `${view.count}`);
+  summary.setAttribute("data-summary", "past");
+  header.appendChild(summary);
+  root.appendChild(header);
+  if (view.count === 0) {
+    const empty = el(doc, "div", "cockpit-past-empty", "No captured sessions yet.");
+    empty.setAttribute("data-empty", "true");
+    root.appendChild(empty);
+    host.appendChild(root);
+    return;
+  }
+  const table = el(doc, "table", "cockpit-past-table");
+  const thead = el(doc, "thead", "cockpit-past-thead");
+  const head = el(doc, "tr", "cockpit-past-head");
+  for (const label of ["session", "status", "size", "captured"]) head.appendChild(el(doc, "th", "cockpit-th", label));
+  thead.appendChild(head);
+  table.appendChild(thead);
+  const tbody = el(doc, "tbody", "cockpit-past-tbody");
+  for (const session of view.sessions) tbody.appendChild(sessionRow(doc, session, onReplay, activeStream));
+  table.appendChild(tbody);
+  root.appendChild(table);
+  host.appendChild(root);
+}
+
+/** Feed a fetched transcript's stored chunks through a resume-from-offset TerminalSession (static playback). */
+function replayTranscript(session, data) {
+  session.handle({ op: "subscribed", stream: data.stream, gap: data.gap, nextOffset: data.nextOffset });
+  for (const entry of data.entries ?? []) {
+    session.handle({ stream: data.stream, offset: entry.offset, chunk: entry.chunk });
+  }
+}
+
 // ── boot orchestration (mirrors app/agentic/cockpit/supply-boot.ts) ────────────────────────────
 
 /** An xterm.js-backed terminal sink mounted into `host`. */
@@ -219,6 +327,10 @@ function relaySocketFactory(url) {
  * @param {number} [opts.refreshMs] — poll interval (default 2000).
  * @param {number} [opts.staleAfterMs] — a worker is rendered "stale" once its last heartbeat is at
  *   least this many ms old (default 15000).
+ * @param {number} [opts.pastFetchTimeoutMs] — upper bound (ms) on a single past-sessions transcripts
+ *   fetch; the fetch is aborted past this so a hung endpoint can't wedge the past panel (default 15000).
+ * @param {string} [opts.transcriptsUrl] — the captured-session list endpoint (default
+ *   /app/api/agentic/transcripts) backing the always-on "past sessions" history + replay.
  * @returns a handle with `.dispose()`.
  */
 export function mountCockpit(host, opts = {}) {
@@ -229,6 +341,7 @@ export function mountCockpit(host, opts = {}) {
   }
   const doc = document;
   const reportUrl = opts.reportUrl ?? "/app/api/agentic/supply";
+  const transcriptsUrl = opts.transcriptsUrl ?? "/app/api/agentic/transcripts";
   const hookSecret = opts.hookSecret;
   const relayUrl = opts.relayUrl ?? defaultRelayUrl(opts.relayToken, opts.relayCapability);
   const refreshMs = opts.refreshMs ?? DEFAULT_REFRESH_MS;
@@ -239,20 +352,40 @@ export function mountCockpit(host, opts = {}) {
     throw new RangeError(`mountCockpit(opts.refreshMs): must be a positive safe integer, got ${refreshMs}.`);
   }
   const staleAfterMs = opts.staleAfterMs ?? DEFAULT_STALE_AFTER_MS;
+  // Upper bound on a single "past sessions" transcripts fetch. refreshPast() is single-flight, so a
+  // fetch that HANGS (never settles) would otherwise leave `pastRefreshing` stuck true forever and
+  // permanently disable the past panel; a bounded (aborting) fetch clears the flag so the next poll retries.
+  const pastFetchTimeoutMs = opts.pastFetchTimeoutMs ?? DEFAULT_PAST_FETCH_TIMEOUT_MS;
+  if (!isPosInt(pastFetchTimeoutMs)) {
+    throw new RangeError(
+      `mountCockpit(opts.pastFetchTimeoutMs): must be a positive safe integer, got ${pastFetchTimeoutMs}.`,
+    );
+  }
   const connectRelay = relaySocketFactory(relayUrl);
   const onError = (err) => console.error("[cockpit]", err);
 
-  // Stable skeleton: a volatile list region the poll re-renders + a PERSISTENT terminal region a
-  // refresh never touches (so a drilled-in terminal survives a list refresh).
+  const jsonHeaders = () => {
+    const headers = { accept: "application/json" };
+    if (hookSecret) headers["x-hook-secret"] = hookSecret;
+    return headers;
+  };
+
+  // Stable skeleton: a volatile supply-list region + a volatile "past sessions" region the poll
+  // re-renders, and a PERSISTENT terminal region a refresh never touches (so a drilled-in/replayed
+  // terminal survives a list refresh). The terminal panel title distinguishes live vs replayed.
   host.replaceChildren();
   const shell = el(doc, "div", "cockpit-shell");
   const listRegion = el(doc, "div", "cockpit-supply-region");
+  const pastRegion = el(doc, "div", "cockpit-past-region");
   const terminalPanel = el(doc, "section", "cockpit-terminal");
-  terminalPanel.appendChild(el(doc, "h2", "cockpit-panel-title", "Worker terminal"));
+  terminalPanel.setAttribute("data-terminal-mode", "idle");
+  const terminalTitle = el(doc, "h2", "cockpit-panel-title", "Worker terminal");
+  terminalPanel.appendChild(terminalTitle);
   const terminalHost = el(doc, "div", "cockpit-terminal-host");
   terminalHost.setAttribute("data-terminal", "host");
   terminalPanel.appendChild(terminalHost);
   shell.appendChild(listRegion);
+  shell.appendChild(pastRegion);
   shell.appendChild(terminalPanel);
   host.appendChild(shell);
 
@@ -262,13 +395,36 @@ export function mountCockpit(host, opts = {}) {
   let generation = 0;
   let drill; // { stream, client }
   let terminal; // the current xterm sink
+  let mode; // "live" | "replay" | undefined
+  let shownStream;
+  // Bumped by every drillInto()/replayInto()/dispose() that claims the terminal region, so a slow
+  // replay fetch that resolves after a newer selection drops its result instead of clobbering it.
+  let opToken = 0;
+  // True while a refreshPast() fetch is outstanding, so the supply poll never stacks past-fetches
+  // against a slow/hung transcripts endpoint.
+  let pastRefreshing = false;
 
-  function drillInto(stream) {
-    if (disposed || drill?.stream === stream) return;
+  function setMode(next, stream) {
+    mode = next;
+    shownStream = stream;
+    terminalPanel.setAttribute("data-terminal-mode", next ?? "idle");
+    if (next === "live") terminalTitle.textContent = "Worker terminal — live";
+    else if (next === "replay") terminalTitle.textContent = "Worker terminal — replay (past session)";
+    else terminalTitle.textContent = "Worker terminal";
+  }
+
+  function teardownTerminal() {
     drill?.client.close();
     drill = undefined;
     terminal?.dispose?.();
     terminal = undefined;
+  }
+
+  function drillInto(stream) {
+    if (disposed || (mode === "live" && drill?.stream === stream)) return;
+    // Claim the terminal region: bump the op token so an in-flight replay drops its stale result.
+    opToken++;
+    teardownTerminal();
     try {
       terminalHost.replaceChildren();
       const sink = xtermSink(terminalHost);
@@ -283,18 +439,102 @@ export function mountCockpit(host, opts = {}) {
       session = new TerminalSession({ stream, sink, send: (message) => client.sendRelay(message) });
       client.open();
       drill = { stream, client };
+      setMode("live", stream);
+    } catch (err) {
+      // The new terminal failed to build after the prior one was torn down: reset the region to idle
+      // (and drop any partially-built terminal) so the UI never shows a stale "live"/"replay"
+      // indicator with nothing behind it — symmetric with replayInto(), which clears mode up-front.
+      teardownTerminal();
+      setMode(undefined, undefined);
+      onError(err);
+    }
+  }
+
+  async function replayInto(stream) {
+    if (disposed) return;
+    // Claim the terminal region under a fresh op token, captured for the post-fetch re-check below.
+    const token = ++opToken;
+    // Drop any live drill + prior terminal before fetching so replay never overlaps a live stream.
+    teardownTerminal();
+    setMode(undefined, undefined);
+    let data;
+    try {
+      // Bound the fetch: a transcript endpoint that never responds would otherwise leave replay() pending
+      // forever with an in-flight request and the terminal wedged out of live mode. Abort after
+      // pastFetchTimeoutMs so the fetch always settles (here, rejects) and this catch leaves mode idle.
+      const controller = new AbortController();
+      const abortTimer = setTimeout(() => controller.abort(), pastFetchTimeoutMs);
+      abortTimer.unref?.();
+      let res;
+      try {
+        res = await fetch(`${transcriptsUrl}/${encodeURIComponent(stream)}`, { headers: jsonHeaders(), signal: controller.signal });
+      } finally {
+        clearTimeout(abortTimer);
+      }
+      if (!res.ok) throw new Error(`transcript fetch failed: ${res.status}`);
+      data = await res.json();
+    } catch (err) {
+      onError(err);
+      return;
+    }
+    // A newer drill/replay (or dispose) claimed the terminal while this fetch was outstanding — drop
+    // the stale result rather than overwrite the newer selection with an out-of-date replay.
+    if (disposed || token !== opToken) return;
+    try {
+      terminalHost.replaceChildren();
+      const sink = xtermSink(terminalHost);
+      terminal = sink;
+      const session = new TerminalSession({ stream, sink, send: () => {}, from: data.from ?? 0 });
+      replayTranscript(session, data);
+      setMode("replay", stream);
+      void refreshPast();
     } catch (err) {
       onError(err);
     }
   }
 
+  async function refreshPast() {
+    // Single-flight: while one past-fetch is outstanding (including a hung one), skip starting another
+    // so the supply poll can't stack pending fetches against a slow/unresponsive transcripts endpoint.
+    if (pastRefreshing) return;
+    pastRefreshing = true;
+    try {
+      let report;
+      try {
+        // Bound the fetch: refreshPast() is single-flight, so a transcripts endpoint that never responds
+        // would otherwise wedge `pastRefreshing` true forever. Abort after pastFetchTimeoutMs so the fetch
+        // always settles (here, rejects), the finally clears the flag, and the next poll can retry.
+        const controller = new AbortController();
+        const abortTimer = setTimeout(() => controller.abort(), pastFetchTimeoutMs);
+        abortTimer.unref?.();
+        let res;
+        try {
+          res = await fetch(transcriptsUrl, { headers: jsonHeaders(), signal: controller.signal });
+        } finally {
+          clearTimeout(abortTimer);
+        }
+        if (!res.ok) throw new Error(`transcripts fetch failed: ${res.status}`);
+        report = await res.json();
+      } catch (err) {
+        onError(err);
+        return;
+      }
+      if (disposed) return;
+      try {
+        renderTranscripts(pastRegion, doc, transcriptsView(report), replayInto, mode === "replay" ? shownStream : undefined);
+      } catch (err) {
+        onError(err);
+      }
+    } finally {
+      pastRefreshing = false;
+    }
+  }
+
   async function refresh() {
     if (disposed) return;
     let report;
     try {
-      const headers = { accept: "application/json" };
-      if (hookSecret) headers["x-hook-secret"] = hookSecret;
-      const res = await fetch(reportUrl, { headers });
+      const res = await fetch(reportUrl, { headers: jsonHeaders() });
       if (!res.ok) throw new Error(`supply fetch failed: ${res.status}`);
       report = await res.json();
     } catch (err) {
@@ -307,6 +547,8 @@ export function mountCockpit(host, opts = {}) {
     } catch (err) {
       onError(err);
     }
+    // Fire-and-forget: a hung transcripts endpoint must never stall the supply poll's next tick.
+    void refreshPast();
   }
 
   function tick(gen) {
@@ -332,15 +574,14 @@ export function mountCockpit(host, opts = {}) {
   function dispose() {
     if (disposed) return;
     disposed = true;
+    opToken++;
     stop();
-    drill?.client.close();
-    drill = undefined;
-    terminal?.dispose?.();
-    terminal = undefined;
+    teardownTerminal();
+    setMode(undefined, undefined);
   }
 
   start();
-  return { start, stop, dispose, refresh, drill: drillInto };
+  return { start, stop, dispose, refresh, drill: drillInto, replay: replayInto };
 }
 
 /**