@nanobpm/nano-workforce 0.69.1 → 0.70.0

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"]));
+});

package/app/agentic/transcript-read.ts

@@ -0,0 +1,161 @@
+// nano-workforce — the transcript READ projection (ADR 0056, H3 / #146, read path #222).
+//
+// The write path (relay.family.ts) flushes an ephemeral agent's PTY stream to a durable transcript on
+// job completion; this module is the READ counterpart the advisory `GET /agentic/transcripts*`
+// endpoints share. It projects a {@link TranscriptStore} row (+ its retained chunks) onto the wire
+// shape and enriches it with the H6 correlation (`app/agentic/correlation.ts`) so a captured session
+// lines up with "that process instance / this plan" — even after the ephemeral agent has exited.
+//
+// Correlation is BEST-EFFORT and advisory: the correlation registry is in-memory and only holds
+// currently-linked jobs, so a completed session's process-instance / plan context is present only
+// while the job is still live. The jobKey itself is always recoverable — it is encoded in the stream
+// id (`job:<jobKey>`), so a past session is never anonymous even once its correlation has been released.
+//
+// Pure and side-effect-free apart from reading the store: no I/O beyond the injected store, so it is
+// unit-testable on the injected env (Node, no browser), and never touches the engine or a BPMN flow.
+
+import type { TranscriptChunk, TranscriptStore, TranscriptStream } from "@nanobpm/agentic/transcript";
+import type { AgenticTranscript, AgenticTranscriptData } from "../../nano-generated/api-io.d.ts";
+import { type CorrelationRegistry, jobKeyOfStream } from "./correlation.ts";
+
+/** Total captured bytes across a set of retained chunks (UTF-8, the on-the-wire terminal encoding). */
+export function byteLengthOf(chunks: readonly TranscriptChunk[]): number {
+  let total = 0;
+  for (const c of chunks) total += Buffer.byteLength(c.chunk, "utf8");
+  return total;
+}
+
+/** The correlation fields (jobKey + engine context) a stream id resolves to, best-effort. */
+interface CorrelationFields {
+  jobKey?: string;
+  processInstanceKey?: string;
+  bpmnProcessId?: string;
+  elementId?: string;
+  planKey?: string;
+}
+
+/**
+ * Resolve a stream id to its correlation fields: the jobKey is always decoded from a `job:<jobKey>`
+ * stream id; the engine context (process instance / plan) is added only when the correlation registry
+ * still holds the (live) job. Non-job streams yield an empty object.
+ */
+export function correlationFieldsFor(stream: string, correlation: CorrelationRegistry | undefined): CorrelationFields {
+  const jobKey = jobKeyOfStream(stream);
+  if (jobKey === undefined) return {};
+  const fields: CorrelationFields = { jobKey };
+  const context = correlation?.resolve(jobKey);
+  if (context) {
+    if (context.processInstanceKey !== undefined) fields.processInstanceKey = context.processInstanceKey;
+    if (context.bpmnProcessId !== undefined) fields.bpmnProcessId = context.bpmnProcessId;
+    if (context.elementId !== undefined) fields.elementId = context.elementId;
+    if (context.planKey !== undefined) fields.planKey = context.planKey;
+  }
+  return fields;
+}
+
+/** Project a stored transcript's metadata (+ its retained chunks) onto the list wire shape. */
+export function toTranscript(
+  meta: TranscriptStream,
+  store: TranscriptStore,
+  correlation: CorrelationRegistry | undefined,
+): AgenticTranscript {
+  const chunks = store.read(meta.stream);
+  const out: AgenticTranscript = {
+    stream: meta.stream,
+    lifecycle: meta.lifecycle,
+    status: meta.status,
+    createdAt: meta.createdAt,
+    nextOffset: meta.nextOffset,
+    byteLength: byteLengthOf(chunks),
+    chunkCount: chunks.length,
+  };
+  if (meta.completedAt !== undefined) out.completedAt = meta.completedAt;
+  if (meta.firstOffset !== undefined) out.firstOffset = meta.firstOffset;
+  const fields = correlationFieldsFor(meta.stream, correlation);
+  if (fields.jobKey !== undefined) out.jobKey = fields.jobKey;
+  if (fields.processInstanceKey !== undefined) out.processInstanceKey = fields.processInstanceKey;
+  if (fields.bpmnProcessId !== undefined) out.bpmnProcessId = fields.bpmnProcessId;
+  if (fields.elementId !== undefined) out.elementId = fields.elementId;
+  if (fields.planKey !== undefined) out.planKey = fields.planKey;
+  return out;
+}
+
+/** The filters {@link listTranscripts} understands (all optional; an empty filter returns everything). */
+export interface TranscriptFilter {
+  readonly jobKey?: string;
+  readonly processInstanceKey?: string;
+  readonly planKey?: string;
+  /** ISO-8601 lower bound (inclusive) on the session's createdAt. */
+  readonly since?: string;
+  /** ISO-8601 upper bound (inclusive) on the session's createdAt. */
+  readonly until?: string;
+}
+
+/**
+ * List every captured session projected to the wire shape, sorted newest-first by createdAt (then by
+ * stream for a stable tie-break), after applying the (advisory) filters. jobKey / process-instance /
+ * plan filters match the correlation-enriched fields; since/until bound createdAt.
+ */
+export function listTranscripts(
+  store: TranscriptStore,
+  correlation: CorrelationRegistry | undefined,
+  filter: TranscriptFilter = {},
+): AgenticTranscript[] {
+  const sinceMs = filter.since !== undefined ? Date.parse(filter.since) : undefined;
+  const untilMs = filter.until !== undefined ? Date.parse(filter.until) : undefined;
+  const rows = store
+    .list()
+    .map((meta) => toTranscript(meta, store, correlation))
+    .filter((t) => {
+      if (filter.jobKey !== undefined && t.jobKey !== filter.jobKey) return false;
+      if (filter.processInstanceKey !== undefined && t.processInstanceKey !== filter.processInstanceKey) return false;
+      if (filter.planKey !== undefined && t.planKey !== filter.planKey) return false;
+      const createdMs = Date.parse(t.createdAt);
+      if (sinceMs !== undefined && Number.isFinite(createdMs) && createdMs < sinceMs) return false;
+      if (untilMs !== undefined && Number.isFinite(createdMs) && createdMs > untilMs) return false;
+      return true;
+    });
+  // Newest session first (a "past sessions" feed reads best most-recent-first); stable on stream id.
+  rows.sort((a, b) => {
+    const byTime = b.createdAt.localeCompare(a.createdAt);
+    return byTime !== 0 ? byTime : a.stream.localeCompare(b.stream);
+  });
+  return rows;
+}
+
+/**
+ * Fetch a stored transcript's bytes from offset `from` (inclusive), projected onto the range/offset
+ * wire shape — the SAME resume-from-offset contract the live terminal renders, so the cockpit replays
+ * a closed stream through its existing renderer. Returns undefined when the stream has no transcript.
+ */
+export function readTranscriptFrom(
+  stream: string,
+  from: number,
+  store: TranscriptStore,
+  correlation: CorrelationRegistry | undefined,
+): AgenticTranscriptData | undefined {
+  const meta = store.get(stream);
+  if (meta === undefined) return undefined;
+  const slice = store.since(stream, from);
+  const entries = slice.entries.map((c) => ({ offset: c.offset, chunk: c.chunk }));
+  const out: AgenticTranscriptData = {
+    stream: meta.stream,
+    lifecycle: meta.lifecycle,
+    status: meta.status,
+    createdAt: meta.createdAt,
+    nextOffset: slice.nextOffset,
+    byteLength: byteLengthOf(slice.entries),
+    chunkCount: entries.length,
+    from,
+    gap: slice.gap,
+    entries,
+  };
+  if (meta.completedAt !== undefined) out.completedAt = meta.completedAt;
+  const fields = correlationFieldsFor(meta.stream, correlation);
+  if (fields.jobKey !== undefined) out.jobKey = fields.jobKey;
+  if (fields.processInstanceKey !== undefined) out.processInstanceKey = fields.processInstanceKey;
+  if (fields.bpmnProcessId !== undefined) out.bpmnProcessId = fields.bpmnProcessId;
+  if (fields.elementId !== undefined) out.elementId = fields.elementId;
+  if (fields.planKey !== undefined) out.planKey = fields.planKey;
+  return out;
+}