@nanobpm/nano-workforce 0.78.0 → 0.79.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [0.79.0](https://github.com/nanobpm/nano-workforce/compare/v0.78.0...v0.79.0) (2026-08-17)
+
+
+### Features
+
+* **agentic:** event-sourced transcripts — typed vocabulary + derive fold + replay-by-fork ([#251](https://github.com/nanobpm/nano-workforce/issues/251)) ([#252](https://github.com/nanobpm/nano-workforce/issues/252)) ([afa7190](https://github.com/nanobpm/nano-workforce/commit/afa7190db2c19e088ae3fb058a2b43d72f54a8df)), closes [146/#222](https://github.com/nanobpm/nano-workforce/issues/222)
+
 # [0.78.0](https://github.com/nanobpm/nano-workforce/compare/v0.77.0...v0.78.0) (2026-08-17)
 
 

package/app/agentic/README.md

@@ -50,6 +50,26 @@ H0 itself needs no migration.
   present as `?token=…`. When neither is set, the channel is **not mounted** (logged), so the app
   never exposes an unauthenticated upgrade.
 
+## Event-sourced transcripts (#251)
+
+The H3 transcript store (`db/migrations/024_agentic_transcript.sql`) is already **append-only and
+offset-keyed** — the log half of dsh's event-sourced-session pattern. `transcript-events.ts` adds the
+derivation half:
+
+- **Typed, merge-extensible event vocabulary** — `parseTranscriptEvent` is the **one** parser that
+  classifies each stored chunk into a typed `TranscriptEvent` (`message` / `tool-call` / `tool-result`
+  / `turn` / `step` / `lifecycle`, plus `stream-chunk` for raw terminal bytes retained **verbatim** for
+  byte-replay fidelity). A structured producer tags a chunk with the `nwfTranscriptEvent` marker;
+  anything else stays a raw `stream-chunk`. Authors extend the vocabulary additively with
+  `mergeTranscriptVocab` — never a second parser.
+- **One `deriveView()` fold** — every higher-level view (the cockpit's structured message/tool/turn
+  view in `cockpit/transcript-derive.ts`, and any future search / token-accounting / export consumer)
+  is a **derivation** of the single log: "the log IS the state". `transcript-events.drift.test.ts`
+  asserts exactly one parser (no consumer re-parses raw bytes).
+- **Replay-by-reseed / fork** — `transcript-fork.ts` seeds a **new** stream from an existing log up to
+  a chosen offset, so an exited session can be branched and replayed independently, offset-parity
+  preserved. Byte-replay and resume-from-offset (`transcript-read.ts`) are untouched.
+
 ## Invariants (ADR 0056)
 
 - **App-tier only** — never the engine. The Camunda-8 job protocol (worker⇄engine) is untouched;

package/app/agentic/cockpit/index.ts

@@ -29,6 +29,11 @@ export {
   type SupplyWorkerView,
   supplyView,
 } from "./supply-view.ts";
+export {
+  type DerivedTranscriptDom,
+  deriveTranscript,
+  renderDerivedTranscript,
+} from "./transcript-derive.ts";
 export {
   type RenderTranscriptsOptions,
   renderTranscripts,

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

@@ -0,0 +1,78 @@
+// Unit tests for the cockpit STRUCTURED transcript view derived from the one fold (#251).
+//
+// Proves the cockpit's structured view is a DERIVATION of the typed event log (message history, tool
+// cards, per-turn boundaries), and that raw chunks are preserved in the fidelity footer — the byte
+// replay is not lost. It renders into the in-memory DOM double, no browser.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import { FakeDocument, FakeElement } from "../../../test/agentic-cockpit-doubles.ts";
+import { TRANSCRIPT_EVENT_MARKER, TRANSCRIPT_EVENT_VERSION } from "../transcript-events.ts";
+import { deriveTranscript, renderDerivedTranscript } from "./transcript-derive.ts";
+import type { TranscriptDataReport } from "./transcript-render.ts";
+
+const doc = new FakeDocument();
+
+function env(kind: string, extra: Record<string, unknown> = {}): string {
+  return JSON.stringify({ [TRANSCRIPT_EVENT_MARKER]: TRANSCRIPT_EVENT_VERSION, kind, ...extra });
+}
+
+function report(): TranscriptDataReport {
+  return {
+    stream: "job:1",
+    from: 0,
+    gap: false,
+    nextOffset: 6,
+    entries: [
+      { offset: 0, chunk: env("turn", { index: 0 }) },
+      { offset: 1, chunk: env("message", { role: "user", text: "please build it" }) },
+      { offset: 2, chunk: env("tool-call", { name: "grep", callId: "c1" }) },
+      { offset: 3, chunk: env("tool-result", { callId: "c1", ok: true, content: "hit" }) },
+      { offset: 4, chunk: "\u001b[2Jraw terminal frame" },
+      { offset: 5, chunk: env("message", { role: "assistant", text: "done" }) },
+    ],
+  };
+}
+
+test("deriveTranscript folds the fetched page into structured turns/messages/tools", () => {
+  const view = deriveTranscript(report());
+  assertEquals(view.turns.length, 1);
+  assertEquals(view.messages.map((m) => m.text), ["please build it", "done"]);
+  assertEquals(view.tools.length, 1);
+  assertEquals(view.tools[0]?.result?.ok, true);
+  assertEquals(view.rawChunkCount, 1); // the one raw terminal frame is retained
+});
+
+test("renderDerivedTranscript draws a turn section with derived messages and tool cards", () => {
+  const host = new FakeElement("div");
+  renderDerivedTranscript(host, doc, report());
+  assertEquals(host.byData("turn-count", "1").length, 1);
+  assertEquals(host.byData("message-count", "2").length, 1);
+  assertEquals(host.byData("tool-count", "1").length, 1);
+  const tool = host.byData("tool", "grep")[0];
+  assertEquals(tool?.getAttribute("data-status"), "ok");
+  const roles = host.byClass("cockpit-transcript-message").map((n) => n.getAttribute("data-role"));
+  assertEquals(roles, ["user", "assistant"]);
+});
+
+test("renderDerivedTranscript keeps the raw-fidelity footer so byte replay is visibly preserved", () => {
+  const host = new FakeElement("div");
+  renderDerivedTranscript(host, doc, report());
+  const footer = host.byClass("cockpit-transcript-raw")[0];
+  assertEquals(footer?.getAttribute("data-raw-chunks"), "1");
+});
+
+test("renderDerivedTranscript shows an empty state for an all-raw (unstructured) transcript", () => {
+  const host = new FakeElement("div");
+  renderDerivedTranscript(host, doc, {
+    stream: "job:2",
+    from: 0,
+    gap: false,
+    nextOffset: 2,
+    entries: [
+      { offset: 0, chunk: "just raw\n" },
+      { offset: 1, chunk: "bytes\n" },
+    ],
+  });
+  assertEquals(host.byData("empty", "true").length, 1);
+  assertEquals(host.byData("turn-count", "0").length, 1);
+});

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

@@ -0,0 +1,90 @@
+// The cockpit STRUCTURED transcript view — derived from the one event fold (ADR 0056, #251).
+//
+// Beside the byte-level replay (`transcript-render.ts` feeds stored chunks through the live terminal
+// renderer for pixel-faithful playback), the cockpit can also show a STRUCTURED view of a captured
+// session: its derived message history, tool cards and per-turn boundaries. Per the issue's acceptance
+// criterion, that structured view is a DERIVATION of the one typed event log — it re-parses nothing.
+// It reads a fetched transcript page and folds it through the single {@link deriveViewFromChunks} entry
+// point (which routes every chunk through the ONE parser, `parseTranscriptEvent`), so there is no
+// second parser of the raw bytes. The drift-guard test enforces that this module never parses chunks
+// itself.
+//
+// Framework-free and side-effect-free, like the sibling cockpit views: the same report always yields
+// the same {@link DerivedView}, and the renderer draws into the injected {@link DocumentLike} subset so
+// a real DOM satisfies it at runtime and an in-memory fake satisfies it for DOM-free Node tests.
+import type { DocumentLike, ElementLike } from "@nanobpm/agentic/cockpit";
+import { type DerivedView, deriveViewFromChunks } from "../transcript-events.ts";
+import type { TranscriptDataReport } from "./transcript-render.ts";
+
+/**
+ * Derive the structured view of a fetched transcript page by folding its stored chunks through the ONE
+ * event parser + fold. Pure: the cockpit reads THIS instead of re-parsing raw frame bytes.
+ */
+export function deriveTranscript(data: TranscriptDataReport): DerivedView {
+  return deriveViewFromChunks(data.entries);
+}
+
+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;
+}
+
+/** Handles into the rendered structured tree the caller may need. */
+export interface DerivedTranscriptDom {
+  readonly root: ElementLike;
+}
+
+/**
+ * Render the DERIVED structured view of a fetched transcript into `host`, replacing whatever was there.
+ * Draws per-turn sections with their derived messages and tool cards, plus a raw-fidelity footer
+ * (retained bytes/chunks) so the operator sees the byte-replay is preserved alongside the structure.
+ * Idempotent — call again on each refresh. Everything it shows is a derivation of the one event log.
+ */
+export function renderDerivedTranscript(host: ElementLike, doc: DocumentLike, data: TranscriptDataReport): DerivedTranscriptDom {
+  const view = deriveTranscript(data);
+  host.replaceChildren();
+  const root = el(doc, "div", "cockpit-transcript-derived");
+  root.setAttribute("data-stream", data.stream);
+  root.setAttribute("data-lifecycle", view.lifecycle);
+  root.setAttribute("data-turn-count", String(view.turns.length));
+  root.setAttribute("data-message-count", String(view.messages.length));
+  root.setAttribute("data-tool-count", String(view.tools.length));
+
+  if (view.turns.length === 0) {
+    const empty = el(doc, "div", "cockpit-transcript-empty", "No structured events derived — raw replay only.");
+    empty.setAttribute("data-empty", "true");
+    root.appendChild(empty);
+  }
+
+  for (const turn of view.turns) {
+    const section = el(doc, "section", "cockpit-transcript-turn");
+    section.setAttribute("data-turn", String(turn.index));
+    section.setAttribute("data-steps", String(turn.steps));
+    section.appendChild(el(doc, "h3", "cockpit-transcript-turn-title", `Turn ${turn.index}`));
+    for (const msg of turn.messages) {
+      const row = el(doc, "div", "cockpit-transcript-message", msg.text);
+      row.setAttribute("data-role", msg.role);
+      row.setAttribute("data-offset", String(msg.offset));
+      section.appendChild(row);
+    }
+    for (const tool of turn.tools) {
+      const card = el(doc, "div", "cockpit-transcript-tool", tool.name);
+      card.setAttribute("data-tool", tool.name);
+      card.setAttribute("data-offset", String(tool.offset));
+      card.setAttribute("data-status", tool.result === undefined ? "pending" : tool.result.ok ? "ok" : "error");
+      section.appendChild(card);
+    }
+    root.appendChild(section);
+  }
+
+  const footer = el(doc, "footer", "cockpit-transcript-raw");
+  footer.setAttribute("data-raw-bytes", String(view.rawByteLength));
+  footer.setAttribute("data-raw-chunks", String(view.rawChunkCount));
+  footer.textContent = `${view.rawChunkCount} raw chunk(s) · ${view.rawByteLength} B retained for replay`;
+  root.appendChild(footer);
+
+  host.appendChild(root);
+  return { root };
+}

package/app/agentic/transcript-events.drift.test.ts

@@ -0,0 +1,55 @@
+// Drift-guard: exactly ONE parser of the transcript log (ADR 0056, #251).
+//
+// Acceptance criterion (#251): "the cockpit renders from a single derive*() fold, with no independent
+// re-parse of raw bytes (drift-guard test asserts one parser)". This is that guard. It enforces
+// structurally — by scanning the app-tier source — that the raw-chunk → typed-event classification
+// lives in exactly one module (`transcript-events.ts`), so a second, divergent parser of the same
+// bytes cannot creep in. The whole point of the event-sourced model is "the log IS the state": every
+// view derives from the one fold, none re-parses the bytes itself.
+import { test } from "node:test";
+import { readdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { assert, assertEquals } from "#test-assert";
+import { TRANSCRIPT_EVENT_MARKER } from "./transcript-events.ts";
+
+const AGENTIC_DIR = dirname(fileURLToPath(import.meta.url));
+
+/** Every non-test `.ts` source file under app/agentic, recursively. */
+function sourceFiles(dir: string): string[] {
+  const out: string[] = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...sourceFiles(path));
+    else if (entry.name.endsWith(".ts") && !entry.name.endsWith(".test.ts")) out.push(path);
+  }
+  return out;
+}
+
+const PARSER_MODULE = join(AGENTIC_DIR, "transcript-events.ts");
+
+test("the transcript-event marker literal is DEFINED in exactly one module (no second parser)", () => {
+  // Consumers reference the marker via the imported `TRANSCRIPT_EVENT_MARKER` identifier; only the ONE
+  // parser embeds the marker's string literal. A second module hardcoding it would be a second parser.
+  // Match every quote form (double, single, backtick) so a second parser can't bypass the guard by
+  // hardcoding the marker in a different literal style.
+  const quotedMarkerForms = ['"', "'", "`"].map((q) => `${q}${TRANSCRIPT_EVENT_MARKER}${q}`);
+  const owners = sourceFiles(AGENTIC_DIR).filter((path) => {
+    const src = readFileSync(path, "utf8");
+    return quotedMarkerForms.some((literal) => src.includes(literal));
+  });
+  assertEquals(owners, [PARSER_MODULE]);
+});
+
+test("no transcript consumer re-parses raw chunks — JSON.parse of the log lives only in the parser", () => {
+  // The cockpit + read projections must fold through the single parser, never JSON.parse a chunk
+  // themselves. Scan the transcript-facing consumers and assert none contains a raw JSON.parse.
+  const consumers = sourceFiles(AGENTIC_DIR).filter(
+    (path) => path !== PARSER_MODULE && /transcript-(read|render|view|derive|fork)\.ts$/.test(path),
+  );
+  assert(consumers.length >= 3, "expected to scan several transcript consumers");
+  for (const path of consumers) {
+    const src = readFileSync(path, "utf8");
+    assert(!src.includes("JSON.parse"), `${path} must derive through parseTranscriptEvent, not re-parse the log itself`);
+  }
+});

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

@@ -0,0 +1,186 @@
+// Unit tests for the typed transcript-event vocabulary + the single derive() fold (#251).
+//
+// Pins: the ONE parser classifies raw bytes vs typed envelopes (raw fidelity preserved), the core
+// vocabulary decodes each kind, merge-extensibility adds/overrides kinds without a second parser,
+// encode↔parse round-trips, and deriveView folds the log into per-turn structure / message history /
+// tool cards / raw-byte accounting / lifecycle — "the log IS the state".
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import {
+  CORE_TRANSCRIPT_VOCAB,
+  deriveView,
+  deriveViewFromChunks,
+  encodeTranscriptEvent,
+  mergeTranscriptVocab,
+  parseTranscriptEvent,
+  type TranscriptEvent,
+  TRANSCRIPT_EVENT_MARKER,
+  TRANSCRIPT_EVENT_VERSION,
+} from "./transcript-events.ts";
+
+function env(kind: string, extra: Record<string, unknown> = {}): string {
+  return JSON.stringify({ [TRANSCRIPT_EVENT_MARKER]: TRANSCRIPT_EVENT_VERSION, kind, ...extra });
+}
+
+test("parseTranscriptEvent: raw terminal bytes are retained verbatim as a stream-chunk", () => {
+  const event = parseTranscriptEvent({ offset: 3, chunk: "\u001b[32mok\u001b[0m\r\n" });
+  assertEquals(event, { kind: "stream-chunk", offset: 3, chunk: "\u001b[32mok\u001b[0m\r\n" });
+});
+
+test("parseTranscriptEvent: JSON without the marker is NOT mis-classified — stays a raw chunk", () => {
+  const chunk = JSON.stringify({ kind: "message", text: "hi" }); // no marker → raw
+  const event = parseTranscriptEvent({ offset: 0, chunk });
+  assertEquals(event.kind, "stream-chunk");
+});
+
+test("parseTranscriptEvent: a marker envelope with an unknown kind falls back to raw", () => {
+  const event = parseTranscriptEvent({ offset: 0, chunk: env("no-such-kind", { foo: 1 }) });
+  assertEquals(event.kind, "stream-chunk");
+});
+
+test("parseTranscriptEvent: malformed JSON carrying the marker text falls back to raw", () => {
+  const event = parseTranscriptEvent({ offset: 0, chunk: `{"${TRANSCRIPT_EVENT_MARKER}":1, broken` });
+  assertEquals(event.kind, "stream-chunk");
+});
+
+test("core vocab decodes message with role (default assistant)", () => {
+  assertEquals(parseTranscriptEvent({ offset: 1, chunk: env("message", { text: "hello" }) }), {
+    kind: "message",
+    offset: 1,
+    role: "assistant",
+    text: "hello",
+  });
+  assertEquals(parseTranscriptEvent({ offset: 2, chunk: env("message", { role: "user", text: "hi" }) }), {
+    kind: "message",
+    offset: 2,
+    role: "user",
+    text: "hi",
+  });
+});
+
+test("core vocab: a message envelope missing text is rejected → raw fallback", () => {
+  assertEquals(parseTranscriptEvent({ offset: 0, chunk: env("message", { role: "user" }) }).kind, "stream-chunk");
+});
+
+test("core vocab decodes tool-call / tool-result / turn / step / lifecycle", () => {
+  assertEquals(parseTranscriptEvent({ offset: 1, chunk: env("tool-call", { name: "grep", callId: "c1", args: { q: "x" } }) }), {
+    kind: "tool-call",
+    offset: 1,
+    name: "grep",
+    callId: "c1",
+    args: { q: "x" },
+  });
+  assertEquals(parseTranscriptEvent({ offset: 2, chunk: env("tool-result", { callId: "c1", ok: true, content: "found" }) }), {
+    kind: "tool-result",
+    offset: 2,
+    ok: true,
+    callId: "c1",
+    content: "found",
+  });
+  assertEquals(parseTranscriptEvent({ offset: 3, chunk: env("turn", { index: 4 }) }), { kind: "turn", offset: 3, index: 4 });
+  assertEquals(parseTranscriptEvent({ offset: 4, chunk: env("step", { label: "loop" }) }), { kind: "step", offset: 4, label: "loop" });
+  assertEquals(parseTranscriptEvent({ offset: 5, chunk: env("lifecycle", { phase: "completed" }) }), {
+    kind: "lifecycle",
+    offset: 5,
+    phase: "completed",
+  });
+});
+
+test("mergeTranscriptVocab: adds a new kind without forking the parser, and can override a core one", () => {
+  const vocab = mergeTranscriptVocab(CORE_TRANSCRIPT_VOCAB, {
+    // A brand new merge-extensible kind, decoded into a message so deriveView still folds it.
+    reasoning: (body, offset) => ({ kind: "message", offset, role: "system", text: String(body.text ?? "") }),
+  });
+  const event = parseTranscriptEvent({ offset: 7, chunk: env("reasoning", { text: "thinking" }) }, vocab);
+  assertEquals(event, { kind: "message", offset: 7, role: "system", text: "thinking" });
+  // The core vocab is unchanged (merge returns a new object).
+  assertEquals(parseTranscriptEvent({ offset: 7, chunk: env("reasoning", { text: "thinking" }) }).kind, "stream-chunk");
+});
+
+test("encodeTranscriptEvent round-trips every non-raw kind through the one parser", () => {
+  const events: TranscriptEvent[] = [
+    { kind: "message", offset: 0, role: "assistant", text: "hi" },
+    { kind: "tool-call", offset: 1, name: "ls", callId: "c1" },
+    { kind: "tool-result", offset: 2, ok: false, callId: "c1", content: "boom" },
+    { kind: "turn", offset: 3, index: 1 },
+    { kind: "step", offset: 4, label: "s" },
+    { kind: "lifecycle", offset: 5, phase: "exited" },
+  ];
+  for (const original of events) {
+    const chunk = encodeTranscriptEvent(original);
+    assertEquals(parseTranscriptEvent({ offset: original.offset, chunk }), original);
+  }
+});
+
+test("encodeTranscriptEvent returns raw bytes verbatim for a stream-chunk", () => {
+  assertEquals(encodeTranscriptEvent({ kind: "stream-chunk", offset: 0, chunk: "raw" }), "raw");
+});
+
+test("deriveView: folds messages + tool cards into per-turn structure with lifecycle", () => {
+  const events: TranscriptEvent[] = [
+    { kind: "turn", offset: 0, index: 0 },
+    { kind: "message", offset: 1, role: "user", text: "do it" },
+    { kind: "step", offset: 2 },
+    { kind: "tool-call", offset: 3, name: "grep", callId: "c1" },
+    { kind: "tool-result", offset: 4, ok: true, callId: "c1", content: "hit" },
+    { kind: "message", offset: 5, role: "assistant", text: "done" },
+    { kind: "turn", offset: 6, index: 1 },
+    { kind: "message", offset: 7, role: "assistant", text: "next" },
+    { kind: "stream-chunk", offset: 8, chunk: "raw-bytes" },
+    { kind: "lifecycle", offset: 9, phase: "completed" },
+  ];
+  const view = deriveView(events);
+  assertEquals(view.turns.length, 2);
+  assertEquals(view.turns[0]?.messages.map((m) => m.text), ["do it", "done"]);
+  assertEquals(view.turns[0]?.steps, 1);
+  assertEquals(view.turns[0]?.tools.length, 1);
+  assertEquals(view.turns[0]?.tools[0]?.result, { ok: true, offset: 4, content: "hit" });
+  assertEquals(view.turns[1]?.messages.map((m) => m.text), ["next"]);
+  assertEquals(view.messages.length, 3);
+  assertEquals(view.tools.length, 1);
+  assertEquals(view.lifecycle, "completed");
+  assertEquals(view.rawChunkCount, 1);
+  assertEquals(view.rawByteLength, Buffer.byteLength("raw-bytes", "utf8"));
+  assertEquals(view.eventCount, 10);
+});
+
+test("deriveView: content before any turn event opens an implicit turn 0", () => {
+  const view = deriveView([
+    { kind: "message", offset: 0, role: "assistant", text: "hello" },
+    { kind: "tool-call", offset: 1, name: "ls" },
+  ]);
+  assertEquals(view.turns.length, 1);
+  assertEquals(view.turns[0]?.index, 0);
+  assertEquals(view.turns[0]?.messages.length, 1);
+  assertEquals(view.turns[0]?.tools.length, 1);
+});
+
+test("deriveView: an anonymous tool-result pairs with the most recent open anonymous call", () => {
+  const view = deriveView([
+    { kind: "tool-call", offset: 0, name: "a" },
+    { kind: "tool-result", offset: 1, ok: false, content: "nope" },
+  ]);
+  assertEquals(view.tools[0]?.result, { ok: false, offset: 1, content: "nope" });
+});
+
+test("deriveViewFromChunks: an all-raw log derives no structure but full raw fidelity accounting", () => {
+  const view = deriveViewFromChunks([
+    { offset: 0, chunk: "line-1\n" },
+    { offset: 1, chunk: "line-2\n" },
+  ]);
+  assertEquals(view.turns.length, 0);
+  assertEquals(view.messages.length, 0);
+  assertEquals(view.rawChunkCount, 2);
+  assert(view.rawByteLength > 0);
+});
+
+test("deriveViewFromChunks: a mixed log derives typed structure while retaining raw chunks", () => {
+  const view = deriveViewFromChunks([
+    { offset: 0, chunk: env("turn", { index: 0 }) },
+    { offset: 1, chunk: "\u001b[2Jraw frame" },
+    { offset: 2, chunk: env("message", { role: "assistant", text: "hi" }) },
+  ]);
+  assertEquals(view.turns.length, 1);
+  assertEquals(view.messages.map((m) => m.text), ["hi"]);
+  assertEquals(view.rawChunkCount, 1);
+});

package/app/agentic/transcript-events.ts

@@ -0,0 +1,470 @@
+// nano-workforce — the transcript EVENT vocabulary + the single derive() fold (ADR 0056, #251).
+//
+// This is the "event-sourced session" layer over the H3 transcript store (#146/#222). The store is
+// already append-only and offset-keyed — chunks are appended, never mutated — which is half of the
+// dsh (DeepSeek Harness) event-sourced-session pattern. The gap it left is that chunks are opaque
+// `TEXT`: every richer view (structured message history, tool cards, per-turn boundaries, token
+// accounting) had to re-parse the raw frame bytes ad hoc, a DRIFT SURFACE (two parsers of the same
+// bytes), which our "Derivation Over Duplication" doctrine forbids.
+//
+// This module closes that gap the way dsh does: the append-only log of TYPED events is the single
+// source of truth, and every higher-level view is a DERIVATION of that one log via a single
+// {@link deriveView} fold — "the log IS the state, so divergence is structurally impossible". A raw
+// terminal chunk is retained verbatim as a `stream-chunk` event (byte-level replay fidelity is
+// preserved); a producer that emits a structured, marker-tagged JSON envelope is decoded into the
+// authoritative typed events (message / tool-call / tool-result / turn / step / lifecycle) the derived
+// views fold over — mirroring dsh (raw chunks for token-replay, `assistant/message` authoritative).
+//
+// THE ONE PARSER. {@link parseTranscriptEvent} is the SINGLE place a stored chunk is classified into a
+// typed event; every consumer (cockpit, search, token accounting, export) reads the derived view, not
+// the raw bytes. A drift-guard test (`transcript-events.drift.test.ts`) asserts the event marker — and
+// therefore the raw→event parse — appears in exactly this module, so a second parser cannot creep in.
+//
+// MERGE-EXTENSIBLE. The vocabulary is a small core ({@link CORE_TRANSCRIPT_VOCAB}) authors extend in the
+// same schema with {@link mergeTranscriptVocab} (cribbed from dsh's merge-extensible event taxonomy and
+// the S3 `mergeVocab`), so a new event kind is an additive merge, never a fork of the parser.
+//
+// Pure and side-effect-free: no I/O, unit-testable on Node, and it never touches the engine or a BPMN
+// flow (ADR 0056: app-tier only, advisory).
+
+/**
+ * Runtime-safe UTF-8 byte length. This module is imported by cockpit code that runs in the BROWSER
+ * (via `cockpit/transcript-derive.ts`), where Node's `Buffer` global is not available — a bare
+ * `Buffer.byteLength` would throw at runtime when deriving the view for a replayed transcript. Prefer
+ * `Buffer` when present (Node) and fall back to `TextEncoder` (a Web/Node standard) otherwise, so the
+ * single derive fold is portable across both hosts. This is the one canonical UTF-8 byte-length
+ * implementation the transcript plane derives from (reused by `transcript-read.ts`).
+ */
+let cachedTextEncoder: TextEncoder | undefined;
+export function utf8ByteLength(text: string): number {
+  if (typeof Buffer !== "undefined") return Buffer.byteLength(text, "utf8");
+  // Cache one TextEncoder in the browser hot path (folding many stream-chunk events) to avoid
+  // allocating a new encoder — and the GC pressure it creates — on every call.
+  cachedTextEncoder ??= new TextEncoder();
+  return cachedTextEncoder.encode(text).length;
+}
+
+/**
+ * The reserved marker field that distinguishes a structured transcript-event envelope from raw
+ * terminal bytes. A stored chunk is decoded as a typed event ONLY when it is a JSON object carrying
+ * this field set to the schema version — otherwise it is retained verbatim as a raw `stream-chunk`, so
+ * a raw ANSI frame that happens to be valid JSON is never mis-classified. Namespaced to nano-workforce
+ * so it cannot collide with a producer's own payload keys.
+ */
+export const TRANSCRIPT_EVENT_MARKER = "nwfTranscriptEvent" as const;
+
+/** The current transcript-event envelope schema version (the value {@link TRANSCRIPT_EVENT_MARKER} carries). */
+export const TRANSCRIPT_EVENT_VERSION = 1 as const;
+
+/** The core, merge-extensible transcript-event kinds (authors add more via {@link mergeTranscriptVocab}). */
+export type TranscriptEventKind =
+  | "stream-chunk"
+  | "message"
+  | "tool-call"
+  | "tool-result"
+  | "turn"
+  | "step"
+  | "lifecycle";
+
+/** The message roles the derived history distinguishes (assistant is authoritative for derivation). */
+export type TranscriptRole = "assistant" | "user" | "system" | "tool";
+
+/** Fields every typed event carries: its kind and the store offset it was decoded from. */
+interface TranscriptEventBase {
+  readonly offset: number;
+}
+
+/** A raw terminal chunk retained verbatim for byte-level replay fidelity (the default classification). */
+export interface StreamChunkEvent extends TranscriptEventBase {
+  readonly kind: "stream-chunk";
+  /** The exact stored bytes — unmodified, so raw-byte replay stays faithful. */
+  readonly chunk: string;
+}
+
+/** An assistant/user/system message — authoritative for the derived message history. */
+export interface MessageEvent extends TranscriptEventBase {
+  readonly kind: "message";
+  readonly role: TranscriptRole;
+  readonly text: string;
+}
+
+/** A tool invocation the agent issued. */
+export interface ToolCallEvent extends TranscriptEventBase {
+  readonly kind: "tool-call";
+  readonly name: string;
+  /** A stable id linking this call to its {@link ToolResultEvent}, when the producer supplies one. */
+  readonly callId?: string;
+  readonly args?: unknown;
+}
+
+/** A tool result, paired back to its {@link ToolCallEvent} by `callId` (else the most recent open call). */
+export interface ToolResultEvent extends TranscriptEventBase {
+  readonly kind: "tool-result";
+  readonly callId?: string;
+  readonly ok: boolean;
+  readonly content?: string;
+}
+
+/** A turn boundary — the start of a new request/response cycle. */
+export interface TurnEvent extends TranscriptEventBase {
+  readonly kind: "turn";
+  /** The producer's turn index, when supplied (else derived positionally). */
+  readonly index?: number;
+}
+
+/** A step boundary within a turn (a tool loop iteration, a sub-agent hop, …). */
+export interface StepEvent extends TranscriptEventBase {
+  readonly kind: "step";
+  readonly label?: string;
+}
+
+/** A session lifecycle transition (open → completed, or an explicit exit). */
+export interface LifecycleEvent extends TranscriptEventBase {
+  readonly kind: "lifecycle";
+  readonly phase: "open" | "completed" | "exited";
+}
+
+/** The core typed transcript-event union (merge-extensible: authors add kinds via the vocab). */
+export type TranscriptEvent =
+  | StreamChunkEvent
+  | MessageEvent
+  | ToolCallEvent
+  | ToolResultEvent
+  | TurnEvent
+  | StepEvent
+  | LifecycleEvent;
+
+/** A stored chunk as the store/read path exposes it (mirrors `TranscriptChunk`). */
+export interface StoredChunk {
+  readonly offset: number;
+  readonly chunk: string;
+}
+
+/**
+ * A decoder for one event kind: given the parsed envelope body and the chunk offset, it returns the
+ * typed event (or `undefined` to reject a malformed envelope, which then falls back to `stream-chunk`).
+ * A vocabulary is the map kind → decoder; {@link mergeTranscriptVocab} extends it additively.
+ */
+export type TranscriptEventDecoder = (body: Record<string, unknown>, offset: number) => TranscriptEvent | undefined;
+
+/** A transcript-event vocabulary: the ONE registry of kind → decoder the single parser consults. */
+export type TranscriptVocab = Readonly<Record<string, TranscriptEventDecoder>>;
+
+function str(body: Record<string, unknown>, key: string): string | undefined {
+  const v = body[key];
+  return typeof v === "string" ? v : undefined;
+}
+
+function num(body: Record<string, unknown>, key: string): number | undefined {
+  const v = body[key];
+  return typeof v === "number" && Number.isFinite(v) ? v : undefined;
+}
+
+const ROLES: readonly TranscriptRole[] = ["assistant", "user", "system", "tool"];
+
+/** Narrow an arbitrary string to a known {@link TranscriptRole}, defaulting to `assistant`. */
+function toRole(value: string | undefined): TranscriptRole {
+  return ROLES.find((role) => role === value) ?? "assistant";
+}
+
+/** A structural guard: a non-null, non-array object is a plain record of unknown values. */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * The opinionated core vocabulary — the built-in event kinds every consumer understands out of the
+ * box. Authors extend it in the SAME schema via {@link mergeTranscriptVocab}; they never fork the
+ * parser. (`stream-chunk` is not decoded here — it is the fallback the parser applies to any chunk
+ * that is not a well-formed typed envelope, so raw fidelity needs no decoder.)
+ */
+export const CORE_TRANSCRIPT_VOCAB: TranscriptVocab = Object.freeze({
+  message: (body, offset) => {
+    const text = str(body, "text");
+    if (text === undefined) return undefined;
+    const roleRaw = str(body, "role");
+    return { kind: "message", offset, role: toRole(roleRaw), text };
+  },
+  "tool-call": (body, offset) => {
+    const name = str(body, "name");
+    if (name === undefined) return undefined;
+    const event: ToolCallEvent = { kind: "tool-call", offset, name };
+    const callId = str(body, "callId");
+    return {
+      ...event,
+      ...(callId !== undefined ? { callId } : {}),
+      ...("args" in body ? { args: body.args } : {}),
+    };
+  },
+  "tool-result": (body, offset) => {
+    const ok = typeof body.ok === "boolean" ? body.ok : true;
+    const event: ToolResultEvent = { kind: "tool-result", offset, ok };
+    const callId = str(body, "callId");
+    const content = str(body, "content");
+    return {
+      ...event,
+      ...(callId !== undefined ? { callId } : {}),
+      ...(content !== undefined ? { content } : {}),
+    };
+  },
+  turn: (body, offset) => {
+    const index = num(body, "index");
+    return index !== undefined ? { kind: "turn", offset, index } : { kind: "turn", offset };
+  },
+  step: (body, offset) => {
+    const label = str(body, "label");
+    return label !== undefined ? { kind: "step", offset, label } : { kind: "step", offset };
+  },
+  lifecycle: (body, offset) => {
+    const phase = str(body, "phase");
+    if (phase !== "open" && phase !== "completed" && phase !== "exited") return undefined;
+    return { kind: "lifecycle", offset, phase };
+  },
+});
+
+/**
+ * Extend a vocabulary additively: later entries win on a key clash, so an author can either register a
+ * brand-new kind or deliberately override a core decoder. Returns a NEW frozen vocab — neither input is
+ * mutated — so the core stays canonical. (Cribbed from dsh's merge-extensible taxonomy / the S3
+ * `mergeVocab`: one schema, extended by merge, never a second parser.)
+ */
+export function mergeTranscriptVocab(base: TranscriptVocab, ...extensions: TranscriptVocab[]): TranscriptVocab {
+  return Object.freeze(Object.assign({}, base, ...extensions));
+}
+
+/**
+ * THE ONE PARSER. Classify a single stored chunk into a typed {@link TranscriptEvent}.
+ *
+ * A chunk is decoded as a structured event ONLY when it is a JSON object carrying the
+ * {@link TRANSCRIPT_EVENT_MARKER} at the current version AND a `kind` the vocab knows AND its decoder
+ * accepts the body. Anything else — raw terminal bytes, non-JSON, a JSON value without the marker, an
+ * unknown kind, a decoder rejection — is retained verbatim as a `stream-chunk`, so byte-level replay
+ * fidelity is never lost. This is the SINGLE point at which raw bytes become typed events; every view
+ * folds over the result of this function, so there is exactly one parser of the log.
+ */
+export function parseTranscriptEvent(
+  entry: StoredChunk,
+  vocab: TranscriptVocab = CORE_TRANSCRIPT_VOCAB,
+): TranscriptEvent {
+  const raw: StreamChunkEvent = { kind: "stream-chunk", offset: entry.offset, chunk: entry.chunk };
+  const body = decodeEnvelope(entry.chunk);
+  if (body === undefined) return raw;
+  const kind = typeof body.kind === "string" ? body.kind : undefined;
+  if (kind === undefined) return raw;
+  const decoder = vocab[kind];
+  if (decoder === undefined) return raw;
+  return decoder(body, entry.offset) ?? raw;
+}
+
+/**
+ * Decode a chunk into a marker-tagged envelope body, or `undefined` when it is not one. Kept private
+ * so `JSON.parse` of a chunk lives in exactly one place (the drift-guard depends on this).
+ */
+function decodeEnvelope(chunk: string): Record<string, unknown> | undefined {
+  // Cheap reject before the parse: a valid envelope is a JSON object mentioning the marker key.
+  const trimmed = chunk.trimStart();
+  if (!trimmed.startsWith("{") || !chunk.includes(TRANSCRIPT_EVENT_MARKER)) return undefined;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(chunk);
+  } catch {
+    return undefined;
+  }
+  if (!isRecord(parsed)) return undefined;
+  return parsed[TRANSCRIPT_EVENT_MARKER] === TRANSCRIPT_EVENT_VERSION ? parsed : undefined;
+}
+
+/**
+ * Encode a typed event into the stored-chunk wire form a structured producer appends. The inverse of
+ * {@link parseTranscriptEvent} for every non-raw kind (a `stream-chunk` is stored as its own raw bytes,
+ * so it is returned verbatim). Provided so producers and tests speak the one envelope grammar rather
+ * than hand-rolling the marker — the derivation-over-duplication rule applied to the write side too.
+ */
+export function encodeTranscriptEvent(event: TranscriptEvent): string {
+  if (event.kind === "stream-chunk") return event.chunk;
+  const { offset: _offset, ...rest } = event;
+  return JSON.stringify({ [TRANSCRIPT_EVENT_MARKER]: TRANSCRIPT_EVENT_VERSION, ...rest });
+}
+
+/** A derived tool card: a tool-call paired with its result (result absent while the call is pending). */
+export interface DerivedTool {
+  readonly name: string;
+  readonly callId?: string;
+  readonly args?: unknown;
+  readonly offset: number;
+  readonly result?: { readonly ok: boolean; readonly content?: string; readonly offset: number };
+}
+
+/** A derived message in the folded history. */
+export interface DerivedMessage {
+  readonly role: TranscriptRole;
+  readonly text: string;
+  readonly offset: number;
+}
+
+/** A derived turn: the messages, tool cards and step count folded within one turn boundary. */
+export interface DerivedTurn {
+  readonly index: number;
+  readonly startOffset: number;
+  readonly messages: readonly DerivedMessage[];
+  readonly tools: readonly DerivedTool[];
+  readonly steps: number;
+}
+
+/** The single derived view every higher-level consumer reads instead of re-parsing raw bytes. */
+export interface DerivedView {
+  /** The per-turn structure (a turn is opened implicitly before the first turn event, if any content precedes it). */
+  readonly turns: readonly DerivedTurn[];
+  /** Every message across all turns, in offset order (the flat derived history). */
+  readonly messages: readonly DerivedMessage[];
+  /** Every tool card across all turns, in offset order. */
+  readonly tools: readonly DerivedTool[];
+  /** Total retained raw bytes (UTF-8) across `stream-chunk` events — the byte-replay fidelity accounting. */
+  readonly rawByteLength: number;
+  /** Number of retained raw chunks. */
+  readonly rawChunkCount: number;
+  /** The session lifecycle as the last lifecycle event reports it (defaults to `open`). */
+  readonly lifecycle: "open" | "completed" | "exited";
+  /** Number of typed events folded. */
+  readonly eventCount: number;
+}
+
+interface MutableTurn {
+  index: number;
+  startOffset: number;
+  messages: DerivedMessage[];
+  tools: DerivedTool[];
+  steps: number;
+}
+
+/**
+ * THE SINGLE FOLD. Derive every higher-level view from the typed event log — "the log IS the state".
+ *
+ * Folds the events (assumed in offset order — the store's append order) into per-turn structure, a flat
+ * message history, tool cards (each call paired to its result by `callId`, else the most recent open
+ * call), raw-byte accounting for replay fidelity, and the session lifecycle. It is a pure reduction of
+ * one log: the cockpit, search, token accounting and export all read THIS, so there is never a second
+ * parser of the same bytes. Content that precedes the first explicit `turn` event opens an implicit
+ * turn 0, so a producer that never emits turn boundaries still derives a coherent single-turn view.
+ */
+export function deriveView(events: Iterable<TranscriptEvent>): DerivedView {
+  const turns: MutableTurn[] = [];
+  const messages: DerivedMessage[] = [];
+  const tools: DerivedTool[] = [];
+  const openTools = new Map<string, DerivedTool>();
+  let anonymousTool: DerivedTool | undefined;
+  let rawByteLength = 0;
+  let rawChunkCount = 0;
+  let lifecycle: "open" | "completed" | "exited" = "open";
+  let eventCount = 0;
+  let current: MutableTurn | undefined;
+
+  const ensureTurn = (offset: number): MutableTurn => {
+    if (current === undefined) {
+      current = { index: turns.length, startOffset: offset, messages: [], tools: [], steps: 0 };
+      turns.push(current);
+    }
+    return current;
+  };
+
+  for (const event of events) {
+    eventCount++;
+    switch (event.kind) {
+      case "turn": {
+        current = { index: event.index ?? turns.length, startOffset: event.offset, messages: [], tools: [], steps: 0 };
+        turns.push(current);
+        break;
+      }
+      case "step": {
+        ensureTurn(event.offset).steps++;
+        break;
+      }
+      case "message": {
+        const msg: DerivedMessage = { role: event.role, text: event.text, offset: event.offset };
+        messages.push(msg);
+        ensureTurn(event.offset).messages.push(msg);
+        break;
+      }
+      case "tool-call": {
+        const tool: DerivedTool = {
+          name: event.name,
+          offset: event.offset,
+          ...(event.callId !== undefined ? { callId: event.callId } : {}),
+          ...(event.args !== undefined ? { args: event.args } : {}),
+        };
+        tools.push(tool);
+        ensureTurn(event.offset).tools.push(tool);
+        if (event.callId !== undefined) openTools.set(event.callId, tool);
+        else anonymousTool = tool;
+        break;
+      }
+      case "tool-result": {
+        const target = event.callId !== undefined ? openTools.get(event.callId) : anonymousTool;
+        if (target !== undefined) {
+          pairResult(tools, target, event);
+          pairResultInTurns(turns, target, event);
+          if (event.callId !== undefined) openTools.delete(event.callId);
+          else anonymousTool = undefined;
+        }
+        break;
+      }
+      case "lifecycle": {
+        lifecycle = event.phase;
+        break;
+      }
+      case "stream-chunk": {
+        rawByteLength += utf8ByteLength(event.chunk);
+        rawChunkCount++;
+        break;
+      }
+    }
+  }
+
+  return {
+    turns: turns.map((t) => ({ index: t.index, startOffset: t.startOffset, messages: t.messages, tools: t.tools, steps: t.steps })),
+    messages,
+    tools,
+    rawByteLength,
+    rawChunkCount,
+    lifecycle,
+    eventCount,
+  };
+}
+
+/** Replace a pending tool with its result in the flat list. A pending tool starts as the same object in
+ * both the flat list and its turn (pushed by reference), so {@link pairResultInTurns} locates it there by
+ * identity; each list is then replaced independently with its own resolved copy via {@link withResult}. */
+function pairResult(list: DerivedTool[], target: DerivedTool, result: ToolResultEvent): void {
+  const idx = list.indexOf(target);
+  if (idx >= 0) list[idx] = withResult(target, result);
+}
+
+/** Replace a pending tool with its result inside whichever turn holds it. */
+function pairResultInTurns(turns: MutableTurn[], target: DerivedTool, result: ToolResultEvent): void {
+  for (const turn of turns) {
+    const idx = turn.tools.indexOf(target);
+    if (idx >= 0) {
+      turn.tools[idx] = withResult(target, result);
+      return;
+    }
+  }
+}
+
+function withResult(tool: DerivedTool, result: ToolResultEvent): DerivedTool {
+  return {
+    ...tool,
+    result: { ok: result.ok, offset: result.offset, ...(result.content !== undefined ? { content: result.content } : {}) },
+  };
+}
+
+/**
+ * Convenience: parse a run of stored chunks into typed events through {@link parseTranscriptEvent} (the
+ * one parser) and fold them with {@link deriveView} in a single call — the entry point a consumer uses
+ * to go from stored bytes to a derived view without ever touching a second parser.
+ */
+export function deriveViewFromChunks(chunks: Iterable<StoredChunk>, vocab: TranscriptVocab = CORE_TRANSCRIPT_VOCAB): DerivedView {
+  function* parsed(): Generator<TranscriptEvent> {
+    for (const entry of chunks) yield parseTranscriptEvent(entry, vocab);
+  }
+  return deriveView(parsed());
+}

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

@@ -0,0 +1,156 @@
+// Unit tests for replay-by-reseed / fork of a transcript log (#251).
+//
+// Uses a real TranscriptStore over an in-memory node:sqlite db (the same double the relay-family suite
+// uses), so the fork is exercised against the store's real idempotent, offset-keyed record/read path.
+import { test } from "node:test";
+import { DatabaseSync } from "node:sqlite";
+import { type SqliteDb, TranscriptStore } from "@nanobpm/agentic/transcript";
+import { assert, assertEquals, assertThrows } from "#test-assert";
+import { forkTranscript, TranscriptForkError } from "./transcript-fork.ts";
+
+/** An in-memory {@link SqliteDb} over `node:sqlite`, matching the store's exec/run/all surface. */
+function memoryDb(): SqliteDb {
+  const raw = new DatabaseSync(":memory:");
+  return {
+    exec: (sql) => raw.exec(sql),
+    run: (sql, params = []) => raw.prepare(sql).run(...params),
+    all: <T = Record<string, unknown>>(sql: string, params: unknown[] = []): T[] => raw.prepare(sql).all(...params) as T[],
+  };
+}
+
+function seededStore(): TranscriptStore {
+  const store = new TranscriptStore(memoryDb());
+  store.ensureSchema();
+  return store;
+}
+
+/** Record chunks c0..c(n-1) into `stream` and complete it (an "exited" ephemeral session). */
+function recordExited(store: TranscriptStore, stream: string, n: number): void {
+  const entries = Array.from({ length: n }, (_, i) => ({ offset: i, chunk: `c${i}` }));
+  store.record(stream, entries, "ephemeral");
+  // Complete via a flush of a ring that reports the whole window, marking the stream completed.
+  store.flush(stream, { since: () => ({ entries }), nextOffset: n }, "ephemeral");
+}
+
+test("forkTranscript: seeds a new stream from the whole source log, offset-parity preserved", () => {
+  const store = seededStore();
+  recordExited(store, "job:src", 4);
+
+  const result = forkTranscript(store, "job:src", "fork:a");
+  assertEquals(result.seeded, 4);
+  assertEquals(result.throughOffset, 3);
+  assertEquals(result.stream, "fork:a");
+  // The fork replays the identical chunks at the identical offsets.
+  assertEquals(store.read("fork:a"), [
+    { offset: 0, chunk: "c0" },
+    { offset: 1, chunk: "c1" },
+    { offset: 2, chunk: "c2" },
+    { offset: 3, chunk: "c3" },
+  ]);
+});
+
+test("forkTranscript: throughOffset seeds only the prefix up to (and including) N", () => {
+  const store = seededStore();
+  recordExited(store, "job:src", 5);
+
+  const result = forkTranscript(store, "job:src", "fork:b", { throughOffset: 2 });
+  assertEquals(result.seeded, 3);
+  assertEquals(result.throughOffset, 2);
+  assertEquals(
+    store.read("fork:b").map((c) => c.offset),
+    [0, 1, 2],
+  );
+});
+
+test("forkTranscript: the branch is independent — appending to the source never touches the fork", () => {
+  const store = seededStore();
+  recordExited(store, "job:src", 3);
+  forkTranscript(store, "job:src", "fork:c", { throughOffset: 1, lifecycle: "long-lived" });
+
+  // Continue the fork with a divergent chunk, and separately grow a long-lived source.
+  store.record("fork:c", [{ offset: 2, chunk: "branch-continuation" }], "long-lived");
+  assertEquals(
+    store.read("fork:c").map((c) => c.chunk),
+    ["c0", "c1", "branch-continuation"],
+  );
+  // The source is untouched by the fork's divergence.
+  assertEquals(
+    store.read("job:src").map((c) => c.chunk),
+    ["c0", "c1", "c2"],
+  );
+});
+
+test("forkTranscript: a fork replays through the SAME resume-from-offset (since) path as a native stream", () => {
+  const store = seededStore();
+  recordExited(store, "job:src", 4);
+  forkTranscript(store, "job:src", "fork:d");
+
+  const slice = store.since("fork:d", 2);
+  assertEquals(slice.gap, false);
+  assertEquals(
+    slice.entries.map((c) => c.offset),
+    [2, 3],
+  );
+});
+
+test("forkTranscript: throughOffset below the log yields an empty — but real, listed — fork", () => {
+  const store = seededStore();
+  recordExited(store, "job:src", 3);
+
+  const result = forkTranscript(store, "job:src", "fork:empty", { throughOffset: -1 });
+  assertEquals(result.seeded, 0);
+  assertEquals(result.throughOffset, undefined);
+  assert(store.get("fork:empty") !== undefined);
+  assertEquals(store.read("fork:empty"), []);
+});
+
+test("forkTranscript: refuses to fork a missing source", () => {
+  const store = seededStore();
+  assertThrows(() => forkTranscript(store, "job:nope", "fork:x"), TranscriptForkError, "no transcript");
+});
+
+test("forkTranscript: refuses an existing target unless allowExisting is set", () => {
+  const store = seededStore();
+  recordExited(store, "job:src", 2);
+  forkTranscript(store, "job:src", "fork:e");
+
+  assertThrows(() => forkTranscript(store, "job:src", "fork:e"), TranscriptForkError, "already exists");
+  // With allowExisting the reseed is an idempotent no-op (offset-keyed record).
+  const again = forkTranscript(store, "job:src", "fork:e", { allowExisting: true });
+  assertEquals(again.seeded, 0);
+});
+
+test("forkTranscript: allowExisting refuses a target whose contents diverge from the reseed prefix", () => {
+  const store = seededStore();
+  recordExited(store, "job:src", 3);
+  // A pre-existing target that carries DIFFERENT bytes at an overlapping offset — reseeding here would
+  // leave an interleaved mixture (offset-keyed record silently no-ops the divergent offset).
+  store.record("fork:diverge", [{ offset: 0, chunk: "not-c0" }], "ephemeral");
+  assertThrows(
+    () => forkTranscript(store, "job:src", "fork:diverge", { allowExisting: true }),
+    TranscriptForkError,
+    "does not match the reseed prefix",
+  );
+  // The target is left untouched — no partial interleave.
+  assertEquals(
+    store.read("fork:diverge").map((c) => c.chunk),
+    ["not-c0"],
+  );
+});
+
+test("forkTranscript: allowExisting refuses a target opened under a different lifecycle", () => {
+  const store = seededStore();
+  recordExited(store, "job:src", 2);
+  store.open("fork:lc", "long-lived");
+  assertThrows(
+    () => forkTranscript(store, "job:src", "fork:lc", { allowExisting: true }),
+    TranscriptForkError,
+    "cannot reseed",
+  );
+});
+
+test("forkTranscript: refuses to fork a stream onto itself", () => {
+  const store = seededStore();
+  recordExited(store, "job:src", 1);
+  assertThrows(() => forkTranscript(store, "job:src", "job:src"), TranscriptForkError, "onto itself");
+});

package/app/agentic/transcript-fork.ts

@@ -0,0 +1,151 @@
+// nano-workforce — replay-by-reseed / fork of a transcript log (ADR 0056, #251).
+//
+// The H3 read path (#222) can RESUME the same stream from an offset (reattach parity), but it cannot
+// FORK: seed a NEW stream from an existing log so an exited agent's session can be branched or re-run
+// from a chosen point ("what-if" a different continuation). dsh gets this for free because a session IS
+// its append-only log, so forking is just re-seeding a new session from an existing log up to offset N.
+// This module gives the transcript store the same capability WITHOUT touching the store package: it
+// reads the source log and re-records it into a fresh stream through the store's own idempotent,
+// offset-keyed {@link TranscriptStore.record} — so the fork is itself append-only and offset-parity
+// with its source, and replays through the SAME resume-from-offset read path a native stream uses.
+//
+// Invariants preserved (ADR 0056): app-tier only, append-only (we only ever `record`, never mutate),
+// advisory (a fork is a new advisory transcript — it gates no BPMN flow), and offset/resume wire-shape
+// parity (the fork keeps the source offsets, so a reattach behaves identically on the branch).
+
+import type { TranscriptChunk, TranscriptLifecycle, TranscriptStore, TranscriptStream } from "@nanobpm/agentic/transcript";
+
+/** Raised when a fork/reseed cannot proceed — the source is missing, or the target already exists. */
+export class TranscriptForkError extends Error {
+  readonly source: string;
+  readonly target: string;
+  constructor(source: string, target: string, message: string) {
+    super(message);
+    this.name = "TranscriptForkError";
+    this.source = source;
+    this.target = target;
+  }
+}
+
+/** Options controlling how a source log is reseeded into a new stream. */
+export interface ForkTranscriptOptions {
+  /**
+   * Seed only chunks with `offset <= throughOffset` (inclusive) — the point the branch diverges from.
+   * Omit to fork the WHOLE source log (every retained chunk). A `throughOffset` below the source's
+   * oldest retained offset yields an empty fork (a valid, if trivial, branch point).
+   */
+  readonly throughOffset?: number;
+  /**
+   * The forked stream's retention lifecycle. Defaults to `ephemeral` — a fork is a captured branch,
+   * retained-whole then swept like any completed session, not a growing live stream.
+   */
+  readonly lifecycle?: TranscriptLifecycle;
+  /**
+   * Allow reseeding into a target that already exists. Off by default: forking onto a populated stream
+   * would interleave two logs' bytes and defeat offset-parity, so we refuse rather than clobber. When
+   * on, seeding is still idempotent (offset-keyed), so re-running the SAME fork is a safe no-op — but
+   * the existing target must already hold exactly this seed prefix (same offsets, same chunk bytes,
+   * same lifecycle); a target that diverges from the prefix throws rather than silently interleaving.
+   */
+  readonly allowExisting?: boolean;
+}
+
+/** The outcome of a {@link forkTranscript}: the new stream, how many chunks it seeded, and its window. */
+export interface ForkResult {
+  /** The forked stream id (the `target` argument). */
+  readonly stream: string;
+  /** The source stream the fork was seeded from. */
+  readonly source: string;
+  /** Number of chunks newly persisted into the fork. */
+  readonly seeded: number;
+  /** The highest source offset included in the fork (undefined when the fork is empty). */
+  readonly throughOffset?: number;
+  /** The forked stream's metadata after seeding. */
+  readonly meta: TranscriptStream;
+}
+
+/**
+ * Fork a transcript: seed a NEW stream (`target`) from an existing log (`source`) up to a chosen offset,
+ * so an exited session can be branched and replayed independently.
+ *
+ * The fork keeps the SOURCE offsets (offset-parity), so it resumes through the identical
+ * resume-from-offset read path a native stream uses. It reads the source's retained window
+ * (`store.read`), takes the prefix at or below `throughOffset` (default: the whole log), and re-records
+ * it into `target` via the store's idempotent offset-keyed `record` — so the operation is append-only
+ * and safe to re-run. The branch is fully independent of its source thereafter: appending to either
+ * stream never affects the other.
+ *
+ * Throws {@link TranscriptForkError} when the source has no transcript, when the target already
+ * exists and `allowExisting` is not set, or when `allowExisting` is set but the existing target does
+ * not already match the reseed prefix exactly (divergent chunk bytes/offsets or a different lifecycle).
+ */
+export function forkTranscript(
+  store: TranscriptStore,
+  source: string,
+  target: string,
+  options: ForkTranscriptOptions = {},
+): ForkResult {
+  if (source === target) {
+    throw new TranscriptForkError(source, target, "cannot fork a stream onto itself");
+  }
+  if (store.get(source) === undefined) {
+    throw new TranscriptForkError(source, target, `source stream "${source}" has no transcript to fork`);
+  }
+  const existing = store.get(target);
+  if (existing !== undefined && !options.allowExisting) {
+    throw new TranscriptForkError(source, target, `target stream "${target}" already exists (pass allowExisting to reseed it)`);
+  }
+
+  const lifecycle: TranscriptLifecycle = options.lifecycle ?? "ephemeral";
+  const through = options.throughOffset;
+  const chunks: TranscriptChunk[] = store
+    .read(source)
+    .filter((c) => through === undefined || c.offset <= through);
+
+  // Reseeding onto an EXISTING target (allowExisting) is only safe when that target already holds
+  // exactly the prefix we are about to seed. `record()` is offset-keyed and idempotent, so it silently
+  // no-ops any offset already present — if the existing chunk at that offset differs (or the target
+  // carries offsets outside this prefix, or a different lifecycle), the reseed would leave a stream
+  // that is a MIXTURE of the prior data and the seed, breaking the documented offset-parity invariant.
+  // Validate the overlap before writing and refuse rather than clobber/interleave.
+  if (existing !== undefined) {
+    if (existing.lifecycle !== lifecycle) {
+      throw new TranscriptForkError(
+        source,
+        target,
+        `target stream "${target}" already exists with lifecycle "${existing.lifecycle}", cannot reseed as "${lifecycle}"`,
+      );
+    }
+    const seedByOffset = new Map(chunks.map((c) => [c.offset, c.chunk]));
+    for (const c of store.read(target)) {
+      const expected = seedByOffset.get(c.offset);
+      if (expected === undefined || expected !== c.chunk) {
+        throw new TranscriptForkError(
+          source,
+          target,
+          `target stream "${target}" already contains data that does not match the reseed prefix at offset ${c.offset}; refusing to interleave`,
+        );
+      }
+    }
+  }
+
+  // Open the fork explicitly so an empty fork (throughOffset predating the log) is still a real,
+  // listed stream under its own lifecycle rather than a phantom — mirrors the store's open-then-record.
+  store.open(target, lifecycle);
+  const seeded = chunks.length > 0 ? store.record(target, chunks, lifecycle) : 0;
+
+  const meta = store.get(target);
+  if (meta === undefined) {
+    // Defensive: open() above guarantees a row, so this only fires on a store contract breach.
+    throw new TranscriptForkError(source, target, `fork of "${source}" into "${target}" did not persist a stream`);
+  }
+
+  const result: ForkResult = {
+    stream: target,
+    source,
+    seeded,
+    meta,
+  };
+  const last = chunks.at(-1);
+  return last !== undefined ? { ...result, throughOffset: last.offset } : result;
+}

package/app/agentic/transcript-read.ts

@@ -17,11 +17,12 @@
 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";
+import { utf8ByteLength } from "./transcript-events.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");
+  for (const c of chunks) total += utf8ByteLength(c.chunk);
   return total;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.78.0",
+  "version": "0.79.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",