@nanobpm/nano-workforce 0.146.0 → 0.148.0

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,
+  optionKindAllows,
+} from "../transcript-events.ts";
 import type { TranscriptDataReport } from "./transcript-render.ts";
 
 /**
@@ -36,13 +42,230 @@ 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;
+}
+
+/**
+ * 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 = optionKindAllows(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 +274,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 +294,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/permission-bridge.test.ts

@@ -0,0 +1,288 @@
+// The escalation-bridge acceptance tests (issue #559, ADR 0056). They drive the REAL in-repo operator
+// path end to end with in-memory fakes:
+//   escalate-policy permission REQUEST → a Tasks-inbox row raised (the new ACP_PERMISSION_ELEMENT kind) →
+//   an operator Allow/Deny answered through the canonical `completeEscalationAsHuman` door →
+//   a permission RESOLUTION frame sent down the relay CONTROL lane with the matching callId/optionId/allowed.
+// A focused unit test proves the exported `onPermissionResolve` adapter converges on the SAME frame, and
+// a yolo/opt-out test proves the bridge is bypassed by default.
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import {
+  buildPermissionResolutionFrame,
+  completePermissionEscalationAsHuman,
+  createOnPermissionResolve,
+  optionKindAllows,
+  type PermissionBridgeDeps,
+  permissionEscalationEnabled,
+  permissionOptionAllows,
+  permissionQuestion,
+  permissionUserTaskRow,
+} from "./permission-bridge.ts";
+import { jobStream } from "./correlation.ts";
+import {
+  type DerivedPermission,
+  parseTranscriptEvent,
+  type PermissionResolutionEvent,
+} from "./transcript-events.ts";
+
+// ── In-memory fakes (mirroring the shared patterns in app/agentCompletion.test.ts) ────────────────
+
+/** A minimal in-memory `Table<T>` with AUTOINCREMENT ids on insert and structural find/get/delete. */
+function memTable(rows: any[], key: string) {
+  let seq = rows.reduce((m, r) => Math.max(m, Number(r[key]) || 0), 0);
+  return {
+    insert: (row: any) => {
+      const id = ++seq;
+      const stored = key === "id" ? { ...row, id } : { ...row };
+      rows.push(stored);
+      return Promise.resolve(key === "id" ? id : stored[key]);
+    },
+    get: (k: any) => Promise.resolve(rows.find((r) => r[key] === k)),
+    find: (q: any = {}) => Promise.resolve(rows.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v))),
+    findOne: (q: any = {}) => Promise.resolve(rows.find((r) => Object.entries(q).every(([f, v]) => r[f] === v))),
+    update: (k: any, patch: any) => {
+      const r = rows.find((x) => x[key] === k);
+      if (r) Object.assign(r, patch);
+      return Promise.resolve(r ? 1 : 0);
+    },
+    delete: (k: any) => {
+      const i = rows.findIndex((r) => r[key] === k);
+      if (i >= 0) rows.splice(i, 1);
+      return Promise.resolve(i >= 0 ? 1 : 0);
+    },
+    count: (q: any = {}) => Promise.resolve(rows.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v)).length),
+    all: () => Promise.resolve(rows.slice()),
+  };
+}
+
+function memData(stores: Record<string, { rows: any[]; key: string }>) {
+  return {
+    table: (name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key),
+  } as any;
+}
+
+/** A stub engine that records every `completeUserTask` against a seeded set of open user tasks (the
+ *  completer resolves via `openUserTasks`, CREATED only). */
+function fakeEngine(openTasks: Array<{ userTaskKey: string; elementId?: string }>) {
+  const completed: Array<{ userTaskKey: string; variables?: Record<string, unknown> }> = [];
+  const engine = {
+    openUserTasks: () => Promise.resolve(openTasks),
+    searchUserTasks: () => Promise.reject(new Error("completer must resolve via openUserTasks")),
+    completeUserTask: (userTaskKey: string, variables?: Record<string, unknown>) => {
+      completed.push({ userTaskKey, variables });
+      return Promise.resolve();
+    },
+  } as any;
+  return { engine, completed };
+}
+
+/** A relay-send spy: records every frame the bridge emits. */
+function sendSpy() {
+  const frames: any[] = [];
+  const deps: PermissionBridgeDeps = { send: (frame) => frames.push(frame) };
+  return { deps, frames };
+}
+
+/** Decode a produced resolution chunk back through the ONE parser (never re-parsing bytes by hand). */
+function decodeResolution(frame: any): PermissionResolutionEvent {
+  const chunk = frame.payload.chunk as string;
+  const event = parseTranscriptEvent({ offset: 0, chunk });
+  assert(event.kind === "permission" && event.phase === "resolution", "expected a permission RESOLUTION");
+  return event;
+}
+
+/** An escalate-policy permission REQUEST offering Allow (allow-once) and Deny (reject-once). */
+function escalateRequest(callId = "job-1"): DerivedPermission {
+  return {
+    callId,
+    policy: "escalate",
+    options: [
+      { optionId: "allow", name: "Allow", kind: "allow-once" },
+      { optionId: "deny", name: "Deny", kind: "reject-once" },
+    ],
+    toolName: "write_file",
+    title: "Write /etc/hosts",
+    reason: "The agent wants to modify a protected file.",
+    offset: 3,
+  };
+}
+
+// ── Acceptance: the full real-operator path, Allow and Deny ────────────────────────────────────────
+
+test("escalate REQUEST → Tasks-inbox row → operator ALLOW via the completion door → RESOLUTION down the control lane", async () => {
+  const request = escalateRequest("job-allow");
+  const stream = jobStream(request.callId);
+
+  // 1. The request surfaces as an answerable Tasks-inbox row of the new permission kind.
+  const row = permissionUserTaskRow(request, { userTaskKey: "ut-perm-1", subjectKey: "hire-42" }, { enabled: true });
+  assert(row !== null, "an escalate-policy request must raise a row");
+  assertEquals(row.element_id, "acp-permission");
+  assertEquals(row.kind_label, "Agent permission");
+  assertEquals(row.subject_type, "agent");
+  assertEquals(row.user_task_key, "ut-perm-1");
+  assert(row.question?.includes("Write /etc/hosts"), "the row carries the request's title/reason as the question");
+  assert(row.question?.includes("modify a protected file"), "the row carries the request's reason");
+
+  // 2. The operator answers Allow through the ONE canonical completion door.
+  const stores = { task_completions: { rows: [] as any[], key: "id" } };
+  const data = memData(stores);
+  const { engine, completed } = fakeEngine([{ userTaskKey: "ut-perm-1", elementId: "acp-permission" }]);
+  const { deps, frames } = sendSpy();
+
+  const result = await completePermissionEscalationAsHuman(data, engine, deps, {
+    permission: request,
+    userTaskKey: "ut-perm-1",
+    optionId: "allow",
+    operatorId: "op:ada",
+  });
+
+  // The completion took through the canonical door (recorded attribution + engine completion).
+  assertEquals(result.completion.ok, true);
+  assertEquals(result.completion.elementId, "acp-permission");
+  assertEquals(completed.length, 1);
+  assertEquals(completed[0].userTaskKey, "ut-perm-1");
+  assertEquals(completed[0].variables, { optionId: "allow", allowed: true });
+  assertEquals(stores.task_completions.rows.length, 1);
+  assertEquals(stores.task_completions.rows[0].actor_kind, "human");
+
+  // 3. A RESOLUTION frame flowed back down the relay CONTROL lane, releasing the blocked request.
+  assertEquals(frames.length, 1);
+  assertEquals(frames[0].lane, "control");
+  assertEquals(frames[0].family, "relay");
+  assertEquals(frames[0].payload.op, "produce");
+  assertEquals(frames[0].payload.stream, stream);
+  const resolution = decodeResolution(frames[0]);
+  assertEquals(resolution.callId, "job-allow");
+  assertEquals(resolution.optionId, "allow");
+  assertEquals(resolution.allowed, true);
+  assertEquals(resolution.by, "operator");
+});
+
+test("escalate REQUEST → operator DENY via the completion door → RESOLUTION allowed=false down the control lane", async () => {
+  const request = escalateRequest("job-deny");
+  const stores = { task_completions: { rows: [] as any[], key: "id" } };
+  const data = memData(stores);
+  const { engine, completed } = fakeEngine([{ userTaskKey: "ut-perm-2", elementId: "acp-permission" }]);
+  const { deps, frames } = sendSpy();
+
+  const result = await completePermissionEscalationAsHuman(data, engine, deps, {
+    permission: request,
+    userTaskKey: "ut-perm-2",
+    optionId: "deny",
+    operatorId: "op:ada",
+  });
+
+  assertEquals(result.completion.ok, true);
+  assertEquals(completed[0].variables, { optionId: "deny", allowed: false });
+  assertEquals(frames.length, 1);
+  const resolution = decodeResolution(frames[0]);
+  assertEquals(resolution.callId, "job-deny");
+  assertEquals(resolution.optionId, "deny");
+  assertEquals(resolution.allowed, false);
+  assertEquals(resolution.by, "operator");
+});
+
+test("a failed completion (no open task) NEVER sends a resolution — the block is only released on a real answer", async () => {
+  const request = escalateRequest("job-missing");
+  const stores = { task_completions: { rows: [] as any[], key: "id" } };
+  const data = memData(stores);
+  const { engine } = fakeEngine([]); // no open task with this key
+  const { deps, frames } = sendSpy();
+
+  const result = await completePermissionEscalationAsHuman(data, engine, deps, {
+    permission: request,
+    userTaskKey: "ut-nope",
+    optionId: "allow",
+    operatorId: "op:ada",
+  });
+
+  assertEquals(result.completion.ok, false);
+  assertEquals(result.resolution, undefined);
+  assertEquals(frames.length, 0);
+});
+
+// ── Convergence: the onPermissionResolve adapter and the completion door build the SAME frame ───────
+
+test("the exported onPermissionResolve adapter produces the SAME relay RESOLUTION as the completion door", async () => {
+  const request = escalateRequest("job-converge");
+  const stream = jobStream(request.callId);
+
+  // Path A: the completion-door path.
+  const stores = { task_completions: { rows: [] as any[], key: "id" } };
+  const data = memData(stores);
+  const { engine } = fakeEngine([{ userTaskKey: "ut-perm-3", elementId: "acp-permission" }]);
+  const doorSpy = sendSpy();
+  await completePermissionEscalationAsHuman(data, engine, doorSpy.deps, {
+    permission: request,
+    userTaskKey: "ut-perm-3",
+    optionId: "allow",
+    operatorId: "op:ada",
+  });
+
+  // Path B: the exported cockpit seam adapter, invoked with the cockpit-derived {callId, optionId, allowed}.
+  const seamSpy = sendSpy();
+  const onPermissionResolve = createOnPermissionResolve(seamSpy.deps);
+  onPermissionResolve({ callId: request.callId, optionId: "allow", allowed: true });
+
+  assertEquals(doorSpy.frames.length, 1);
+  assertEquals(seamSpy.frames.length, 1);
+  // Byte-identical frames: same lane, family, seq, and produce payload (stream + encoded chunk).
+  assertEquals(seamSpy.frames[0], doorSpy.frames[0]);
+  assertEquals(seamSpy.frames[0].payload.stream, stream);
+  // And they equal the pure builder's frame for the same decision + stream.
+  const pure = buildPermissionResolutionFrame(stream, { callId: request.callId, optionId: "allow", allowed: true, by: "operator" });
+  assertEquals(doorSpy.frames[0], pure.frame);
+});
+
+// ── yolo / opt-out: the bridge is bypassed by default ──────────────────────────────────────────────
+
+test("a yolo-policy request NEVER raises a user task and never emits a bridge resolution", () => {
+  const yolo: DerivedPermission = {
+    callId: "job-yolo",
+    policy: "yolo",
+    options: [{ optionId: "allow", name: "Allow", kind: "allow-once" }],
+    offset: 1,
+  };
+  // No row for yolo, even when the bridge is enabled (yolo auto-allows elsewhere; the bridge is inert).
+  assertEquals(permissionUserTaskRow(yolo, { userTaskKey: "ut-y", subjectKey: "hire-1" }, { enabled: true }), null);
+  // No completion door is invoked for yolo, so no send edge fires — nothing to assert beyond the null row:
+  // the bridge only ever emits from `completePermissionEscalationAsHuman`/`createOnPermissionResolve`.
+});
+
+test("the bridge is opt-in: a disabled bridge raises no row even for an escalate-policy request", () => {
+  const request = escalateRequest("job-off");
+  assertEquals(permissionUserTaskRow(request, { userTaskKey: "ut-off", subjectKey: "hire-1" }, { enabled: false }), null);
+});
+
+test("permissionEscalationEnabled defaults OFF and honours the truthy forms of the master switch", () => {
+  assertEquals(permissionEscalationEnabled({}), false);
+  assertEquals(permissionEscalationEnabled({ NANO_WORKFORCE_PERMISSION_ESCALATION: "off" }), false);
+  assertEquals(permissionEscalationEnabled({ NANO_WORKFORCE_PERMISSION_ESCALATION: "false" }), false);
+  for (const on of ["1", "true", "on", "yes", "TRUE", "On"]) {
+    assertEquals(permissionEscalationEnabled({ NANO_WORKFORCE_PERMISSION_ESCALATION: on }), true, `expected ${on} to enable`);
+  }
+});
+
+// ── Pure derivations ────────────────────────────────────────────────────────────────────────────
+
+test("optionKindAllows / permissionOptionAllows derive allow vs reject from the option kind (fail-closed)", () => {
+  assertEquals(optionKindAllows("allow-once"), true);
+  assertEquals(optionKindAllows("allow-always"), true);
+  assertEquals(optionKindAllows("reject-once"), false);
+  assertEquals(optionKindAllows("reject-always"), false);
+  const request = escalateRequest();
+  assertEquals(permissionOptionAllows(request, "allow"), true);
+  assertEquals(permissionOptionAllows(request, "deny"), false);
+  assertEquals(permissionOptionAllows(request, "unknown-option"), false); // fail-closed
+});
+
+test("permissionQuestion folds title + reason, falling back to the tool name", () => {
+  assertEquals(
+    permissionQuestion(escalateRequest()),
+    "Write /etc/hosts — The agent wants to modify a protected file.",
+  );
+  assertEquals(
+    permissionQuestion({ callId: "c", policy: "escalate", options: [], toolName: "run_shell", offset: 0 }),
+    "Permission requested for run_shell",
+  );
+});