@sublang/playbook 0.8.0 → 1.0.0

package/reference/sdlc/code.playbook/playbook-captain.ts

@@ -1,6 +1,9 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
 
+import { randomUUID } from 'node:crypto';
+import PQueue from 'p-queue';
+
 import type {
   BossTurn,
   Captain,
@@ -8,57 +11,119 @@ import type {
   CaptainSession,
 } from '@sublang/cligent/tmux-play';
 import type {
+  NormalizedError,
+  PlaybookCallRequest,
+  PlaybookCallResult,
+  PlaybookCallStart,
   PlaybookPorts,
+  PlaybookRunResult,
   PlaybookRuntime,
-} from './code.playbook.js';
-import {
-  codePlaybookRegistryEntry,
-  type RegistryPlayer,
-} from './code.registry.js';
+  PlaybookState,
+} from '@sublang/playbook/runtime';
+import { registerPlaybookAbortCleanup } from '../../../src/xstate-runtime.js';
+import createDefaultCaptainRuntime from '../captain.playbook/captain.playbook.js';
+import type { PlaybookSummaryPolicy, RegistryPlayer } from './code.registry.js';
 
 export interface CreatePlaybookRuntimeOptions {
   captainOptions: unknown;
   players: readonly RegistryPlayer[];
 }
 
+export interface PlaybookCaptainDeps {
+  loadModule?: (specifier: string) => Promise<unknown>;
+  createSessionId?: () => string;
+  createCaptainRuntime?: (options: {
+    readonly enabledPlaybooks: readonly {
+      readonly id: string;
+      readonly command: string;
+      readonly intent: string;
+    }[];
+  }) => PlaybookRuntime;
+}
+
 export interface PlaybookCaptainRegistryEntry {
   id: string;
   command: string;
   intent: string;
-  idleStateId: string;
-  finalStateId: string;
-  copyPasteGuardNames: readonly string[];
-  stateCountLabels?: Readonly<Record<string, string>>;
+  requiredRoleIds: readonly string[];
+  summaryPolicy?: PlaybookSummaryPolicy;
   validateOptions(captainOptions: unknown): unknown;
   createRuntime(options: CreatePlaybookRuntimeOptions): PlaybookRuntime;
 }
 
-interface ActiveEngagement {
+// Per-enabled-playbook binding the shell resolves at init from
+// `captain.options.playbooks`: each playbook binds its local roles to
+// `<id>-<role>` host players and carries the generated visible set.
+interface Enablement {
+  entry: PlaybookCaptainRegistryEntry;
+  command: string;
+  optionInput: unknown;
+  boundPlayers: readonly RegistryPlayer[];
+  hostPlayerId: (localRole: string) => string;
+  visiblePlayerIds?: readonly string[];
+}
+
+interface EngagementFrame {
   entry: PlaybookCaptainRegistryEntry;
+  enablement: Enablement;
   runtime: PlaybookRuntime;
+  sessionId: string;
+  rootSessionId: string;
+  depth: number;
+  parent?: {
+    frame: EngagementFrame;
+    callId: string;
+  };
+  state?: PlaybookState;
+  abortListener?: () => void;
+  invocationSignal?: AbortSignal;
+  inFlightHostCalls: Set<Promise<unknown>>;
+  disposePromise?: Promise<void>;
+  removal?: {
+    reason: 'return' | 'abandoned' | 'stack';
+    promise: Promise<void>;
+  };
+  internal: boolean;
 }
 
-type RouterDecision =
-  | { decision: 'chat'; text: string }
-  | { decision: 'dispatch'; playbookId: string; text: string }
-  | { decision: 'sub'; text: string }
-  | { decision: 'dismiss'; text?: string };
+type LifecycleDecision = { decision: 'deliver' | 'dismiss' };
+
+class VisibilityControlError extends Error {
+  constructor(cause: unknown) {
+    super(
+      `playbook visibility request failed: ${String(
+        (cause as { message?: unknown })?.message ?? cause,
+      )}`,
+      { cause },
+    );
+    this.name = 'VisibilityControlError';
+  }
+}
 
 type DisposalReason = 'dismiss' | 'final' | 'dispose';
 
 interface ControlLedger {
   activePlaybookId?: string;
+  activeSessionId?: string;
+  rootPlaybookId?: string;
+  rootSessionId?: string;
+  stackDepth: number;
+  stackPath: readonly string[];
   mode: ShellMode;
   latestSubRuntimeStateId?: string;
-  pendingBossQuestion?: unknown;
+  latestSubRuntimeState?: PlaybookState;
+  pendingBossQuestions?: unknown;
   lastError?: { name: string; message: string };
-  lastRouteDecision?: RouterDecision['decision'];
+  lastRouteDecision?: LifecycleDecision['decision'];
 }
 
 type ShellMode = 'chat' | 'engaged.driving' | 'engaged.parked';
 
 const SUB_RUNTIME_FSM_TOPIC = 'playbook.fsm.state';
 const SHELL_FSM_TOPIC = 'playbook.captain.fsm.state';
+const INTERNAL_CAPTAIN_ID = 'captain';
+const UUID_PATTERN =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 
 interface TurnSummaryCounts {
   interruptions: number;
@@ -66,14 +131,11 @@ interface TurnSummaryCounts {
 }
 
 interface ActiveTurnSummary {
+  owner: EngagementFrame;
   counts: TurnSummaryCounts;
   stateCounts: Map<string, number>;
 }
 
-export const playbookCaptainRegistry: readonly PlaybookCaptainRegistryEntry[] = [
-  codePlaybookRegistryEntry,
-];
-
 function parseRegisteredCommand(
   prompt: string,
 ): { command: string; text: string } | undefined {
@@ -84,14 +146,10 @@ function parseRegisteredCommand(
   return { command: match[1], text: (match[2] ?? '').trim() };
 }
 
-function playbookCommandLabel(entry: PlaybookCaptainRegistryEntry): string {
-  return `/${entry.command}`;
-}
-
 function visibleChatEnvelope(message: string): string {
   return [
     'You are the Playbook Captain shell.',
-    'This is visible Boss chat. Do not reveal hidden control JSON, hidden router decisions, or hidden judge replies.',
+    'This is visible Boss chat. Do not reveal hidden control JSON, hidden lifecycle decisions, or hidden judge replies.',
     message,
   ].join('\n\n');
 }
@@ -101,58 +159,37 @@ function visibleTurnSummaryEnvelope(input: {
   submittedText: string;
   counts: TurnSummaryCounts;
   progressPhrase: string;
-  reviewRebuttalRounds: number;
+  progressRounds: number;
+  savedLine: string;
 }): string {
-  const savedLine = savedCountsLine(input.counts, input.reviewRebuttalRounds);
   return [
     'You are the Playbook Captain shell.',
-    'This is visible Boss chat after a sub-playbook command completed. Do not reveal hidden control JSON, hidden router decisions, or hidden judge replies.',
+    'This is visible Boss chat after a sub-playbook command completed. Do not reveal hidden control JSON, hidden lifecycle decisions, or hidden judge replies.',
     'Write a brief, clearly formatted turn-summary block for Boss.',
     'Use a natural, chat-like tone and no more than two short sentences before the saved-counts line.',
     'State only what was done or what changed; do not explain how it was done.',
     'Do not list raw state names, transitions, guard names, prompts, tools, hidden calls, or reasoning.',
     'If progress detail is useful, use only the aggregate progress phrase supplied below.',
-    'Do not mention counts for plan or implementation steps, tests green, or any other internal state.',
-    `Then write the saved-counts line exactly: ${savedLine}`,
+    "Do not mention counts for states the active playbook's summary policy does not label.",
+    `Then write the saved-counts line exactly: ${input.savedLine}`,
     'Use the exact counts supplied; do not change them.',
-    'Do not repeat the exact review/rebuttal round count outside the saved-counts line.',
+    'Do not repeat the exact progress round count outside the saved-counts line.',
     `Playbook: ${input.playbookId}`,
     `Submitted Boss text:\n${input.submittedText}`,
     `Progress counts:\n${input.progressPhrase}`,
     `Counts:\n${JSON.stringify({
       ...input.counts,
-      reviewRebuttalRounds: input.reviewRebuttalRounds,
+      progressRounds: input.progressRounds,
     })}`,
   ].join('\n\n');
 }
 
-function countNoun(count: number, singular: string, plural = `${singular}s`): string {
-  return `${count} ${count === 1 ? singular : plural}`;
-}
-
-function savedCountsLine(
-  counts: TurnSummaryCounts,
-  reviewRebuttalRounds: number,
-): string {
-  return [
-    'Saved you',
-    countNoun(counts.interruptions, 'interruption'),
-    'and',
-    countNoun(counts.copyPastes, 'copy-paste'),
-    'across',
-    countNoun(reviewRebuttalRounds, 'round'),
-    'of reviews/rebuttals.',
-  ].join(' ');
-}
-
 function stateCountLabel(
   stateId: string,
   entry: PlaybookCaptainRegistryEntry,
 ): string | undefined {
-  if (stateId === entry.idleStateId || stateId === entry.finalStateId) {
-    return undefined;
-  }
-  const registryLabel = entry.stateCountLabels?.[stateId]?.trim();
+  const registryLabel =
+    entry.summaryPolicy?.stateCountLabels?.[stateId]?.trim();
   return registryLabel || undefined;
 }
 
@@ -163,14 +200,18 @@ function pluralizeStateCount(label: string, count: number): string {
   return `${count} ${label}s`;
 }
 
-function summaryProgressPhrase(stateCounts: ReadonlyMap<string, number>): string {
+function summaryProgressPhrase(
+  stateCounts: ReadonlyMap<string, number>,
+): string {
   if (stateCounts.size === 0) return 'none';
   return [...stateCounts.entries()]
     .map(([label, count]) => pluralizeStateCount(label, count))
     .join(', ');
 }
 
-function summaryProgressRoundCount(stateCounts: ReadonlyMap<string, number>): number {
+function summaryProgressRoundCount(
+  stateCounts: ReadonlyMap<string, number>,
+): number {
   return [...stateCounts.values()].reduce((total, count) => total + count, 0);
 }
 
@@ -178,38 +219,179 @@ function guardFromJudgeReply(finalText: string): string | undefined {
   return /"guard"\s*:\s*"([^"]+)"/.exec(finalText)?.[1];
 }
 
-function normalizeRegistry(
-  registry: readonly PlaybookCaptainRegistryEntry[],
-): {
+function isValidRegistryEntry(
+  value: unknown,
+): value is PlaybookCaptainRegistryEntry {
+  if (typeof value !== 'object' || value === null) return false;
+  const e = value as Record<string, unknown>;
+  return (
+    typeof e.id === 'string' &&
+    typeof e.command === 'string' &&
+    typeof e.intent === 'string' &&
+    Array.isArray(e.requiredRoleIds) &&
+    typeof e.validateOptions === 'function' &&
+    typeof e.createRuntime === 'function'
+  );
+}
+
+function readPlaybooksConfig(
+  options: unknown,
+): Record<string, unknown> | undefined {
+  if (typeof options !== 'object' || options === null) return undefined;
+  const pb = (options as Record<string, unknown>).playbooks;
+  if (typeof pb !== 'object' || pb === null || Array.isArray(pb)) {
+    return undefined;
+  }
+  return pb as Record<string, unknown>;
+}
+
+interface BuiltRegistry {
   entries: readonly PlaybookCaptainRegistryEntry[];
   byCommand: Map<string, PlaybookCaptainRegistryEntry>;
   byId: Map<string, PlaybookCaptainRegistryEntry>;
-} {
+  enablementById: Map<string, Enablement>;
+}
+
+// Resolve the active registry at init from `captain.options.playbooks`
+// (CAPTAIN-16): each enabled playbook is loaded from its explicit `from`
+// module and bound to namespaced `<id>-<role>` host players.
+async function buildEnablements(
+  options: unknown,
+  players: readonly RegistryPlayer[],
+  loadModule: (specifier: string) => Promise<unknown>,
+): Promise<BuiltRegistry> {
+  const entries: PlaybookCaptainRegistryEntry[] = [];
   const byCommand = new Map<string, PlaybookCaptainRegistryEntry>();
   const byId = new Map<string, PlaybookCaptainRegistryEntry>();
-  for (const entry of registry) {
-    byCommand.set(entry.command, entry);
+  const enablementById = new Map<string, Enablement>();
+
+  const config = readPlaybooksConfig(options);
+  if (config === undefined) {
+    throw new Error('captain.options.playbooks is required');
+  }
+
+  const ids = Object.keys(config);
+  if (ids.length === 0) {
+    throw new Error(
+      'captain.options.playbooks must enable at least one playbook',
+    );
+  }
+  for (const id of ids) {
+    if (id === INTERNAL_CAPTAIN_ID) {
+      throw new Error(
+        `captain.options.playbooks.${id} collides with the reserved internal Captain id`,
+      );
+    }
+    const block = config[id];
+    if (typeof block !== 'object' || block === null || Array.isArray(block)) {
+      throw new Error(`captain.options.playbooks.${id} must be an object`);
+    }
+    const record = block as Record<string, unknown>;
+    const from = record.from;
+    if (typeof from !== 'string' || from.length === 0) {
+      throw new Error(
+        `captain.options.playbooks.${id}.from must be a module specifier`,
+      );
+    }
+    let mod: unknown;
+    try {
+      mod = await loadModule(from);
+    } catch (cause) {
+      throw new Error(
+        `captain.options.playbooks.${id}.from "${from}" failed to import: ${String(
+          (cause as { message?: unknown })?.message ?? cause,
+        )}`,
+      );
+    }
+    const entry = (mod as { default?: unknown })?.default;
+    if (!isValidRegistryEntry(entry)) {
+      throw new Error(
+        `captain.options.playbooks.${id}.from "${from}" exposes no valid registry entry`,
+      );
+    }
+    if (entry.id !== id) {
+      throw new Error(
+        `captain.options.playbooks.${id} key must equal the module manifest id "${entry.id}"`,
+      );
+    }
+    if (byId.has(entry.id)) {
+      throw new Error(
+        `captain.options.playbooks has a duplicate playbook id "${entry.id}"`,
+      );
+    }
+    const command =
+      typeof record.command === 'string' && record.command.length > 0
+        ? record.command
+        : entry.command;
+    if (command === INTERNAL_CAPTAIN_ID) {
+      throw new Error(
+        `captain.options.playbooks.${id} command collides with the reserved internal Captain command`,
+      );
+    }
+    if (byCommand.has(command)) {
+      throw new Error(
+        `captain.options.playbooks has a duplicate effective command "${command}"`,
+      );
+    }
+    const boundPlayers = entry.requiredRoleIds.map((role) => {
+      const host = players.find((p) => p.id === `${entry.id}-${role}`);
+      return {
+        id: role,
+        ...(host?.adapter !== undefined ? { adapter: host.adapter } : {}),
+        ...(host?.model !== undefined ? { model: host.model } : {}),
+      };
+    });
+    entries.push(entry);
     byId.set(entry.id, entry);
+    byCommand.set(command, entry);
+    enablementById.set(entry.id, {
+      entry,
+      command,
+      optionInput: record.options,
+      boundPlayers,
+      hostPlayerId: (localRole) => `${entry.id}-${localRole}`,
+      visiblePlayerIds: entry.requiredRoleIds.map(
+        (role) => `${entry.id}-${role}`,
+      ),
+    });
   }
-  return { entries: registry, byCommand, byId };
+  return { entries, byCommand, byId, enablementById };
 }
 
 export function createPlaybookCaptainShell(
   options: unknown,
-  registry: readonly PlaybookCaptainRegistryEntry[] = playbookCaptainRegistry,
+  deps: PlaybookCaptainDeps = {},
 ): Captain {
-  const { entries, byCommand, byId } = normalizeRegistry(registry);
+  const loadModule =
+    deps.loadModule ?? ((specifier: string) => import(specifier));
+  const createSessionId = deps.createSessionId ?? randomUUID;
+  const createCaptainRuntime: NonNullable<
+    PlaybookCaptainDeps['createCaptainRuntime']
+  > = deps.createCaptainRuntime ?? createDefaultCaptainRuntime;
+  let entries: readonly PlaybookCaptainRegistryEntry[] = [];
+  let byCommand = new Map<string, PlaybookCaptainRegistryEntry>();
+  let byId = new Map<string, PlaybookCaptainRegistryEntry>();
+  let enablementById = new Map<string, Enablement>();
+  let internalCaptainEnablement: Enablement | undefined;
   let session: CaptainSession | undefined;
   let players: readonly RegistryPlayer[] = [];
   let activeContext: CaptainContext | undefined;
-  let active: ActiveEngagement | undefined;
+  const frames: EngagementFrame[] = [];
   let mode: ShellMode = 'chat';
-  let latestSubRuntimeStateId: string | undefined;
-  let pendingBossQuestion: unknown;
+  let pendingBossQuestions: unknown;
   let lastError: { name: string; message: string } | undefined;
-  let lastRouteDecision: RouterDecision['decision'] | undefined;
-  let finalDisposalRequested: ActiveEngagement | undefined;
+  let lastRouteDecision: LifecycleDecision['decision'] | undefined;
   let activeTurnSummary: ActiveTurnSummary | undefined;
+  let activeTurnHostCalls: Set<Promise<unknown>> | undefined;
+  const issuedSessionIds = new Set<string>();
+  const pendingChildParents = new Set<EngagementFrame>();
+  const captainQueue = new PQueue({ concurrency: 1 });
+  let disposing = false;
+
+  const rootFrame = (): EngagementFrame | undefined => frames[0];
+  const leafFrame = (): EngagementFrame | undefined => frames.at(-1);
+  const frameLabel = (frame: EngagementFrame): string =>
+    frame.internal ? 'Captain' : `/${frame.enablement.command}`;
 
   const requireSession = (): CaptainSession => {
     if (!session) {
@@ -219,12 +401,27 @@ export function createPlaybookCaptainShell(
   };
 
   const ledgerSnapshot = (
-    playbookId: string | undefined = active?.entry.id,
+    playbookId: string | undefined = leafFrame()?.entry.id,
+    activeSessionId: string | undefined = leafFrame()?.sessionId,
   ): ControlLedger => ({
     ...(playbookId ? { activePlaybookId: playbookId } : {}),
+    ...(activeSessionId ? { activeSessionId } : {}),
+    ...(rootFrame()
+      ? {
+          rootPlaybookId: rootFrame()!.entry.id,
+          rootSessionId: rootFrame()!.sessionId,
+        }
+      : {}),
+    stackDepth: frames.length,
+    stackPath: frames.map((frame) => frame.entry.id),
     mode,
-    ...(latestSubRuntimeStateId ? { latestSubRuntimeStateId } : {}),
-    ...(pendingBossQuestion !== undefined ? { pendingBossQuestion } : {}),
+    ...(leafFrame()?.state?.stateId
+      ? { latestSubRuntimeStateId: leafFrame()!.state!.stateId }
+      : {}),
+    ...(leafFrame()?.state
+      ? { latestSubRuntimeState: leafFrame()!.state }
+      : {}),
+    ...(pendingBossQuestions !== undefined ? { pendingBossQuestions } : {}),
     ...(lastError ? { lastError } : {}),
     ...(lastRouteDecision ? { lastRouteDecision } : {}),
   });
@@ -233,7 +430,8 @@ export function createPlaybookCaptainShell(
     from: ShellMode,
     to: ShellMode,
     event: string,
-    playbookId: string | undefined = active?.entry.id,
+    playbookId: string | undefined = leafFrame()?.entry.id,
+    activeSessionId: string | undefined = leafFrame()?.sessionId,
   ): Promise<void> => {
     await requireSession().emitTelemetry({
       topic: SHELL_FSM_TOPIC,
@@ -241,7 +439,7 @@ export function createPlaybookCaptainShell(
         from,
         to,
         event,
-        ledger: ledgerSnapshot(playbookId),
+        ledger: ledgerSnapshot(playbookId, activeSessionId),
       },
     });
   };
@@ -249,12 +447,19 @@ export function createPlaybookCaptainShell(
   const setMode = async (
     nextMode: ShellMode,
     event: string,
-    playbookId: string | undefined = active?.entry.id,
+    playbookId: string | undefined = leafFrame()?.entry.id,
+    activeSessionId: string | undefined = leafFrame()?.sessionId,
   ): Promise<void> => {
     if (mode === nextMode) return;
     const from = mode;
     mode = nextMode;
-    await emitShellTelemetry(from, nextMode, event, playbookId);
+    await emitShellTelemetry(
+      from,
+      nextMode,
+      event,
+      playbookId,
+      activeSessionId,
+    );
   };
 
   const normalizeErrorCompact = (
@@ -283,67 +488,193 @@ export function createPlaybookCaptainShell(
       ? (payload as Record<string, unknown>)
       : undefined;
 
-  const mirroredStateId = (payload: unknown): string | undefined => {
-    const record = payloadRecord(payload);
-    if (!record) return undefined;
-    if (typeof record.to === 'string') return record.to;
-    return typeof record.state === 'string' ? record.state : undefined;
+  const playbookState = (value: unknown): PlaybookState | undefined => {
+    const record = payloadRecord(value);
+    if (
+      !record ||
+      !Array.isArray(record.activeStateIds) ||
+      !record.activeStateIds.every((id) => typeof id === 'string') ||
+      !Array.isArray(record.tags) ||
+      !record.tags.every((tag) => typeof tag === 'string') ||
+      typeof record.status !== 'string' ||
+      typeof record.quiescent !== 'boolean' ||
+      !('value' in record)
+    ) {
+      return undefined;
+    }
+    return record as unknown as PlaybookState;
   };
 
-  const mirrorSubRuntimeTelemetry = async (payload: unknown): Promise<void> => {
-    if (!active) return;
-    const record = payloadRecord(payload);
-    const stateId = mirroredStateId(payload);
-    if (stateId === undefined) return;
-
-    const countLabel = stateCountLabel(stateId, active.entry);
-    if (activeTurnSummary && countLabel) {
-      activeTurnSummary.stateCounts.set(
-        countLabel,
-        (activeTurnSummary.stateCounts.get(countLabel) ?? 0) + 1,
-      );
+  const stateValueContains = (value: unknown, stateId: string): boolean => {
+    if (typeof value === 'string') return value === stateId;
+    const record = payloadRecord(value);
+    if (!record) return false;
+    return Object.entries(record).some(
+      ([key, nested]) => key === stateId || stateValueContains(nested, stateId),
+    );
+  };
+
+  const drainHostCalls = async (
+    calls: Set<Promise<unknown>>,
+  ): Promise<void> => {
+    while (calls.size > 0) {
+      await Promise.allSettled([...calls]);
     }
+  };
 
-    latestSubRuntimeStateId = stateId;
-    pendingBossQuestion = record?.pendingBossQuestion;
-    lastError = normalizeErrorCompact(record?.lastError);
+  const trackHostCall = <T>(
+    frame: EngagementFrame,
+    call: Promise<T>,
+  ): Promise<T> => {
+    // Cligent's host methods are scoped to the whole Boss turn, while an
+    // XState invocation can carry a narrower sibling-cancellation signal.
+    // Keep both frame and turn ownership after XState stops awaiting the
+    // promise so the host cannot outlive frame disposal or turn settlement.
+    const turnCalls = activeTurnHostCalls;
+    let tracked!: Promise<T>;
+    tracked = call.finally(() => {
+      frame.inFlightHostCalls.delete(tracked);
+      turnCalls?.delete(tracked);
+    });
+    frame.inFlightHostCalls.add(tracked);
+    turnCalls?.add(tracked);
+    return tracked;
+  };
 
-    if (stateId === active.entry.finalStateId) {
-      finalDisposalRequested = active;
-      return;
+  const callCaptainQueued = (
+    frame: EngagementFrame,
+    context: CaptainContext,
+    prompt: string,
+    options: Parameters<CaptainContext['callCaptain']>[1],
+    signal: AbortSignal,
+  ): ReturnType<CaptainContext['callCaptain']> => {
+    const queued = captainQueue.add(async () => {
+      signal.throwIfAborted();
+      const result = await trackHostCall(
+        frame,
+        context.callCaptain(prompt, options),
+      );
+      signal.throwIfAborted();
+      return result;
+    });
+    return trackHostCall(frame, queued);
+  };
+
+  const mirrorSubRuntimeTelemetry = async (
+    frame: EngagementFrame,
+    payload: unknown,
+  ): Promise<void> => {
+    const record = payloadRecord(payload);
+    const state = playbookState(record?.state);
+    if (!record || !state) return;
+    const previousActiveIds = new Set(frame.state?.activeStateIds ?? []);
+    frame.state = state;
+
+    if (activeTurnSummary?.owner === frame) {
+      for (const stateId of state.activeStateIds) {
+        const newlyActive = !previousActiveIds.has(stateId);
+        const structuredEntry =
+          stateValueContains(record.to, stateId) &&
+          !stateValueContains(record.from, stateId);
+        if (!newlyActive && !structuredEntry) continue;
+        const countLabel = stateCountLabel(stateId, frame.entry);
+        if (countLabel) {
+          activeTurnSummary.stateCounts.set(
+            countLabel,
+            (activeTurnSummary.stateCounts.get(countLabel) ?? 0) + 1,
+          );
+        }
+      }
     }
 
-    if (
-      stateId === active.entry.idleStateId ||
-      stateId === 'failed' ||
-      stateId === 'awaitBossReply'
-    ) {
-      await setMode('engaged.parked', `sub-runtime:${stateId}`);
+    if (leafFrame() === frame) {
+      pendingBossQuestions =
+        record.pendingBossQuestions ?? record.pendingBossQuestion;
+      lastError = normalizeErrorCompact(record.lastError);
+      if (state.quiescent && state.tags.includes('playbook.parked')) {
+        await setMode(
+          'engaged.parked',
+          `sub-runtime:${state.stateId ?? 'structured'}`,
+        );
+      }
     }
   };
 
-  const createPorts = (): PlaybookPorts => ({
-    callPlayer: async (playerId, prompt, _signal) => {
+  let callNestedPlaybook: (
+    frame: EngagementFrame,
+    request: PlaybookCallRequest,
+    signal: AbortSignal,
+  ) => Promise<PlaybookCallStart>;
+
+  const createPorts = (frame: EngagementFrame): PlaybookPorts => ({
+    callPlayer: async (playerId, prompt, signal, options) => {
       if (!activeContext) {
         throw new Error('callPlayer invoked outside a Boss turn');
       }
-      const result = await activeContext.callPlayer(playerId, prompt);
-      if (activeTurnSummary) {
+      const context = activeContext;
+      signal.throwIfAborted();
+      const hostPlayerId = frame.enablement.hostPlayerId(playerId);
+      const result = await trackHostCall(
+        frame,
+        context.callPlayer(hostPlayerId, prompt, {
+          resume: options.resume,
+        }),
+      );
+      // CaptainContext is turn-scoped and cannot accept a narrower XState
+      // invocation signal. Recheck after the host call so a sibling
+      // cancellation is still reported as aborted and cannot rotate a
+      // stopped branch's player token in the linked runtime.
+      signal.throwIfAborted();
+      if (activeTurnSummary?.owner === frame) {
         activeTurnSummary.counts.interruptions++;
       }
       return {
         status: result.status,
-        finalText: result.finalText,
-        error: result.error,
+        ...(result.resumeToken !== undefined
+          ? { resumeToken: result.resumeToken }
+          : {}),
+        ...(result.finalText !== undefined
+          ? { finalText: result.finalText }
+          : {}),
+        ...(result.error !== undefined ? { error: result.error } : {}),
+      };
+    },
+    callCaptain: async (prompt, signal, options) => {
+      if (!activeContext) {
+        throw new Error('callCaptain invoked outside a Boss turn');
+      }
+      const result = await callCaptainQueued(
+        frame,
+        activeContext,
+        prompt,
+        {
+          visibility: options.visibility,
+          resume: options.resume,
+          ...(options.allowedTools === undefined
+            ? {}
+            : { allowedTools: options.allowedTools }),
+        },
+        signal,
+      );
+      return {
+        status: result.status,
+        ...(result.finalText !== undefined
+          ? { finalText: result.finalText }
+          : {}),
+        ...(result.error !== undefined ? { error: result.error } : {}),
       };
     },
-    callJudge: async (prompt, _signal) => {
+    callJudge: async (prompt, signal) => {
       if (!activeContext) {
         throw new Error('callJudge invoked outside a Boss turn');
       }
-      const result = await activeContext.callCaptain(prompt, {
-        visibility: 'hidden',
-      });
+      const result = await callCaptainQueued(
+        frame,
+        activeContext,
+        prompt,
+        { visibility: 'hidden', resume: false, allowedTools: [] },
+        signal,
+      );
       if (result.status !== 'ok') {
         throw new Error(
           result.error ?? `callCaptain status "${result.status}"`,
@@ -355,14 +686,28 @@ export function createPlaybookCaptainShell(
       const guard = guardFromJudgeReply(result.finalText);
       if (
         guard &&
-        active?.entry.copyPasteGuardNames.includes(guard) &&
-        activeTurnSummary
+        activeTurnSummary?.owner === frame &&
+        frame.entry.summaryPolicy?.copyPasteGuardNames.includes(guard)
       ) {
         activeTurnSummary.counts.copyPastes++;
       }
       return result.finalText;
     },
+    callPlaybook: (request, signal) => {
+      const opening = callNestedPlaybook(frame, request, signal);
+      let exposed!: Promise<PlaybookCallStart>;
+      const registerOpeningCleanup = (): void => {
+        registerPlaybookAbortCleanup(signal, exposed);
+      };
+      exposed = opening.finally(() => {
+        signal.removeEventListener('abort', registerOpeningCleanup);
+      });
+      signal.addEventListener('abort', registerOpeningCleanup, { once: true });
+      if (signal.aborted) registerOpeningCleanup();
+      return exposed;
+    },
     emitStatus: async (message, data) => {
+      if (frame.internal) return;
       await requireSession().emitStatus(
         message,
         data as Record<string, unknown> | undefined,
@@ -370,168 +715,834 @@ export function createPlaybookCaptainShell(
     },
     emitTelemetry: async (event) => {
       if (event.topic === SUB_RUNTIME_FSM_TOPIC) {
-        await mirrorSubRuntimeTelemetry(event.payload);
+        await mirrorSubRuntimeTelemetry(frame, event.payload);
       }
       await requireSession().emitTelemetry(event);
     },
   });
 
-  const engage = async (
-    entry: PlaybookCaptainRegistryEntry,
-  ): Promise<ActiveEngagement> => {
-    if (active?.entry.id === entry.id) return active;
+  // CAPTAIN-22: before dispatching to a playbook, request tmux-play
+  // visibility for that playbook's generated host players. A pane
+  // reconciliation failure is display-only in tmux-play and does not
+  // reject; the legacy path carries no generated set and skips this.
+  const requestVisibility = async (enablement: Enablement): Promise<void> => {
+    const ids = enablement.visiblePlayerIds;
+    if (!ids || ids.length === 0 || !activeContext) return;
+    try {
+      await activeContext.setVisiblePlayers(ids);
+    } catch (error) {
+      throw new VisibilityControlError(error);
+    }
+  };
+
+  const allocateSessionId = (): string => {
+    const sessionId = createSessionId();
+    if (!UUID_PATTERN.test(sessionId)) {
+      throw new Error(
+        `playbook session id generator returned a non-UUID value: ${JSON.stringify(
+          sessionId,
+        )}`,
+      );
+    }
+    if (issuedSessionIds.has(sessionId)) {
+      throw new Error(`playbook session id collision: ${sessionId}`);
+    }
+    issuedSessionIds.add(sessionId);
+    return sessionId;
+  };
+
+  const normalizeErrorFull = (value: unknown): NormalizedError => {
+    const compact = normalizeErrorCompact(value) ?? {
+      name: 'Error',
+      message: String(value),
+    };
+    const stack =
+      value instanceof Error
+        ? value.stack
+        : typeof value === 'object' && value !== null
+          ? (value as Record<string, unknown>).stack
+          : undefined;
+    return typeof stack === 'string' ? { ...compact, stack } : compact;
+  };
+
+  const makeFrame = (
+    enablement: Enablement,
+    parent?: { frame: EngagementFrame; callId: string },
+    internal = false,
+  ): EngagementFrame => {
+    const entry = enablement.entry;
+    const sessionId = allocateSessionId();
     const runtime = entry.createRuntime({
-      captainOptions: options,
-      players,
+      captainOptions: enablement.optionInput,
+      players: enablement.boundPlayers,
+    });
+    return {
+      entry,
+      enablement,
+      runtime,
+      sessionId,
+      rootSessionId: parent?.frame.rootSessionId ?? sessionId,
+      depth: parent ? parent.frame.depth + 1 : 0,
+      ...(parent ? { parent } : {}),
+      inFlightHostCalls: new Set(),
+      internal,
+    };
+  };
+
+  const initFrame = async (frame: EngagementFrame): Promise<void> => {
+    await frame.runtime.init({
+      sessionId: frame.sessionId,
+      playbookId: frame.entry.id,
+      rootSessionId: frame.rootSessionId,
+      ...(frame.parent
+        ? {
+            parentSessionId: frame.parent.frame.sessionId,
+            parentCallId: frame.parent.callId,
+          }
+        : {}),
+      depth: frame.depth,
+      ports: createPorts(frame),
     });
-    active = { entry, runtime };
-    latestSubRuntimeStateId = undefined;
-    pendingBossQuestion = undefined;
+  };
+
+  const clearLeafLedger = (): void => {
+    pendingBossQuestions = undefined;
     lastError = undefined;
-    finalDisposalRequested = undefined;
-    await setMode('engaged.parked', 'engage', entry.id);
-    await runtime.init(createPorts());
-    await requireSession().emitStatus(
-      `◇ ${playbookCommandLabel(entry)} started`,
+  };
+
+  const engageEnablement = async (
+    enablement: Enablement,
+    internal: boolean,
+  ): Promise<EngagementFrame> => {
+    const entry = enablement.entry;
+    const existing = rootFrame();
+    if (existing?.entry.id === entry.id && frames.length === 1) {
+      return existing;
+    }
+    if (existing) {
+      throw new Error('cannot engage a second root playbook');
+    }
+    const frame = makeFrame(enablement, undefined, internal);
+    frames.push(frame);
+    clearLeafLedger();
+    try {
+      await setMode('engaged.parked', 'engage', entry.id, frame.sessionId);
+      await initFrame(frame);
+      if (!internal) {
+        await requireSession().emitStatus(`◇ ${frameLabel(frame)} started`);
+      }
+      return frame;
+    } catch (error) {
+      if (leafFrame() === frame) frames.pop();
+      clearLeafLedger();
+      try {
+        await frame.runtime.dispose();
+      } catch {
+        // Preserve the initialization failure while still making a
+        // best-effort attempt to release partially acquired resources.
+      }
+      try {
+        await setMode('chat', 'engage.failed');
+      } catch {
+        // setMode updates the authoritative mode before telemetry; preserve
+        // the initialization failure if that recovery emission also fails.
+        mode = 'chat';
+      }
+      throw error;
+    }
+  };
+
+  const engage = async (
+    entry: PlaybookCaptainRegistryEntry,
+  ): Promise<EngagementFrame> =>
+    engageEnablement(enablementById.get(entry.id)!, false);
+
+  const createInternalCaptainEnablement = (): Enablement => {
+    const catalog = Object.freeze(
+      entries.map((entry) =>
+        Object.freeze({
+          id: entry.id,
+          command: enablementById.get(entry.id)!.command,
+          intent: entry.intent,
+        }),
+      ),
+    );
+    const entry: PlaybookCaptainRegistryEntry = {
+      id: INTERNAL_CAPTAIN_ID,
+      command: INTERNAL_CAPTAIN_ID,
+      intent: 'internal orchestration policy',
+      requiredRoleIds: [],
+      validateOptions: () => undefined,
+      createRuntime: () => createCaptainRuntime({ enabledPlaybooks: catalog }),
+    };
+    return {
+      entry,
+      command: INTERNAL_CAPTAIN_ID,
+      optionInput: undefined,
+      boundPlayers: [],
+      hostPlayerId(localRole) {
+        throw new Error(
+          `internal Captain has no player binding for ${JSON.stringify(localRole)}`,
+        );
+      },
+    };
+  };
+
+  const engageInternalCaptain = async (): Promise<EngagementFrame> => {
+    if (!internalCaptainEnablement) {
+      throw new Error('internal Captain enablement is unavailable before init');
+    }
+    return engageEnablement(internalCaptainEnablement, true);
+  };
+
+  const disposeFrame = (frame: EngagementFrame): Promise<void> => {
+    if (frame.disposePromise) return frame.disposePromise;
+    const operation = (async (): Promise<void> => {
+      if (frame.invocationSignal && frame.abortListener) {
+        frame.invocationSignal.removeEventListener(
+          'abort',
+          frame.abortListener,
+        );
+      }
+      frame.invocationSignal = undefined;
+      frame.abortListener = undefined;
+      let disposeError: unknown;
+      try {
+        await frame.runtime.dispose();
+      } catch (error) {
+        disposeError = error;
+      }
+      await drainHostCalls(frame.inFlightHostCalls);
+      if (disposeError !== undefined) throw disposeError;
+    })();
+    frame.disposePromise = operation;
+    return operation;
+  };
+
+  const removeTopFrame = (
+    frame: EngagementFrame,
+    reason: NonNullable<EngagementFrame['removal']>['reason'],
+  ): {
+    claimed: boolean;
+    reason: NonNullable<EngagementFrame['removal']>['reason'];
+    promise: Promise<void>;
+  } => {
+    if (frame.removal) {
+      return {
+        claimed: false,
+        reason: frame.removal.reason,
+        promise: frame.removal.promise,
+      };
+    }
+    const operation = (async (): Promise<void> => {
+      if (leafFrame() !== frame) {
+        throw new Error('nested playbook stack is not LIFO');
+      }
+      let removalError: unknown;
+      try {
+        await disposeFrame(frame);
+      } catch (error) {
+        removalError = error;
+      } finally {
+        if (leafFrame() === frame) {
+          frames.pop();
+          if (frame.parent) {
+            pendingChildParents.delete(frame.parent.frame);
+          }
+          pendingChildParents.delete(frame);
+        } else if (frames.includes(frame)) {
+          const stackError = new Error(
+            'nested playbook stack changed during frame removal',
+          );
+          removalError =
+            removalError === undefined
+              ? stackError
+              : new AggregateError(
+                  [removalError, stackError],
+                  'nested playbook frame removal failed',
+                );
+        }
+      }
+      if (removalError !== undefined) throw removalError;
+    })();
+    frame.removal = { reason, promise: operation };
+    return { claimed: true, reason, promise: operation };
+  };
+
+  const unwindFramesFrom = async (
+    frame: EngagementFrame,
+    reason: NonNullable<EngagementFrame['removal']>['reason'] = 'stack',
+  ): Promise<void> => {
+    const index = frames.indexOf(frame);
+    if (index < 0) return;
+    const failures: unknown[] = [];
+    while (frames.length > index) {
+      const current = leafFrame()!;
+      const removal = removeTopFrame(current, reason);
+      try {
+        await removal.promise;
+      } catch (error) {
+        failures.push(error);
+      }
+      if (frames.includes(current)) {
+        failures.push(
+          new Error('nested playbook frame remained after removal attempt'),
+        );
+        break;
+      }
+    }
+    clearLeafLedger();
+    if (failures.length === 1) throw failures[0];
+    if (failures.length > 1) {
+      throw new AggregateError(
+        failures,
+        'nested playbook stack disposal failed',
+      );
+    }
+  };
+
+  const popChild = async (
+    frame: EngagementFrame,
+    status: 'returned' | 'stopped',
+  ): Promise<boolean> => {
+    if (!frame.parent || (leafFrame() !== frame && !frame.removal)) {
+      throw new Error('nested playbook stack is not LIFO');
+    }
+    const parent = frame.parent.frame;
+    const removal = removeTopFrame(frame, 'return');
+    if (!removal.claimed) {
+      await removal.promise;
+      return false;
+    }
+    let cleanupError: unknown;
+    try {
+      await removal.promise;
+    } catch (error) {
+      cleanupError = error;
+    }
+    const message =
+      status === 'returned'
+        ? `◇ ${frameLabel(frame)} returned to ${frameLabel(parent)}`
+        : `◇ ${frameLabel(frame)} stopped; returning to ${frameLabel(parent)}`;
+    try {
+      await requireSession().emitStatus(message);
+    } catch (error) {
+      cleanupError =
+        cleanupError === undefined
+          ? error
+          : new AggregateError(
+              [cleanupError, error],
+              'nested playbook return cleanup failed',
+            );
+    }
+    let visibilityError: unknown;
+    try {
+      await requestVisibility(parent.enablement);
+    } catch (error) {
+      visibilityError = error;
+    }
+    if (visibilityError !== undefined) {
+      if (cleanupError !== undefined) {
+        throw new VisibilityControlError(
+          new AggregateError(
+            [cleanupError, visibilityError],
+            'nested playbook return and visibility failed',
+          ),
+        );
+      }
+      throw visibilityError;
+    }
+    if (cleanupError !== undefined) throw cleanupError;
+    return true;
+  };
+
+  const disposeStack = async (reason: DisposalReason): Promise<void> => {
+    const root = rootFrame();
+    if (!root) return;
+    const rootId = root.entry.id;
+    const rootSessionId = root.sessionId;
+    const failures: unknown[] = [];
+    disposing = true;
+    try {
+      if (reason !== 'dispose') {
+        try {
+          await setMode('chat', reason, rootId, rootSessionId);
+        } catch (error) {
+          failures.push(error);
+          mode = 'chat';
+        }
+      } else {
+        mode = 'chat';
+      }
+      try {
+        await unwindFramesFrom(root);
+      } catch (error) {
+        failures.push(error);
+      }
+    } finally {
+      disposing = false;
+      pendingChildParents.clear();
+      clearLeafLedger();
+    }
+    if (!root.internal) {
+      try {
+        if (reason === 'dismiss') {
+          await requireSession().emitStatus(`◇ ${frameLabel(root)} stopped`);
+        } else if (reason === 'final') {
+          await requireSession().emitStatus(`◇ ${frameLabel(root)} finished`);
+        }
+      } catch (error) {
+        failures.push(error);
+      }
+    }
+    if (failures.length === 1) throw failures[0];
+    if (failures.length > 1) {
+      throw new AggregateError(failures, 'playbook stack disposal failed');
+    }
+  };
+
+  const callResultFor = (
+    frame: EngagementFrame,
+    result: PlaybookRunResult,
+  ): PlaybookCallResult => {
+    if (result.outcome === 'terminal') {
+      return {
+        status: 'ok',
+        playbookId: frame.entry.id,
+        childSessionId: frame.sessionId,
+        state: result.state,
+        ...(result.output !== undefined ? { output: result.output } : {}),
+      };
+    }
+    if (result.outcome === 'aborted') {
+      return {
+        status: 'aborted',
+        playbookId: frame.entry.id,
+        childSessionId: frame.sessionId,
+        state: result.state,
+        ...(result.error ? { error: result.error } : {}),
+      };
+    }
+    throw new Error(`playbook ${frame.entry.id} has not returned`);
+  };
+
+  const assertRetainableResult = (
+    frame: EngagementFrame,
+    result: PlaybookRunResult,
+  ): void => {
+    if (result.outcome === 'suspended') return;
+    if (
+      result.state.quiescent &&
+      result.state.tags.includes('playbook.parked')
+    ) {
+      return;
+    }
+    throw new Error(
+      `playbook ${frame.entry.id} returned outcome "${result.outcome}" ` +
+        'without a quiescent playbook.parked state',
     );
-    return active;
+  };
+
+  const driveFrame = async (
+    frame: EngagementFrame,
+    text: string,
+    context: CaptainContext,
+    signal: AbortSignal = context.signal,
+  ): Promise<PlaybookRunResult> => {
+    if (leafFrame() !== frame) {
+      throw new Error('only the active leaf may receive Boss input');
+    }
+    await requestVisibility(frame.enablement);
+    await setMode('engaged.driving', 'submit');
+    const result = await frame.runtime.handleBossInput({
+      text,
+      signal,
+    });
+    frame.state = result.state;
+    return result;
+  };
+
+  async function resumeParent(
+    child: EngagementFrame,
+    callResult: PlaybookCallResult,
+    context: CaptainContext,
+    status: 'returned' | 'stopped' = 'returned',
+  ): Promise<void> {
+    const parentLink = child.parent;
+    if (!parentLink) throw new Error('root playbook has no caller');
+    const parent = parentLink.frame;
+    const invocationSignal = child.invocationSignal;
+    let effectiveResult = callResult;
+    let ownsReturn = false;
+    let visibilityControlError: unknown;
+    try {
+      ownsReturn = await popChild(child, status);
+    } catch (error) {
+      ownsReturn = child.removal?.reason === 'return';
+      if (error instanceof VisibilityControlError) {
+        visibilityControlError = error;
+      } else {
+        effectiveResult = {
+          status: context.signal.aborted ? 'aborted' : 'error',
+          playbookId: child.entry.id,
+          childSessionId: child.sessionId,
+          ...(child.state ? { state: child.state } : {}),
+          error: normalizeErrorFull(error),
+        };
+      }
+    }
+    if (
+      !ownsReturn ||
+      disposing ||
+      invocationSignal?.aborted ||
+      !frames.includes(parent)
+    ) {
+      return;
+    }
+    let result: PlaybookRunResult;
+    try {
+      result = await parent.runtime.resumePlaybookCall({
+        callId: parentLink.callId,
+        result: effectiveResult,
+        signal: context.signal,
+      });
+    } catch (error) {
+      if (disposing || invocationSignal?.aborted) return;
+      await returnBoundaryFailure(parent, error, context);
+      return;
+    }
+    parent.state = result.state;
+    await processFrameResult(parent, result, context);
+    if (visibilityControlError !== undefined) throw visibilityControlError;
+  }
+
+  async function returnBoundaryFailure(
+    frame: EngagementFrame,
+    error: unknown,
+    context: CaptainContext,
+  ): Promise<void> {
+    if (!frame.parent) throw error;
+    await resumeParent(
+      frame,
+      {
+        status: context.signal.aborted ? 'aborted' : 'error',
+        playbookId: frame.entry.id,
+        childSessionId: frame.sessionId,
+        ...(frame.state ? { state: frame.state } : {}),
+        error: normalizeErrorFull(error),
+      },
+      context,
+    );
+  }
+
+  async function processFrameResult(
+    frame: EngagementFrame,
+    result: PlaybookRunResult,
+    context: CaptainContext,
+  ): Promise<void> {
+    if (result.outcome === 'terminal') {
+      if (frame.parent) {
+        await resumeParent(frame, callResultFor(frame, result), context);
+      } else {
+        await disposeStack('final');
+      }
+      return;
+    }
+    if (result.outcome === 'aborted' && frame.parent) {
+      await resumeParent(frame, callResultFor(frame, result), context);
+      return;
+    }
+    assertRetainableResult(frame, result);
+    if (leafFrame()) {
+      await setMode('engaged.parked', `turn:${result.outcome}`);
+    }
+  }
+
+  const disposeAbandonedChild = async (
+    child: EngagementFrame,
+  ): Promise<void> => {
+    if (disposing || !frames.includes(child) || !child.parent) return;
+    if (child.removal) {
+      await child.removal.promise;
+      return;
+    }
+    const parent = child.parent.frame;
+    let cleanupError: unknown;
+    try {
+      await unwindFramesFrom(child, 'abandoned');
+    } catch (error) {
+      cleanupError = error;
+    }
+    if (frames.includes(parent)) {
+      await requestVisibility(parent.enablement);
+    }
+    if (cleanupError !== undefined) throw cleanupError;
+  };
+
+  callNestedPlaybook = async (
+    parent,
+    request,
+    invocationSignal,
+  ): Promise<PlaybookCallStart> => {
+    if (!activeContext) {
+      throw new Error('callPlaybook invoked outside a Boss turn');
+    }
+    invocationSignal.throwIfAborted();
+    if (leafFrame() !== parent) {
+      throw new Error('only the active leaf may call a child playbook');
+    }
+    if (pendingChildParents.has(parent)) {
+      throw new Error('playbook frame already has an outstanding child');
+    }
+    if (typeof request.callId !== 'string' || request.callId.trim() === '') {
+      throw new Error('nested playbook call id must be a non-empty string');
+    }
+    if (
+      typeof request.playbookId !== 'string' ||
+      request.playbookId.trim() === ''
+    ) {
+      throw new Error('nested playbook id must be a non-empty string');
+    }
+    if (typeof request.text !== 'string') {
+      throw new Error('nested playbook input text must be a string');
+    }
+    if (request.playbookId === INTERNAL_CAPTAIN_ID) {
+      throw new Error('the internal Captain playbook cannot call itself');
+    }
+    const entry = byId.get(request.playbookId);
+    if (!entry) {
+      throw new Error(`playbook "${request.playbookId}" is not enabled`);
+    }
+    if (frames.some((frame) => frame.entry.id === request.playbookId)) {
+      throw new Error(
+        `nested playbook cycle: ${[
+          ...frames.map((frame) => frame.entry.id),
+          request.playbookId,
+        ].join(' -> ')}`,
+      );
+    }
+
+    pendingChildParents.add(parent);
+    let child: EngagementFrame;
+    try {
+      child = makeFrame(enablementById.get(entry.id)!, {
+        frame: parent,
+        callId: request.callId,
+      });
+    } catch (error) {
+      pendingChildParents.delete(parent);
+      throw error;
+    }
+    frames.push(child);
+    clearLeafLedger();
+    let calledStatusEmitted = false;
+    let returnStatusHandled = false;
+    try {
+      await initFrame(child);
+      invocationSignal.throwIfAborted();
+      await requireSession().emitStatus(
+        `◇ ${frameLabel(child)} called by ${frameLabel(parent)}`,
+      );
+      calledStatusEmitted = true;
+      const result = await driveFrame(
+        child,
+        request.text,
+        activeContext,
+        AbortSignal.any([invocationSignal, activeContext.signal]),
+      );
+      if (result.outcome === 'terminal' || result.outcome === 'aborted') {
+        const callResult = callResultFor(child, result);
+        returnStatusHandled = true;
+        const returned = await popChild(
+          child,
+          result.outcome === 'aborted' ? 'stopped' : 'returned',
+        );
+        if (!returned) {
+          throw new Error('nested playbook return lost its active frame');
+        }
+        return { state: 'settled', result: callResult };
+      }
+      assertRetainableResult(child, result);
+      if (invocationSignal.aborted) {
+        const callResult: PlaybookCallResult = {
+          status: 'aborted',
+          playbookId: child.entry.id,
+          childSessionId: child.sessionId,
+          state: result.state,
+        };
+        returnStatusHandled = true;
+        const returned = await popChild(child, 'stopped');
+        if (!returned) {
+          throw new Error('nested playbook abort lost its active frame');
+        }
+        return { state: 'settled', result: callResult };
+      }
+      const abortListener = (): void => {
+        registerPlaybookAbortCleanup(
+          invocationSignal,
+          disposeAbandonedChild(child),
+        );
+      };
+      child.invocationSignal = invocationSignal;
+      child.abortListener = abortListener;
+      invocationSignal.addEventListener('abort', abortListener, { once: true });
+      return { state: 'suspended', childSessionId: child.sessionId };
+    } catch (error) {
+      let boundaryError = error;
+      let visibilityControlFailure = error instanceof VisibilityControlError;
+      if (frames.includes(child)) {
+        try {
+          await unwindFramesFrom(child, 'stack');
+        } catch (cleanupError) {
+          boundaryError = new AggregateError(
+            [error, cleanupError],
+            'nested playbook call and cleanup failed',
+          );
+        }
+      }
+      pendingChildParents.delete(parent);
+      if (calledStatusEmitted && !returnStatusHandled) {
+        try {
+          await requireSession().emitStatus(
+            `◇ ${frameLabel(child)} stopped; returning to ${frameLabel(parent)}`,
+          );
+        } catch (statusError) {
+          boundaryError = new AggregateError(
+            [boundaryError, statusError],
+            'nested playbook failure status emission failed',
+          );
+        }
+      }
+      if (frames.includes(parent)) {
+        try {
+          await requestVisibility(parent.enablement);
+        } catch (visibilityError) {
+          visibilityControlFailure = true;
+          boundaryError = new AggregateError(
+            [boundaryError, visibilityError],
+            'nested playbook call return failed',
+          );
+        }
+      }
+      if (visibilityControlFailure) throw boundaryError;
+      return {
+        state: 'settled',
+        result: {
+          status: invocationSignal.aborted ? 'aborted' : 'error',
+          playbookId: request.playbookId,
+          childSessionId: child.sessionId,
+          error: normalizeErrorFull(boundaryError),
+        },
+      };
+    }
   };
 
   const submitToActive = async (
-    engagement: ActiveEngagement,
+    frame: EngagementFrame,
     text: string,
     context: CaptainContext,
   ): Promise<void> => {
+    const policy = frame.entry.summaryPolicy;
     const summaryCounts: TurnSummaryCounts = {
       interruptions: 0,
       copyPastes: 0,
     };
     const summaryStateCounts = new Map<string, number>();
-    let shouldSummarize = false;
-    activeTurnSummary = {
-      counts: summaryCounts,
-      stateCounts: summaryStateCounts,
-    };
-    await setMode('engaged.driving', 'submit');
+    activeTurnSummary = policy
+      ? {
+          owner: frame,
+          counts: summaryCounts,
+          stateCounts: summaryStateCounts,
+        }
+      : undefined;
+    let completed = false;
     try {
-      await engagement.runtime.handleBossInput({
-        text,
-        signal: context.signal,
-      });
-      shouldSummarize = true;
+      const result = await driveFrame(frame, text, context);
+      await processFrameResult(frame, result, context);
+      completed = true;
+    } catch (error) {
+      if (frame.parent && frames.includes(frame)) {
+        await returnBoundaryFailure(frame, error, context);
+        completed = true;
+      } else {
+        throw error;
+      }
     } finally {
       activeTurnSummary = undefined;
-      if (active === engagement && finalDisposalRequested === engagement) {
-        finalDisposalRequested = undefined;
-        await disposeActive('final');
-      } else if (active === engagement && mode === 'engaged.driving') {
+      if (leafFrame() && mode === 'engaged.driving') {
         await setMode('engaged.parked', 'turn.settled');
       }
     }
-    if (shouldSummarize) {
-      await callVisibleTurnSummary(context, {
-        playbookId: engagement.entry.id,
+    if (completed && policy) {
+      const progressRounds = summaryProgressRoundCount(summaryStateCounts);
+      await callVisibleTurnSummary(frame, context, {
+        playbookId: frame.entry.id,
         submittedText: text,
         counts: summaryCounts,
         progressPhrase: summaryProgressPhrase(summaryStateCounts),
-        reviewRebuttalRounds: summaryProgressRoundCount(summaryStateCounts),
+        progressRounds,
+        savedLine: policy.savedCountsLine(summaryCounts, progressRounds),
       });
     }
   };
 
-  const disposeActive = async (
-    reason: DisposalReason,
-  ): Promise<void> => {
-    const engagement = active;
-    if (!engagement) return;
-    const playbookId = engagement.entry.id;
-    const commandLabel = playbookCommandLabel(engagement.entry);
-    active = undefined;
-    finalDisposalRequested = undefined;
-    if (reason === 'dispose') {
-      mode = 'chat';
-      await engagement.runtime.dispose();
-      latestSubRuntimeStateId = undefined;
-      pendingBossQuestion = undefined;
-      lastError = undefined;
-      return;
-    }
-    await setMode('chat', reason, playbookId);
-    await engagement.runtime.dispose();
-    if (reason === 'dismiss') {
-      await requireSession().emitStatus(`◇ ${commandLabel} stopped`);
-    } else if (reason === 'final') {
-      await requireSession().emitStatus(`◇ ${commandLabel} finished`);
-    }
-    latestSubRuntimeStateId = undefined;
-    pendingBossQuestion = undefined;
-    lastError = undefined;
-  };
-
   const callVisibleChat = async (
+    frame: EngagementFrame,
     context: CaptainContext,
     message: string,
   ): Promise<void> => {
-    const result = await context.callCaptain(visibleChatEnvelope(message));
+    const result = await callCaptainQueued(
+      frame,
+      context,
+      visibleChatEnvelope(message),
+      { visibility: 'visible', resume: false, allowedTools: [] },
+      context.signal,
+    );
     if (result.status !== 'ok') {
-      throw new Error(
-        result.error ?? `callCaptain status "${result.status}"`,
-      );
+      throw new Error(result.error ?? `callCaptain status "${result.status}"`);
     }
   };
 
   const callVisibleTurnSummary = async (
+    frame: EngagementFrame,
     context: CaptainContext,
     input: {
       playbookId: string;
       submittedText: string;
       counts: TurnSummaryCounts;
       progressPhrase: string;
-      reviewRebuttalRounds: number;
+      progressRounds: number;
+      savedLine: string;
     },
   ): Promise<void> => {
-    const result = await context.callCaptain(visibleTurnSummaryEnvelope(input));
+    const result = await callCaptainQueued(
+      frame,
+      context,
+      visibleTurnSummaryEnvelope(input),
+      { visibility: 'visible', resume: false, allowedTools: [] },
+      context.signal,
+    );
     if (result.status !== 'ok') {
-      throw new Error(
-        result.error ?? `callCaptain status "${result.status}"`,
-      );
+      throw new Error(result.error ?? `callCaptain status "${result.status}"`);
     }
   };
 
-  const hiddenRouterEnvelope = (prompt: string): string =>
+  const hiddenLifecycleEnvelope = (prompt: string): string =>
     [
-      'You are the Playbook Captain shell router.',
+      'You are the Playbook Captain shell lifecycle classifier.',
       'This is hidden control work. Return only one JSON object and no prose.',
       'Allowed decisions:',
-      '{"decision":"chat","text":"visible clarification or chat reply"}',
-      '{"decision":"dispatch","playbookId":"<registered id>","text":"Boss text for that playbook"}',
-      '{"decision":"sub","text":"Boss text for the active playbook"}',
-      '{"decision":"dismiss","text":"optional visible dismissal reply"}',
-      'Use chat for near-miss command-like input or low-confidence playbook selection.',
-      'Treat unregistered slash-prefixed input as ordinary router input.',
-      `Ledger:\n${JSON.stringify(ledgerSnapshot())}`,
-      `Registry:\n${JSON.stringify(
-        entries.map((entry) => ({
-          id: entry.id,
-          command: entry.command,
-          intent: entry.intent,
-        })),
-      )}`,
+      '{"decision":"deliver"}',
+      '{"decision":"dismiss"}',
+      'Choose dismiss only when Boss explicitly asks to stop or dismiss the current active engagement.',
+      'Choose deliver for every task instruction, answer, clarification, continuation, command-like near miss, or ambiguous message.',
+      'Do not rewrite, summarize, or copy the Boss message into the result.',
       `Boss message:\n${prompt}`,
     ].join('\n\n');
 
-  const routerClarification = async (
-    context: CaptainContext,
-  ): Promise<void> => {
-    await callVisibleChat(
-      context,
-      "I'm not sure whether this should be Captain chat or a /code task. Please clarify.",
-    );
-  };
-
-  const parseRouterDecision = (
+  const parseLifecycleDecision = (
     finalText: string,
-  ): RouterDecision | undefined => {
+  ): LifecycleDecision | undefined => {
     let parsed: unknown;
     try {
       parsed = JSON.parse(finalText);
@@ -547,91 +1558,57 @@ export function createPlaybookCaptainShell(
     }
     const record = parsed as Record<string, unknown>;
     const decision = record.decision;
-    if (decision === 'chat') {
-      return typeof record.text === 'string' && record.text.trim()
-        ? { decision, text: record.text.trim() }
-        : undefined;
-    }
-    if (decision === 'dispatch') {
-      return typeof record.playbookId === 'string' &&
-        byId.has(record.playbookId) &&
-        typeof record.text === 'string' &&
-        record.text.trim()
-        ? {
-            decision,
-            playbookId: record.playbookId,
-            text: record.text.trim(),
-          }
-        : undefined;
-    }
-    if (decision === 'sub') {
-      return typeof record.text === 'string' && record.text.trim()
-        ? { decision, text: record.text.trim() }
-        : undefined;
-    }
-    if (decision === 'dismiss') {
-      return typeof record.text === 'string' && record.text.trim()
-        ? { decision, text: record.text.trim() }
-        : { decision };
-    }
+    if (decision === 'deliver') return { decision };
+    if (decision === 'dismiss') return { decision };
     return undefined;
   };
 
-  const routeHidden = async (
+  const routeEngaged = async (
     turn: BossTurn,
     context: CaptainContext,
   ): Promise<void> => {
-    const result = await context.callCaptain(
-      hiddenRouterEnvelope(turn.prompt),
-      { visibility: 'hidden' },
-    );
-    if (result.status !== 'ok' || result.finalText === undefined) {
-      await routerClarification(context);
-      return;
-    }
-    const decision = parseRouterDecision(result.finalText);
-    if (!decision) {
-      await routerClarification(context);
-      return;
-    }
-    lastRouteDecision = decision.decision;
-
-    if (decision.decision === 'chat') {
-      await callVisibleChat(context, decision.text);
-      return;
+    const leaf = leafFrame();
+    if (!leaf) {
+      throw new Error('engaged lifecycle routing requires an active leaf');
     }
-
-    if (decision.decision === 'dispatch') {
-      const entry = byId.get(decision.playbookId);
-      if (!entry || (active && active.entry.id !== entry.id)) {
-        await routerClarification(context);
-        return;
+    let decision: LifecycleDecision | undefined;
+    try {
+      const result = await callCaptainQueued(
+        leaf,
+        context,
+        hiddenLifecycleEnvelope(turn.prompt),
+        { visibility: 'hidden', resume: false, allowedTools: [] },
+        context.signal,
+      );
+      if (result.status === 'ok' && result.finalText !== undefined) {
+        decision = parseLifecycleDecision(result.finalText);
       }
-      const engagement = await engage(entry);
-      await submitToActive(engagement, decision.text, context);
-      return;
+    } catch {
+      // Lifecycle classification is advisory. Delivery is fail-open so an
+      // unavailable classifier can never consume a parked leaf's Boss reply.
     }
-
-    if (decision.decision === 'sub') {
-      if (!active) {
-        await routerClarification(context);
-        return;
-      }
-      await submitToActive(active, decision.text, context);
+    if (decision?.decision !== 'dismiss') {
+      lastRouteDecision = 'deliver';
+      await submitToActive(leaf, turn.prompt, context);
       return;
     }
 
-    if (!active) {
-      await routerClarification(context);
-      return;
+    lastRouteDecision = 'dismiss';
+    if (leaf.parent) {
+      await resumeParent(
+        leaf,
+        {
+          status: 'aborted',
+          playbookId: leaf.entry.id,
+          childSessionId: leaf.sessionId,
+          ...(leaf.state ? { state: leaf.state } : {}),
+        },
+        context,
+        'stopped',
+      );
+    } else {
+      await disposeStack('dismiss');
     }
-
-    const dismissedCommandLabel = playbookCommandLabel(active.entry);
-    await disposeActive('dismiss');
-    await callVisibleChat(
-      context,
-      decision.text ?? `${dismissedCommandLabel} stopped.`,
-    );
   };
 
   const handleRegisteredCommand = async (
@@ -639,19 +1616,24 @@ export function createPlaybookCaptainShell(
     text: string,
     context: CaptainContext,
   ): Promise<void> => {
-    if (active && active.entry.id !== entry.id) {
+    const enablement = enablementById.get(entry.id)!;
+    const leaf = leafFrame();
+    if (leaf && leaf.entry.id !== entry.id) {
       await callVisibleChat(
+        leaf,
         context,
-        `/${active.entry.command} is already running. Finish or stop it before starting /${entry.command}.`,
+        `${frameLabel(leaf)} is already running. Finish or stop it before starting /${enablement.command}.`,
       );
       return;
     }
 
-    const engagement = await engage(entry);
+    const engagement = leaf ?? (await engage(entry));
     if (text.length === 0) {
+      await requestVisibility(engagement.enablement);
       await callVisibleChat(
+        engagement,
         context,
-        `Ask what task to run with /${entry.command}.`,
+        `Ask what task to run with /${enablement.command}.`,
       );
       return;
     }
@@ -663,9 +1645,15 @@ export function createPlaybookCaptainShell(
     async init(initSession: CaptainSession): Promise<void> {
       session = initSession;
       players = initSession.players;
-      for (const entry of entries) {
-        entry.validateOptions(options);
+      const built = await buildEnablements(options, players, loadModule);
+      entries = built.entries;
+      byCommand = built.byCommand;
+      byId = built.byId;
+      enablementById = built.enablementById;
+      for (const enablement of enablementById.values()) {
+        enablement.entry.validateOptions(enablement.optionInput);
       }
+      internalCaptainEnablement = createInternalCaptainEnablement();
       await setMode('chat', 'init');
     },
 
@@ -674,6 +1662,11 @@ export function createPlaybookCaptainShell(
       context: CaptainContext,
     ): Promise<void> {
       requireSession();
+      if (activeTurnHostCalls !== undefined) {
+        throw new Error('cannot handle concurrent Boss turns');
+      }
+      const turnHostCalls = new Set<Promise<unknown>>();
+      activeTurnHostCalls = turnHostCalls;
       activeContext = context;
       try {
         const command = parseRegisteredCommand(turn.prompt);
@@ -685,15 +1678,31 @@ export function createPlaybookCaptainShell(
           }
         }
 
-        await routeHidden(turn, context);
+        const leaf = leafFrame();
+        if (leaf) {
+          await routeEngaged(turn, context);
+          return;
+        }
+        if (turn.prompt.trim().length === 0) return;
+        const captain = await engageInternalCaptain();
+        await submitToActive(captain, turn.prompt, context);
       } finally {
+        await drainHostCalls(turnHostCalls);
+        if (activeTurnHostCalls === turnHostCalls) {
+          activeTurnHostCalls = undefined;
+        }
         activeContext = undefined;
       }
     },
 
+    async prepareDispose(): Promise<void> {
+      activeContext = undefined;
+      await disposeStack('dispose');
+    },
+
     async dispose(): Promise<void> {
       activeContext = undefined;
-      await disposeActive('dispose');
+      await disposeStack('dispose');
     },
   };
 }