@nanobpm/nano-workforce 0.69.0 → 0.70.0

package/app/agentic/cockpit/transcript-render.ts

@@ -0,0 +1,136 @@
+// The cockpit "past sessions" DOM renderer + static-replay helper (ADR 0056, H3 read path / #222).
+//
+// Renders a {@link TranscriptsView} into a host element: the captured-session history list the cockpit
+// shows BESIDE the live supply list. Clicking a session calls {@link RenderTranscriptsOptions.onReplay}
+// with that session's relay stream id, which the boot layer turns into a STATIC playback in the same
+// persistent terminal region a live drill-in uses — clearly distinguished as "replayed" (a closed
+// stream) vs "live". Like the supply renderer it draws only the *volatile* history list; the terminal
+// itself is owned by the boot layer's persistent region.
+//
+// It builds against the structural {@link ElementLike} / {@link DocumentLike} subset (reused from the
+// package) rather than the global `document`, so the real DOM satisfies it at runtime AND a plain
+// in-memory fake satisfies it for DOM-free Node tests.
+//
+// The static-replay helper ({@link replayTranscript}) drives a `@nanobpm/agentic/cockpit`
+// {@link TerminalSession} from a fetched transcript page: it feeds the stored chunks through the SAME
+// resume-from-offset renderer a LIVE stream uses, so a closed session replays faithfully with no live
+// worker and no relay connection.
+import type { DocumentLike, ElementLike, TerminalSession } from "@nanobpm/agentic/cockpit";
+import type { TranscriptsView, TranscriptView } from "./transcript-view.ts";
+
+export interface RenderTranscriptsOptions {
+  /** Called with a session's relay stream id when the operator selects it to replay. */
+  readonly onReplay?: (stream: string) => void;
+  /** The stream currently being replayed, if any — highlighted in the list. */
+  readonly activeStream?: string;
+}
+
+/** Handles into the rendered tree the caller may need. */
+export interface TranscriptsDom {
+  readonly root: ElementLike;
+}
+
+function el(doc: DocumentLike, tag: string, className?: string, text?: string): ElementLike {
+  const node = doc.createElement(tag);
+  if (className !== undefined) node.className = className;
+  if (text !== undefined) node.textContent = text;
+  return node;
+}
+
+function sessionRow(doc: DocumentLike, session: TranscriptView, options: RenderTranscriptsOptions): ElementLike {
+  const row = el(doc, "tr", "cockpit-past-session");
+  row.setAttribute("data-stream", session.stream);
+  row.setAttribute("data-status", session.status);
+  if (session.jobKey !== undefined) row.setAttribute("data-job-key", session.jobKey);
+  if (options.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);
+  const onReplay = options.onReplay;
+  if (onReplay !== undefined) 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;
+}
+
+/**
+ * Render `view` into `host`, replacing whatever was there. Idempotent: call it again on every refresh
+ * to reflect the latest captured-session snapshot.
+ */
+export function renderTranscripts(
+  host: ElementLike,
+  doc: DocumentLike,
+  view: TranscriptsView,
+  options: RenderTranscriptsOptions = {},
+): TranscriptsDom {
+  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 !== undefined ? `${view.count} · 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 { root };
+  }
+
+  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, options));
+  table.appendChild(tbody);
+  root.appendChild(table);
+
+  host.appendChild(root);
+  return { root };
+}
+
+/** One stored transcript chunk as the fetch endpoint returns it (mirrors `AgenticTranscriptChunk`). */
+export interface TranscriptChunkReport {
+  readonly offset: number;
+  readonly chunk: string;
+}
+
+/** A stored transcript's bytes as `GET /agentic/transcripts/{stream}` returns them (mirrors `AgenticTranscriptData`). */
+export interface TranscriptDataReport {
+  readonly stream: string;
+  readonly from: number;
+  readonly gap: boolean;
+  readonly nextOffset: number;
+  readonly entries: readonly TranscriptChunkReport[];
+}
+
+/**
+ * Statically replay a fetched transcript into a {@link TerminalSession}: feed the stored chunks through
+ * the SAME resume-from-offset handler a live stream uses, so a closed session renders faithfully. The
+ * session must be constructed with `from` equal to `data.from` (so it does not drop the leading chunks
+ * as already-applied) and a no-op `send` (there is no live relay to talk to). Returns the count written.
+ */
+export function replayTranscript(session: TerminalSession, data: TranscriptDataReport): number {
+  // The resume ack first (records any retention gap), then the stored chunks in offset order.
+  session.handle({ op: "subscribed", stream: data.stream, gap: data.gap, nextOffset: data.nextOffset });
+  let written = 0;
+  for (const entry of data.entries) {
+    session.handle({ stream: data.stream, offset: entry.offset, chunk: entry.chunk });
+    written++;
+  }
+  return written;
+}

package/app/agentic/cockpit/transcript-view.test.ts

@@ -0,0 +1,61 @@
+// Unit tests for the cockpit "past sessions" view-model (H3 read path / #222).
+//
+// Pure projection: a transcript LIST report → the renderable history view. Covers labelling (process
+// instance / plan → single label, jobKey/stream fallback), human byte/duration formatting, newest-first
+// ordering, and the retention surfacing.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import { humanBytes, humanDuration, type TranscriptListReport, transcriptsView } from "./transcript-view.ts";
+
+test("humanBytes renders B / KB / MB compactly", () => {
+  assertEquals(humanBytes(0), "0 B");
+  assertEquals(humanBytes(512), "512 B");
+  assertEquals(humanBytes(2048), "2.0 KB");
+  assertEquals(humanBytes(5 * 1024 * 1024), "5.0 MB");
+  assertEquals(humanBytes(-1), "0 B");
+});
+
+test("humanDuration renders s / m / h / d, undefined for non-positive", () => {
+  assertEquals(humanDuration(45_000), "45s");
+  assertEquals(humanDuration(30 * 60_000), "30m");
+  assertEquals(humanDuration(24 * 60 * 60_000), "24h");
+  assertEquals(humanDuration(3 * 24 * 60 * 60_000), "3d");
+  assertEquals(humanDuration(undefined), undefined);
+  assertEquals(humanDuration(0), undefined);
+});
+
+test("projects sessions newest-first with a process/plan label and surfaces retention", () => {
+  const report: TranscriptListReport = {
+    count: 2,
+    retentionMs: 86_400_000,
+    transcripts: [
+      { stream: "job:1", lifecycle: "ephemeral", status: "completed", createdAt: "2026-01-01T00:00:00Z", completedAt: "2026-01-01T00:05:00Z", nextOffset: 2, byteLength: 2048, chunkCount: 2, jobKey: "1", bpmnProcessId: "plan-fanout", processInstanceKey: "4612", planKey: "o/r#142" },
+      { stream: "job:2", lifecycle: "ephemeral", status: "completed", createdAt: "2026-01-02T00:00:00Z", completedAt: "2026-01-02T00:05:00Z", nextOffset: 1, byteLength: 10, chunkCount: 1, jobKey: "2" },
+    ],
+  };
+  const view = transcriptsView(report);
+  assertEquals(view.count, 2);
+  assertEquals(view.retention, "24h");
+  // Newest capturedAt (job:2, completed 01-02) first.
+  assertEquals(view.sessions[0]?.stream, "job:2");
+  assertEquals(view.sessions[0]?.label, "job 2", "no engine context → job-key label");
+  assertEquals(view.sessions[0]?.size, "10 B");
+  assertEquals(view.sessions[1]?.stream, "job:1");
+  assertEquals(view.sessions[1]?.label, "plan-fanout · inst 4612 · o/r#142");
+  assertEquals(view.sessions[1]?.size, "2.0 KB");
+  assertEquals(view.sessions[1]?.capturedAt, "2026-01-01T00:05:00Z");
+});
+
+test("falls back to the stream id when neither jobKey nor context is known, and uses createdAt when open", () => {
+  const report: TranscriptListReport = {
+    count: 1,
+    transcripts: [
+      { stream: "ctrl:x", lifecycle: "long-lived", status: "open", createdAt: "2026-01-01T00:00:00Z", nextOffset: 3, byteLength: 3, chunkCount: 3 },
+    ],
+  };
+  const view = transcriptsView(report);
+  assertEquals(view.sessions[0]?.label, "ctrl:x");
+  assertEquals(view.sessions[0]?.status, "open");
+  assertEquals(view.sessions[0]?.capturedAt, "2026-01-01T00:00:00Z", "open session uses createdAt");
+  assertEquals(view.retention, undefined);
+});

package/app/agentic/cockpit/transcript-view.ts

@@ -0,0 +1,131 @@
+// The cockpit "past sessions" view-model (ADR 0056, H3 read path / #222).
+//
+// A pure, deterministic projection of the app's transcript LIST report (`GET /agentic/transcripts`) —
+// the durable transcripts an ephemeral agent flushed on job completion — onto the shape the cockpit's
+// "past sessions" history list renders beside the LIVE supply list. Selecting a past session replays
+// its stored transcript into the SAME persistent terminal region as a live drill-in (static playback
+// of a closed stream), so the operator can review "what did that agent do" after it is gone.
+//
+// Like `./supply-view.ts` it is framework-free and side-effect-free: the same report always yields the
+// same {@link TranscriptView}, so it renders identically embedded (App View) and standalone, and is
+// unit-testable on Node with no browser.
+
+/** One captured session as the app's transcript list reports it (mirrors `AgenticTranscript`). */
+export interface TranscriptSummaryReport {
+  readonly stream: string;
+  readonly lifecycle: "ephemeral" | "long-lived";
+  readonly status: "open" | "completed";
+  readonly createdAt: string;
+  readonly completedAt?: string;
+  readonly firstOffset?: number;
+  readonly nextOffset: number;
+  readonly byteLength: number;
+  readonly chunkCount: number;
+  readonly jobKey?: string;
+  readonly processInstanceKey?: string;
+  readonly bpmnProcessId?: string;
+  readonly elementId?: string;
+  readonly planKey?: string;
+}
+
+/** The transcript list report the cockpit polls (mirrors `AgenticTranscriptList`). */
+export interface TranscriptListReport {
+  readonly count: number;
+  readonly generatedAt?: string;
+  readonly retentionMs?: number;
+  readonly transcripts: readonly TranscriptSummaryReport[];
+}
+
+/** One past-session row in the renderable history view. */
+export interface TranscriptView {
+  /** The relay stream id to replay (`job:<jobKey>` for a job stream). */
+  readonly stream: string;
+  /** A single stable human label for the session's process instance / plan (falls back to the stream). */
+  readonly label: string;
+  /** The Camunda-8 job key, when the stream encodes one. */
+  readonly jobKey?: string;
+  /** open (still capturing) vs completed (the ephemeral run flushed & sealed). */
+  readonly status: "open" | "completed";
+  /** Retention lifecycle. */
+  readonly lifecycle: "ephemeral" | "long-lived";
+  /** A human-readable captured size, e.g. "1.2 KB". */
+  readonly size: string;
+  /** The raw captured byte length. */
+  readonly byteLength: number;
+  /** When the session was captured — completedAt when sealed, else createdAt. */
+  readonly capturedAt: string;
+}
+
+/** The full renderable "past sessions" view. */
+export interface TranscriptsView {
+  readonly sessions: readonly TranscriptView[];
+  readonly count: number;
+  /** A human-readable retention window (e.g. "24h"), or undefined when unknown. */
+  readonly retention?: string;
+}
+
+/** A single stable human label for a captured session's process instance / plan (empty parts dropped). */
+function sessionLabel(t: TranscriptSummaryReport): string {
+  const parts: string[] = [];
+  if (t.bpmnProcessId !== undefined) parts.push(t.bpmnProcessId);
+  if (t.elementId !== undefined) parts.push(t.elementId);
+  if (t.processInstanceKey !== undefined) parts.push(`inst ${t.processInstanceKey}`);
+  if (t.planKey !== undefined) parts.push(t.planKey);
+  if (parts.length > 0) return parts.join(" \u00b7 ");
+  if (t.jobKey !== undefined) return `job ${t.jobKey}`;
+  return t.stream;
+}
+
+/** Render a byte count as a compact human string (B / KB / MB), stable and locale-free. */
+export function humanBytes(bytes: number): string {
+  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`;
+}
+
+/** Render a retention window (ms) as a compact human string (e.g. "24h", "30m", "45s"). */
+export function humanDuration(ms: number | undefined): string | undefined {
+  if (ms === undefined || !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 sessionView(t: TranscriptSummaryReport): TranscriptView {
+  return {
+    stream: t.stream,
+    label: sessionLabel(t),
+    ...(t.jobKey !== undefined ? { jobKey: t.jobKey } : {}),
+    status: t.status,
+    lifecycle: t.lifecycle,
+    size: humanBytes(t.byteLength),
+    byteLength: t.byteLength,
+    capturedAt: t.completedAt ?? t.createdAt,
+  };
+}
+
+/**
+ * Derive the renderable "past sessions" view from the app's transcript list report.
+ *
+ * Pure and total: it re-sorts sessions newest-captured-first (stable on stream id) so the view is
+ * diff-friendly regardless of the report's incoming order; no input mutates and no I/O happens.
+ */
+export function transcriptsView(report: TranscriptListReport): TranscriptsView {
+  const sessions = report.transcripts
+    .map(sessionView)
+    .sort((a, b) => {
+      const byTime = b.capturedAt.localeCompare(a.capturedAt);
+      return byTime !== 0 ? byTime : a.stream.localeCompare(b.stream);
+    });
+  const retention = humanDuration(report.retentionMs);
+  return {
+    sessions,
+    count: sessions.length,
+    ...(retention !== undefined ? { retention } : {}),
+  };
+}

package/app/agentic/families/relay.family.test.ts

@@ -21,9 +21,11 @@ import { assert, assertEquals } from "#test-assert";
 import { noopLog } from "../../../test/log.ts";
 import {
   createRelayFamily,
+  currentRelayTranscriptService,
   family as relayFamily,
   RELAY_FAMILY_NAME,
   RelayTranscriptService,
+  sweepIntervalMs,
 } from "./relay.family.ts";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
@@ -383,6 +385,107 @@ test("advisory resilience: a checkpoint flush failure keeps the long-lived strea
   service.teardown();
 });
 
+test("mount installs the service singleton for the read path and teardown clears it (#222)", () => {
+  const registry = new ConnectionRegistry();
+  const ctx = {
+    hub: capturingHub() as never,
+    registry: registry as never,
+    transport: undefined as never,
+    data: { source: () => ({ db: memoryDb() }) } as never,
+    log: noopLog(),
+  };
+  const family = createRelayFamily();
+  assertEquals(currentRelayTranscriptService(), undefined, "no singleton before mount");
+  family.mount(ctx);
+  const service = currentRelayTranscriptService();
+  assert(service !== undefined, "mount installs the singleton the read endpoints source");
+  assert(service.store !== undefined, "the mounted service is persisted");
+  family.teardown?.();
+  assertEquals(currentRelayTranscriptService(), undefined, "teardown clears the singleton");
+});
+
+test("mount drives a retention sweep so completed-ephemeral transcripts are retired (#222)", () => {
+  const registry = new ConnectionRegistry();
+  // A tiny retention window + a clock we control: complete an ephemeral stream, advance past retention,
+  // then confirm the family's own sweep surface retires it (the periodic tick calls the same path).
+  let nowMs = 1_000_000;
+  const ctx = {
+    hub: capturingHub() as never,
+    registry: registry as never,
+    transport: undefined as never,
+    data: { source: () => ({ db: memoryDb() }) } as never,
+    log: noopLog(),
+  };
+  const family = createRelayFamily({ transcript: { ephemeralRetentionMs: 10, clock: { now: () => nowMs } } });
+  family.mount(ctx);
+  const service = currentRelayTranscriptService();
+  assert(service !== undefined);
+  service.store?.flush("job:9", { since: () => ({ entries: [{ offset: 0, chunk: "x" }] }), nextOffset: 1 }, "ephemeral");
+  assertEquals(service.transcriptOf("job:9")?.status, "completed");
+  nowMs += 1000; // advance well past the 10ms retention window
+  const retired = service.sweep();
+  assertEquals(retired, ["job:9"], "the completed-ephemeral transcript is retired past retention");
+  assertEquals(service.transcriptOf("job:9"), undefined);
+  family.teardown?.();
+});
+
+test("mount runs an eager retention sweep so a transcript already past retention from a previous run is retired on boot (#222)", () => {
+  const registry = new ConnectionRegistry();
+  // One durable db shared across two mounts models a process restart: the transcript table survives,
+  // so a completed-ephemeral transcript persisted before downtime is still present at the next boot.
+  const db = memoryDb();
+  let nowMs = 1_000_000;
+  const mkCtx = () => ({
+    hub: capturingHub() as never,
+    registry: registry as never,
+    transport: undefined as never,
+    data: { source: () => ({ db }) } as never,
+    log: noopLog(),
+  });
+
+  // First run: persist a completed-ephemeral transcript, then simulate downtime past its retention window.
+  const first = createRelayFamily({ transcript: { ephemeralRetentionMs: 10, clock: { now: () => nowMs } } });
+  first.mount(mkCtx());
+  const s1 = currentRelayTranscriptService();
+  assert(s1 !== undefined);
+  s1.store?.flush("job:stale", { since: () => ({ entries: [{ offset: 0, chunk: "x" }] }), nextOffset: 1 }, "ephemeral");
+  assertEquals(s1.transcriptOf("job:stale")?.status, "completed");
+  first.teardown?.();
+  nowMs += 1000; // downtime elapses well past the 10ms retention window
+
+  // Second run (restart) over the SAME durable db: the eager mount sweep must retire the already-expired
+  // transcript immediately — without waiting for the first periodic tick and without an explicit sweep().
+  const second = createRelayFamily({ transcript: { ephemeralRetentionMs: 10, clock: { now: () => nowMs } } });
+  second.mount(mkCtx());
+  const s2 = currentRelayTranscriptService();
+  assert(s2 !== undefined);
+  assertEquals(
+    s2.transcriptOf("job:stale"),
+    undefined,
+    "the eager mount sweep retires a transcript already past retention from a previous run",
+  );
+  second.teardown?.();
+});
+
+test("sweep cadence: a fraction of the retention window, floored at 1ms and capped at the Node timer max", () => {
+  // A normal retention window derives a quarter-window cadence.
+  assertEquals(sweepIntervalMs(1000), 250);
+  // A tiny/zero window still floors at a live 1ms tick rather than 0.
+  assertEquals(sweepIntervalMs(1), 1);
+  assertEquals(sweepIntervalMs(0), 1);
+  // A very large window (~1 year) would derive a >2^31-1 interval; Node clamps such a delay to 1ms and
+  // busy-loops. Cap it at the 32-bit timer ceiling so the periodic sweep stays a slow tick.
+  const oneYearMs = 365 * 24 * 60 * 60 * 1000;
+  assert(Math.floor(oneYearMs / 4) > 2_147_483_647, "precondition: an unclamped year/4 overflows the timer");
+  assertEquals(sweepIntervalMs(oneYearMs), 2_147_483_647);
+  // A non-finite retention config (NaN, ±Infinity) derives a NaN interval that setInterval() coerces
+  // to a 1ms busy tick. Clamp any non-finite window to the same timer ceiling the overflow case uses,
+  // so a broken config degrades to the slowest safe sweep rather than a busy loop.
+  assertEquals(sweepIntervalMs(Number.NaN), 2_147_483_647);
+  assertEquals(sweepIntervalMs(Number.POSITIVE_INFINITY), 2_147_483_647);
+  assertEquals(sweepIntervalMs(Number.NEGATIVE_INFINITY), 2_147_483_647);
+});
+
 test("drift guard: migration 024 mirrors the canonical transcript DDL byte-for-byte", async () => {
   const migrationPath = join(HERE, "..", "..", "..", "db", "migrations", "024_agentic_transcript.sql");
   const raw = await readFile(migrationPath, "utf8");

package/app/agentic/families/relay.family.ts

@@ -38,6 +38,28 @@ import type { AgenticContext, AgenticFamily } from "../registry.ts";
 /** The stable family name this slice registers under the seam (distinct from the wire family key). */
 export const RELAY_FAMILY_NAME = "relay";
 
+/** The default retention-sweep cadence divisor: the periodic sweep runs at a fraction of the retention
+ * window (like the presence family runs its maintenance tick at a fraction of the presence TTL). */
+const SWEEP_DIVISOR = 4;
+
+/** Node's setInterval/setTimeout ceiling (2^31-1 ms ≈ 24.8 days). A delay above this overflows the
+ * 32-bit timer and Node silently clamps it to 1ms — turning a slow periodic tick into a busy loop. */
+const MAX_TIMER_MS = 2_147_483_647;
+
+/**
+ * The retention-sweep cadence (ms) for a given ephemeral-retention window: a fraction of the window,
+ * floored at 1ms and — crucially — capped at {@link MAX_TIMER_MS} so a large retention config (e.g.
+ * a multi-month window) cannot overflow Node's 32-bit timer and degrade the sweep into a busy loop.
+ * A non-finite window (NaN / ±Infinity — a broken config) derives a non-finite interval that
+ * setInterval() would coerce to a 1ms busy tick; clamp it to the same {@link MAX_TIMER_MS} ceiling so
+ * a garbage config degrades to the slowest safe sweep rather than pegging the sweep loop.
+ */
+export function sweepIntervalMs(ephemeralRetentionMs: number): number {
+  if (!Number.isFinite(ephemeralRetentionMs)) return MAX_TIMER_MS;
+  const interval = Math.floor(ephemeralRetentionMs / SWEEP_DIVISOR);
+  return Math.min(MAX_TIMER_MS, Math.max(1, interval));
+}
+
 /** Read a property off an unknown value without an unsafe `as` cast (mirrors the loader's helper). */
 function readProp(value: unknown, key: string): unknown {
   if (!value || typeof value !== "object") return undefined;
@@ -293,6 +315,12 @@ export class RelayTranscriptService {
  * in `mount` (threading the seam's hub/registry/DataLayer/log) and tears it down in `teardown`. The
  * created service is exposed to `onMounted` so a driver (H6 correlation, tests) can reach the
  * completion/reattach surface without re-mounting anything.
+ *
+ * It also (H3 read path, #222): installs the mounted service as the module singleton
+ * {@link currentRelayTranscriptService} — so the advisory transcript READ endpoints (`GET
+ * /agentic/transcripts*`) can source the {@link TranscriptStore} without re-mounting — and starts ONE
+ * periodic retention sweep so completed-ephemeral transcripts are actually retired past the retention
+ * window (the store defines the policy; this drives it, so the transcript table stays bounded).
  */
 export function createRelayFamily(options: {
   readonly relay?: RelayHubOptions;
@@ -302,6 +330,7 @@ export function createRelayFamily(options: {
   readonly onMounted?: (service: RelayTranscriptService) => void;
 } = {}): AgenticFamily {
   let service: RelayTranscriptService | undefined;
+  let sweepTimer: ReturnType<typeof setInterval> | undefined;
   return {
     name: RELAY_FAMILY_NAME,
     mount(ctx: AgenticContext): void {
@@ -316,15 +345,60 @@ export function createRelayFamily(options: {
         transcript: options.transcript,
         ensureSchema: options.ensureSchema,
       });
+      setCurrentRelayTranscriptService(service);
+
+      // Drive the store's retention-by-lifecycle policy: retire completed-ephemeral transcripts past
+      // the retention window on a periodic tick so the durable table does not grow unbounded. Advisory
+      // (a sweep fault is logged, never thrown) and never keeps the process alive on its own.
+      const store = service.store;
+      if (store) {
+        const interval = sweepIntervalMs(store.ephemeralRetentionMs);
+        const tick = () => {
+          try {
+            const retired = service?.sweep() ?? [];
+            if (retired.length > 0) ctx.log.info("agentic transcript retention sweep", { retired: retired.length });
+          } catch (err) {
+            ctx.log.warn("agentic transcript retention sweep failed", { err: String(err) });
+          }
+        };
+        sweepTimer = setInterval(tick, interval);
+        sweepTimer.unref?.();
+        // Run one sweep eagerly at mount so retention is enforced immediately: the transcript table is
+        // durable across restarts, so without this first pass a completed-ephemeral transcript persisted
+        // before downtime (and already past retention) would linger — listed by the read path — until the
+        // first interval tick fires (potentially far off for a large retention window). Mirrors the
+        // presence family's eager maintenance pass (derivation over duplication).
+        tick();
+      }
+
       options.onMounted?.(service);
     },
     teardown(): void {
+      if (sweepTimer !== undefined) {
+        clearInterval(sweepTimer);
+        sweepTimer = undefined;
+      }
       service?.teardown();
+      if (currentService === service) setCurrentRelayTranscriptService(undefined);
       service = undefined;
     },
   };
 }
 
+/** The live relay service from the most recent mount, so the transcript READ endpoints (#222) can
+ * source the durable {@link TranscriptStore} without re-mounting the family. */
+let currentService: RelayTranscriptService | undefined;
+
+/** The mounted relay/transcript service, or undefined before mount / after teardown. */
+export function currentRelayTranscriptService(): RelayTranscriptService | undefined {
+  return currentService;
+}
+
+/** Install the live service (called by the relay family's `mount`; cleared on `teardown`). */
+export function setCurrentRelayTranscriptService(svc: RelayTranscriptService | undefined): void {
+  currentService = svc;
+}
+
 /** The discovered family instance (the loader picks up this `family` export). */
 export const family: AgenticFamily = createRelayFamily();
 

package/app/agentic/transcript-read.test.ts

@@ -0,0 +1,72 @@
+// Focused unit tests for the transcript READ projection's since/until time-bounding (#222 read path).
+//
+// The operation-level suite (operations/listAgenticTranscripts.test.ts) proves the projection and the
+// jobKey/plan filters end-to-end and that a malformed since/until 400s. This file pins the createdAt
+// time-window semantics directly on listTranscripts() — inclusive boundaries, ordering, and the
+// interaction with a missing/invalid createdAt — where a hand-built store lets us fix exact timestamps.
+import { test } from "node:test";
+import type { TranscriptStore, TranscriptStream } from "@nanobpm/agentic/transcript";
+import { assertEquals } from "#test-assert";
+import { listTranscripts } from "./transcript-read.ts";
+
+/** A read-only TranscriptStore double: list() returns the seeded metas; read() has no retained chunks. */
+function fakeStore(metas: TranscriptStream[]): TranscriptStore {
+  return {
+    list: () => metas,
+    read: () => [],
+  } as unknown as TranscriptStore;
+}
+
+function meta(stream: string, createdAt: string): TranscriptStream {
+  return { stream, lifecycle: "ephemeral", status: "completed", createdAt, nextOffset: 0 };
+}
+
+const early = "2026-01-01T00:00:00.000Z";
+const mid = "2026-06-15T12:00:00.000Z";
+const late = "2026-12-31T23:59:59.000Z";
+
+test("listTranscripts: no since/until returns everything, newest-first", () => {
+  const store = fakeStore([meta("job:a", early), meta("job:b", late), meta("job:c", mid)]);
+  const out = listTranscripts(store, undefined);
+  assertEquals(
+    out.map((t) => t.stream),
+    ["job:b", "job:c", "job:a"],
+  );
+});
+
+test("listTranscripts: since is an inclusive lower bound on createdAt", () => {
+  const store = fakeStore([meta("job:early", early), meta("job:mid", mid), meta("job:late", late)]);
+  // A session created exactly at `since` is retained (inclusive); earlier ones are dropped.
+  const out = listTranscripts(store, undefined, { since: mid });
+  assertEquals(
+    out.map((t) => t.stream),
+    ["job:late", "job:mid"],
+  );
+});
+
+test("listTranscripts: until is an inclusive upper bound on createdAt", () => {
+  const store = fakeStore([meta("job:early", early), meta("job:mid", mid), meta("job:late", late)]);
+  // A session created exactly at `until` is retained (inclusive); later ones are dropped.
+  const out = listTranscripts(store, undefined, { until: mid });
+  assertEquals(
+    out.map((t) => t.stream),
+    ["job:mid", "job:early"],
+  );
+});
+
+test("listTranscripts: since+until bound a window on both sides (inclusive)", () => {
+  const store = fakeStore([meta("job:early", early), meta("job:mid", mid), meta("job:late", late)]);
+  const out = listTranscripts(store, undefined, { since: mid, until: mid });
+  assertEquals(
+    out.map((t) => t.stream),
+    ["job:mid"],
+  );
+});
+
+test("listTranscripts: a session with an unparseable createdAt is retained regardless of the window", () => {
+  // Date.parse() of a garbage createdAt is NaN; the guard skips both bounds, so the row is never
+  // silently dropped by a time filter (its context is still recoverable from the stream id).
+  const store = fakeStore([meta("job:mid", mid), meta("job:bad", "not-a-date")]);
+  const out = listTranscripts(store, undefined, { since: late });
+  assertEquals(new Set(out.map((t) => t.stream)), new Set(["job:bad"]));
+});