@sublang/playbook 0.9.0 → 1.3.0

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

@@ -1,7 +1,19 @@
 // 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 { registerPlaybookAbortCleanup } from '../../../src/xstate-runtime.js';
+import createDefaultCaptainRuntime from '../captain.playbook/captain.playbook.js';
+class VisibilityControlError extends Error {
+    constructor(cause) {
+        super(`playbook visibility request failed: ${String(cause?.message ?? cause)}`, { cause });
+        this.name = 'VisibilityControlError';
+    }
+}
 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;
 function parseRegisteredCommand(prompt) {
     const match = /^\/([A-Za-z][A-Za-z0-9_-]*)(?:\s+([\s\S]*))?$/.exec(prompt.trim());
     if (!match)
@@ -11,14 +23,14 @@ function parseRegisteredCommand(prompt) {
 function visibleChatEnvelope(message) {
     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');
 }
 function visibleTurnSummaryEnvelope(input) {
     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.',
@@ -38,9 +50,6 @@ function visibleTurnSummaryEnvelope(input) {
     ].join('\n\n');
 }
 function stateCountLabel(stateId, entry) {
-    if (stateId === entry.idleStateId || stateId === entry.finalStateId) {
-        return undefined;
-    }
     const registryLabel = entry.summaryPolicy?.stateCountLabels?.[stateId]?.trim();
     return registryLabel || undefined;
 }
@@ -74,9 +83,6 @@ function isValidRegistryEntry(value) {
         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');
 }
@@ -106,6 +112,9 @@ async function buildEnablements(options, players, loadModule) {
         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`);
@@ -135,12 +144,19 @@ async function buildEnablements(options, players, loadModule) {
         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, 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);
@@ -158,52 +174,75 @@ async function buildEnablements(options, players, loadModule) {
 }
 export function createPlaybookCaptainShell(options, deps = {}) {
     const loadModule = deps.loadModule ?? ((specifier) => import(specifier));
+    const createSessionId = deps.createSessionId ?? randomUUID;
+    const createCaptainRuntime = deps.createCaptainRuntime ?? createDefaultCaptainRuntime;
     let entries = [];
     let byCommand = new Map();
     let byId = new Map();
     let enablementById = new Map();
+    let internalCaptainEnablement;
     let session;
     let players = [];
     let activeContext;
-    let active;
+    const frames = [];
     let mode = 'chat';
-    let latestSubRuntimeStateId;
-    let pendingBossQuestion;
+    let pendingBossQuestions;
     let lastError;
     let lastRouteDecision;
-    let finalDisposalRequested;
     let activeTurnSummary;
+    let activeTurnHostCalls;
+    const issuedSessionIds = new Set();
+    const pendingChildParents = new Set();
+    const captainQueue = new PQueue({ concurrency: 1 });
+    let disposing = false;
+    const rootFrame = () => frames[0];
+    const leafFrame = () => frames.at(-1);
+    const frameLabel = (frame) => frame.internal ? 'Captain' : `/${frame.enablement.command}`;
     const requireSession = () => {
         if (!session) {
             throw new Error('init must be called first');
         }
         return session;
     };
-    const ledgerSnapshot = (playbookId = active?.entry.id) => ({
+    const ledgerSnapshot = (playbookId = leafFrame()?.entry.id, activeSessionId = leafFrame()?.sessionId) => ({
         ...(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 } : {}),
     });
-    const emitShellTelemetry = async (from, to, event, playbookId = active?.entry.id) => {
+    const emitShellTelemetry = async (from, to, event, playbookId = leafFrame()?.entry.id, activeSessionId = leafFrame()?.sessionId) => {
         await requireSession().emitTelemetry({
             topic: SHELL_FSM_TOPIC,
             payload: {
                 from,
                 to,
                 event,
-                ledger: ledgerSnapshot(playbookId),
+                ledger: ledgerSnapshot(playbookId, activeSessionId),
             },
         });
     };
-    const setMode = async (nextMode, event, playbookId = active?.entry.id) => {
+    const setMode = async (nextMode, event, playbookId = leafFrame()?.entry.id, activeSessionId = leafFrame()?.sessionId) => {
         if (mode === nextMode)
             return;
         const from = mode;
         mode = nextMode;
-        await emitShellTelemetry(from, nextMode, event, playbookId);
+        await emitShellTelemetry(from, nextMode, event, playbookId, activeSessionId);
     };
     const normalizeErrorCompact = (value) => {
         if (value === undefined || value === null)
@@ -225,62 +264,141 @@ export function createPlaybookCaptainShell(options, deps = {}) {
     const payloadRecord = (payload) => typeof payload === 'object' && payload !== null && !Array.isArray(payload)
         ? payload
         : undefined;
-    const mirroredStateId = (payload) => {
-        const record = payloadRecord(payload);
-        if (!record)
+    const playbookState = (value) => {
+        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;
-        if (typeof record.to === 'string')
-            return record.to;
-        return typeof record.state === 'string' ? record.state : undefined;
+        }
+        return record;
     };
-    const mirrorSubRuntimeTelemetry = async (payload) => {
-        if (!active)
-            return;
+    const stateValueContains = (value, stateId) => {
+        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) => {
+        while (calls.size > 0) {
+            await Promise.allSettled([...calls]);
+        }
+    };
+    const trackHostCall = (frame, call) => {
+        // 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;
+        tracked = call.finally(() => {
+            frame.inFlightHostCalls.delete(tracked);
+            turnCalls?.delete(tracked);
+        });
+        frame.inFlightHostCalls.add(tracked);
+        turnCalls?.add(tracked);
+        return tracked;
+    };
+    const callCaptainQueued = (frame, context, prompt, options, signal) => {
+        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, payload) => {
         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);
-        }
-        latestSubRuntimeStateId = stateId;
-        pendingBossQuestion = record?.pendingBossQuestion;
-        lastError = normalizeErrorCompact(record?.lastError);
-        if (stateId === active.entry.finalStateId) {
-            finalDisposalRequested = active;
+        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 = () => ({
-        callPlayer: async (playerId, prompt, _signal) => {
+    let callNestedPlaybook;
+    const createPorts = (frame) => ({
+        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}"`);
             }
@@ -289,18 +407,34 @@ export function createPlaybookCaptainShell(options, deps = {}) {
             }
             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;
+            const registerOpeningCleanup = () => {
+                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);
         },
         emitTelemetry: async (event) => {
             if (event.topic === SUB_RUNTIME_FSM_TOPIC) {
-                await mirrorSubRuntimeTelemetry(event.payload);
+                await mirrorSubRuntimeTelemetry(frame, event.payload);
             }
             await requireSession().emitTelemetry(event);
         },
@@ -313,60 +447,651 @@ export function createPlaybookCaptainShell(options, deps = {}) {
         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) => {
-        if (active?.entry.id === entry.id)
-            return active;
-        const enablement = enablementById.get(entry.id);
+    const allocateSessionId = () => {
+        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) => {
+        const compact = normalizeErrorCompact(value) ?? {
+            name: 'Error',
+            message: String(value),
+        };
+        const stack = value instanceof Error
+            ? value.stack
+            : typeof value === 'object' && value !== null
+                ? value.stack
+                : undefined;
+        return typeof stack === 'string' ? { ...compact, stack } : compact;
+    };
+    const makeFrame = (enablement, parent, internal = false) => {
+        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) => {
+        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 = () => {
+        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 submitToActive = async (engagement, text, context) => {
-        await requestVisibility(engagement.enablement);
-        const policy = engagement.entry.summaryPolicy;
+    };
+    const engageEnablement = async (enablement, internal) => {
+        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) => engageEnablement(enablementById.get(entry.id), false);
+    const createInternalCaptainEnablement = () => {
+        const catalog = Object.freeze(entries.map((entry) => Object.freeze({
+            id: entry.id,
+            command: enablementById.get(entry.id).command,
+            intent: entry.intent,
+        })));
+        const entry = {
+            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 () => {
+        if (!internalCaptainEnablement) {
+            throw new Error('internal Captain enablement is unavailable before init');
+        }
+        return engageEnablement(internalCaptainEnablement, true);
+    };
+    const disposeFrame = (frame) => {
+        if (frame.disposePromise)
+            return frame.disposePromise;
+        const operation = (async () => {
+            if (frame.invocationSignal && frame.abortListener) {
+                frame.invocationSignal.removeEventListener('abort', frame.abortListener);
+            }
+            frame.invocationSignal = undefined;
+            frame.abortListener = undefined;
+            let disposeError;
+            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, reason) => {
+        if (frame.removal) {
+            return {
+                claimed: false,
+                reason: frame.removal.reason,
+                promise: frame.removal.promise,
+            };
+        }
+        const operation = (async () => {
+            if (leafFrame() !== frame) {
+                throw new Error('nested playbook stack is not LIFO');
+            }
+            let removalError;
+            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, reason = 'stack') => {
+        const index = frames.indexOf(frame);
+        if (index < 0)
+            return;
+        const failures = [];
+        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, status) => {
+        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;
+        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;
+        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) => {
+        const root = rootFrame();
+        if (!root)
+            return;
+        const rootId = root.entry.id;
+        const rootSessionId = root.sessionId;
+        const failures = [];
+        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, result) => {
+        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, result) => {
+        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, text, context, signal = context.signal) => {
+        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, callResult, context, status = 'returned') {
+        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;
+        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;
+        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, error, context) {
+        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, result, context) {
+        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) => {
+        if (disposing || !frames.includes(child) || !child.parent)
+            return;
+        if (child.removal) {
+            await child.removal.promise;
+            return;
+        }
+        const parent = child.parent.frame;
+        let cleanupError;
+        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) => {
+        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;
+        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 = {
+                    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 = () => {
+                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 (frame, text, context) => {
+        const policy = frame.entry.summaryPolicy;
         const summaryCounts = {
             interruptions: 0,
             copyPastes: 0,
         };
         const summaryStateCounts = new Map();
-        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),
@@ -375,68 +1100,30 @@ export function createPlaybookCaptainShell(options, deps = {}) {
             });
         }
     };
-    const disposeActive = async (reason) => {
-        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 (context, message) => {
-        const result = await context.callCaptain(visibleChatEnvelope(message));
+    const callVisibleChat = async (frame, context, 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}"`);
         }
     };
-    const callVisibleTurnSummary = async (context, input) => {
-        const result = await context.callCaptain(visibleTurnSummaryEnvelope(input));
+    const callVisibleTurnSummary = async (frame, context, 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}"`);
         }
     };
-    const hiddenRouterEnvelope = (prompt) => [
-        'You are the Playbook Captain shell router.',
+    const hiddenLifecycleEnvelope = (prompt) => [
+        '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) => {
-        await callVisibleChat(context, "I'm not sure whether this should be Captain chat or a /code task. Please clarify.");
-    };
-    const parseRouterDecision = (finalText) => {
+    const parseLifecycleDecision = (finalText) => {
         let parsed;
         try {
             parsed = JSON.parse(finalText);
@@ -451,87 +1138,57 @@ export function createPlaybookCaptainShell(options, deps = {}) {
         }
         const record = parsed;
         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 (turn, context) => {
-        const result = await context.callCaptain(hiddenRouterEnvelope(turn.prompt), { visibility: 'hidden' });
-        if (result.status !== 'ok' || result.finalText === undefined) {
-            await routerClarification(context);
-            return;
+    const routeEngaged = async (turn, context) => {
+        const leaf = leafFrame();
+        if (!leaf) {
+            throw new Error('engaged lifecycle routing requires an active leaf');
         }
-        const decision = parseRouterDecision(result.finalText);
-        if (!decision) {
-            await routerClarification(context);
-            return;
+        let decision;
+        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);
+            }
         }
-        lastRouteDecision = decision.decision;
-        if (decision.decision === 'chat') {
-            await callVisibleChat(context, decision.text);
-            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 === 'dispatch') {
-            const entry = byId.get(decision.playbookId);
-            if (!entry || (active && active.entry.id !== entry.id)) {
-                await routerClarification(context);
-                return;
-            }
-            const engagement = await engage(entry);
-            await submitToActive(engagement, decision.text, context);
+        if (decision?.decision !== 'dismiss') {
+            lastRouteDecision = 'deliver';
+            await submitToActive(leaf, turn.prompt, context);
             return;
         }
-        if (decision.decision === 'sub') {
-            if (!active) {
-                await routerClarification(context);
-                return;
-            }
-            await submitToActive(active, decision.text, 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');
         }
-        if (!active) {
-            await routerClarification(context);
-            return;
+        else {
+            await disposeStack('dismiss');
         }
-        const dismissedCommandLabel = `/${active.enablement.command}`;
-        await disposeActive('dismiss');
-        await callVisibleChat(context, decision.text ?? `${dismissedCommandLabel} stopped.`);
     };
     const handleRegisteredCommand = async (entry, text, context) => {
         const enablement = enablementById.get(entry.id);
-        if (active && active.entry.id !== entry.id) {
-            await callVisibleChat(context, `/${active.enablement.command} is already running. Finish or stop it before starting /${enablement.command}.`);
+        const leaf = leafFrame();
+        if (leaf && leaf.entry.id !== entry.id) {
+            await callVisibleChat(leaf, context, `${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(context, `Ask what task to run with /${enablement.command}.`);
+            await callVisibleChat(engagement, context, `Ask what task to run with /${enablement.command}.`);
             return;
         }
         await submitToActive(engagement, text, context);
@@ -548,10 +1205,16 @@ export function createPlaybookCaptainShell(options, deps = {}) {
             for (const enablement of enablementById.values()) {
                 enablement.entry.validateOptions(enablement.optionInput);
             }
+            internalCaptainEnablement = createInternalCaptainEnablement();
             await setMode('chat', 'init');
         },
         async handleBossTurn(turn, context) {
             requireSession();
+            if (activeTurnHostCalls !== undefined) {
+                throw new Error('cannot handle concurrent Boss turns');
+            }
+            const turnHostCalls = new Set();
+            activeTurnHostCalls = turnHostCalls;
             activeContext = context;
             try {
                 const command = parseRegisteredCommand(turn.prompt);
@@ -562,15 +1225,31 @@ export function createPlaybookCaptainShell(options, deps = {}) {
                         return;
                     }
                 }
-                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() {
+            activeContext = undefined;
+            await disposeStack('dispose');
+        },
         async dispose() {
             activeContext = undefined;
-            await disposeActive('dispose');
+            await disposeStack('dispose');
         },
     };
 }