@sublang/playbook 0.9.0 → 1.3.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,13 +11,18 @@ import type {
   CaptainSession,
 } from '@sublang/cligent/tmux-play';
 import type {
+  NormalizedError,
+  PlaybookCallRequest,
+  PlaybookCallResult,
+  PlaybookCallStart,
   PlaybookPorts,
+  PlaybookRunResult,
   PlaybookRuntime,
-} from './code.playbook.js';
-import type {
-  PlaybookSummaryPolicy,
-  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;
@@ -23,6 +31,14 @@ export interface CreatePlaybookRuntimeOptions {
 
 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 {
@@ -30,9 +46,6 @@ export interface PlaybookCaptainRegistryEntry {
   command: string;
   intent: string;
   requiredRoleIds: readonly string[];
-  idleStateId: string;
-  finalStateId: string;
-  parkStateIds: readonly string[];
   summaryPolicy?: PlaybookSummaryPolicy;
   validateOptions(captainOptions: unknown): unknown;
   createRuntime(options: CreatePlaybookRuntimeOptions): PlaybookRuntime;
@@ -50,33 +63,67 @@ interface Enablement {
   visiblePlayerIds?: readonly string[];
 }
 
-interface ActiveEngagement {
+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;
@@ -84,6 +131,7 @@ interface TurnSummaryCounts {
 }
 
 interface ActiveTurnSummary {
+  owner: EngagementFrame;
   counts: TurnSummaryCounts;
   stateCounts: Map<string, number>;
 }
@@ -101,7 +149,7 @@ function parseRegisteredCommand(
 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');
 }
@@ -116,7 +164,7 @@ function visibleTurnSummaryEnvelope(input: {
 }): string {
   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.',
@@ -140,10 +188,8 @@ function stateCountLabel(
   stateId: string,
   entry: PlaybookCaptainRegistryEntry,
 ): string | undefined {
-  if (stateId === entry.idleStateId || stateId === entry.finalStateId) {
-    return undefined;
-  }
-  const registryLabel = entry.summaryPolicy?.stateCountLabels?.[stateId]?.trim();
+  const registryLabel =
+    entry.summaryPolicy?.stateCountLabels?.[stateId]?.trim();
   return registryLabel || undefined;
 }
 
@@ -154,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);
 }
 
@@ -179,9 +229,6 @@ function isValidRegistryEntry(
     typeof e.command === 'string' &&
     typeof e.intent === 'string' &&
     Array.isArray(e.requiredRoleIds) &&
-    typeof e.idleStateId === 'string' &&
-    typeof e.finalStateId === 'string' &&
-    Array.isArray(e.parkStateIds) &&
     typeof e.validateOptions === 'function' &&
     typeof e.createRuntime === 'function'
   );
@@ -230,6 +277,11 @@ async function buildEnablements(
     );
   }
   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`);
@@ -271,6 +323,11 @@ async function buildEnablements(
       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}"`,
@@ -278,7 +335,11 @@ async function buildEnablements(
     }
     const boundPlayers = entry.requiredRoleIds.map((role) => {
       const host = players.find((p) => p.id === `${entry.id}-${role}`);
-      return { id: role, adapter: host?.adapter, model: host?.model };
+      return {
+        id: role,
+        ...(host?.adapter !== undefined ? { adapter: host.adapter } : {}),
+        ...(host?.model !== undefined ? { model: host.model } : {}),
+      };
     });
     entries.push(entry);
     byId.set(entry.id, entry);
@@ -303,21 +364,34 @@ export function createPlaybookCaptainShell(
 ): Captain {
   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) {
@@ -327,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 } : {}),
   });
@@ -341,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,
@@ -349,7 +439,7 @@ export function createPlaybookCaptainShell(
         from,
         to,
         event,
-        ledger: ledgerSnapshot(playbookId),
+        ledger: ledgerSnapshot(playbookId, activeSessionId),
       },
     });
   };
@@ -357,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 = (
@@ -391,69 +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 ||
-      active.entry.parkStateIds.includes(stateId)
-    ) {
-      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 hostPlayerId = active
-        ? active.enablement.hostPlayerId(playerId)
-        : playerId;
-      const result = await activeContext.callPlayer(hostPlayerId, 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 } : {}),
       };
     },
-    callJudge: async (prompt, _signal) => {
+    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) => {
       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}"`,
@@ -465,14 +686,28 @@ export function createPlaybookCaptainShell(
       const guard = guardFromJudgeReply(result.finalText);
       if (
         guard &&
-        active?.entry.summaryPolicy?.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,
@@ -480,7 +715,7 @@ 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);
     },
@@ -493,65 +728,755 @@ export function createPlaybookCaptainShell(
   const requestVisibility = async (enablement: Enablement): Promise<void> => {
     const ids = enablement.visiblePlayerIds;
     if (!ids || ids.length === 0 || !activeContext) return;
-    await activeContext.setVisiblePlayers(ids);
+    try {
+      await activeContext.setVisiblePlayers(ids);
+    } catch (error) {
+      throw new VisibilityControlError(error);
+    }
   };
 
-  const engage = async (
-    entry: PlaybookCaptainRegistryEntry,
-  ): Promise<ActiveEngagement> => {
-    if (active?.entry.id === entry.id) return active;
-    const enablement = enablementById.get(entry.id)!;
+  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: enablement.optionInput,
       players: enablement.boundPlayers,
     });
-    active = { entry, enablement, runtime };
-    latestSubRuntimeStateId = undefined;
-    pendingBossQuestion = undefined;
+    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),
+    });
+  };
+
+  const clearLeafLedger = (): void => {
+    pendingBossQuestions = undefined;
     lastError = undefined;
-    finalDisposalRequested = undefined;
-    await setMode('engaged.parked', 'engage', entry.id);
-    await runtime.init(createPorts());
-    await requireSession().emitStatus(`◇ /${enablement.command} started`);
-    return active;
+  };
+
+  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',
+    );
+  };
+
+  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> => {
-    await requestVisibility(engagement.enablement);
-    const policy = engagement.entry.summaryPolicy;
+    const policy = frame.entry.summaryPolicy;
     const summaryCounts: TurnSummaryCounts = {
       interruptions: 0,
       copyPastes: 0,
     };
     const summaryStateCounts = new Map<string, number>();
-    let shouldSummarize = false;
     activeTurnSummary = policy
-      ? { counts: summaryCounts, stateCounts: summaryStateCounts }
+      ? {
+          owner: frame,
+          counts: summaryCounts,
+          stateCounts: summaryStateCounts,
+        }
       : undefined;
-    await setMode('engaged.driving', 'submit');
+    let completed = false;
     try {
-      await engagement.runtime.handleBossInput({
-        text,
-        signal: context.signal,
-      });
-      shouldSummarize = policy !== undefined;
+      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 && policy) {
+    if (completed && policy) {
       const progressRounds = summaryProgressRoundCount(summaryStateCounts);
-      await callVisibleTurnSummary(context, {
-        playbookId: engagement.entry.id,
+      await callVisibleTurnSummary(frame, context, {
+        playbookId: frame.entry.id,
         submittedText: text,
         counts: summaryCounts,
         progressPhrase: summaryProgressPhrase(summaryStateCounts),
@@ -561,48 +1486,25 @@ export function createPlaybookCaptainShell(
     }
   };
 
-  const disposeActive = async (
-    reason: DisposalReason,
-  ): Promise<void> => {
-    const engagement = active;
-    if (!engagement) return;
-    const playbookId = engagement.entry.id;
-    const commandLabel = `/${engagement.enablement.command}`;
-    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;
@@ -613,48 +1515,34 @@ export function createPlaybookCaptainShell(
       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: enablementById.get(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);
@@ -670,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 = `/${active.enablement.command}`;
-    await disposeActive('dismiss');
-    await callVisibleChat(
-      context,
-      decision.text ?? `${dismissedCommandLabel} stopped.`,
-    );
   };
 
   const handleRegisteredCommand = async (
@@ -763,18 +1617,21 @@ export function createPlaybookCaptainShell(
     context: CaptainContext,
   ): Promise<void> => {
     const enablement = enablementById.get(entry.id)!;
-    if (active && active.entry.id !== entry.id) {
+    const leaf = leafFrame();
+    if (leaf && leaf.entry.id !== entry.id) {
       await callVisibleChat(
+        leaf,
         context,
-        `/${active.enablement.command} is already running. Finish or stop it before starting /${enablement.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 /${enablement.command}.`,
       );
@@ -796,6 +1653,7 @@ export function createPlaybookCaptainShell(
       for (const enablement of enablementById.values()) {
         enablement.entry.validateOptions(enablement.optionInput);
       }
+      internalCaptainEnablement = createInternalCaptainEnablement();
       await setMode('chat', 'init');
     },
 
@@ -804,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);
@@ -815,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');
     },
   };
 }