@nanobpm/nano-workforce 0.146.0 → 0.147.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.147.0](https://github.com/nanobpm/nano-workforce/compare/v0.146.0...v0.147.0) (2026-08-26)
+
+### Features
+
+* **cockpit:** rich tool/diff cards + permission prompt mounted into the typed replay path ([#561](https://github.com/nanobpm/nano-workforce/issues/561)) ([4bd04a0](https://github.com/nanobpm/nano-workforce/commit/4bd04a06f12569e418566cb47b8a7bbf053cdb20)), closes [#559](https://github.com/nanobpm/nano-workforce/issues/559) [#setMode](https://github.com/nanobpm/nano-workforce/issues/setMode) [#structuredRegion](https://github.com/nanobpm/nano-workforce/issues/structuredRegion)
+
 ## [0.146.0](https://github.com/nanobpm/nano-workforce/compare/v0.145.1...v0.146.0) (2026-08-26)
 
 ### Features

package/app/agentic/cockpit/index.ts

@@ -36,6 +36,7 @@ export {
 export {
   type DerivedTranscriptDom,
   deriveTranscript,
+  type RenderDerivedTranscriptOptions,
   renderDerivedTranscript,
 } from "./transcript-derive.ts";
 export {

package/app/agentic/cockpit/supply-boot.test.ts

@@ -7,8 +7,10 @@ import assert from "node:assert/strict";
 import { test } from "node:test";
 
 import { FakeDocument, FakeElement, FakeSocket } from "../../../test/agentic-cockpit-doubles.ts";
+import { TRANSCRIPT_EVENT_MARKER, TRANSCRIPT_EVENT_VERSION } from "../transcript-events.ts";
 import { bootSupplyCockpit, type SupplyCockpitEnv } from "./supply-boot.ts";
 import type { SupplyReport } from "./supply-view.ts";
+import type { TranscriptDataReport } from "./transcript-render.ts";
 
 const flush = () => new Promise<void>((resolve) => setImmediate(resolve));
 
@@ -358,3 +360,95 @@ test("a drill whose terminal build throws resets the panel to idle instead of le
   assert.equal(cockpit.currentMode, "live");
   assert.equal(cockpit.currentStream, "wk-a");
 });
+
+// A transcript envelope (marker + kind + fields), matching the one event grammar the fold parses.
+function env(kind: string, extra: Record<string, unknown> = {}): string {
+  return JSON.stringify({ [TRANSCRIPT_EVENT_MARKER]: TRANSCRIPT_EVENT_VERSION, kind, ...extra });
+}
+
+// A captured transcript carrying a pending ESCALATE permission request, for the structured replay path.
+function permissionTranscript(stream: string): TranscriptDataReport {
+  const chunks = [
+    env("turn", { index: 0 }),
+    env("message", { role: "assistant", text: "I need to run a command" }),
+    env("permission", {
+      phase: "request",
+      callId: "perm-1",
+      policy: "escalate",
+      title: "Run `rm -rf build`?",
+      options: [
+        { optionId: "allow", name: "Allow", kind: "allow-once" },
+        { optionId: "deny", name: "Deny", kind: "reject-once" },
+      ],
+    }),
+  ];
+  return { stream, from: 0, gap: false, nextOffset: chunks.length, entries: chunks.map((chunk, offset) => ({ offset, chunk })) };
+}
+
+// A rig whose replay endpoints (list + per-session bytes) are wired, plus an optional permission hook.
+function replayRig(onPermissionResolve?: SupplyCockpitEnv["onPermissionResolve"]): {
+  readonly env: SupplyCockpitEnv;
+  readonly host: FakeElement;
+  readonly data: TranscriptDataReport;
+} {
+  const r = rig();
+  const data = permissionTranscript("job:done");
+  const env: SupplyCockpitEnv = {
+    ...r.env,
+    fetchTranscripts: () => Promise.resolve({ count: 0, transcripts: [] }),
+    fetchTranscript: () => Promise.resolve(data),
+    ...(onPermissionResolve !== undefined ? { onPermissionResolve } : {}),
+  };
+  return { env, host: r.host, data };
+}
+
+test("replay MOUNTS the structured derived view beside the byte replay (typed boot/replay path)", async () => {
+  const { env, host } = replayRig();
+  const cockpit = bootSupplyCockpit(env);
+  await cockpit.replay("job:done");
+
+  // The dedicated structured region exists and now holds the derived view (the byte terminal replay,
+  // asserted elsewhere, is untouched — this is additive beside it).
+  const region = host.byData("structured", "region")[0];
+  assert.ok(region !== undefined, "the structured region is present");
+  assert.equal(region?.byClass("cockpit-transcript-derived").length, 1, "the derived structured view is mounted");
+  assert.equal(host.byData("permission", "request").length, 1, "the permission prompt is rendered in the structured view");
+});
+
+test("a SupplyCockpitEnv.onPermissionResolve hook is threaded into the structured render so a click reaches it", async () => {
+  const resolutions: Array<{ callId: string; optionId: string; allowed: boolean }> = [];
+  const { env, host } = replayRig((resolution) => resolutions.push(resolution));
+  const cockpit = bootSupplyCockpit(env);
+  await cockpit.replay("job:done");
+
+  const allow = host.byClass("cockpit-transcript-permission-option").find((b) => b.getAttribute("data-option-id") === "allow");
+  assert.ok(allow !== undefined, "the Allow button rendered");
+  allow?.dispatch("click");
+  assert.deepEqual(resolutions, [{ callId: "perm-1", optionId: "allow", allowed: true }]);
+});
+
+test("the structured view renders even without an onPermissionResolve hook (buttons are inert, no throw)", async () => {
+  const { env, host } = replayRig();
+  const cockpit = bootSupplyCockpit(env);
+  await cockpit.replay("job:done");
+  const allow = host.byClass("cockpit-transcript-permission-option").find((b) => b.getAttribute("data-option-id") === "allow");
+  assert.ok(allow !== undefined, "the Allow button rendered without a hook");
+  allow?.dispatch("click"); // no handler wired — must not throw
+});
+
+test("switching from replay to a LIVE drill CLEARS the stale structured derived view (no wrong-callId clicks)", async () => {
+  const { env, host } = replayRig();
+  const cockpit = bootSupplyCockpit(env);
+  await cockpit.replay("job:done");
+  // The structured region is populated with the derived view + pending permission prompt.
+  assert.equal(host.byData("permission", "request").length, 1, "the permission prompt is mounted on replay");
+
+  // Drilling into a live stream must tear the stale structured view down — leaving a clickable permission
+  // prompt over a live terminal risks an operator action against the wrong callId.
+  cockpit.drill("wk-a");
+  assert.equal(cockpit.currentMode, "live");
+  const region = host.byData("structured", "region")[0];
+  assert.ok(region !== undefined, "the structured region element persists (it is cleared, not removed)");
+  assert.equal(region?.byClass("cockpit-transcript-derived").length, 0, "the derived structured view is cleared on live drill");
+  assert.equal(host.byData("permission", "request").length, 0, "the stale permission prompt is gone in live mode");
+});

package/app/agentic/cockpit/supply-boot.ts

@@ -32,6 +32,7 @@ import type { CockpitRoute } from "./cockpit-route.ts";
 import { renderSupply } from "./supply-render.ts";
 import type { SupplyReport, SupplyView } from "./supply-view.ts";
 import { supplyView } from "./supply-view.ts";
+import { type RenderDerivedTranscriptOptions, renderDerivedTranscript } from "./transcript-derive.ts";
 import { renderTranscripts, replayTranscript, type TranscriptDataReport } from "./transcript-render.ts";
 import type { TranscriptListReport } from "./transcript-view.ts";
 import { transcriptsView } from "./transcript-view.ts";
@@ -88,6 +89,16 @@ export interface SupplyCockpitEnv {
   readonly pastFetchTimeoutMs?: number;
   /** Notified of a fetch/render/relay error (the poll keeps going). */
   readonly onError?: (err: unknown) => void;
+  /**
+   * The seam the wave-2 escalation bridge attaches to: threaded into the STRUCTURED replay view's
+   * {@link RenderDerivedTranscriptOptions.onPermissionResolve}, so a pending escalate-permission
+   * prompt's Allow/Deny click reaches the bridge. Optional (default `undefined`): the structured view
+   * still renders, its prompt buttons just have no handler. NOTE (runtime-layer truth): this is the
+   * TYPED boot/replay path exercised by unit tests + the published package, NOT the operator's live
+   * browser cockpit (`pages/cockpit/mount.js`, a hand-maintained drift twin) — surfacing the prompt
+   * there is a separate follow-up.
+   */
+  readonly onPermissionResolve?: RenderDerivedTranscriptOptions["onPermissionResolve"];
 }
 
 /** The running supply cockpit; dispose to stop polling and tear down the terminal. */
@@ -132,6 +143,10 @@ class SupplyCockpit implements SupplyCockpitHandle {
   readonly #env: SupplyCockpitEnv;
   readonly #listRegion: ElementLike;
   readonly #pastRegion: ElementLike | undefined;
+  // A dedicated volatile region the STRUCTURED derived view (messages, rich tool/diff cards, permission
+  // prompts) is mounted into on a replay — beside, and additive to, the byte-level terminal replay
+  // (which is left untouched). Present only when the transcript read endpoints are wired.
+  readonly #structuredRegion: ElementLike | undefined;
   readonly #terminalHost: ElementLike;
   readonly #terminalTitle: ElementLike;
   readonly #terminalNote: ElementLike;
@@ -247,6 +262,14 @@ class SupplyCockpit implements SupplyCockpitHandle {
     this.#terminalHost.className = "cockpit-terminal-host";
     this.#terminalHost.setAttribute("data-terminal", "host");
     this.#terminalPanel.appendChild(this.#terminalHost);
+    // The STRUCTURED derived view is mounted here on a replay, additive beside the byte terminal above.
+    // Only exists when the transcript read endpoints are wired (same pairing as the past-sessions list).
+    if (env.fetchTranscripts !== undefined) {
+      this.#structuredRegion = env.doc.createElement("div");
+      this.#structuredRegion.className = "cockpit-structured-region";
+      this.#structuredRegion.setAttribute("data-structured", "region");
+      this.#terminalPanel.appendChild(this.#structuredRegion);
+    }
     // A status note under the terminal, shown while a LIVE drill has connected but no output has
     // arrived yet (a quiet job between frames): without it the panel is an indistinguishable blank
     // black rectangle, so the operator can't tell "connected, waiting" from "broken". Cleared the
@@ -284,6 +307,11 @@ class SupplyCockpit implements SupplyCockpitHandle {
     // Any mode change replaces what's behind the panel, so the prior "waiting for output" note is
     // stale — clear it. A live drill re-arms it (below) once its fresh terminal is mounted.
     this.#setNote(undefined);
+    // The STRUCTURED derived view is only valid alongside a replay. Any non-replay mode (a live drill
+    // or idle) must clear it, or a stale derived transcript / pending permission prompt would linger —
+    // visible and CLICKABLE — over the live terminal, risking an operator action against the wrong
+    // callId. A replay re-mounts it (in replay(), after this #setMode("replay", …)).
+    if (mode !== "replay") this.#structuredRegion?.replaceChildren();
   }
 
   /** Show (or clear) the terminal status note — the "connected, waiting for output" affordance. */
@@ -577,6 +605,14 @@ class SupplyCockpit implements SupplyCockpitHandle {
       const session = new TerminalSession({ stream, sink, send: () => {}, from: data.from });
       replayTranscript(session, data);
       this.#setMode("replay", stream);
+      // Additively mount the STRUCTURED derived view beside the byte replay above (the byte replay is
+      // left untouched). The env's onPermissionResolve seam is threaded into the render so a pending
+      // escalate-permission prompt's Allow/Deny click reaches whatever the bridge wires there.
+      if (this.#structuredRegion !== undefined) {
+        renderDerivedTranscript(this.#structuredRegion, this.#env.doc, data, {
+          onPermissionResolve: this.#env.onPermissionResolve,
+        });
+      }
       // Re-render the past list so the just-selected session shows as active (best-effort).
       void this.#refreshPast(this.#route.kind === "worker" ? this.#route.instance : undefined);
     } catch (err) {

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

@@ -4,7 +4,7 @@
 // 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 { assert, assertEquals, assertStringIncludes } 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";
@@ -76,3 +76,184 @@ test("renderDerivedTranscript shows an empty state for an all-raw (unstructured)
   assertEquals(host.byData("empty", "true").length, 1);
   assertEquals(host.byData("turn-count", "0").length, 1);
 });
+
+// A minimal single-page report of the given entries (offsets assigned in order).
+function page(chunks: readonly string[], stream = "job:x"): TranscriptDataReport {
+  return { stream, from: 0, gap: false, nextOffset: chunks.length, entries: chunks.map((chunk, offset) => ({ offset, chunk })) };
+}
+
+test("a tool card renders its args and result content", () => {
+  const host = new FakeElement("div");
+  renderDerivedTranscript(
+    host,
+    doc,
+    page([
+      env("tool-call", { name: "read", callId: "c1", args: { path: "README.md" } }),
+      env("tool-result", { callId: "c1", ok: true, content: "file contents here" }),
+    ]),
+  );
+  const card = host.byData("tool", "read")[0];
+  assertEquals(card?.getAttribute("data-status"), "ok");
+  assertEquals(card?.getAttribute("data-tool-kind"), undefined); // not a diff
+  const argsEl = host.byData("tool-args", "true")[0];
+  assertStringIncludes(argsEl?.textContent ?? "", "README.md");
+  const resultEl = host.byData("tool-result", "true")[0];
+  assertEquals(resultEl?.textContent, "file contents here");
+});
+
+test("a diff tool renders a cockpit-transcript-diff block with per-line add/del/ctx markers", () => {
+  const host = new FakeElement("div");
+  const unified = "--- a/foo.txt\n+++ b/foo.txt\n@@ -1,2 +1,2 @@\n-old line\n+new line\n unchanged\n";
+  renderDerivedTranscript(
+    host,
+    doc,
+    page([
+      env("tool-call", { name: "edit", callId: "d1" }),
+      env("tool-result", { callId: "d1", ok: true, content: unified }),
+    ]),
+  );
+  const card = host.byData("tool", "edit")[0];
+  assertEquals(card?.getAttribute("data-tool-kind"), "diff");
+  assertEquals(host.byClass("cockpit-transcript-diff").length, 1);
+  assertEquals(host.byData("diff-line", "add").length, 1);
+  assertEquals(host.byData("diff-line", "del").length, 1);
+  assert(host.byData("diff-line", "ctx").length >= 1, "the hunk/header/context lines are marked ctx");
+  // The diff replaces the plain result rendering — no raw result <pre> for a diff tool.
+  assertEquals(host.byData("tool-result", "true").length, 0);
+});
+
+test("structured edit args (path + old/new text) render as a synthesized diff", () => {
+  const host = new FakeElement("div");
+  renderDerivedTranscript(
+    host,
+    doc,
+    page([env("tool-call", { name: "write", callId: "s1", args: { path: "a.txt", oldText: "one\ntwo", newText: "one\nTWO" } })]),
+  );
+  const card = host.byData("tool", "write")[0];
+  assertEquals(card?.getAttribute("data-tool-kind"), "diff");
+  assertEquals(host.byData("diff-line", "del").length, 2);
+  assertEquals(host.byData("diff-line", "add").length, 2);
+  // The diff was synthesized FROM args, so the raw args <pre> is not ALSO rendered.
+  assertEquals(host.byData("tool-args", "true").length, 0);
+});
+
+test("structured edit args ending in a trailing newline do not synthesize a spurious empty diff line", () => {
+  const host = new FakeElement("div");
+  renderDerivedTranscript(
+    host,
+    doc,
+    page([env("tool-call", { name: "write", callId: "s2", args: { path: "a.txt", oldText: "one\ntwo\n", newText: "one\nTWO\n" } })]),
+  );
+  // "one\ntwo\n" would naively split into 3 segments (…, "two", "") — the trailing empty is dropped.
+  assertEquals(host.byData("diff-line", "del").length, 2);
+  assertEquals(host.byData("diff-line", "add").length, 2);
+});
+
+test("an args-synthesized diff still renders non-diff result content (args+result, diff special render)", () => {
+  const host = new FakeElement("div");
+  renderDerivedTranscript(
+    host,
+    doc,
+    page([
+      env("tool-call", { name: "write", callId: "s3", args: { path: "a.txt", oldText: "one", newText: "ONE" } }),
+      env("tool-result", { callId: "s3", ok: true, content: "wrote 1 file" }),
+    ]),
+  );
+  const card = host.byData("tool", "write")[0];
+  assertEquals(card?.getAttribute("data-tool-kind"), "diff");
+  // The diff came from args, so the result content is not the diff source — it is still shown.
+  const resultEl = host.byData("tool-result", "true")[0];
+  assertEquals(resultEl?.textContent, "wrote 1 file");
+});
+
+test("a pending escalate permission renders Allow/Deny buttons that invoke onPermissionResolve", () => {
+  const host = new FakeElement("div");
+  const calls: Array<{ callId: string; optionId: string; allowed: boolean }> = [];
+  renderDerivedTranscript(
+    host,
+    doc,
+    page([
+      env("permission", {
+        phase: "request",
+        callId: "p1",
+        policy: "escalate",
+        title: "Run a shell command?",
+        options: [
+          { optionId: "allow", name: "Allow", kind: "allow-once" },
+          { optionId: "deny", name: "Deny", kind: "reject-once" },
+        ],
+      }),
+    ]),
+    { onPermissionResolve: (resolution) => calls.push(resolution) },
+  );
+  const card = host.byData("permission", "request")[0];
+  assertEquals(card?.getAttribute("data-policy"), "escalate");
+  assertEquals(card?.getAttribute("data-status"), "pending");
+  assertEquals(card?.getAttribute("data-call-id"), "p1");
+  const buttons = host.byClass("cockpit-transcript-permission-option");
+  assertEquals(buttons.length, 2);
+
+  buttons.find((b) => b.getAttribute("data-option-id") === "allow")?.dispatch("click");
+  buttons.find((b) => b.getAttribute("data-option-id") === "deny")?.dispatch("click");
+  assertEquals(calls, [
+    { callId: "p1", optionId: "allow", allowed: true },
+    { callId: "p1", optionId: "deny", allowed: false },
+  ]);
+});
+
+test("a yolo permission request renders informational only — no Allow/Deny buttons", () => {
+  const host = new FakeElement("div");
+  const calls: unknown[] = [];
+  renderDerivedTranscript(
+    host,
+    doc,
+    page([
+      env("permission", {
+        phase: "request",
+        callId: "y1",
+        policy: "yolo",
+        options: [{ optionId: "allow", name: "Allow", kind: "allow-always" }],
+      }),
+    ]),
+    { onPermissionResolve: (resolution) => calls.push(resolution) },
+  );
+  const card = host.byData("permission", "request")[0];
+  assertEquals(card?.getAttribute("data-policy"), "yolo");
+  assertEquals(card?.getAttribute("data-status"), "auto");
+  assertEquals(host.byClass("cockpit-transcript-permission-option").length, 0);
+  assertEquals(calls.length, 0);
+});
+
+test("a resolved permission renders settled (allowed/denied) with the chosen option and no live buttons", () => {
+  const host = new FakeElement("div");
+  renderDerivedTranscript(
+    host,
+    doc,
+    page([
+      env("permission", {
+        phase: "request",
+        callId: "r1",
+        policy: "escalate",
+        title: "Delete the file?",
+        options: [
+          { optionId: "allow", name: "Allow once", kind: "allow-once" },
+          { optionId: "deny", name: "Deny", kind: "reject-once" },
+        ],
+      }),
+      env("permission", { phase: "resolution", callId: "r1", optionId: "deny", allowed: false, by: "operator" }),
+    ]),
+  );
+  const card = host.byData("permission", "request")[0];
+  assertEquals(card?.getAttribute("data-status"), "denied");
+  const settled = host.byClass("cockpit-transcript-permission-settled")[0];
+  assertEquals(settled?.getAttribute("data-chosen-option"), "deny");
+  assertEquals(settled?.textContent, "Deny");
+  assertEquals(host.byClass("cockpit-transcript-permission-option").length, 0);
+});
+
+test("the existing 3-arg renderDerivedTranscript(host, doc, data) call still works (options optional)", () => {
+  const host = new FakeElement("div");
+  renderDerivedTranscript(host, doc, report());
+  assertEquals(host.byData("turn-count", "1").length, 1);
+  assertEquals(host.byData("permission-count", "0").length, 1);
+});

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

@@ -13,7 +13,13 @@
 // 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 DerivedPermission,
+  type DerivedTool,
+  type DerivedView,
+  deriveViewFromChunks,
+  type PermissionOptionKind,
+} from "../transcript-events.ts";
 import type { TranscriptDataReport } from "./transcript-render.ts";
 
 /**
@@ -36,13 +42,235 @@ export interface DerivedTranscriptDom {
   readonly root: ElementLike;
 }
 
+/**
+ * Options for {@link renderDerivedTranscript}. This is the SHARED SEAM the wave-2 escalation bridge
+ * attaches its handler to: an escalate-policy permission prompt's Allow/Deny buttons invoke
+ * {@link onPermissionResolve} on click (mirroring how `transcript-render.ts` wires `onReplay`). The
+ * render itself only *invokes* the callback — the relay round-trip that actually releases the blocked
+ * agent lives in the bridge, not here. Optional/defaulted so the 3-arg call sites keep working.
+ */
+export interface RenderDerivedTranscriptOptions {
+  /**
+   * Called when the operator picks an Allow/Deny option on a pending `escalate` permission prompt. The
+   * resolution shape is the minimal `{ callId, optionId, allowed }` the bridge folds into a
+   * `permission` RESOLUTION frame — `allowed` is derived from the chosen option's kind (allow-* ⇒ true,
+   * reject-* ⇒ false). Yolo requests never prompt, so this never fires for a yolo policy.
+   */
+  readonly onPermissionResolve?: (resolution: { callId: string; optionId: string; allowed: boolean }) => void;
+}
+
+/** A single classified line of a rendered diff block. */
+type DiffLineKind = "add" | "del" | "ctx";
+interface DiffLine {
+  readonly kind: DiffLineKind;
+  readonly text: string;
+}
+interface DetectedDiff {
+  readonly lines: readonly DiffLine[];
+  /** Where the diff came from — so the raw `args`/`result` content isn't ALSO rendered redundantly. */
+  readonly source: "args" | "result";
+}
+
+/** Render an arbitrary derived value (tool args/result) as displayable text without re-parsing the log. */
+function toText(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (value === undefined) return "";
+  return JSON.stringify(value, null, 2);
+}
+
+/** Read the first string-valued field among `keys` off an object, without an `as` cast. */
+function pickString(obj: object, keys: readonly string[]): string | undefined {
+  for (const key of keys) {
+    const value = Reflect.get(obj, key);
+    if (typeof value === "string") return value;
+  }
+  return undefined;
+}
+
+/** Classify one line of a unified diff (file/hunk headers are context, not add/del). */
+function classifyUnifiedLine(line: string): DiffLineKind {
+  if (line.startsWith("+++") || line.startsWith("---") || line.startsWith("@@") || line.startsWith("diff ")) return "ctx";
+  if (line.startsWith("+")) return "add";
+  if (line.startsWith("-")) return "del";
+  return "ctx";
+}
+
+/** Heuristic: does this string look like a unified diff (a hunk header, or paired +/- content lines)? */
+function looksLikeUnifiedDiff(text: string): boolean {
+  if (text.length === 0) return false;
+  let add = false;
+  let del = false;
+  let hunk = false;
+  for (const line of text.split("\n")) {
+    if (line.startsWith("@@") || line.startsWith("diff --git")) hunk = true;
+    else if (line.startsWith("+++") || line.startsWith("---")) continue;
+    else if (line.startsWith("+")) add = true;
+    else if (line.startsWith("-")) del = true;
+  }
+  return hunk || (add && del);
+}
+
+/** Split a unified-diff string into classified lines (dropping a single trailing empty line). */
+function parseUnifiedDiff(text: string): DiffLine[] {
+  const lines = text.split("\n");
+  if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+  return lines.map((line) => ({ kind: classifyUnifiedLine(line), text: line }));
+}
+
+/** Split a block of text into lines, dropping a single trailing empty segment (text ending in "\n"). */
+function splitTextLines(text: string): string[] {
+  const lines = text.split("\n");
+  if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+  return lines;
+}
+
+/** Synthesize a diff from structured edit args (`{ path?, oldText/old_string, newText/new_string }`). */
+function structuredDiff(args: unknown): DiffLine[] | undefined {
+  if (typeof args !== "object" || args === null) return undefined;
+  const oldText = pickString(args, ["oldText", "old_string", "oldStr", "old", "before"]);
+  const newText = pickString(args, ["newText", "new_string", "newStr", "new", "after"]);
+  if (oldText === undefined && newText === undefined) return undefined;
+  const lines: DiffLine[] = [];
+  const path = pickString(args, ["path", "file", "filePath", "fileName"]);
+  if (path !== undefined) lines.push({ kind: "ctx", text: `diff --git a/${path} b/${path}` });
+  if (oldText !== undefined && oldText.length > 0) {
+    for (const line of splitTextLines(oldText)) lines.push({ kind: "del", text: `-${line}` });
+  }
+  if (newText !== undefined && newText.length > 0) {
+    for (const line of splitTextLines(newText)) lines.push({ kind: "add", text: `+${line}` });
+  }
+  return lines.length > 0 ? lines : undefined;
+}
+
+/** Detect diff-shaped content on a tool call/result — a unified-diff string or structured edit args. */
+function detectDiff(tool: DerivedTool): DetectedDiff | undefined {
+  const content = tool.result?.content;
+  if (typeof content === "string" && looksLikeUnifiedDiff(content)) {
+    return { lines: parseUnifiedDiff(content), source: "result" };
+  }
+  if (typeof tool.args === "string" && looksLikeUnifiedDiff(tool.args)) {
+    return { lines: parseUnifiedDiff(tool.args), source: "args" };
+  }
+  const structured = structuredDiff(tool.args);
+  if (structured !== undefined) return { lines: structured, source: "args" };
+  return undefined;
+}
+
+/** Render one tool card: name, status, args + result content, and a distinguishable diff block. */
+function renderTool(doc: DocumentLike, tool: DerivedTool): ElementLike {
+  const card = el(doc, "div", "cockpit-transcript-tool");
+  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");
+  card.appendChild(el(doc, "div", "cockpit-transcript-tool-name", tool.name));
+
+  const diff = detectDiff(tool);
+  if (diff !== undefined) card.setAttribute("data-tool-kind", "diff");
+
+  // Show the raw args unless the diff was synthesized FROM the args (then the diff block replaces it).
+  if (tool.args !== undefined && !(diff !== undefined && diff.source === "args")) {
+    const argsEl = el(doc, "pre", "cockpit-transcript-tool-args", toText(tool.args));
+    argsEl.setAttribute("data-tool-args", "true");
+    card.appendChild(argsEl);
+  }
+
+  if (diff !== undefined) {
+    const pre = el(doc, "pre", "cockpit-transcript-diff");
+    pre.setAttribute("data-diff", "true");
+    for (const line of diff.lines) {
+      // A <pre> may only contain phrasing content, so each diff line is a phrasing <span>
+      // (not a block <div>, which would be invalid markup) carrying a trailing "\n". The
+      // enclosing <pre> preserves that newline, so lines break onto their own line without
+      // depending on host CSS forcing display:block.
+      const row = el(doc, "span", "cockpit-transcript-diff-line", `${line.text}\n`);
+      row.setAttribute("data-diff-line", line.kind);
+      pre.appendChild(row);
+    }
+    card.appendChild(pre);
+  }
+
+  // Render the result content unless it was itself consumed as the diff source (source === "result").
+  if (typeof tool.result?.content === "string" && !(diff !== undefined && diff.source === "result")) {
+    const resEl = el(doc, "pre", "cockpit-transcript-tool-result", tool.result.content);
+    resEl.setAttribute("data-tool-result", "true");
+    card.appendChild(resEl);
+  }
+  return card;
+}
+
+/** Does a permission option kind allow (true) or reject (false) the proposed action? */
+function optionAllows(kind: PermissionOptionKind): boolean {
+  return kind === "allow-once" || kind === "allow-always";
+}
+
+/**
+ * Render one permission prompt card from a {@link DerivedPermission}:
+ * - a pending `escalate` request → interactive Allow/Deny buttons wired to `onPermissionResolve`;
+ * - a `yolo` request → informational only (yolo auto-allows, it never prompts a human);
+ * - a resolved permission → settled (`allowed`/`denied`), showing the chosen option, no live buttons.
+ */
+function renderPermission(doc: DocumentLike, perm: DerivedPermission, options: RenderDerivedTranscriptOptions): ElementLike {
+  const card = el(doc, "div", "cockpit-transcript-permission");
+  card.setAttribute("data-permission", "request");
+  card.setAttribute("data-policy", perm.policy);
+  card.setAttribute("data-call-id", perm.callId);
+  card.setAttribute("data-offset", String(perm.offset));
+  if (perm.toolName !== undefined) card.setAttribute("data-tool", perm.toolName);
+  if (perm.title !== undefined) card.appendChild(el(doc, "div", "cockpit-transcript-permission-title", perm.title));
+  if (perm.reason !== undefined) card.appendChild(el(doc, "div", "cockpit-transcript-permission-reason", perm.reason));
+
+  if (perm.resolved !== undefined) {
+    // Settled: show which option was chosen and no live buttons.
+    card.setAttribute("data-status", perm.resolved.allowed ? "allowed" : "denied");
+    const chosen = perm.options.find((option) => option.optionId === perm.resolved?.optionId);
+    const settled = el(doc, "div", "cockpit-transcript-permission-settled", chosen?.name ?? perm.resolved.optionId);
+    settled.setAttribute("data-chosen-option", perm.resolved.optionId);
+    if (perm.resolved.by !== undefined) settled.setAttribute("data-by", perm.resolved.by);
+    card.appendChild(settled);
+    return card;
+  }
+
+  if (perm.policy === "yolo") {
+    // Informational: yolo auto-allows and never prompts a human, so no Allow/Deny buttons.
+    card.setAttribute("data-status", "auto");
+    card.appendChild(el(doc, "div", "cockpit-transcript-permission-note", "Auto-allowed (yolo) — no operator prompt."));
+    return card;
+  }
+
+  // Pending escalate: one interactive button per offered option, wired to the resolve seam.
+  card.setAttribute("data-status", "pending");
+  const actions = el(doc, "div", "cockpit-transcript-permission-actions");
+  for (const option of perm.options) {
+    const allowed = optionAllows(option.kind);
+    const button = el(doc, "button", "cockpit-transcript-permission-option", option.name);
+    button.setAttribute("type", "button");
+    button.setAttribute("data-option-id", option.optionId);
+    button.setAttribute("data-option-kind", option.kind);
+    button.setAttribute("data-allowed", String(allowed));
+    const onPermissionResolve = options.onPermissionResolve;
+    if (onPermissionResolve !== undefined) {
+      button.addEventListener("click", () => onPermissionResolve({ callId: perm.callId, optionId: option.optionId, allowed }));
+    }
+    actions.appendChild(button);
+  }
+  card.appendChild(actions);
+  return card;
+}
+
 /**
  * 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.
+ * Draws per-turn sections with their derived messages, rich tool/diff cards and permission prompts, 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. `options.onPermissionResolve`, when provided, is invoked by a pending
+ * escalate-permission prompt's Allow/Deny buttons.
  */
-export function renderDerivedTranscript(host: ElementLike, doc: DocumentLike, data: TranscriptDataReport): DerivedTranscriptDom {
+export function renderDerivedTranscript(
+  host: ElementLike,
+  doc: DocumentLike,
+  data: TranscriptDataReport,
+  options: RenderDerivedTranscriptOptions = {},
+): DerivedTranscriptDom {
   const view = deriveTranscript(data);
   host.replaceChildren();
   const root = el(doc, "div", "cockpit-transcript-derived");
@@ -51,6 +279,7 @@ export function renderDerivedTranscript(host: ElementLike, doc: DocumentLike, da
   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));
+  root.setAttribute("data-permission-count", String(view.permissions.length));
 
   if (view.turns.length === 0) {
     const empty = el(doc, "div", "cockpit-transcript-empty", "No structured events derived — raw replay only.");
@@ -70,11 +299,10 @@ export function renderDerivedTranscript(host: ElementLike, doc: DocumentLike, da
       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);
+      section.appendChild(renderTool(doc, tool));
+    }
+    for (const perm of turn.permissions) {
+      section.appendChild(renderPermission(doc, perm, options));
     }
     root.appendChild(section);
   }

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

@@ -275,6 +275,14 @@ test("core vocab: malformed permission envelopes fall back to raw stream-chunk",
     }).kind,
     "stream-chunk",
   );
+  // resolution with a present-but-NON-STRING `by` (e.g. 123) — rejected, not accepted with `by` dropped
+  assertEquals(
+    parseTranscriptEvent({
+      offset: 0,
+      chunk: env("permission", { phase: "resolution", callId: "p1", optionId: "allow", allowed: true, by: 123 }),
+    }).kind,
+    "stream-chunk",
+  );
   // missing callId
   assertEquals(
     parseTranscriptEvent({ offset: 0, chunk: env("permission", { phase: "request", policy: "escalate", options: REQUEST_OPTIONS }) }).kind,

package/app/agentic/transcript-events.ts

@@ -346,7 +346,10 @@ export const CORE_TRANSCRIPT_VOCAB: TranscriptVocab = Object.freeze({
       if (typeof body.allowed !== "boolean") return undefined;
       const by = str(body, "by");
       // Reject a malformed `by` rather than silently dropping it: a present-but-unknown provenance is a
-      // producer bug, and swallowing it would make the typed event diverge from the on-wire JSON.
+      // producer bug, and swallowing it would make the typed event diverge from the on-wire JSON. This
+      // covers BOTH a present-but-non-string `by` (e.g. `by: 123`, where str() coerces to undefined) and
+      // a string that isn't a known provenance — either way the on-wire `by` is present but invalid.
+      if (body.by !== undefined && by === undefined) return undefined;
       if (by !== undefined && by !== "operator" && by !== "auto") return undefined;
       const event: PermissionResolutionEvent = {
         kind: "permission",

package/package.json

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