@nanobpm/nano-workforce 0.145.0 → 0.146.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.146.0](https://github.com/nanobpm/nano-workforce/compare/v0.145.1...v0.146.0) (2026-08-26)
+
+### Features
+
+* **agentic:** add a permission transcript-event kind (request + resolution) ([#560](https://github.com/nanobpm/nano-workforce/issues/560)) ([722bb96](https://github.com/nanobpm/nano-workforce/commit/722bb962b24c85faf585e598b905bf67a43040d4)), closes [#559](https://github.com/nanobpm/nano-workforce/issues/559)
+
+## [0.145.1](https://github.com/nanobpm/nano-workforce/compare/v0.145.0...v0.145.1) (2026-08-26)
+
+### Bug Fixes
+
+* bound the merge-loop wait-landed wait so a never-enqueued PR escalates ([#556](https://github.com/nanobpm/nano-workforce/issues/556)) ([#558](https://github.com/nanobpm/nano-workforce/issues/558)) ([0e14578](https://github.com/nanobpm/nano-workforce/commit/0e14578e23d3914f8ae82a9fd84280fbc05c6588))
+
 ## [0.145.0](https://github.com/nanobpm/nano-workforce/compare/v0.144.0...v0.145.0) (2026-08-25)
 
 ### Features

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

@@ -184,3 +184,219 @@ test("deriveViewFromChunks: a mixed log derives typed structure while retaining
   assertEquals(view.messages.map((m) => m.text), ["hi"]);
   assertEquals(view.rawChunkCount, 1);
 });
+
+// --- permission kind (issue #559) -----------------------------------------------------------------
+
+const REQUEST_OPTIONS = [
+  { optionId: "allow", name: "Allow", kind: "allow-once" },
+  { optionId: "deny", name: "Deny", kind: "reject-once" },
+];
+
+test("core vocab decodes a permission REQUEST envelope", () => {
+  const chunk = env("permission", {
+    phase: "request",
+    callId: "p1",
+    policy: "escalate",
+    options: REQUEST_OPTIONS,
+    toolName: "write_file",
+    title: "Write to /etc/hosts?",
+    reason: "The agent wants to modify a system file",
+  });
+  assertEquals(parseTranscriptEvent({ offset: 1, chunk }), {
+    kind: "permission",
+    phase: "request",
+    offset: 1,
+    callId: "p1",
+    policy: "escalate",
+    options: REQUEST_OPTIONS,
+    toolName: "write_file",
+    title: "Write to /etc/hosts?",
+    reason: "The agent wants to modify a system file",
+  });
+});
+
+test("core vocab decodes a permission REQUEST with only required fields (optional fields omitted)", () => {
+  const chunk = env("permission", { phase: "request", callId: "p2", policy: "yolo", options: REQUEST_OPTIONS });
+  assertEquals(parseTranscriptEvent({ offset: 0, chunk }), {
+    kind: "permission",
+    phase: "request",
+    offset: 0,
+    callId: "p2",
+    policy: "yolo",
+    options: REQUEST_OPTIONS,
+  });
+});
+
+test("core vocab decodes a permission RESOLUTION envelope", () => {
+  const chunk = env("permission", { phase: "resolution", callId: "p1", optionId: "allow", allowed: true, by: "operator" });
+  assertEquals(parseTranscriptEvent({ offset: 2, chunk }), {
+    kind: "permission",
+    phase: "resolution",
+    offset: 2,
+    callId: "p1",
+    optionId: "allow",
+    allowed: true,
+    by: "operator",
+  });
+});
+
+test("core vocab: malformed permission envelopes fall back to raw stream-chunk", () => {
+  // request missing options
+  assertEquals(
+    parseTranscriptEvent({ offset: 0, chunk: env("permission", { phase: "request", callId: "p1", policy: "escalate" }) }).kind,
+    "stream-chunk",
+  );
+  // request with a bad policy
+  assertEquals(
+    parseTranscriptEvent({
+      offset: 0,
+      chunk: env("permission", { phase: "request", callId: "p1", policy: "maybe", options: REQUEST_OPTIONS }),
+    }).kind,
+    "stream-chunk",
+  );
+  // request with a malformed option (bad kind)
+  assertEquals(
+    parseTranscriptEvent({
+      offset: 0,
+      chunk: env("permission", { phase: "request", callId: "p1", policy: "escalate", options: [{ optionId: "a", name: "A", kind: "nope" }] }),
+    }).kind,
+    "stream-chunk",
+  );
+  // resolution missing allowed
+  assertEquals(
+    parseTranscriptEvent({ offset: 0, chunk: env("permission", { phase: "resolution", callId: "p1", optionId: "allow" }) }).kind,
+    "stream-chunk",
+  );
+  // resolution with a present-but-unknown `by` provenance (rejected, not silently dropped)
+  assertEquals(
+    parseTranscriptEvent({
+      offset: 0,
+      chunk: env("permission", { phase: "resolution", callId: "p1", optionId: "allow", allowed: true, by: "robot" }),
+    }).kind,
+    "stream-chunk",
+  );
+  // missing callId
+  assertEquals(
+    parseTranscriptEvent({ offset: 0, chunk: env("permission", { phase: "request", policy: "escalate", options: REQUEST_OPTIONS }) }).kind,
+    "stream-chunk",
+  );
+  // unknown phase
+  assertEquals(
+    parseTranscriptEvent({ offset: 0, chunk: env("permission", { phase: "wat", callId: "p1" }) }).kind,
+    "stream-chunk",
+  );
+});
+
+test("mergeTranscriptVocab: the permission kind is additive — provable via a merged vocab too", () => {
+  // Registering an unrelated kind via merge must not disturb the core `permission` decoder.
+  const vocab = mergeTranscriptVocab(CORE_TRANSCRIPT_VOCAB, {
+    reasoning: (body, offset) => ({ kind: "message", offset, role: "system", text: String(body.text ?? "") }),
+  });
+  const chunk = env("permission", { phase: "request", callId: "p9", policy: "escalate", options: REQUEST_OPTIONS });
+  assertEquals(parseTranscriptEvent({ offset: 5, chunk }, vocab), {
+    kind: "permission",
+    phase: "request",
+    offset: 5,
+    callId: "p9",
+    policy: "escalate",
+    options: REQUEST_OPTIONS,
+  });
+});
+
+test("encodeTranscriptEvent round-trips the permission kind through the one parser", () => {
+  const events: TranscriptEvent[] = [
+    {
+      kind: "permission",
+      phase: "request",
+      offset: 10,
+      callId: "p1",
+      policy: "escalate",
+      options: REQUEST_OPTIONS.map((o) => ({ optionId: o.optionId, name: o.name, kind: o.kind === "allow-once" ? "allow-once" : "reject-once" })),
+      toolName: "rm",
+      title: "Delete?",
+      reason: "why",
+    },
+    { kind: "permission", phase: "resolution", offset: 11, callId: "p1", optionId: "deny", allowed: false, by: "auto" },
+  ];
+  for (const original of events) {
+    const chunk = encodeTranscriptEvent(original);
+    assertEquals(parseTranscriptEvent({ offset: original.offset, chunk }), original);
+  }
+});
+
+test("deriveView: pairs a permission request with its resolution by callId, carrying policy + options", () => {
+  const view = deriveView([
+    { kind: "turn", offset: 0, index: 0 },
+    {
+      kind: "permission",
+      phase: "request",
+      offset: 1,
+      callId: "p1",
+      policy: "escalate",
+      options: [
+        { optionId: "allow", name: "Allow", kind: "allow-once" },
+        { optionId: "deny", name: "Deny", kind: "reject-once" },
+      ],
+      title: "Write file?",
+    },
+    { kind: "permission", phase: "resolution", offset: 2, callId: "p1", optionId: "allow", allowed: true, by: "operator" },
+  ]);
+  assertEquals(view.permissions.length, 1);
+  const permission = view.permissions[0];
+  assertEquals(permission?.policy, "escalate");
+  assertEquals(permission?.title, "Write file?");
+  assertEquals(permission?.options.length, 2);
+  assertEquals(permission?.resolved, { allowed: true, optionId: "allow", offset: 2, by: "operator" });
+  // Also attached to its enclosing turn.
+  assertEquals(view.turns[0]?.permissions.length, 1);
+  assertEquals(view.turns[0]?.permissions[0]?.resolved?.optionId, "allow");
+});
+
+test("deriveView: an unresolved permission request stays pending (no resolution)", () => {
+  const view = deriveView([
+    {
+      kind: "permission",
+      phase: "request",
+      offset: 0,
+      callId: "p1",
+      policy: "escalate",
+      options: [{ optionId: "allow", name: "Allow", kind: "allow-once" }],
+    },
+  ]);
+  assertEquals(view.permissions.length, 1);
+  assertEquals(view.permissions[0]?.resolved, undefined);
+  assertEquals(view.permissions[0]?.policy, "escalate");
+  // Content before any turn event opens an implicit turn 0 (consistent with messages/tools).
+  assertEquals(view.turns.length, 1);
+  assertEquals(view.turns[0]?.permissions.length, 1);
+});
+
+test("deriveView: the policy field survives derivation for a yolo request", () => {
+  const view = deriveView([
+    {
+      kind: "permission",
+      phase: "request",
+      offset: 0,
+      callId: "p1",
+      policy: "yolo",
+      options: [{ optionId: "allow", name: "Allow", kind: "allow-always" }],
+    },
+    { kind: "permission", phase: "resolution", offset: 1, callId: "p1", optionId: "allow", allowed: true, by: "auto" },
+  ]);
+  assertEquals(view.permissions[0]?.policy, "yolo");
+  assertEquals(view.permissions[0]?.resolved?.by, "auto");
+});
+
+test("ACP plan updates map onto the existing step/turn vocabulary (no new kind)", () => {
+  // An ACP plan entry becomes a `step` (its label the entry title); a plan/turn boundary a `turn`.
+  const view = deriveViewFromChunks([
+    { offset: 0, chunk: env("turn", { index: 0 }) },
+    { offset: 1, chunk: env("step", { label: "Investigate the failing test", index: 0 }) },
+    { offset: 2, chunk: env("step", { label: "Fix the bug", index: 1 }) },
+    { offset: 3, chunk: env("turn", { index: 1 }) },
+    { offset: 4, chunk: env("step", { label: "Write a regression test" }) },
+  ]);
+  assertEquals(view.turns.length, 2);
+  assertEquals(view.turns[0]?.steps, 2);
+  assertEquals(view.turns[1]?.steps, 1);
+});

package/app/agentic/transcript-events.ts

@@ -64,7 +64,8 @@ export type TranscriptEventKind =
   | "tool-result"
   | "turn"
   | "step"
-  | "lifecycle";
+  | "lifecycle"
+  | "permission";
 
 /** The message roles the derived history distinguishes (assistant is authoritative for derivation). */
 export type TranscriptRole = "assistant" | "user" | "system" | "tool";
@@ -124,6 +125,70 @@ export interface LifecycleEvent extends TranscriptEventBase {
   readonly phase: "open" | "completed" | "exited";
 }
 
+// --- Permission (ACP `session/request_permission`) — SHARED CONTRACT (issue #559) ------------------
+// A `permission` event models ACP's `session/request_permission`: the agent asks the operator to
+// allow/deny a proposed action (usually a tool call), and the operator (or an auto policy) resolves it.
+// It is decoded here (the ONE parser) and folded here (the ONE fold) into a paired {@link DerivedPermission}.
+// These exported types are the SINGLE SOURCE OF TRUTH the sibling slices (cockpit render, escalation
+// bridge) consume — they must import these, never reinvent a divergent permission shape. See the durable
+// declaration in `app/contracts.ts` (`type:PermissionPolicy`, `wire:transcript.permission`).
+
+/**
+ * The role's permission policy the PRODUCER tags a request with. `"escalate"` means a human must be
+ * asked (the cockpit renders an Allow/Deny prompt, the escalation bridge raises a user task);
+ * `"yolo"` means the action is auto-allowed and never prompts a human. Cockpit + bridge branch on this.
+ */
+export type PermissionPolicy = "escalate" | "yolo";
+
+/** The kind of a permission option — mirrors ACP's option kinds (allow/reject × once/always). */
+export type PermissionOptionKind = "allow-once" | "allow-always" | "reject-once" | "reject-always";
+
+/** One offered permission option (ACP `options[]` member): a stable id, a label, and its kind. */
+export interface PermissionOption {
+  readonly optionId: string;
+  readonly name: string;
+  readonly kind: PermissionOptionKind;
+}
+
+/**
+ * A permission REQUEST: the agent asks the operator to allow/deny a proposed action. The `callId`
+ * pairs the eventual {@link PermissionResolutionEvent} back to this request (mirroring how
+ * `tool-call`/`tool-result` pair by `callId`).
+ */
+export interface PermissionRequestEvent extends TranscriptEventBase {
+  readonly kind: "permission";
+  readonly phase: "request";
+  /** Stable id pairing this request to its resolution. */
+  readonly callId: string;
+  /** The producer-tagged policy the cockpit + bridge branch on. */
+  readonly policy: PermissionPolicy;
+  /** The offered options — always at least one (the decoder rejects an empty list). */
+  readonly options: readonly PermissionOption[];
+  /** The tool the proposed action would invoke, when known. */
+  readonly toolName?: string;
+  /** A short human-readable title for the prompt. */
+  readonly title?: string;
+  /** A longer human-readable reason for the prompt. */
+  readonly reason?: string;
+}
+
+/**
+ * A permission RESOLUTION: the operator's (or an auto policy's) decision, carrying the same `callId`,
+ * the chosen `optionId`, and whether the action was `allowed`.
+ */
+export interface PermissionResolutionEvent extends TranscriptEventBase {
+  readonly kind: "permission";
+  readonly phase: "resolution";
+  /** The `callId` of the {@link PermissionRequestEvent} this resolves. */
+  readonly callId: string;
+  /** The chosen option's id. */
+  readonly optionId: string;
+  /** True = allowed, false = denied. */
+  readonly allowed: boolean;
+  /** Provenance of the decision, when supplied. */
+  readonly by?: "operator" | "auto";
+}
+
 /** The core typed transcript-event union (merge-extensible: authors add kinds via the vocab). */
 export type TranscriptEvent =
   | StreamChunkEvent
@@ -132,7 +197,9 @@ export type TranscriptEvent =
   | ToolResultEvent
   | TurnEvent
   | StepEvent
-  | LifecycleEvent;
+  | LifecycleEvent
+  | PermissionRequestEvent
+  | PermissionResolutionEvent;
 
 /** A stored chunk as the store/read path exposes it (mirrors `TranscriptChunk`). */
 export interface StoredChunk {
@@ -172,6 +239,32 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 
+const PERMISSION_OPTION_KINDS: readonly PermissionOptionKind[] = [
+  "allow-once",
+  "allow-always",
+  "reject-once",
+  "reject-always",
+];
+
+/**
+ * Decode ACP's `options[]` into typed {@link PermissionOption}s, or `undefined` if the array is
+ * missing/empty or any member is malformed (so the whole request envelope is rejected → `stream-chunk`).
+ */
+function decodePermissionOptions(value: unknown): PermissionOption[] | undefined {
+  if (!Array.isArray(value) || value.length === 0) return undefined;
+  const options: PermissionOption[] = [];
+  for (const raw of value) {
+    if (!isRecord(raw)) return undefined;
+    const optionId = str(raw, "optionId");
+    const name = str(raw, "name");
+    const kindRaw = str(raw, "kind");
+    const kind = PERMISSION_OPTION_KINDS.find((k) => k === kindRaw);
+    if (optionId === undefined || name === undefined || kind === undefined) return undefined;
+    options.push({ optionId, name, kind });
+  }
+  return options;
+}
+
 /**
  * The opinionated core vocabulary — the built-in event kinds every consumer understands out of the
  * box. Authors extend it in the SAME schema via {@link mergeTranscriptVocab}; they never fork the
@@ -207,6 +300,11 @@ export const CORE_TRANSCRIPT_VOCAB: TranscriptVocab = Object.freeze({
       ...(content !== undefined ? { content } : {}),
     };
   },
+  // ACP `plan` mapping: ACP `session/update` plan updates map onto the EXISTING `step`/`turn`
+  // vocabulary rather than a new kind — an ACP plan ENTRY becomes a `step` (its `label` is the plan
+  // entry's title; the entry ordinal is not preserved, as `StepEvent` carries only a `label`), and a
+  // plan/turn BOUNDARY becomes a `turn` (its `index` the ACP turn/plan ordinal). The decoders below
+  // already cope with an ACP-shaped `label` (`step`) / `index` (`turn`), so no new kind is needed.
   turn: (body, offset) => {
     const index = num(body, "index");
     return index !== undefined ? { kind: "turn", offset, index } : { kind: "turn", offset };
@@ -220,6 +318,48 @@ export const CORE_TRANSCRIPT_VOCAB: TranscriptVocab = Object.freeze({
     if (phase !== "open" && phase !== "completed" && phase !== "exited") return undefined;
     return { kind: "lifecycle", offset, phase };
   },
+  // A single `permission` decoder handles BOTH shapes (never a parser fork), branching on `phase`.
+  // Malformed envelopes return `undefined` and fall back to `stream-chunk`, like the other decoders.
+  permission: (body, offset) => {
+    const callId = str(body, "callId");
+    if (callId === undefined) return undefined;
+    const phase = str(body, "phase");
+    if (phase === "request") {
+      const policy = str(body, "policy");
+      if (policy !== "escalate" && policy !== "yolo") return undefined;
+      const options = decodePermissionOptions(body.options);
+      if (options === undefined) return undefined;
+      const toolName = str(body, "toolName");
+      const title = str(body, "title");
+      const reason = str(body, "reason");
+      const event: PermissionRequestEvent = { kind: "permission", phase: "request", offset, callId, policy, options };
+      return {
+        ...event,
+        ...(toolName !== undefined ? { toolName } : {}),
+        ...(title !== undefined ? { title } : {}),
+        ...(reason !== undefined ? { reason } : {}),
+      };
+    }
+    if (phase === "resolution") {
+      const optionId = str(body, "optionId");
+      if (optionId === undefined) return undefined;
+      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.
+      if (by !== undefined && by !== "operator" && by !== "auto") return undefined;
+      const event: PermissionResolutionEvent = {
+        kind: "permission",
+        phase: "resolution",
+        offset,
+        callId,
+        optionId,
+        allowed: body.allowed,
+      };
+      return { ...event, ...(by !== undefined ? { by } : {}) };
+    }
+    return undefined;
+  },
 });
 
 /**
@@ -302,12 +442,35 @@ export interface DerivedMessage {
   readonly offset: number;
 }
 
+/**
+ * A derived permission: a permission REQUEST paired with its RESOLUTION by `callId` (resolution absent
+ * while the request is still pending), mirroring how {@link DerivedTool} pairs a call with its result.
+ * The cockpit and the escalation bridge read THIS — they never re-parse the log.
+ */
+export interface DerivedPermission {
+  readonly callId: string;
+  readonly policy: PermissionPolicy;
+  readonly options: readonly PermissionOption[];
+  readonly toolName?: string;
+  readonly title?: string;
+  readonly reason?: string;
+  readonly offset: number;
+  /** The resolution, once present (pending request → `undefined`). */
+  readonly resolved?: {
+    readonly allowed: boolean;
+    readonly optionId: string;
+    readonly by?: "operator" | "auto";
+    readonly offset: number;
+  };
+}
+
 /** A derived turn: the messages, tool cards and step count folded within one turn boundary. */
 export interface DerivedTurn {
   readonly index: number;
   readonly startOffset: number;
   readonly messages: readonly DerivedMessage[];
   readonly tools: readonly DerivedTool[];
+  readonly permissions: readonly DerivedPermission[];
   readonly steps: number;
 }
 
@@ -319,6 +482,8 @@ export interface DerivedView {
   readonly messages: readonly DerivedMessage[];
   /** Every tool card across all turns, in offset order. */
   readonly tools: readonly DerivedTool[];
+  /** Every permission across all turns, in offset order (each request paired to its resolution by `callId`). */
+  readonly permissions: readonly DerivedPermission[];
   /** Total retained raw bytes (UTF-8) across `stream-chunk` events — the byte-replay fidelity accounting. */
   readonly rawByteLength: number;
   /** Number of retained raw chunks. */
@@ -334,6 +499,7 @@ interface MutableTurn {
   startOffset: number;
   messages: DerivedMessage[];
   tools: DerivedTool[];
+  permissions: DerivedPermission[];
   steps: number;
 }
 
@@ -351,8 +517,10 @@ export function deriveView(events: Iterable<TranscriptEvent>): DerivedView {
   const turns: MutableTurn[] = [];
   const messages: DerivedMessage[] = [];
   const tools: DerivedTool[] = [];
+  const permissions: DerivedPermission[] = [];
   const openTools = new Map<string, DerivedTool>();
   let anonymousTool: DerivedTool | undefined;
+  const openPermissions = new Map<string, DerivedPermission>();
   let rawByteLength = 0;
   let rawChunkCount = 0;
   let lifecycle: "open" | "completed" | "exited" = "open";
@@ -361,7 +529,7 @@ export function deriveView(events: Iterable<TranscriptEvent>): DerivedView {
 
   const ensureTurn = (offset: number): MutableTurn => {
     if (current === undefined) {
-      current = { index: turns.length, startOffset: offset, messages: [], tools: [], steps: 0 };
+      current = { index: turns.length, startOffset: offset, messages: [], tools: [], permissions: [], steps: 0 };
       turns.push(current);
     }
     return current;
@@ -371,7 +539,14 @@ export function deriveView(events: Iterable<TranscriptEvent>): DerivedView {
     eventCount++;
     switch (event.kind) {
       case "turn": {
-        current = { index: event.index ?? turns.length, startOffset: event.offset, messages: [], tools: [], steps: 0 };
+        current = {
+          index: event.index ?? turns.length,
+          startOffset: event.offset,
+          messages: [],
+          tools: [],
+          permissions: [],
+          steps: 0,
+        };
         turns.push(current);
         break;
       }
@@ -408,6 +583,33 @@ export function deriveView(events: Iterable<TranscriptEvent>): DerivedView {
         }
         break;
       }
+      case "permission": {
+        // A `permission` event is one of two phases (same discriminant `kind`); branch on `phase`. A
+        // REQUEST opens a pending DerivedPermission (paired to its turn); a RESOLUTION folds back into
+        // the open request by `callId` — mirroring the tool-call/tool-result open-map pairing above.
+        if (event.phase === "request") {
+          const permission: DerivedPermission = {
+            policy: event.policy,
+            options: event.options,
+            offset: event.offset,
+            callId: event.callId,
+            ...(event.toolName !== undefined ? { toolName: event.toolName } : {}),
+            ...(event.title !== undefined ? { title: event.title } : {}),
+            ...(event.reason !== undefined ? { reason: event.reason } : {}),
+          };
+          permissions.push(permission);
+          ensureTurn(event.offset).permissions.push(permission);
+          openPermissions.set(event.callId, permission);
+        } else {
+          const target = openPermissions.get(event.callId);
+          if (target !== undefined) {
+            pairResolution(permissions, target, event);
+            pairResolutionInTurns(turns, target, event);
+            openPermissions.delete(event.callId);
+          }
+        }
+        break;
+      }
       case "lifecycle": {
         lifecycle = event.phase;
         break;
@@ -421,9 +623,17 @@ export function deriveView(events: Iterable<TranscriptEvent>): DerivedView {
   }
 
   return {
-    turns: turns.map((t) => ({ index: t.index, startOffset: t.startOffset, messages: t.messages, tools: t.tools, steps: t.steps })),
+    turns: turns.map((t) => ({
+      index: t.index,
+      startOffset: t.startOffset,
+      messages: t.messages,
+      tools: t.tools,
+      permissions: t.permissions,
+      steps: t.steps,
+    })),
     messages,
     tools,
+    permissions,
     rawByteLength,
     rawChunkCount,
     lifecycle,
@@ -457,6 +667,35 @@ function withResult(tool: DerivedTool, result: ToolResultEvent): DerivedTool {
   };
 }
 
+/** Replace a pending permission with its resolution in the flat list (by identity — see {@link pairResult}). */
+function pairResolution(list: DerivedPermission[], target: DerivedPermission, resolution: PermissionResolutionEvent): void {
+  const idx = list.indexOf(target);
+  if (idx >= 0) list[idx] = withResolution(target, resolution);
+}
+
+/** Replace a pending permission with its resolution inside whichever turn holds it. */
+function pairResolutionInTurns(turns: MutableTurn[], target: DerivedPermission, resolution: PermissionResolutionEvent): void {
+  for (const turn of turns) {
+    const idx = turn.permissions.indexOf(target);
+    if (idx >= 0) {
+      turn.permissions[idx] = withResolution(target, resolution);
+      return;
+    }
+  }
+}
+
+function withResolution(permission: DerivedPermission, resolution: PermissionResolutionEvent): DerivedPermission {
+  return {
+    ...permission,
+    resolved: {
+      allowed: resolution.allowed,
+      optionId: resolution.optionId,
+      offset: resolution.offset,
+      ...(resolution.by !== undefined ? { by: resolution.by } : {}),
+    },
+  };
+}
+
 /**
  * Convenience: parse a run of stored chunks into typed events through {@link parseTranscriptEvent} (the
  * one parser) and fold them with {@link deriveView} in a single call — the entry point a consumer uses

package/app/contracts.ts

@@ -136,6 +136,13 @@ export const ENV_CONTRACTS = {
     owner: "app/service.ts",
     semantics: "Minutes between review nudges.",
   },
+  NANO_PR_MERGE_LANDED_WAIT_TIMEOUT: {
+    category: "env",
+    name: "NANO_PR_MERGE_LANDED_WAIT_TIMEOUT",
+    owner: "app/service.ts",
+    semantics:
+      "How long the merge loop waits for a queued PR to actually land before escalating (FEEL/ISO-8601 duration).",
+  },
   NANO_PR_AUTO_MERGE: {
     category: "env",
     name: "NANO_PR_AUTO_MERGE",
@@ -400,9 +407,26 @@ export const WIRE_CONTRACTS = {
       "Filesystem-import request body POSTed to /actions/delivery-graph/library/import (issue #524, epic #519 S5). Declared in openapi.yaml as `ImportToLibrarySubmit`; the compose App-View's `<input type=file accept=.json>` reads the picked file's text client-side and POSTs it here as the raw `graphJson` string. The door validates + compiles it through the SAME `parseAndCompileText` pipeline preview/stage/save use, then persists `source: imported` — an uncompilable graph is a clean 400 and NOTHING is written. Its `name` defaults to the imported graph's own `name`; an explicit `name` overrides it (an unnamed graph with no override is a clean 400 — the library id is name-derived). Related to but DISTINCT from `SaveToLibrarySubmit` (which is graphJson-OR-digest and needs no required file text); consume this ONE shape across the openapi edge, the door, and the compose mount — do not re-declare a synonym.",
     shape: "{ graphJson: string, name?: string, description?: string }",
   },
+  "transcript.permission": {
+    category: "wire",
+    name: "transcript.permission",
+    owner: "app/agentic/transcript-events.ts",
+    semantics:
+      "The `permission` transcript-event envelope (issue #559) modelling ACP's `session/request_permission`, decoded by the ONE parser (`parseTranscriptEvent`) and folded by the ONE fold (`deriveView`) in app/agentic/transcript-events.ts. Two phases share the `kind:\"permission\"` discriminant, distinguished by `phase`. A REQUEST carries a stable `callId` (pairs the resolution back, like tool-call/tool-result), the producer-tagged `policy` (\"escalate\" = must ask a human, \"yolo\" = auto-allowed), the offered `options` (a NON-EMPTY array of ACP `{optionId,name,kind}` where kind is allow-once/allow-always/reject-once/reject-always — the decoder rejects a missing or empty `options`), and optional `toolName`/`title`/`reason`. A RESOLUTION carries the same `callId`, the chosen `optionId`, a boolean `allowed`, and optional `by` provenance (operator/auto). deriveView surfaces these as `DerivedPermission` (paired by callId) on `DerivedView.permissions` and `DerivedTurn.permissions`. The cockpit-render and escalation-bridge slices CONSUME this exact wire shape — do not re-declare a synonym.",
+    shape:
+      '{ nwfTranscriptEvent: 1, kind: "permission", phase: "request", callId: string, policy: "escalate"|"yolo", options: [{ optionId: string, name: string, kind: "allow-once"|"allow-always"|"reject-once"|"reject-always" }, ...Array<{ optionId: string, name: string, kind: "allow-once"|"allow-always"|"reject-once"|"reject-always" }>], toolName?: string, title?: string, reason?: string } | { nwfTranscriptEvent: 1, kind: "permission", phase: "resolution", callId: string, optionId: string, allowed: boolean, by?: "operator"|"auto" }',
+  },
 } as const satisfies Record<string, WireContract>;
 
 export const TYPE_CONTRACTS = {
+  PermissionPolicy: {
+    category: "type",
+    name: "PermissionPolicy",
+    owner: "app/agentic/transcript-events.ts",
+    semantics:
+      "The role's permission policy a `permission` transcript-event REQUEST is tagged with (issue #559): `\"escalate\"` (a human must be asked — cockpit renders an Allow/Deny prompt, the escalation bridge raises a user task) vs `\"yolo\"` (auto-allowed, never prompts). Exported from app/agentic/transcript-events.ts alongside the shared permission contract types (`PermissionOption`, `PermissionOptionKind`, `PermissionRequestEvent`, `PermissionResolutionEvent`, and the derived `DerivedPermission` surface on `DerivedView`/`DerivedTurn`). The cockpit-render and escalation-bridge siblings IMPORT these — they must not reinvent a divergent permission shape or a synonym policy enum.",
+    module: "app/agentic/transcript-events.ts",
+  },
   BlackboardEntry: {
     category: "type",
     name: "BlackboardEntry",

package/app/mergeLandedWait.test.ts

@@ -0,0 +1,39 @@
+// Unit coverage for the merge-queue landing liveness timeout policy. The value is baked into every
+// merge-loop instance's `landedWaitTimeout` process variable and evaluated by the `wait-landed-timeout`
+// timer catch (the timer arm of the `eg-landed` event-based gateway), so a malformed operator env
+// must never deploy an uninterpretable `<bpmn:timeDuration>` — it falls back to the default instead.
+// Run with `node --test`.
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { DEFAULT_MERGE_LANDED_WAIT_TIMEOUT, mergeLandedWaitTimeout } from "./mergeLandedWait.ts";
+
+test("mergeLandedWaitTimeout: blank / absent / malformed → default", () => {
+  assert.equal(mergeLandedWaitTimeout(undefined), DEFAULT_MERGE_LANDED_WAIT_TIMEOUT);
+  assert.equal(mergeLandedWaitTimeout(""), DEFAULT_MERGE_LANDED_WAIT_TIMEOUT);
+  assert.equal(mergeLandedWaitTimeout("   "), DEFAULT_MERGE_LANDED_WAIT_TIMEOUT);
+  assert.equal(mergeLandedWaitTimeout("1h"), DEFAULT_MERGE_LANDED_WAIT_TIMEOUT); // missing leading P/T
+  assert.equal(mergeLandedWaitTimeout("P"), DEFAULT_MERGE_LANDED_WAIT_TIMEOUT); // no component
+  assert.equal(mergeLandedWaitTimeout("PT"), DEFAULT_MERGE_LANDED_WAIT_TIMEOUT); // T with no time part
+  assert.equal(mergeLandedWaitTimeout("garbage"), DEFAULT_MERGE_LANDED_WAIT_TIMEOUT);
+});
+
+test("mergeLandedWaitTimeout: a valid ISO-8601 duration is honoured and upper-cased", () => {
+  assert.equal(mergeLandedWaitTimeout("PT30M"), "PT30M");
+  assert.equal(mergeLandedWaitTimeout("pt2h"), "PT2H");
+  assert.equal(mergeLandedWaitTimeout("P1D"), "P1D");
+  assert.equal(mergeLandedWaitTimeout("  pt90m  "), "PT90M");
+});
+
+test("mergeLandedWaitTimeout: an explicit fallback is honoured for a bad value", () => {
+  assert.equal(mergeLandedWaitTimeout("nope", "PT10M"), "PT10M");
+  assert.equal(mergeLandedWaitTimeout("PT45M", "PT10M"), "PT45M");
+});
+
+test("the default is itself a well-formed ISO-8601 duration (never an uninterpretable timer)", () => {
+  // Validate the default against the grammar with a *distinct* fallback: if the default were
+  // malformed it would fall through to the sentinel, so equality to itself proves it parses.
+  const sentinel = "PT1S";
+  assert.notEqual(DEFAULT_MERGE_LANDED_WAIT_TIMEOUT, sentinel);
+  assert.equal(mergeLandedWaitTimeout(DEFAULT_MERGE_LANDED_WAIT_TIMEOUT, sentinel), DEFAULT_MERGE_LANDED_WAIT_TIMEOUT);
+});