@nanobpm/nano-workforce 0.77.0 → 0.79.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [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)
+
+
+### Features
+
+* converge the merge-loop escalation onto one native user-task pathway ([#256](https://github.com/nanobpm/nano-workforce/issues/256)) ([#257](https://github.com/nanobpm/nano-workforce/issues/257)) ([16551ee](https://github.com/nanobpm/nano-workforce/commit/16551ee59015081dcf20294ffdd05a078564b775))
+
 # [0.77.0](https://github.com/nanobpm/nano-workforce/compare/v0.76.0...v0.77.0) (2026-08-17)
 
 

package/SPEC.md

@@ -103,19 +103,22 @@ known at submit time, carried as a process variable and stored on the DB row.
 │      │                     ├── review-ready (msg catch, key = prKey) → round++ ─────┐
 │      │                     └── =reviewWaitTimeout (timer catch)                     │
 │      │                          → [Escalate: review stalled] (blocked)              │
-│      │                          → [Wait: escalation-answered] ──────────────────────┤
+│      │                          → [Wait: wait-answer userTask] ─────────────────────┤
 │      │                                                                             │
 │      └── needs_input     [Record escalation]                       │               │
 │          or blocked  →   (kind = question | blocker)               │               │
-│                          → [Wait: escalation-answered] (msg catch) │               │
+│                          → [Wait: wait-answer userTask]            │               │
+│                          → [record-answer: pr.answer-escalation]   │               │
 │                          → set answer ──────────────────────────────┤               │
 │                                                                    │               │
 └────────────────────────────────────────────────────────────────────┴───────────────┘
 
 Both `needs_input` (the agent has a question) and `blocked` (the agent is stuck
 on something external — auth, a failing push, a missing secret) route to the
-**same escalation path**: record it, sleep at `escalation-answered`, then retry
-the same round with the human's `answer`. They differ only by escalation `kind`,
+**same escalation path**: record it, park on the native `wait-answer` user task
+(answered through the canonical `completeUserTask` door and surfaced in the Tasks
+inbox), reconcile the answer via the `record-answer` (`pr.answer-escalation`)
+step, then retry the same round with the human's `answer`. They differ only by escalation `kind`,
 which the UI uses to label the card. Neither ends the run — a human always gets
 a chance to unblock and resume.
 
@@ -200,16 +203,15 @@ Consequences the prompt (`resources/prompts/review-round.md`) encodes:
 |---|---|---|---|
 | `pr-submitted` | — (start) | submit route/webhook | `{repo, prNumber, prUrl, prKey}` |
 | `review-ready` | `prKey` | **poller** | `{reviewId, reviewState, submittedAt}` |
-| `escalation-answered` | `prKey` | merge-loop answer (`answerEscalation`) | `{answer, escalationId}` |
 | `deps-cleared` | `prKey` | **poller** (merge) | — (all `Depends-on` PRs merged) |
 | `merge-ready` | `prKey` | **poller** (merge) | `{mergeState}` (`ready` \| `conflict` \| `blocked`); when `blocked`, also `{failingChecks, failingChecksList}` for the `senior:fix-ci` branch |
 | `merge-landed` | `prKey` | **poller** (merge) | — (queued PR merged, or merged out-of-band) |
 
-Note `escalation-answered` is now used only by the `merge-loop` process (the
-`convergence-loop` review escalation is a native `userTask` answered through the
-task inbox, not this message). The merge-loop `.bpmn` gives it a distinct message
-**id** (and distinct envelope shape ids) to avoid duplicate-id collisions when the
-manifest deploys both files.
+The `escalation-answered` message was retired (#256): the merge-loop escalation is
+now a native `wait-merge-answer` `userTask`, exactly like the `convergence-loop`
+review escalation (`wait-answer`). Both are answered through the ONE canonical
+`completeUserTask` door and surface in the Tasks inbox — there is no longer a
+merge-only message pathway.
 
 ## 7. Domain model (SQLite — `db/migrations/001_init.sql`) — PROPOSED
 
@@ -287,8 +289,8 @@ The full, authoritative contract is `openapi.yaml` (Swagger UI at
 | `GET` | `/app/api/version` | app + engine version |
 | `POST` | `/app/api/actions/start/convergence-loop` | parse the PR ref → create the aggregate + start the process (the ONE submit door — page + external callers) |
 | `POST` | `/app/api/actions/start/plan-fanout` | parse the issue ref → start a plan fan-out run (the ONE plan door) |
-| `POST` | `/app/api/actions/message` (`escalation-answered`) | answer an open merge-loop escalation → publish `escalation-answered` (the four #156 escalation kinds are native user tasks answered via the task inbox) |
-| `POST` | `/app/api/actions/complete-user-task` | complete an open native user-task escalation from the Tasks page (plan-review / trial-merge / PR `wait-answer`) → `completeEscalationAsHuman` (the same resume path the task inbox uses) |
+| `POST` | `/app/api/actions/message` | publish a BPMN message (optionally correlated) into the engine (generic; every escalation kind is now answered via `/actions/complete-user-task`) |
+| `POST` | `/app/api/actions/complete-user-task` | complete an open native user-task escalation from the Tasks page (plan-review / trial-merge / PR `wait-answer` / PR merge `wait-merge-answer`) → `completeEscalationAsHuman` (the same resume path the task inbox uses) |
 | `GET`/`POST` | `/app/api/hooks/blackboard` | per-plan coordination blackboard (capability-token side-channel) |
 | `GET` | `/app/api/hooks/abandon` | cooperative abandon check (per-PR capability token) |
 
@@ -401,7 +403,7 @@ start ─► wait: deps merged ─► arm merge ─► wait: mergeable ─┬─
                                                         └─ could not fix ─► escalate ─┐               │             │
                                                                                       ▼               ▼             ▼
                                                              wait: answered ─► (re-arm) ◄──────── (all escalations)
-                                                                   (escalation-answered)
+                                                            (wait-merge-answer userTask)
 ```
 
 - **CI auto-fix** — a `blocked` verdict means a **required check failed**
@@ -438,7 +440,8 @@ start ─► wait: deps merged ─► arm merge ─► wait: mergeable ─┬─
   recorded in the `merges` audit table.
 - **Escalation** — a conflict or a failing gate raises the same
   `pr.persist-escalation` worker as the review stage (status `escalated`), answered
-  via the merge-loop `escalation-answered` message; answering re-arms and retries.
+  via the native `wait-merge-answer` `userTask` (the same `completeUserTask` door as
+  the review escalation, #256); answering re-arms and retries.
 - **Terminal** — `merged` (with `merged_at`), or `converged` when
   `NANO_PR_AUTO_MERGE=0` (review-only), or `abandoned` on cancel.
 

package/app/agentCompletion.ts

@@ -68,6 +68,7 @@ export const ESCALATION_TASK_ELEMENTS: ReadonlySet<string> = new Set([
   "plan-review-decision",
   "trial-merge-decision",
   "wait-answer", // PR review-loop escalation (convergence-loop.bpmn, U3)
+  "wait-merge-answer", // PR merge-loop escalation (merge-loop.bpmn) — same native user-task path (#256)
 ]);
 
 /** Each escalation `elementId` → the `.form` whose contract governs its completion variables (the
@@ -78,6 +79,7 @@ const ESCALATION_FORM_BY_ELEMENT: Readonly<Record<string, string>> = {
   "plan-review-decision": "plan-review-decision",
   "trial-merge-decision": "trial-merge-decision",
   "wait-answer": "pr-escalation",
+  "wait-merge-answer": "pr-escalation",
 };
 
 interface FormContract {

package/app/agentGuide.ts

@@ -33,7 +33,8 @@ const RAW_GUIDE: string = (() => {
       "- `GET /version` — which code is live.",
       "- `POST /actions/start/convergence-loop` — submit a PR (`{ pr, convergeOnly?, maxRounds?, dependsOn? }`).",
       "- `POST /actions/start/plan-fanout` — submit an epic (`{ issue, baseBranch }` or `{ url, baseBranch }`; base is required — a missing `epic/*` base is auto-created, and `confirmDefaultBase`/`allowSharedBase` gate the default-branch and shared-base cases — see ADR 0003).",
-      "- `POST /actions/message` — answer an escalation (`escalation-answered`, correlate by PR key).",
+      "- `POST /actions/complete-user-task` — answer an escalation (`{ userTaskKey, variables }`); the parked user task's key comes from `GET /status`/the Tasks inbox, and the typed variables match its `.form` (e.g. a PR escalation's `{ answer }`).",
+      "- `POST /actions/message` — publish a BPMN message (optionally correlated) into the engine.",
       "",
       "Engine (Camunda-8 v2 REST) base for debugging: `__ENGINE__`.",
       "Source repository: `nanobpm/nano-workforce`.",

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