@sublang/playbook 6.0.0 → 7.0.0

package/reference/sdlc/code.playbook/playbook.config.template.yaml

@@ -1,10 +1,10 @@
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
 
-# Generic `playbook` launcher config.
+# Shared `playbook` and `playbook run` launcher config.
 # Top-level host fields only — no `config:` wrapper, no top-level `players`.
 # The launcher injects captain.from and the namespaced <id>-<role> host
-# players, then launches cligent's tmux-play under the Playbook Captain shell.
+# players, then hosts the same Playbook Captain shell interactively or headlessly.
 
 # Every agent — the Captain and each playbook role — carries its own
 # settings inline: an adapter shorthand (claude, codex) or a block with
@@ -33,7 +33,8 @@ captain:
   permissions:
     mode: auto
 
-# Host notifications. Omitting turn_aborted resolves it to off.
+# Interactive host notifications. Headless runs ignore presentation fields.
+# Omitting turn_aborted resolves it to off.
 notifications:
   player_finished: bell
   turn_finished: desktop
@@ -90,14 +91,3 @@ playbooks:
         permissions:
           mode: auto
           writablePaths: ['.git']
-
-# Non-interactive `playbook run` defaults (optional). Each value is an
-# agent string <adapter>[:<model>][@<effort>]; `player` is the catch-all
-# for any required role without its own `players.<role>` entry, across
-# every playbook. Flags override per role (--player / --captain), and
-# `playbook run resume` keeps the lineup stored with the parked session.
-#run:
-#  captain: claude:claude-opus-4-8@high
-#  player: claude:claude-opus-4-8@high
-#  players:
-#    coder: claude:claude-opus-4-8[1m]@xhigh

package/reference/sdlc/decide.playbook/decide.playbook.js

@@ -203,6 +203,22 @@ function parseJudgeJson(raw) {
 function isPlainObject(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
+function sortJson(value) {
+    if (Array.isArray(value))
+        return value.map((entry) => sortJson(entry));
+    if (value !== null && typeof value === 'object') {
+        const record = value;
+        const sorted = {};
+        for (const key of Object.keys(record).sort()) {
+            sorted[key] = sortJson(record[key]);
+        }
+        return sorted;
+    }
+    return value;
+}
+function stableJson(value, path) {
+    return JSON.stringify(sortJson(snapshotJsonValue(value, path)));
+}
 function stripCodeFence(text) {
     const fence = text.match(/^```(?:json)?\s*\n?([\s\S]*?)\n?```$/i);
     return fence ? fence[1].trim() : text;
@@ -677,13 +693,13 @@ export const createPlaybookRuntime = (options) => {
             playerResumeTokens.set(playerId, token);
         }
     };
-    const currentState = () => {
+    const currentState = (pendingCall = nestedBridge.getPendingCall()) => {
         const live = actor;
         if (!live) {
             throw new Error('decide runtime: actor is not initialized');
         }
         return normalizePlaybookSnapshot(live.getSnapshot(), {
-            pendingCall: nestedBridge.getPendingCall(),
+            pendingCall,
         });
     };
     const stateIdentity = (state) => {
@@ -1181,7 +1197,7 @@ export const createPlaybookRuntime = (options) => {
     // The caller rethrows its original failure. A restore failure skips
     // the disposal trace — the parked session was never re-bound in this
     // process, so its persisted snapshot stays authoritative (DR-014 §2).
-    const cleanupFailedStart = async (options) => {
+    const cleanupFailedStart = async (cause, options) => {
         let finalState;
         if (options.emitDisposal && actor) {
             try {
@@ -1197,6 +1213,12 @@ export const createPlaybookRuntime = (options) => {
         catch {
             // Preserve the original startup failure.
         }
+        try {
+            await nestedBridge.abortPending(cause);
+        }
+        catch {
+            // Preserve the original startup failure.
+        }
         try {
             await judgeQueue.onIdle();
             await drainBoundaryCallsAndEmissions();
@@ -1269,7 +1291,7 @@ export const createPlaybookRuntime = (options) => {
                 await flush();
             }
             catch (error) {
-                await cleanupFailedStart({ emitDisposal: true });
+                await cleanupFailedStart(error, { emitDisposal: true });
                 throw error;
             }
             finally {
@@ -1278,10 +1300,11 @@ export const createPlaybookRuntime = (options) => {
                     initInFlight = undefined;
             }
         },
-        // DR-014 §1 / PBRT-45: JSON-safe capture of a parked session.
+        // DR-014 §1 / DR-031 §5 / PBRT-45: JSON-safe capture of a parked
+        // session, including one already-started suspended REVIEW call.
         // Defined only at a safe capture point — initialized, not disposing
-        // or disposed, no active public boundary, and the actor quiescent
-        // with status `active` and no pending nested REVIEW call.
+        // or disposed, no active public boundary, and the actor quiescent with
+        // status `active`.
         exportSnapshot() {
             if (!actor ||
                 !sessionIdentity ||
@@ -1292,15 +1315,40 @@ export const createPlaybookRuntime = (options) => {
             if (currentTurnId !== undefined || currentSignal !== undefined) {
                 return undefined;
             }
-            if (nestedBridge.getPendingCall())
+            const pendingCall = nestedBridge.getPendingCall();
+            const bridgeSuspendedCall = nestedBridge.getSuspendedCall();
+            if ((pendingCall === undefined) !== (bridgeSuspendedCall === undefined)) {
+                return undefined;
+            }
+            if (pendingCall !== undefined &&
+                bridgeSuspendedCall !== undefined &&
+                (pendingCall.callId !== bridgeSuspendedCall.callId ||
+                    pendingCall.playbookId !== bridgeSuspendedCall.playbookId ||
+                    pendingCall.childSessionId !== bridgeSuspendedCall.childSessionId)) {
                 return undefined;
+            }
+            let suspendedCall;
+            if (bridgeSuspendedCall !== undefined) {
+                if (!playbookCallTurnIds.has(bridgeSuspendedCall.callId)) {
+                    return undefined;
+                }
+                const turnId = playbookCallTurnIds.get(bridgeSuspendedCall.callId);
+                if (bridgeSuspendedCall.turnId !== undefined &&
+                    bridgeSuspendedCall.turnId !== turnId) {
+                    return undefined;
+                }
+                suspendedCall = {
+                    ...bridgeSuspendedCall,
+                    ...(turnId === undefined ? {} : { turnId }),
+                };
+            }
             const state = currentState();
             if (state.status !== 'active' || !state.quiescent)
                 return undefined;
             const machine = detachPersistedMachineSnapshot(actor.getPersistedSnapshot());
             const context = actor.getSnapshot().context;
             return {
-                schemaVersion: 1,
+                schemaVersion: 2,
                 playbookId: sessionIdentity.playbookId,
                 machine,
                 playerResumeTokens: snapshotPlayerResumeTokens(),
@@ -1318,6 +1366,7 @@ export const createPlaybookRuntime = (options) => {
                     question: pending.question,
                     sourceItem: pending.sourceItem,
                 })),
+                ...(suspendedCall === undefined ? {} : { suspendedCall }),
             };
         },
         // DR-014 §1 / PBRT-45: alternative to `init` that rehydrates an
@@ -1333,7 +1382,10 @@ export const createPlaybookRuntime = (options) => {
                 throw new Error('decide runtime: restore(session, snapshot) may only be called once');
             }
             const identity = snapshotPlaybookSession(session);
-            const boundSnapshot = assertPlaybookRuntimeSnapshot(snapshot, identity.playbookId);
+            const boundSnapshot = assertPlaybookRuntimeSnapshot(snapshot, identity.playbookId, { allowSuspendedCall: true });
+            const suspendedCall = boundSnapshot.schemaVersion === 2
+                ? boundSnapshot.suspendedCall
+                : undefined;
             let finishInitialization;
             const initialization = new Promise((resolve) => {
                 finishInitialization = resolve;
@@ -1353,16 +1405,28 @@ export const createPlaybookRuntime = (options) => {
                     priorExternalPlayerTokens = snapshotPlayerResumeTokens();
                 }
                 restorePlayerResumeTokens(boundSnapshot.playerResumeTokens);
+                nestedBridge.prepareRestore(suspendedCall);
+                if (suspendedCall !== undefined) {
+                    playbookCallTurnIds.set(suspendedCall.callId, suspendedCall.turnId);
+                }
                 suppressInspectionEmissions = true;
                 createRuntimeActor(boundSnapshot.machine);
                 actor?.start();
-                const restoredState = currentState();
+                const restoredState = currentState(suspendedCall);
                 if (restoredState.status !== 'active') {
                     throw new Error(`decide runtime: restored actor status is ${restoredState.status}, expected active`);
                 }
-                suppressInspectionEmissions = false;
+                if (stableJson(restoredState, 'restored runtime state') !==
+                    stableJson(boundSnapshot.state, 'runtime snapshot state')) {
+                    throw new Error('decide runtime: restored actor state does not match snapshot state');
+                }
                 previousState = restoredState;
                 await flush();
+                suppressInspectionEmissions = false;
+                // Final fallible step: after this publication the authoritative
+                // child has rejoined ordinary resume/abort ownership, so no later
+                // restore validation may trigger failed-start rollback.
+                nestedBridge.confirmRestore();
             }
             catch (error) {
                 let failure = error;
@@ -1374,7 +1438,7 @@ export const createPlaybookRuntime = (options) => {
                         failure = new AggregateError([error, rollbackError], 'DECIDE restore and player continuation rollback failed');
                     }
                 }
-                await cleanupFailedStart({ emitDisposal: false });
+                await cleanupFailedStart(failure, { emitDisposal: false });
                 throw failure;
             }
             finally {

package/reference/sdlc/decide.playbook/decide.playbook.ts

@@ -324,6 +324,23 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
   return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
 
+function sortJson(value: JsonValue): JsonValue {
+  if (Array.isArray(value)) return value.map((entry) => sortJson(entry));
+  if (value !== null && typeof value === 'object') {
+    const record = value as { readonly [key: string]: JsonValue };
+    const sorted: Record<string, JsonValue> = {};
+    for (const key of Object.keys(record).sort()) {
+      sorted[key] = sortJson(record[key]);
+    }
+    return sorted;
+  }
+  return value;
+}
+
+function stableJson(value: unknown, path: string): string {
+  return JSON.stringify(sortJson(snapshotJsonValue(value, path)));
+}
+
 function stripCodeFence(text: string): string {
   const fence = text.match(/^```(?:json)?\s*\n?([\s\S]*?)\n?```$/i);
   return fence ? fence[1].trim() : text;
@@ -920,13 +937,16 @@ export const createPlaybookRuntime: PlaybookRuntimeFactory<
       playerResumeTokens.set(playerId, token);
     }
   };
-  const currentState = (): PlaybookState => {
+  const currentState = (
+    pendingCall: PlaybookPendingCall | undefined =
+      nestedBridge.getPendingCall(),
+  ): PlaybookState => {
     const live = actor;
     if (!live) {
       throw new Error('decide runtime: actor is not initialized');
     }
     return normalizePlaybookSnapshot(live.getSnapshot(), {
-      pendingCall: nestedBridge.getPendingCall(),
+      pendingCall,
     });
   };
   const stateIdentity = (state: PlaybookState): { stateId?: string } => {
@@ -1592,9 +1612,10 @@ export const createPlaybookRuntime: PlaybookRuntimeFactory<
   // The caller rethrows its original failure. A restore failure skips
   // the disposal trace — the parked session was never re-bound in this
   // process, so its persisted snapshot stays authoritative (DR-014 §2).
-  const cleanupFailedStart = async (options: {
-    emitDisposal: boolean;
-  }): Promise<void> => {
+  const cleanupFailedStart = async (
+    cause: unknown,
+    options: { emitDisposal: boolean },
+  ): Promise<void> => {
     let finalState: PlaybookState | undefined;
     if (options.emitDisposal && actor) {
       try {
@@ -1608,6 +1629,11 @@ export const createPlaybookRuntime: PlaybookRuntimeFactory<
     } catch {
       // Preserve the original startup failure.
     }
+    try {
+      await nestedBridge.abortPending(cause);
+    } catch {
+      // Preserve the original startup failure.
+    }
     try {
       await judgeQueue.onIdle();
       await drainBoundaryCallsAndEmissions();
@@ -1682,7 +1708,7 @@ export const createPlaybookRuntime: PlaybookRuntimeFactory<
         actor?.start();
         await flush();
       } catch (error) {
-        await cleanupFailedStart({ emitDisposal: true });
+        await cleanupFailedStart(error, { emitDisposal: true });
         throw error;
       } finally {
         finishInitialization();
@@ -1690,10 +1716,11 @@ export const createPlaybookRuntime: PlaybookRuntimeFactory<
       }
     },
 
-    // DR-014 §1 / PBRT-45: JSON-safe capture of a parked session.
+    // DR-014 §1 / DR-031 §5 / PBRT-45: JSON-safe capture of a parked
+    // session, including one already-started suspended REVIEW call.
     // Defined only at a safe capture point — initialized, not disposing
-    // or disposed, no active public boundary, and the actor quiescent
-    // with status `active` and no pending nested REVIEW call.
+    // or disposed, no active public boundary, and the actor quiescent with
+    // status `active`.
     exportSnapshot(): PlaybookRuntimeSnapshot | undefined {
       if (
         !actor ||
@@ -1706,7 +1733,37 @@ export const createPlaybookRuntime: PlaybookRuntimeFactory<
       if (currentTurnId !== undefined || currentSignal !== undefined) {
         return undefined;
       }
-      if (nestedBridge.getPendingCall()) return undefined;
+      const pendingCall = nestedBridge.getPendingCall();
+      const bridgeSuspendedCall = nestedBridge.getSuspendedCall();
+      if ((pendingCall === undefined) !== (bridgeSuspendedCall === undefined)) {
+        return undefined;
+      }
+      if (
+        pendingCall !== undefined &&
+        bridgeSuspendedCall !== undefined &&
+        (pendingCall.callId !== bridgeSuspendedCall.callId ||
+          pendingCall.playbookId !== bridgeSuspendedCall.playbookId ||
+          pendingCall.childSessionId !== bridgeSuspendedCall.childSessionId)
+      ) {
+        return undefined;
+      }
+      let suspendedCall: typeof bridgeSuspendedCall;
+      if (bridgeSuspendedCall !== undefined) {
+        if (!playbookCallTurnIds.has(bridgeSuspendedCall.callId)) {
+          return undefined;
+        }
+        const turnId = playbookCallTurnIds.get(bridgeSuspendedCall.callId);
+        if (
+          bridgeSuspendedCall.turnId !== undefined &&
+          bridgeSuspendedCall.turnId !== turnId
+        ) {
+          return undefined;
+        }
+        suspendedCall = {
+          ...bridgeSuspendedCall,
+          ...(turnId === undefined ? {} : { turnId }),
+        };
+      }
       const state = currentState();
       if (state.status !== 'active' || !state.quiescent) return undefined;
       const machine = detachPersistedMachineSnapshot(
@@ -1716,7 +1773,7 @@ export const createPlaybookRuntime: PlaybookRuntimeFactory<
         actor.getSnapshot() as SnapshotFrom<typeof decideMachine>
       ).context as unknown as Record<string, unknown>;
       return {
-        schemaVersion: 1,
+        schemaVersion: 2,
         playbookId: sessionIdentity.playbookId,
         machine,
         playerResumeTokens: snapshotPlayerResumeTokens(),
@@ -1736,6 +1793,7 @@ export const createPlaybookRuntime: PlaybookRuntimeFactory<
             sourceItem: pending.sourceItem,
           }),
         ),
+        ...(suspendedCall === undefined ? {} : { suspendedCall }),
       };
     },
 
@@ -1762,7 +1820,12 @@ export const createPlaybookRuntime: PlaybookRuntimeFactory<
       const boundSnapshot = assertPlaybookRuntimeSnapshot(
         snapshot,
         identity.playbookId,
+        { allowSuspendedCall: true },
       );
+      const suspendedCall =
+        boundSnapshot.schemaVersion === 2
+          ? boundSnapshot.suspendedCall
+          : undefined;
       let finishInitialization!: () => void;
       const initialization = new Promise<void>((resolve) => {
         finishInitialization = resolve;
@@ -1784,18 +1847,34 @@ export const createPlaybookRuntime: PlaybookRuntimeFactory<
           priorExternalPlayerTokens = snapshotPlayerResumeTokens();
         }
         restorePlayerResumeTokens(boundSnapshot.playerResumeTokens);
+        nestedBridge.prepareRestore(suspendedCall);
+        if (suspendedCall !== undefined) {
+          playbookCallTurnIds.set(suspendedCall.callId, suspendedCall.turnId);
+        }
         suppressInspectionEmissions = true;
         createRuntimeActor(boundSnapshot.machine);
         actor?.start();
-        const restoredState = currentState();
+        const restoredState = currentState(suspendedCall);
         if (restoredState.status !== 'active') {
           throw new Error(
             `decide runtime: restored actor status is ${restoredState.status}, expected active`,
           );
         }
-        suppressInspectionEmissions = false;
+        if (
+          stableJson(restoredState, 'restored runtime state') !==
+          stableJson(boundSnapshot.state, 'runtime snapshot state')
+        ) {
+          throw new Error(
+            'decide runtime: restored actor state does not match snapshot state',
+          );
+        }
         previousState = restoredState;
         await flush();
+        suppressInspectionEmissions = false;
+        // Final fallible step: after this publication the authoritative
+        // child has rejoined ordinary resume/abort ownership, so no later
+        // restore validation may trigger failed-start rollback.
+        nestedBridge.confirmRestore();
       } catch (error) {
         let failure = error;
         if (priorExternalPlayerTokens !== undefined) {
@@ -1808,7 +1887,7 @@ export const createPlaybookRuntime: PlaybookRuntimeFactory<
             );
           }
         }
-        await cleanupFailedStart({ emitDisposal: false });
+        await cleanupFailedStart(failure, { emitDisposal: false });
         throw failure;
       } finally {
         finishInitialization();

package/slc/link.md

@@ -1240,12 +1240,12 @@ durability, the pair shall behave as follows.
 
 `exportSnapshot()` shall return `undefined` unless the runtime is at a safe
 capture point: initialized, not disposing or disposed, no active
-`handleBossInput`/`resumePlaybookCall` boundary, no pending nested playbook
-call, and the root actor at a quiescent state with actor status `active`.
+`handleBossInput`/`resumePlaybookCall` boundary, and the root actor at a
+quiescent state with actor status `active`.
 At a safe capture point it shall return a JSON-safe
 `PlaybookRuntimeSnapshot` carrying:
 
-- `schemaVersion`: literal `1`.
+- `schemaVersion`: literal `2`.
 - `playbookId`: the bound session's playbook id.
 - `machine`: the root actor's `getPersistedSnapshot()` result, passed
   through the shared JSON detachment with any raw `Error` context value
@@ -1255,19 +1255,33 @@ At a safe capture point it shall return a JSON-safe
   (§PlaybookPorts contract).
 - `sequences`: the live `trace`, `turn`, `judgeCall`, `playerCall`, and
   `playbookCall` counters, plus `captainCall` when the runtime supports direct
-  Captain calls. `captainCall` remains optional under schema version `1` for
-  backward compatibility; a direct-Captain-capable runtime shall persist it.
+  Captain calls. A direct-Captain-capable runtime shall persist it in current
+  schema-version-2 exports; it remains optional in legacy schema-version-1
+  input, where restore uses `trace` as its collision-safe floor.
 - `state`: the current normalized state descriptor.
 - `pendingBossQuestions`: the pending Boss question(s) from FSM context as
   a list of `{ questionId, player, question, sourceItem? }`, empty when the
   parked state awaits no reply. This list exists so hosts can surface the
   question without parsing status lines or telemetry.
+- `suspendedCall`: omitted when no nested call is pending; otherwise the
+  shared nested bridge's complete `callId`, source `stateId`, target
+  `playbookId`, exact handed-off `text`, and `childSessionId`, enriched with
+  the call-to-turn map's optional `turnId`.
+
+A pending nested call is exportable only when the bridge's pending identity
+and complete descriptor agree and the call-to-turn map owns that exact call
+id, including ownership whose value is absent. A bridge descriptor that
+already carries a turn id shall equal that map value. Any missing or
+inconsistent bridge, descriptor, or turn-ownership record makes the capture
+unsafe and returns `undefined`.
 
 `restore(session, snapshot)` is an alternative to `init` under the same
 lifecycle guards (§Session lifecycle): it shall reject when already
 initialized, disposing, or disposed, and shall validate
-`snapshot.schemaVersion` and that `snapshot.playbookId` equals
-`session.playbookId` before touching state.
+schema version `1` or `2` and that `snapshot.playbookId` equals
+`session.playbookId` before touching state. Schema version `1` remains a
+descriptor-free legacy input; schema version `2` may carry the suspended-call
+descriptor above.
 The host supplies the same immutable `PlaybookSession` identity the
 snapshot was exported under and recreates the runtime through the same
 factory with equivalent options; the runtime does not diff options, and
@@ -1278,13 +1292,22 @@ make before calling `restore`.
 sequence counters (using the persisted global `trace` counter as a
 collision-safe floor for an absent legacy `captainCall`), and the
 prior-state descriptor from the snapshot,
-construct the actor with the persisted `machine` snapshot, and start it
+prepare the shared nested bridge with the suspended-call descriptor or its
+explicit absence, restore a descriptor's call-to-turn map entry, construct
+the actor with the persisted `machine` snapshot, and start it
 with root inspection emissions suppressed so rehydration emits no
 `session.started` trace, no transition trace, and no human status — the
 session already started, and the next public boundary continues the
-contiguous trace sequence. After start, a restored actor whose status is
-not `active` or whose state descriptor cannot be normalized shall fail
-`restore` through the same failed-start cleanup path as `init`.
+contiguous trace sequence. After start, the runtime shall normalize the
+actual actor state with the prepared suspended call as its pending identity
+and require it to equal the detached persisted state exactly, including
+active status. It shall drain suppressed startup work and invoke the bridge's
+`confirmRestore` as the final fallible restore step, publishing the pending
+identity only after every other validation succeeds. A missing, extra, or
+mismatched reconstructed invocation, an actual/persisted state mismatch, or
+any other failed validation shall fail `restore` through the same
+failed-start cleanup path as `init`, rolling back provisional bridge and turn
+ownership without a child-host call or duplicate start/finish boundary.
 A restore failure shall leave the runtime unbound so `dispose` remains
 callable and terminal.
 
@@ -1440,7 +1463,7 @@ runtime's emission-failure channel to surface from the next public boundary
 that drains.
 
 The recorded receipts and the recorded last classified event are
-process-local: the schema-1 parked-session snapshot persists neither, and a
+process-local: the durable runtime snapshot persists neither, and a
 restored runtime advertises a retry again only after its next classified
 event.
 

package/src/runtime.d.ts

@@ -47,6 +47,11 @@ export interface PlaybookPendingCall {
     playbookId: string;
     childSessionId: string;
 }
+export interface PlaybookSuspendedCall extends PlaybookPendingCall {
+    stateId: string;
+    text: string;
+    turnId?: number;
+}
 export interface PlaybookCallRequest {
     callId: string;
     playbookId: string;
@@ -137,8 +142,7 @@ export interface PlaybookPendingBossQuestion {
     question: string;
     sourceItem?: string;
 }
-export interface PlaybookRuntimeSnapshot {
-    schemaVersion: 1;
+interface PlaybookRuntimeSnapshotFields {
     playbookId: string;
     machine: JsonValue;
     playerResumeTokens: {
@@ -155,6 +159,13 @@ export interface PlaybookRuntimeSnapshot {
     state: PlaybookState;
     pendingBossQuestions: readonly PlaybookPendingBossQuestion[];
 }
+export type PlaybookRuntimeSnapshot = PlaybookRuntimeSnapshotFields & ({
+    schemaVersion: 1;
+    suspendedCall?: never;
+} | {
+    schemaVersion: 2;
+    suspendedCall?: PlaybookSuspendedCall;
+});
 export interface PlaybookControlAction {
     id: string;
     label: string;
@@ -199,3 +210,4 @@ export interface PlaybookRuntime {
     dispose(): Promise<void>;
 }
 export type PlaybookRuntimeFactory<Options = unknown> = (options: Options) => PlaybookRuntime;
+export {};

package/src/runtime.ts

@@ -75,6 +75,15 @@ export interface PlaybookPendingCall {
   childSessionId: string;
 }
 
+// DR-031 §5: complete durable identity for one nested call whose start
+// boundary has already been published and whose child remains suspended.
+// `turnId` is absent when the call was opened outside a Boss-turn boundary.
+export interface PlaybookSuspendedCall extends PlaybookPendingCall {
+  stateId: string;
+  text: string;
+  turnId?: number;
+}
+
 export interface PlaybookCallRequest {
   callId: string;
   playbookId: string;
@@ -199,12 +208,11 @@ export interface PlaybookPendingBossQuestion {
   sourceItem?: string;
 }
 
-// DR-014 §1: JSON-safe capture of a parked session. `machine` is the
-// XState persisted snapshot and is opaque to hosts; the pending Boss
-// questions are first-class so a host can surface what was asked
-// without parsing status lines or telemetry.
-export interface PlaybookRuntimeSnapshot {
-  schemaVersion: 1;
+// DR-014 §1 / DR-031 §5: JSON-safe capture of a parked or nested-call
+// suspended session. `machine` is the opaque XState persisted snapshot;
+// pending Boss questions and a schema-2 suspended call are first-class so a
+// host never has to reconstruct durable ownership from presentation records.
+interface PlaybookRuntimeSnapshotFields {
   playbookId: string;
   machine: JsonValue;
   playerResumeTokens: { readonly [playerId: string]: string };
@@ -220,6 +228,18 @@ export interface PlaybookRuntimeSnapshot {
   pendingBossQuestions: readonly PlaybookPendingBossQuestion[];
 }
 
+export type PlaybookRuntimeSnapshot = PlaybookRuntimeSnapshotFields &
+  (
+    | {
+        schemaVersion: 1;
+        suspendedCall?: never;
+      }
+    | {
+        schemaVersion: 2;
+        suspendedCall?: PlaybookSuspendedCall;
+      }
+  );
+
 // DR-029: one currently valid, runtime-advertised control action. The id
 // is stable within the returned view; the label is runtime-written,
 // Boss-appropriate text derived from source state descriptions.