@sublang/playbook 9.0.0 → 10.0.0

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

@@ -4,8 +4,30 @@ import { randomUUID } from 'node:crypto';
 import { isDeepStrictEqual } from 'node:util';
 import PQueue from 'p-queue';
 import { isAgentCallSettingsError, } from '@sublang/cligent/tmux-play';
-import { assertPlaybookRuntimeSnapshot, hiddenControlEnvelope, registerPlaybookAbortCleanup, snapshotJsonValue, validatePlayerResult, } from '../../../src/xstate-runtime.js';
+import { assertPlaybookRuntimeSnapshot, assertPlaybookEffectLedger, emptyPlaybookEffectLedger, hiddenControlEnvelope, isPlaybookEffectLedgerMonotonicExtension, registerPlaybookAbortCleanup, snapshotJsonValue, validatePlayerResult, } from '../../../src/xstate-runtime.js';
 import createDefaultCaptainRuntime from '../captain.playbook/captain.playbook.js';
+function retainedEffectLedgerCanRebase(checkpoint, current) {
+    if (checkpoint.boundaries.some(({ physicalReceipt }) => physicalReceipt === undefined)) {
+        return false;
+    }
+    if (!isPlaybookEffectLedgerMonotonicExtension(checkpoint, current)) {
+        return false;
+    }
+    if (!isDeepStrictEqual(current.boundaries.slice(0, checkpoint.boundaries.length), checkpoint.boundaries) ||
+        !isDeepStrictEqual(current.logicalOperations, checkpoint.logicalOperations)) {
+        return false;
+    }
+    return current.boundaries
+        .slice(checkpoint.boundaries.length)
+        .every(({ physicalReceipt }) => physicalReceipt?.classification === 'unchanged');
+}
+function createRuntimeForEnablement(enablement, hostCapabilitiesById) {
+    const hostCapabilities = hostCapabilitiesById.get(enablement.entry.id);
+    if (hostCapabilities === undefined) {
+        throw new Error(`/${enablement.command} schema-3 runtime requires current-host construction capabilities`);
+    }
+    return enablement.entry.createRuntime(enablement.options, hostCapabilities);
+}
 class VisibilityControlError extends Error {
     constructor(cause) {
         super(`playbook visibility request failed: ${String(cause?.message ?? cause)}`, { cause });
@@ -39,6 +61,10 @@ 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;
 const PLAYER_ID_PATTERN = /^[a-z][a-z0-9_-]*(?:\.[a-z][a-z0-9_-]*)*$/;
 const ROLE_ID_PATTERN = /^[a-z][a-z0-9_-]*$/;
+const HOST_CAPABILITIES_OPTION_KEY = 'hostCapabilities';
+const UNRESOLVED_EFFECT_RECONCILIATION_ACTION_ID = 'reconcile:unresolved-effect';
+const UNRESOLVED_EFFECT_ABANDONMENT_ACTION_ID = 'abandon:unresolved-effect';
+const RESUMPTION_DUPLICATE_EFFECT_WARNING = 'Warning: resumption may duplicate external effects attempted after the retained boundary; verify the current world before continuing.';
 function parseRegisteredCommand(prompt) {
     const match = /^\/([A-Za-z][A-Za-z0-9_-]*)(?:\s+([\s\S]*))?$/.exec(prompt.trim());
     if (!match)
@@ -405,11 +431,45 @@ function forwardedToolOptions(requested, captainAdapter) {
     return { allowedTools: requested };
 }
 const hiddenJudgeEnvelope = hiddenControlEnvelope;
+function unresolvedEffectReportLines(unresolvedEffects) {
+    return unresolvedEffects.map((effect, index) => {
+        const merelyPossible = effect.classification === 'observation-ambiguous' ||
+            effect.classification === 'incomplete';
+        return [
+            `${index + 1}. ${merelyPossible ? 'Possible repository effect; a change could not be excluded' : 'Observed repository change'} (${effect.classification})`,
+            `baseline HEAD ${effect.baselineHead}`,
+            effect.afterHead === undefined
+                ? 'after HEAD was not available'
+                : `after HEAD ${effect.afterHead}`,
+            ...(effect.commitOid === undefined
+                ? []
+                : [`proven commit OID ${effect.commitOid}`]),
+        ].join('; ') + '.';
+    });
+}
+function unresolvedEffectBossReport(unresolvedEffects) {
+    if (unresolvedEffects.length === 0)
+        return undefined;
+    return [
+        'Repository-effect evidence:',
+        ...unresolvedEffectReportLines(unresolvedEffects).map((line) => `- ${line}`),
+        'This evidence does not establish workflow completion or attribute any repository change or commit to this workflow.',
+    ].join('\n');
+}
+function appendMandatoryPresentationSuffix(turn, suffix) {
+    const current = turn.mandatoryPresentationSuffix;
+    if (current === undefined) {
+        turn.mandatoryPresentationSuffix = suffix;
+    }
+    else if (!current.includes(suffix)) {
+        turn.mandatoryPresentationSuffix = `${current}\n\n${suffix}`;
+    }
+}
 // CAPTAIN-20: the result-phase block the shell supplies inside the closing
 // reply call's envelope — the settlement's outcome-report facts verbatim, the
 // exact counts, and the saved-counts line only when counted activity is
 // nonzero.
-function outcomeReportBlock(report) {
+function outcomeReportBlock(report, unresolvedEffects) {
     const lines = [
         `Settlement status: ${report.status}`,
         ...(report.playbookId === undefined
@@ -433,6 +493,12 @@ function outcomeReportBlock(report) {
     if (report.leafStateSummary !== undefined) {
         lines.push(`Resulting leaf state: ${report.leafStateSummary}`);
     }
+    const effectLines = unresolvedEffectReportLines(unresolvedEffects);
+    if (effectLines.length > 0) {
+        lines.push('Repository-effect evidence (canonical, in ledger order):');
+        lines.push(...effectLines.map((line) => `- ${line}`));
+        lines.push('Report this evidence without claiming workflow completion or attributing any repository change or commit to the workflow.');
+    }
     lines.push(`Progress counts: ${report.progressPhrase}`);
     lines.push(`Counts: ${JSON.stringify({
         ...report.counts,
@@ -467,10 +533,150 @@ function summaryProgressPhrase(stateCounts) {
 function summaryProgressRoundCount(stateCounts) {
     return [...stateCounts.values()].reduce((total, count) => total + count, 0);
 }
-function guardFromJudgeReply(finalText) {
-    return /"guard"\s*:\s*"([^"]+)"/.exec(finalText)?.[1];
+function captureRegistryEntry(value) {
+    if (value === null || typeof value !== 'object')
+        return value;
+    const source = value;
+    return {
+        id: source.id,
+        command: source.command,
+        intent: source.intent,
+        artifactSchema: source.artifactSchema,
+        runtimeProfile: source.runtimeProfile,
+        requiredRoleIds: source.requiredRoleIds,
+        concurrentRoleSets: source.concurrentRoleSets,
+        summaryPolicy: source.summaryPolicy,
+        validateOptions: source.validateOptions,
+        createRuntime: source.createRuntime,
+    };
+}
+function exactOwnDataRecord(value, keys) {
+    if (value === null ||
+        typeof value !== 'object' ||
+        Array.isArray(value) ||
+        (Object.getPrototypeOf(value) !== Object.prototype &&
+            Object.getPrototypeOf(value) !== null)) {
+        return undefined;
+    }
+    const descriptors = Object.getOwnPropertyDescriptors(value);
+    if (Reflect.ownKeys(descriptors).length !== keys.length ||
+        keys.some((key) => !Object.hasOwn(descriptors, key) ||
+            !Object.hasOwn(descriptors[key], 'value') ||
+            descriptors[key].enumerable !== true)) {
+        return undefined;
+    }
+    return Object.fromEntries(keys.map((key) => [key, descriptors[key].value]));
+}
+function captureHostCapabilityRecord(value) {
+    if (value === undefined)
+        return Object.freeze({});
+    const captured = exactOwnDataRecord(value, Object.keys(value));
+    if (captured === undefined) {
+        throw new TypeError('current-host construction capabilities must be an exact data-property record');
+    }
+    return captured;
+}
+function validateHostCapabilities(value, entry, command) {
+    if (value === undefined) {
+        throw new Error(`/${command} schema-3 runtime requires current-host construction capabilities`);
+    }
+    const capability = exactOwnDataRecord(value, [
+        'authority',
+        'repository',
+        'effectLedger',
+    ]);
+    const authority = exactOwnDataRecord(capability?.authority, [
+        'playbookId',
+        'artifactSchema',
+        'cwd',
+        'sessionId',
+        'leaseOwnerToken',
+        'canonicalWorktree',
+        'requiredRoleIds',
+        'concurrentRoleSets',
+    ]);
+    const canonicalWorktree = exactOwnDataRecord(authority?.canonicalWorktree, ['worktree', 'gitDir']);
+    const repository = exactOwnDataRecord(capability?.repository, [
+        'identity',
+        'observe',
+        'acquire',
+        'runExclusive',
+        'runCohort',
+        'runDeferred',
+    ]);
+    const identity = exactOwnDataRecord(repository?.identity, [
+        'worktree',
+        'gitDir',
+    ]);
+    const effectLedger = exactOwnDataRecord(capability?.effectLedger, [
+        'snapshot',
+        'writeAhead',
+    ]);
+    if (authority?.playbookId !== entry.id ||
+        authority.artifactSchema !== 3 ||
+        typeof authority.cwd !== 'string' ||
+        authority.cwd.length === 0 ||
+        typeof authority.sessionId !== 'string' ||
+        authority.sessionId.length === 0 ||
+        typeof authority.leaseOwnerToken !== 'string' ||
+        authority.leaseOwnerToken.length === 0 ||
+        canonicalWorktree === undefined ||
+        typeof canonicalWorktree.worktree !== 'string' ||
+        canonicalWorktree.worktree.length === 0 ||
+        typeof canonicalWorktree.gitDir !== 'string' ||
+        canonicalWorktree.gitDir.length === 0 ||
+        !isDeepStrictEqual(authority.requiredRoleIds, entry.requiredRoleIds) ||
+        !isDeepStrictEqual(authority.concurrentRoleSets, entry.concurrentRoleSets) ||
+        identity === undefined ||
+        !isDeepStrictEqual(identity, canonicalWorktree) ||
+        typeof repository?.observe !== 'function' ||
+        typeof repository.acquire !== 'function' ||
+        typeof repository.runExclusive !== 'function' ||
+        typeof repository.runCohort !== 'function' ||
+        typeof repository.runDeferred !== 'function' ||
+        typeof effectLedger?.snapshot !== 'function' ||
+        typeof effectLedger.writeAhead !== 'function') {
+        throw new Error(`/${command} schema-3 current-host capability authority does not match its imported artifact`);
+    }
+    return value;
+}
+function effectLedgerMirrorFromCapabilities(capabilities) {
+    const values = [...capabilities.values()];
+    if (values.length === 0)
+        return emptyPlaybookEffectLedger();
+    const mirror = assertPlaybookEffectLedger(values[0].effectLedger.snapshot());
+    for (const capability of values.slice(1)) {
+        if (!isDeepStrictEqual(assertPlaybookEffectLedger(capability.effectLedger.snapshot()), mirror)) {
+            throw new Error('schema-3 current-host capabilities disagree on their effect ledger');
+        }
+    }
+    return mirror;
+}
+function validateRuntimeProfile(value) {
+    const shared = exactOwnDataRecord(value, ['kind', 'compat']);
+    if (shared?.kind === 'shared-factory') {
+        const compat = exactOwnDataRecord(shared.compat, [
+            'artifactSchema',
+            'runtimeAbi',
+        ]);
+        if (compat?.artifactSchema === 3 &&
+            typeof compat.runtimeAbi === 'number' &&
+            Number.isSafeInteger(compat.runtimeAbi)) {
+            return {
+                kind: 'shared-factory',
+                artifactSchema: compat.artifactSchema,
+            };
+        }
+        return undefined;
+    }
+    const bespoke = exactOwnDataRecord(value, ['kind', 'artifactSchema']);
+    if (bespoke?.kind === 'bespoke' &&
+        bespoke.artifactSchema === 3) {
+        return { kind: 'bespoke', artifactSchema: bespoke.artifactSchema };
+    }
+    return undefined;
 }
-function isValidRegistryEntry(value) {
+function isValidRegistryEntry(value, artifactSchema) {
     if (typeof value !== 'object' || value === null)
         return false;
     const e = value;
@@ -495,7 +701,7 @@ function isValidRegistryEntry(value) {
     return (typeof e.id === 'string' &&
         typeof e.command === 'string' &&
         typeof e.intent === 'string' &&
-        e.artifactSchema === 2 &&
+        artifactSchema === 3 &&
         typeof e.validateOptions === 'function' &&
         typeof e.createRuntime === 'function');
 }
@@ -503,6 +709,7 @@ const SNAPSHOT_ACTIONS = new Set([
     'respond',
     'start',
     'switch',
+    'resume',
     'dismiss',
     'deliver',
     'runtime',
@@ -519,6 +726,68 @@ const SNAPSHOT_JOURNAL_KINDS = new Set([
     'action',
     'outcome',
 ]);
+const UNRESOLVED_EFFECT_CLASSIFICATIONS = new Set([
+    'one-descendant-commit',
+    'multiple-commits',
+    'rewritten-or-non-descendant',
+    'worktree-only-change',
+    'concurrent-or-foreign-change',
+    'observation-ambiguous',
+    'incomplete',
+]);
+const GIT_OID_PATTERN = /^[0-9a-f]{40}(?:[0-9a-f]{24})?$/;
+export function assertPlaybookCaptainUnresolvedEffects(value) {
+    const detached = snapshotJsonValue(value, 'Captain unresolved effects');
+    if (!Array.isArray(detached)) {
+        throw new TypeError('Captain unresolved effects must be an array');
+    }
+    for (const [index, raw] of detached.entries()) {
+        const path = `Captain unresolved effects[${index}]`;
+        if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+            throw new TypeError(`${path} must be an object`);
+        }
+        const entry = raw;
+        const allowed = new Set([
+            'classification',
+            'baselineHead',
+            'afterHead',
+            'commitOid',
+        ]);
+        const unknown = Object.keys(entry).find((key) => !allowed.has(key));
+        if (unknown !== undefined) {
+            throw new TypeError(`${path} has unknown field ${JSON.stringify(unknown)}`);
+        }
+        if (typeof entry.classification !== 'string' ||
+            !UNRESOLVED_EFFECT_CLASSIFICATIONS.has(entry.classification)) {
+            throw new TypeError(`${path}.classification is not supported`);
+        }
+        if (typeof entry.baselineHead !== 'string' ||
+            !GIT_OID_PATTERN.test(entry.baselineHead)) {
+            throw new TypeError(`${path}.baselineHead must be a Git OID`);
+        }
+        if (entry.afterHead !== undefined &&
+            (typeof entry.afterHead !== 'string' ||
+                !GIT_OID_PATTERN.test(entry.afterHead))) {
+            throw new TypeError(`${path}.afterHead must be a Git OID`);
+        }
+        if (entry.classification !== 'observation-ambiguous' &&
+            entry.classification !== 'incomplete' &&
+            entry.afterHead === undefined) {
+            throw new TypeError(`${path}.afterHead is required for ${entry.classification}`);
+        }
+        if (entry.classification === 'one-descendant-commit') {
+            if (typeof entry.commitOid !== 'string' ||
+                !GIT_OID_PATTERN.test(entry.commitOid) ||
+                entry.commitOid !== entry.afterHead) {
+                throw new TypeError(`${path}.commitOid must equal afterHead for one-descendant-commit`);
+            }
+        }
+        else if (entry.commitOid !== undefined) {
+            throw new TypeError(`${path}.commitOid is permitted only for one-descendant-commit`);
+        }
+    }
+    return detached;
+}
 function snapshotRecord(value, path) {
     if (typeof value !== 'object' || value === null || Array.isArray(value)) {
         throw new TypeError(`${path} must be an object`);
@@ -706,9 +975,16 @@ function normalizeHostPlayerResult(value, expectedPlayerId) {
 export function assertPlaybookCaptainShellSnapshot(value) {
     const detached = snapshotJsonValue(value, 'Captain shell snapshot');
     const snapshot = snapshotRecord(detached, 'Captain shell snapshot');
+    if (snapshot.schemaVersion !== 4) {
+        if (snapshot.schemaVersion === 1) {
+            throw new TypeError('Captain shell snapshot schemaVersion 1 has incompatible player identity; schema 4 is required');
+        }
+        throw new TypeError(`Captain shell snapshot.schemaVersion ${String(snapshot.schemaVersion)} is not supported (expected 4)`);
+    }
     const mode = snapshot.mode;
     const commonKeys = [
         'schemaVersion',
+        'effectLedger',
         'captain',
         'playerSessions',
         'issuedSessionIds',
@@ -725,6 +1001,7 @@ export function assertPlaybookCaptainShellSnapshot(value) {
         rejectSnapshotKeys(snapshot, [
             ...commonKeys,
             'frames',
+            'retainedEffectReconciliation',
             'pendingBossQuestions',
             'lastError',
         ], 'Captain shell snapshot');
@@ -732,13 +1009,28 @@ export function assertPlaybookCaptainShellSnapshot(value) {
     else {
         throw new TypeError('Captain shell snapshot.mode must be "chat" or "engaged.parked"');
     }
-    if (snapshot.schemaVersion !== 3) {
-        throw new TypeError(`Captain shell snapshot.schemaVersion ${String(snapshot.schemaVersion)} is not supported (expected 3)`);
-    }
     const captain = snapshotRecord(snapshot.captain, 'Captain shell snapshot.captain');
     rejectSnapshotKeys(captain, ['sessionId', 'runtime', 'agent', 'conversation'], 'Captain shell snapshot.captain');
     const captainSessionId = snapshotUuid(captain.sessionId, 'Captain shell snapshot.captain.sessionId');
     const captainRuntime = assertPlaybookRuntimeSnapshot(captain.runtime, INTERNAL_CAPTAIN_ID);
+    const effectLedger = assertPlaybookEffectLedger(snapshot.effectLedger);
+    let retainedEffectReconciliation;
+    if (snapshot.retainedEffectReconciliation !== undefined) {
+        const reconciliation = snapshotRecord(snapshot.retainedEffectReconciliation, 'Captain shell snapshot.retainedEffectReconciliation');
+        rejectSnapshotKeys(reconciliation, ['sourceGenerationId', 'checkpoint'], 'Captain shell snapshot.retainedEffectReconciliation');
+        const checkpoint = assertPlaybookEffectLedger(reconciliation.checkpoint, 'Captain shell snapshot retained-effect checkpoint');
+        if (isDeepStrictEqual(checkpoint, effectLedger) ||
+            !isPlaybookEffectLedgerMonotonicExtension(checkpoint, effectLedger)) {
+            throw new TypeError('Captain shell retained-effect checkpoint must be a strict monotonic prefix of its current mirror');
+        }
+        retainedEffectReconciliation = {
+            sourceGenerationId: snapshotUuid(reconciliation.sourceGenerationId, 'Captain shell snapshot.retainedEffectReconciliation.sourceGenerationId'),
+            checkpoint,
+        };
+    }
+    if (!isDeepStrictEqual(captainRuntime.effectLedger, emptyPlaybookEffectLedger())) {
+        throw new TypeError('Captain shell snapshot internal Captain runtime effect ledger must be empty');
+    }
     const captainAgent = snapshotFixedAgent(captain.agent, 'Captain shell snapshot.captain.agent');
     const conversation = snapshotRecord(captain.conversation, 'Captain shell snapshot.captain.conversation');
     let normalizedConversation;
@@ -855,7 +1147,8 @@ export function assertPlaybookCaptainShellSnapshot(value) {
     }
     const playerSessions = snapshotPlayerSessions(snapshot.playerSessions, 'Captain shell snapshot.playerSessions');
     const common = {
-        schemaVersion: 3,
+        schemaVersion: 4,
+        effectLedger,
         captain: {
             sessionId: captainSessionId,
             runtime: captainRuntime,
@@ -941,6 +1234,32 @@ export function assertPlaybookCaptainShellSnapshot(value) {
     const issuedIds = new Set(issued);
     const rootSessionId = normalizedFrames[0].sessionId;
     for (const [index, frame] of normalizedFrames.entries()) {
+        const frameLedger = frame.runtime.effectLedger;
+        if (!isDeepStrictEqual(frameLedger, emptyPlaybookEffectLedger()) &&
+            !isDeepStrictEqual(frameLedger, effectLedger)) {
+            throw new TypeError(`Captain shell snapshot frame ${JSON.stringify(frame.playbookId)} effect ledger is neither empty nor the shell mirror`);
+        }
+        const frameReconciliation = frame.runtime.retainedEffectReconciliation;
+        if (retainedEffectReconciliation === undefined) {
+            if (frameReconciliation !== undefined) {
+                throw new TypeError(`Captain shell snapshot frame ${JSON.stringify(frame.playbookId)} carries an unmirrored retained-effect fence`);
+            }
+        }
+        else if (isDeepStrictEqual(frameLedger, effectLedger)) {
+            if (frameReconciliation === undefined ||
+                !isDeepStrictEqual(frameReconciliation.checkpoint, retainedEffectReconciliation.checkpoint)) {
+                throw new TypeError(`Captain shell snapshot frame ${JSON.stringify(frame.playbookId)} does not mirror the root retained-effect fence`);
+            }
+            if (index === 0 &&
+                frameReconciliation.sourceSessionId !==
+                    retainedEffectReconciliation.sourceGenerationId) {
+                throw new TypeError('Captain shell snapshot retained-effect root source identity differs from its generation');
+            }
+        }
+        else if (frameReconciliation !== undefined ||
+            frame.runtime.retainedEffectSourceSessionId !== undefined) {
+            throw new TypeError(`Captain shell snapshot empty-ledger frame ${JSON.stringify(frame.playbookId)} carries retained-effect adoption state`);
+        }
         if (activePlaybooks.has(frame.playbookId)) {
             throw new TypeError('Captain shell snapshot engagement path must not contain a playbook cycle');
         }
@@ -1003,13 +1322,21 @@ export function assertPlaybookCaptainShellSnapshot(value) {
         !leafRuntime.state.tags.includes('playbook.parked')) {
         throw new TypeError('Captain shell snapshot leaf runtime must be parked without a dangling suspended child call');
     }
-    if (!isDeepStrictEqual(snapshot.pendingBossQuestions ?? [], leafRuntime.pendingBossQuestions)) {
-        throw new TypeError('Captain shell snapshot pending Boss questions must equal the leaf runtime projection');
+    if (retainedEffectReconciliation === undefined) {
+        if (!isDeepStrictEqual(snapshot.pendingBossQuestions ?? [], leafRuntime.pendingBossQuestions)) {
+            throw new TypeError('Captain shell snapshot pending Boss questions must equal the leaf runtime projection');
+        }
+    }
+    else if (snapshot.pendingBossQuestions !== undefined) {
+        throw new TypeError('Captain shell snapshot must withhold pending Boss questions behind retained-effect reconciliation');
     }
     return snapshotJsonValue({
         ...common,
         mode,
         frames: normalizedFrames,
+        ...(retainedEffectReconciliation === undefined
+            ? {}
+            : { retainedEffectReconciliation }),
         ...(snapshot.pendingBossQuestions === undefined
             ? {}
             : { pendingBossQuestions: snapshot.pendingBossQuestions }),
@@ -1088,14 +1415,25 @@ function promptIdentity(binding) {
         ? binding.model.value
         : binding.agent.adapter;
 }
+function rejectConfiguredHostCapabilities(value, path) {
+    if (value !== null &&
+        typeof value === 'object' &&
+        !Array.isArray(value) &&
+        Object.prototype.hasOwnProperty.call(value, HOST_CAPABILITIES_OPTION_KEY)) {
+        throw new Error(`${path}.${HOST_CAPABILITIES_OPTION_KEY} is host-owned and cannot be configured`);
+    }
+}
 // Resolve the active registry at init from exact normalized role and session
 // agent projections (CAPTAIN-16). No role, ancestor, or generated-name fallback
 // exists at this boundary.
-async function buildEnablements(options, loadModule) {
+async function buildEnablements(options, loadModule, hostCapabilities) {
     const entries = [];
     const byCommand = new Map();
     const byId = new Map();
     const enablementById = new Map();
+    const hostCapabilitiesById = new Map();
+    const suppliedHostCapabilities = captureHostCapabilityRecord(hostCapabilities);
+    const expectedHostCapabilityIds = [];
     const detached = snapshotJsonValue(options, 'captain.options');
     const top = snapshotRecord(detached, 'captain.options');
     rejectSnapshotKeys(top, ['playbooks', 'sessionAgents', 'captainAdapter'], 'captain.options');
@@ -1135,6 +1473,7 @@ async function buildEnablements(options, loadModule) {
         }
         const record = block;
         rejectSnapshotKeys(record, ['from', 'command', 'roles', 'options'], `captain.options.playbooks.${id}`);
+        rejectConfiguredHostCapabilities(record.options, `captain.options.playbooks.${id}.options`);
         const from = record.from;
         if (typeof from !== 'string' || from.length === 0) {
             throw new Error(`captain.options.playbooks.${id}.from must be a module specifier`);
@@ -1146,10 +1485,27 @@ async function buildEnablements(options, loadModule) {
         catch (cause) {
             throw new Error(`captain.options.playbooks.${id}.from "${from}" failed to import: ${String(cause?.message ?? cause)}`);
         }
-        const entry = mod?.default;
-        if (!isValidRegistryEntry(entry)) {
+        const capturedEntry = captureRegistryEntry(mod?.default);
+        const artifactSchema = capturedEntry
+            ?.artifactSchema;
+        const runtimeProfile = validateRuntimeProfile(capturedEntry?.runtimeProfile);
+        if (artifactSchema !== 3 ||
+            runtimeProfile === undefined ||
+            !isValidRegistryEntry(capturedEntry, artifactSchema)) {
             throw new Error(`captain.options.playbooks.${id}.from "${from}" exposes no valid registry entry`);
         }
+        const entry = Object.freeze({
+            ...capturedEntry,
+            requiredRoleIds: Object.freeze([...capturedEntry.requiredRoleIds]),
+            concurrentRoleSets: Object.freeze(capturedEntry.concurrentRoleSets.map((roles) => Object.freeze([...roles]))),
+        });
+        if (runtimeProfile.artifactSchema !== artifactSchema) {
+            const implementation = runtimeProfile.kind === 'shared-factory'
+                ? 'shared factory'
+                : 'bespoke runtime';
+            throw new Error(`captain.options.playbooks.${id}.from "${from}" advertises artifact schema ${artifactSchema} ` +
+                `but its ${implementation} implements schema ${runtimeProfile.artifactSchema}`);
+        }
         if (entry.id !== id) {
             throw new Error(`captain.options.playbooks.${id} key must equal the module manifest id "${entry.id}"`);
         }
@@ -1200,16 +1556,26 @@ async function buildEnablements(options, loadModule) {
             }
         }
         const validatedOptions = snapshotJsonValue(entry.validateOptions(record.options), `captain.options.playbooks.${id}.options`);
+        rejectConfiguredHostCapabilities(validatedOptions, `captain.options.playbooks.${id}.options`);
         entries.push(entry);
         byId.set(entry.id, entry);
         byCommand.set(command, entry);
+        const hostCapability = validateHostCapabilities(suppliedHostCapabilities[entry.id], entry, command);
+        expectedHostCapabilityIds.push(entry.id);
+        hostCapabilitiesById.set(entry.id, hostCapability);
         enablementById.set(entry.id, {
             entry,
+            artifactSchema,
             command,
             options: validatedOptions,
             roleBindings,
         });
     }
+    const suppliedHostCapabilityIds = Object.keys(suppliedHostCapabilities).sort();
+    expectedHostCapabilityIds.sort();
+    if (!isDeepStrictEqual(suppliedHostCapabilityIds, expectedHostCapabilityIds)) {
+        throw new Error('current-host construction capabilities must exactly cover schema-3 playbooks');
+    }
     const referenced = new Set([...enablementById.values()].flatMap((enablement) => [...enablement.roleBindings.values()].map((binding) => binding.playerId)));
     const unreferenced = [...playerAgents.keys()].find((id) => !referenced.has(id));
     if (unreferenced !== undefined) {
@@ -1220,6 +1586,7 @@ async function buildEnablements(options, loadModule) {
         byCommand,
         byId,
         enablementById,
+        hostCapabilitiesById,
         captainAgent,
         playerAgents,
     };
@@ -1228,6 +1595,17 @@ export function createPlaybookCaptainShell(options, deps = {}) {
     const loadModule = deps.loadModule ?? ((specifier) => import(specifier));
     const createSessionId = deps.createSessionId ?? randomUUID;
     const createCaptainRuntime = deps.createCaptainRuntime ?? createDefaultCaptainRuntime;
+    const unresolvedEffectSettlement = deps.unresolvedEffectSettlement;
+    let pendingHostCapabilities = deps.hostCapabilities;
+    let currentEffectLedger = () => emptyPlaybookEffectLedger();
+    // The returned shell must not retain the caller's aggregate dependency
+    // object after its one live capability input has moved to a clearable slot.
+    deps = {};
+    const buildCurrentEnablements = async () => {
+        const hostCapabilities = pendingHostCapabilities;
+        pendingHostCapabilities = undefined;
+        return buildEnablements(options, loadModule, hostCapabilities);
+    };
     let captainAgent;
     let captainAdapter;
     let playerAgents = new Map();
@@ -1237,6 +1615,7 @@ export function createPlaybookCaptainShell(options, deps = {}) {
     let byCommand = new Map();
     let byId = new Map();
     let enablementById = new Map();
+    let hostCapabilitiesById = new Map();
     let session;
     let sessionEmissionsOpen = false;
     let closedGateAttempted = false;
@@ -1245,6 +1624,7 @@ export function createPlaybookCaptainShell(options, deps = {}) {
     let activeContext;
     const frames = [];
     let mode = 'chat';
+    let retainedEffectReconciliation;
     let pendingBossQuestions;
     let lastError;
     let activeTurnSummary;
@@ -1314,6 +1694,19 @@ export function createPlaybookCaptainShell(options, deps = {}) {
     let decisionCall;
     let lastAction;
     let lastSettlementStatus;
+    const retainedGenerationCandidates = new Map();
+    const pendingRetentionUpdates = new Map();
+    const retainedGenerations = new Map();
+    const retainedGenerationOffers = new Map();
+    const ineligibleRetainedGenerations = new Set();
+    const retainedGenerationRootClears = new Set();
+    const retiredRetainedRuntimes = [];
+    let retainedGenerationsInstalled = false;
+    let retainedGenerationInstallationInProgress = false;
+    let retainedGenerationInstallationClosed = false;
+    let retentionSettlementReady = false;
+    let abandonmentSettlementUnsafe = false;
+    let settledTurnUnresolvedEffects;
     // DR-029: a run that lands in the runtime's own failure state
     // is an outcome the report must name. `processFrameResult` records it here
     // and the settling selection folds it into its facts, so the grounding the
@@ -1322,6 +1715,568 @@ export function createPlaybookCaptainShell(options, deps = {}) {
     const rootFrame = () => frames[0];
     const leafFrame = () => frames.at(-1);
     const frameLabel = (frame) => `/${frame.enablement.command}`;
+    const capturedUnresolvedEnvelopeReferences = (frame) => {
+        let advertisesUnresolved = false;
+        try {
+            advertisesUnresolved =
+                frame.runtime
+                    .describe?.()
+                    .actions.some(({ id }) => id === UNRESOLVED_EFFECT_RECONCILIATION_ACTION_ID ||
+                    id === UNRESOLVED_EFFECT_ABANDONMENT_ACTION_ID) === true;
+        }
+        catch {
+            advertisesUnresolved = true;
+        }
+        if (typeof frame.runtime.unresolvedEffectEnvelopes !== 'function') {
+            if (advertisesUnresolved) {
+                throw new Error(`${frameLabel(frame)} unresolved-effect runtime exposes no envelope identities`);
+            }
+            return [];
+        }
+        const detached = snapshotJsonValue(frame.runtime.unresolvedEffectEnvelopes(), `${frameLabel(frame)} unresolved effect envelope identities`);
+        if (!Array.isArray(detached)) {
+            throw new TypeError(`${frameLabel(frame)} unresolved effect envelope identities must be an array`);
+        }
+        return detached.map((raw, index) => {
+            const path = `${frameLabel(frame)} unresolved effect envelope identities[${index}]`;
+            const record = snapshotRecord(raw, path);
+            if (record.kind === 'boundary') {
+                rejectSnapshotKeys(record, ['kind', 'boundaryId'], path);
+                return {
+                    kind: 'boundary',
+                    boundaryId: snapshotString(record.boundaryId, `${path}.boundaryId`),
+                };
+            }
+            if (record.kind === 'logical-operation') {
+                rejectSnapshotKeys(record, ['kind', 'operationId'], path);
+                return {
+                    kind: 'logical-operation',
+                    operationId: snapshotString(record.operationId, `${path}.operationId`),
+                };
+            }
+            throw new TypeError(`${path}.kind is not supported`);
+        });
+    };
+    const unresolvedEffectFromReceipt = (receipt, baselineHead = receipt.baseline.head) => {
+        if (receipt.classification === 'unchanged')
+            return undefined;
+        return {
+            classification: receipt.classification,
+            baselineHead,
+            ...(receipt.after === undefined ? {} : { afterHead: receipt.after.head }),
+            ...(receipt.commitOid === undefined ? {} : { commitOid: receipt.commitOid }),
+        };
+    };
+    const cumulativeOpenLogicalEffect = (operation, boundaries) => {
+        const original = operation.originalBaseline;
+        const latest = boundaries.at(-1);
+        const after = latest.after ?? operation.checkpoint;
+        const receipt = latest.physicalReceipt;
+        if (receipt === undefined) {
+            return {
+                classification: 'incomplete',
+                baselineHead: original.head,
+                ...(after === undefined ? {} : { afterHead: after.head }),
+            };
+        }
+        if (after === undefined) {
+            return unresolvedEffectFromReceipt(receipt, original.head);
+        }
+        // An open deferred chain has no authoritative cumulative receipt. Reuse
+        // physical ancestry only while every preceding checkpoint is one of the
+        // same-HEAD dispositions that can lawfully keep a deferred operation
+        // open. Any other history is bounded but not cumulatively attributable.
+        const checkpointChainIsSafe = boundaries
+            .slice(0, -1)
+            .every((boundary) => boundary.after?.head === original.head &&
+            (boundary.physicalReceipt?.classification === 'unchanged' ||
+                boundary.physicalReceipt?.classification ===
+                    'worktree-only-change'));
+        if (!checkpointChainIsSafe || latest.baseline.head !== original.head) {
+            return {
+                classification: 'observation-ambiguous',
+                baselineHead: original.head,
+                afterHead: after.head,
+            };
+        }
+        if (receipt.classification !== 'unchanged' &&
+            receipt.classification !== 'worktree-only-change' &&
+            receipt.classification !== 'one-descendant-commit') {
+            return unresolvedEffectFromReceipt(receipt, original.head);
+        }
+        const sameProjection = isDeepStrictEqual(original.projection, after.projection);
+        if (after.head === original.head) {
+            if (receipt.classification !== 'unchanged' &&
+                receipt.classification !== 'worktree-only-change') {
+                return {
+                    classification: 'observation-ambiguous',
+                    baselineHead: original.head,
+                    afterHead: after.head,
+                };
+            }
+            if (sameProjection)
+                return undefined;
+            const preservesOriginal = Object.entries(original.projection).every(([path, entry]) => Object.hasOwn(after.projection, path) &&
+                isDeepStrictEqual(entry, after.projection[path]));
+            return {
+                classification: preservesOriginal
+                    ? 'worktree-only-change'
+                    : 'observation-ambiguous',
+                baselineHead: original.head,
+                afterHead: after.head,
+            };
+        }
+        if (receipt.classification === 'one-descendant-commit' &&
+            sameProjection) {
+            return {
+                classification: 'one-descendant-commit',
+                baselineHead: original.head,
+                afterHead: after.head,
+                commitOid: after.head,
+            };
+        }
+        return {
+            classification: 'observation-ambiguous',
+            baselineHead: original.head,
+            afterHead: after.head,
+        };
+    };
+    const projectUnresolvedEffects = (ledger, references) => {
+        const pendingReferences = [...references];
+        const projected = [];
+        const seenBoundaries = new Set();
+        const seenOperations = new Set();
+        for (let index = 0; index < pendingReferences.length; index += 1) {
+            const reference = pendingReferences[index];
+            if (reference.kind === 'boundary') {
+                if (seenBoundaries.has(reference.boundaryId))
+                    continue;
+                seenBoundaries.add(reference.boundaryId);
+                const boundary = ledger.boundaries.find(({ boundaryId }) => boundaryId === reference.boundaryId);
+                if (boundary === undefined) {
+                    throw new Error(`unresolved effect boundary ${JSON.stringify(reference.boundaryId)} is absent from the authoritative ledger`);
+                }
+                if (boundary.logicalOperationId !== undefined) {
+                    if (!seenOperations.has(boundary.logicalOperationId)) {
+                        pendingReferences.push({
+                            kind: 'logical-operation',
+                            operationId: boundary.logicalOperationId,
+                        });
+                    }
+                    continue;
+                }
+                const effect = boundary.physicalReceipt === undefined
+                    ? {
+                        classification: 'incomplete',
+                        baselineHead: boundary.baseline.head,
+                        ...(boundary.after === undefined
+                            ? {}
+                            : { afterHead: boundary.after.head }),
+                    }
+                    : unresolvedEffectFromReceipt(boundary.physicalReceipt);
+                if (effect !== undefined) {
+                    projected.push({ order: boundary.sequence, effect });
+                }
+                continue;
+            }
+            if (seenOperations.has(reference.operationId))
+                continue;
+            seenOperations.add(reference.operationId);
+            const operation = ledger.logicalOperations.find(({ operationId }) => operationId === reference.operationId);
+            if (operation === undefined) {
+                throw new Error(`unresolved logical operation ${JSON.stringify(reference.operationId)} is absent from the authoritative ledger`);
+            }
+            const boundaries = operation.boundaryIds.map((boundaryId) => {
+                const boundary = ledger.boundaries.find((candidate) => candidate.boundaryId === boundaryId);
+                if (boundary === undefined) {
+                    throw new Error(`unresolved logical operation ${JSON.stringify(reference.operationId)} names an absent boundary`);
+                }
+                seenBoundaries.add(boundaryId);
+                return boundary;
+            });
+            let effect;
+            if (operation.logicalReceipt !== undefined) {
+                effect = unresolvedEffectFromReceipt(operation.logicalReceipt, operation.originalBaseline.head);
+            }
+            else {
+                effect = cumulativeOpenLogicalEffect(operation, boundaries);
+            }
+            if (effect !== undefined) {
+                projected.push({ order: boundaries[0].sequence, effect });
+            }
+        }
+        return assertPlaybookCaptainUnresolvedEffects(projected
+            .sort((left, right) => left.order - right.order)
+            .map(({ effect }) => effect));
+    };
+    const currentUnresolvedEffects = () => {
+        const ledger = assertPlaybookEffectLedger(currentEffectLedger());
+        const references = [];
+        for (const frame of frames) {
+            references.push(...capturedUnresolvedEnvelopeReferences(frame));
+        }
+        if (retainedEffectReconciliation !== undefined) {
+            for (const boundary of ledger.boundaries.slice(retainedEffectReconciliation.checkpoint.boundaries.length)) {
+                if (boundary.physicalReceipt?.classification === 'unchanged') {
+                    continue;
+                }
+                references.push(boundary.logicalOperationId === undefined
+                    ? { kind: 'boundary', boundaryId: boundary.boundaryId }
+                    : {
+                        kind: 'logical-operation',
+                        operationId: boundary.logicalOperationId,
+                    });
+            }
+        }
+        return projectUnresolvedEffects(ledger, references);
+    };
+    const freezeTurnUnresolvedEffects = () => {
+        const turn = activeTurn;
+        if (turn?.unresolvedEffects !== undefined)
+            return turn.unresolvedEffects;
+        const frozen = currentUnresolvedEffects();
+        if (turn !== undefined)
+            turn.unresolvedEffects = frozen;
+        settledTurnUnresolvedEffects = frozen;
+        return frozen;
+    };
+    const normalizeInstalledRetainedGenerations = (value) => {
+        const path = 'Captain retained generations';
+        const detached = snapshotJsonValue(value, path);
+        const record = snapshotRecord(detached, path);
+        const authoritativeEffectLedger = assertPlaybookEffectLedger(currentEffectLedger(), `${path} current host effect ledger`);
+        const sourceSessionIds = new Set();
+        const normalized = new Map();
+        for (const [rootPlaybookId, rawGeneration] of Object.entries(record)) {
+            const generationPath = `${path}[${JSON.stringify(rootPlaybookId)}]`;
+            const enablement = enablementById.get(rootPlaybookId);
+            if (enablement === undefined) {
+                throw new TypeError(`${generationPath} names a disabled root playbook`);
+            }
+            const generation = snapshotRecord(rawGeneration, generationPath);
+            rejectSnapshotKeys(generation, [
+                'effectLedger',
+                'frames',
+                'retainedEffectReconciliation',
+                'rootStateDescription',
+            ], generationPath);
+            const generationEffectLedger = assertPlaybookEffectLedger(generation.effectLedger, `${generationPath}.effectLedger`);
+            if (generationEffectLedger.boundaries.some(({ physicalReceipt }) => physicalReceipt === undefined)) {
+                throw new TypeError(`${generationPath}.effectLedger contains an incomplete physical boundary`);
+            }
+            if (!isPlaybookEffectLedgerMonotonicExtension(generationEffectLedger, authoritativeEffectLedger)) {
+                throw new TypeError(`${generationPath}.effectLedger is not a monotonic prefix of the current host mirror`);
+            }
+            const generationReconciliation = generation.retainedEffectReconciliation === undefined
+                ? undefined
+                : snapshotRecord(generation.retainedEffectReconciliation, `${generationPath}.retainedEffectReconciliation`);
+            if (generationReconciliation !== undefined) {
+                rejectSnapshotKeys(generationReconciliation, ['sourceGenerationId'], `${generationPath}.retainedEffectReconciliation`);
+            }
+            const sourceGenerationId = generationReconciliation === undefined
+                ? undefined
+                : snapshotUuid(generationReconciliation.sourceGenerationId, `${generationPath}.retainedEffectReconciliation.sourceGenerationId`);
+            if (!Array.isArray(generation.frames) || generation.frames.length === 0) {
+                throw new TypeError(`${generationPath}.frames must be non-empty`);
+            }
+            const rootStateDescription = generation.rootStateDescription === undefined
+                ? undefined
+                : snapshotString(generation.rootStateDescription, `${generationPath}.rootStateDescription`);
+            const normalizedFrames = [];
+            const playbookIds = new Set();
+            let markedCaptureEffectLedger;
+            for (const [index, rawFrame] of generation.frames.entries()) {
+                const framePath = `${generationPath}.frames[${index}]`;
+                const frame = snapshotRecord(rawFrame, framePath);
+                rejectSnapshotKeys(frame, [
+                    'playbookId',
+                    'sessionId',
+                    'rootSessionId',
+                    'depth',
+                    'parentSessionId',
+                    'parentCallId',
+                    'options',
+                    'roleBindings',
+                    'runtime',
+                ], framePath);
+                const playbookId = snapshotString(frame.playbookId, `${framePath}.playbookId`);
+                const frameEnablement = enablementById.get(playbookId);
+                if (frameEnablement === undefined) {
+                    throw new TypeError(`${framePath} names a disabled playbook`);
+                }
+                if (playbookIds.has(playbookId)) {
+                    throw new TypeError(`${generationPath}.frames must not contain a playbook cycle`);
+                }
+                playbookIds.add(playbookId);
+                const sessionId = snapshotUuid(frame.sessionId, `${framePath}.sessionId`);
+                if (sourceSessionIds.has(sessionId)) {
+                    throw new TypeError(`${path} frame session ids must be unique across generations`);
+                }
+                sourceSessionIds.add(sessionId);
+                const rootSessionId = snapshotUuid(frame.rootSessionId, `${framePath}.rootSessionId`);
+                const depth = snapshotInteger(frame.depth, `${framePath}.depth`);
+                const parentSessionId = frame.parentSessionId === undefined
+                    ? undefined
+                    : snapshotUuid(frame.parentSessionId, `${framePath}.parentSessionId`);
+                const parentCallId = frame.parentCallId === undefined
+                    ? undefined
+                    : snapshotString(frame.parentCallId, `${framePath}.parentCallId`);
+                const options = frame.options;
+                if (index === 0 &&
+                    !isDeepStrictEqual(options, frameEnablement.options)) {
+                    throw new TypeError(`${framePath}.options changed`);
+                }
+                const roleBindings = snapshotFrameRoleBindings(frame.roleBindings, `${framePath}.roleBindings`);
+                if (!isDeepStrictEqual(Object.keys(roleBindings).sort(), [...frameEnablement.entry.requiredRoleIds].sort())) {
+                    throw new TypeError(`${framePath}.roleBindings do not cover the current role set`);
+                }
+                const runtime = assertPlaybookRuntimeSnapshot(frame.runtime, playbookId, { allowSuspendedCall: true });
+                const retainedReconciliation = runtime.retainedEffectReconciliation;
+                if (retainedReconciliation === undefined) {
+                    if (!isDeepStrictEqual(runtime.effectLedger, generationEffectLedger)) {
+                        throw new TypeError(`${framePath}.runtime effect ledger differs from the retained checkpoint`);
+                    }
+                }
+                else {
+                    if (!isDeepStrictEqual(retainedReconciliation.checkpoint, generationEffectLedger) ||
+                        isDeepStrictEqual(runtime.effectLedger, generationEffectLedger) ||
+                        !isPlaybookEffectLedgerMonotonicExtension(runtime.effectLedger, authoritativeEffectLedger)) {
+                        throw new TypeError(`${framePath}.runtime retained-effect evidence is inconsistent`);
+                    }
+                    if (markedCaptureEffectLedger === undefined) {
+                        markedCaptureEffectLedger = runtime.effectLedger;
+                    }
+                    else if (!isDeepStrictEqual(runtime.effectLedger, markedCaptureEffectLedger)) {
+                        throw new TypeError(`${framePath}.runtime effect ledger differs from the marked generation capture mirror`);
+                    }
+                }
+                if (runtime.state.status !== 'active' ||
+                    !runtime.state.quiescent ||
+                    typeof runtime.state.stateId !== 'string' ||
+                    runtime.state.stateId.trim().length === 0) {
+                    throw new TypeError(`${framePath}.runtime must be active, quiescent, and state-identified`);
+                }
+                for (const question of runtime.pendingBossQuestions) {
+                    if (question.asker.kind === 'role' &&
+                        roleBindings[question.asker.roleId] === undefined) {
+                        throw new TypeError(`${framePath}.runtime pending question names an unbound role`);
+                    }
+                }
+                for (const roleId of Object.keys(runtime.roleResumeTokens)) {
+                    if (roleBindings[roleId] === undefined) {
+                        throw new TypeError(`${framePath}.runtime role-resume token names an unbound role`);
+                    }
+                }
+                normalizedFrames.push({
+                    playbookId,
+                    sessionId,
+                    rootSessionId,
+                    depth,
+                    ...(parentSessionId === undefined ? {} : { parentSessionId }),
+                    ...(parentCallId === undefined ? {} : { parentCallId }),
+                    options,
+                    roleBindings,
+                    runtime,
+                });
+            }
+            const sourceRootSessionId = normalizedFrames[0].sessionId;
+            for (const [index, frame] of normalizedFrames.entries()) {
+                if (frame.depth !== index || frame.rootSessionId !== sourceRootSessionId) {
+                    throw new TypeError(`${generationPath}.frames have inconsistent depth or root identity`);
+                }
+                if (index === 0) {
+                    if (frame.playbookId !== rootPlaybookId ||
+                        frame.sessionId !== frame.rootSessionId ||
+                        frame.parentSessionId !== undefined ||
+                        frame.parentCallId !== undefined) {
+                        throw new TypeError(`${generationPath}.frames[0] is not the named root`);
+                    }
+                    continue;
+                }
+                const parent = normalizedFrames[index - 1];
+                const suspended = parent.runtime.suspendedCall;
+                if (frame.parentSessionId !== parent.sessionId ||
+                    frame.parentCallId === undefined ||
+                    suspended === undefined ||
+                    suspended.callId !== frame.parentCallId ||
+                    suspended.playbookId !== frame.playbookId ||
+                    suspended.childSessionId !== frame.sessionId) {
+                    throw new TypeError(`${generationPath}.frames[${index}] does not match its suspended parent edge`);
+                }
+            }
+            const leaf = normalizedFrames.at(-1);
+            if (leaf.runtime.suspendedCall !== undefined ||
+                !leaf.runtime.state.tags.includes('playbook.parked')) {
+                throw new TypeError(`${generationPath} leaf must be parked without a suspended child`);
+            }
+            const markedFrames = normalizedFrames.filter(({ runtime }) => runtime.retainedEffectReconciliation !== undefined);
+            if ((sourceGenerationId === undefined && markedFrames.length !== 0) ||
+                (sourceGenerationId !== undefined &&
+                    markedFrames.length !== normalizedFrames.length) ||
+                (sourceGenerationId !== undefined &&
+                    normalizedFrames[0].runtime.retainedEffectReconciliation
+                        ?.sourceSessionId !== sourceGenerationId)) {
+                throw new TypeError(`${generationPath} retained-effect source marker is inconsistent`);
+            }
+            normalized.set(rootPlaybookId, snapshotJsonValue({
+                effectLedger: generationEffectLedger,
+                frames: normalizedFrames,
+                ...(sourceGenerationId === undefined
+                    ? {}
+                    : {
+                        retainedEffectReconciliation: { sourceGenerationId },
+                    }),
+                ...(rootStateDescription === undefined
+                    ? {}
+                    : { rootStateDescription }),
+            }, generationPath));
+        }
+        return normalized;
+    };
+    const runtimeRetainsGenerations = (runtime) => {
+        const metadata = runtime.retainedGenerationMetadata;
+        return (typeof runtime.exportSnapshot === 'function' &&
+            typeof runtime.restore === 'function' &&
+            typeof runtime.adopt === 'function' &&
+            metadata !== undefined &&
+            Array.isArray(metadata.unfinishedFinalStateIds) &&
+            metadata.unfinishedFinalStateIds.every((stateId) => typeof stateId === 'string'));
+    };
+    class RetainedRuntimeCleanupError extends AggregateError {
+        failedRuntimes;
+        constructor(failures, message, failedRuntimes = []) {
+            super(failures, message);
+            this.name = 'RetainedRuntimeCleanupError';
+            this.failedRuntimes = failedRuntimes;
+        }
+    }
+    const disposeRetainedRuntimeSet = async (runtimes, message) => {
+        const failures = [];
+        const failedRuntimes = [];
+        for (const runtime of [...runtimes].reverse()) {
+            try {
+                await runtime.dispose();
+            }
+            catch (error) {
+                failures.push(error);
+                failedRuntimes.unshift(runtime);
+            }
+        }
+        if (failures.length > 0) {
+            throw new RetainedRuntimeCleanupError(failures, message, failedRuntimes);
+        }
+    };
+    const retireRetainedOffer = (rootPlaybookId) => {
+        const offer = retainedGenerationOffers.get(rootPlaybookId);
+        if (offer === undefined)
+            return;
+        retainedGenerationOffers.delete(rootPlaybookId);
+        retiredRetainedRuntimes.push(...offer.runtimes);
+    };
+    const applyRetentionUpdateToCatalog = (update) => {
+        if (update.kind === 'clear') {
+            retireRetainedOffer(update.rootPlaybookId);
+            retainedGenerations.delete(update.rootPlaybookId);
+            ineligibleRetainedGenerations.delete(update.rootPlaybookId);
+            retainedGenerationRootClears.delete(update.rootPlaybookId);
+            return;
+        }
+        const prior = retainedGenerations.get(update.rootPlaybookId);
+        if (isDeepStrictEqual(prior, update.generation))
+            return;
+        retireRetainedOffer(update.rootPlaybookId);
+        retainedGenerations.set(update.rootPlaybookId, update.generation);
+        ineligibleRetainedGenerations.delete(update.rootPlaybookId);
+        retainedGenerationRootClears.delete(update.rootPlaybookId);
+    };
+    const drainRetiredRetainedRuntimes = async () => {
+        if (retiredRetainedRuntimes.length === 0)
+            return;
+        const runtimes = retiredRetainedRuntimes.splice(0);
+        try {
+            await disposeRetainedRuntimeSet(runtimes, 'retired retained-generation runtime cleanup failed');
+        }
+        catch (error) {
+            if (error instanceof RetainedRuntimeCleanupError) {
+                retiredRetainedRuntimes.unshift(...error.failedRuntimes);
+            }
+            terminallyDisposed = true;
+            lifecycle = 'closed';
+            throw error;
+        }
+    };
+    const takeRetainedOfferRuntimes = () => {
+        const runtimes = [
+            ...[...retainedGenerationOffers.values()].flatMap((offer) => [
+                ...offer.runtimes,
+            ]),
+            ...retiredRetainedRuntimes.splice(0),
+        ];
+        retainedGenerationOffers.clear();
+        return runtimes;
+    };
+    const prepareRetainedGenerationOffers = async () => {
+        if (rootFrame() !== undefined)
+            return;
+        for (const [rootPlaybookId, generation] of [...retainedGenerations].sort(([left], [right]) => left.localeCompare(right))) {
+            if (retainedGenerationOffers.has(rootPlaybookId) ||
+                ineligibleRetainedGenerations.has(rootPlaybookId)) {
+                continue;
+            }
+            const runtimes = [];
+            try {
+                for (const sourceFrame of generation.frames) {
+                    const enablement = enablementById.get(sourceFrame.playbookId);
+                    runtimes.push(createRuntimeForEnablement(enablement, hostCapabilitiesById));
+                }
+                if (runtimes.some((runtime) => !runtimeRetainsGenerations(runtime))) {
+                    const rootRetainsGenerations = runtimeRetainsGenerations(runtimes[0]);
+                    await disposeRetainedRuntimeSet(runtimes, `/${enablementById.get(rootPlaybookId).command} retained-generation capability cleanup failed`);
+                    runtimes.splice(0);
+                    ineligibleRetainedGenerations.add(rootPlaybookId);
+                    if (!rootRetainsGenerations) {
+                        retainedGenerationRootClears.add(rootPlaybookId);
+                    }
+                    continue;
+                }
+                retainedGenerationOffers.set(rootPlaybookId, {
+                    generation,
+                    requiresEffectReconciliation: generation.retainedEffectReconciliation !== undefined ||
+                        generation.frames.some(({ runtime }) => runtime.retainedEffectReconciliation !== undefined) ||
+                        !retainedEffectLedgerCanRebase(generation.effectLedger, assertPlaybookEffectLedger(currentEffectLedger())),
+                    runtimes,
+                });
+            }
+            catch (error) {
+                if (error instanceof RetainedRuntimeCleanupError) {
+                    retiredRetainedRuntimes.push(...error.failedRuntimes);
+                    terminallyDisposed = true;
+                    lifecycle = 'closed';
+                    throw error;
+                }
+                let cleanupError;
+                if (runtimes.length > 0) {
+                    try {
+                        await disposeRetainedRuntimeSet(runtimes, 'retained-generation preparation cleanup failed');
+                    }
+                    catch (caught) {
+                        cleanupError = caught;
+                    }
+                }
+                if (cleanupError !== undefined) {
+                    if (cleanupError instanceof RetainedRuntimeCleanupError) {
+                        retiredRetainedRuntimes.push(...cleanupError.failedRuntimes);
+                    }
+                    terminallyDisposed = true;
+                    lifecycle = 'closed';
+                    throw new RetainedRuntimeCleanupError([error, cleanupError], 'retained-generation preparation and cleanup failed', cleanupError instanceof RetainedRuntimeCleanupError
+                        ? cleanupError.failedRuntimes
+                        : []);
+                }
+                ineligibleRetainedGenerations.add(rootPlaybookId);
+            }
+        }
+    };
     const bindingFor = (frame, localRole) => {
         const binding = frame.playerBindings.get(localRole);
         if (!binding) {
@@ -1364,7 +2319,10 @@ export function createPlaybookCaptainShell(options, deps = {}) {
         ...(leafFrame()?.state
             ? { latestSubRuntimeState: leafFrame().state }
             : {}),
-        ...(pendingBossQuestions !== undefined ? { pendingBossQuestions } : {}),
+        ...(retainedEffectReconciliation === undefined &&
+            pendingBossQuestions !== undefined
+            ? { pendingBossQuestions }
+            : {}),
         ...(lastError ? { lastError } : {}),
         ...(captainSessionId ? { captainSessionId } : {}),
         // Presence only: the pinned token value never reaches telemetry
@@ -1526,6 +2484,59 @@ export function createPlaybookCaptainShell(options, deps = {}) {
             }
         }
     };
+    const observeSummaryTrace = (frame, payload) => {
+        const trace = payloadRecord(payload);
+        const turn = activeTurn;
+        const summary = activeTurnSummary;
+        const expectedParentSessionId = frame.parent?.frame.sessionId;
+        const expectedParentCallId = frame.parent?.callId;
+        if (trace?.schemaVersion !== 4 ||
+            trace.sessionId !== frame.sessionId ||
+            trace.playbookId !== frame.entry.id ||
+            trace.rootSessionId !== frame.rootSessionId ||
+            (expectedParentSessionId === undefined
+                ? Object.hasOwn(trace, 'parentSessionId')
+                : !Object.hasOwn(trace, 'parentSessionId') ||
+                    trace.parentSessionId !== expectedParentSessionId) ||
+            (expectedParentCallId === undefined
+                ? Object.hasOwn(trace, 'parentCallId')
+                : !Object.hasOwn(trace, 'parentCallId') ||
+                    trace.parentCallId !== expectedParentCallId) ||
+            trace.depth !== frame.depth ||
+            turn === undefined ||
+            !Number.isSafeInteger(trace.turnId) ||
+            trace.turnId <= 0 ||
+            !Number.isSafeInteger(trace.sequence) ||
+            trace.sequence <= 0 ||
+            summary === undefined ||
+            !summaryIncludes(frame)) {
+            return;
+        }
+        if (trace.type !== 'outcome.accepted')
+            return;
+        const receipt = exactOwnDataRecord(trace.payload, [
+            'source',
+            'target',
+            'acceptedOutcome',
+        ]);
+        if (receipt === undefined ||
+            typeof receipt.source !== 'string' ||
+            receipt.source.trim().length === 0 ||
+            typeof receipt.target !== 'string' ||
+            receipt.target.trim().length === 0 ||
+            typeof receipt.acceptedOutcome !== 'string' ||
+            receipt.acceptedOutcome.trim().length === 0) {
+            return;
+        }
+        const traceKey = `${frame.sessionId}:${trace.sequence}`;
+        if (summary.acceptedOutcomeTraceKeys.has(traceKey))
+            return;
+        summary.acceptedOutcomeTraceKeys.add(traceKey);
+        summary.counts.interruptions++;
+        if (frame.entry.summaryPolicy?.copyPasteGuardNames.includes(receipt.acceptedOutcome)) {
+            summary.counts.copyPastes++;
+        }
+    };
     let callNestedPlaybook;
     const createPorts = (frame) => ({
         callPlayer: async (roleId, prompt, signal, options) => {
@@ -1687,14 +2698,6 @@ export function createPlaybookCaptainShell(options, deps = {}) {
             if (result.finalText === undefined) {
                 throw new Error('callCaptain returned status=ok with no finalText');
             }
-            const guard = guardFromJudgeReply(result.finalText);
-            const summary = activeTurnSummary;
-            if (guard &&
-                summary &&
-                summaryIncludes(frame) &&
-                frame.entry.summaryPolicy?.copyPasteGuardNames.includes(guard)) {
-                summary.counts.copyPastes++;
-            }
             return result.finalText;
         },
         callPlaybook: (request, signal) => {
@@ -1727,6 +2730,9 @@ export function createPlaybookCaptainShell(options, deps = {}) {
                     await mirrorSubRuntimeTelemetry(frame, event.payload);
                 }
                 await requireSession().emitTelemetry(event);
+                if (event.topic === 'playbook.trace') {
+                    observeSummaryTrace(frame, event.payload);
+                }
             })();
             return trackHostCall(frame, emission);
         },
@@ -1748,17 +2754,42 @@ export function createPlaybookCaptainShell(options, deps = {}) {
             throw new VisibilityControlError(error);
         }
     };
-    const allocateSessionId = () => {
+    const generatedSessionId = () => {
         const sessionId = createSessionId();
         if (!UUID_PATTERN.test(sessionId)) {
             throw new Error(`playbook session id generator returned a non-UUID value: ${JSON.stringify(sessionId)}`);
         }
+        return sessionId;
+    };
+    const allocateSessionId = () => {
+        const sessionId = generatedSessionId();
         if (issuedSessionIds.has(sessionId)) {
             throw new Error(`playbook session id collision: ${sessionId}`);
         }
         issuedSessionIds.add(sessionId);
         return sessionId;
     };
+    const allocateAdoptionSessionIds = (count, sourceSessionIds) => {
+        const candidates = [];
+        const rejectedSourceIds = new Set();
+        while (candidates.length < count) {
+            const candidate = generatedSessionId();
+            if (sourceSessionIds.has(candidate)) {
+                if (rejectedSourceIds.has(candidate)) {
+                    throw new Error(`playbook source session id collision: ${candidate}`);
+                }
+                rejectedSourceIds.add(candidate);
+                continue;
+            }
+            if (issuedSessionIds.has(candidate) || candidates.includes(candidate)) {
+                throw new Error(`playbook session id collision: ${candidate}`);
+            }
+            candidates.push(candidate);
+        }
+        for (const candidate of candidates)
+            issuedSessionIds.add(candidate);
+        return candidates;
+    };
     const normalizeErrorFull = (value) => {
         const compact = normalizeErrorCompact(value) ?? {
             name: 'Error',
@@ -1778,7 +2809,7 @@ export function createPlaybookCaptainShell(options, deps = {}) {
         const entry = enablement.entry;
         const sessionId = allocateSessionId();
         const playerBindings = makePlayerBindings(enablement);
-        const runtime = entry.createRuntime(enablement.options);
+        const runtime = createRuntimeForEnablement(enablement, hostCapabilitiesById);
         return {
             entry,
             enablement,
@@ -1794,7 +2825,7 @@ export function createPlaybookCaptainShell(options, deps = {}) {
     const makeRestoredFrame = (enablement, snapshot, parent) => {
         const entry = enablement.entry;
         const playerBindings = makePlayerBindings(enablement);
-        const runtime = entry.createRuntime(enablement.options);
+        const runtime = createRuntimeForEnablement(enablement, hostCapabilitiesById);
         return {
             entry,
             enablement,
@@ -1844,14 +2875,6 @@ export function createPlaybookCaptainShell(options, deps = {}) {
                     delete ledger.resumeToken;
                 else
                     ledger.resumeToken = resumeToken;
-                // CAPTAIN-20: a result counts only after the runtime validated it and
-                // atomically published its authorized continuation transition.
-                const summary = activeTurnSummary;
-                if (pending.status === 'ok' &&
-                    summary &&
-                    summaryIncludes(frame)) {
-                    summary.counts.interruptions++;
-                }
             }
             finally {
                 playerTransactions.delete(binding.playerId);
@@ -2101,6 +3124,8 @@ export function createPlaybookCaptainShell(options, deps = {}) {
             }
         }
         clearLeafLedger();
+        if (frames.length === 0)
+            retainedEffectReconciliation = undefined;
         if (failures.length === 1)
             throw failures[0];
         if (failures.length > 1) {
@@ -2205,7 +3230,46 @@ export function createPlaybookCaptainShell(options, deps = {}) {
             throw new AggregateError(failures, 'playbook stack disposal failed');
         }
     };
+    /**
+     * DR-040 task 11: abandonment is a host settlement, not an authored FSM
+     * result.  Freeze the bounded evidence while the complete stack and its
+     * runtime-owned envelope identities still exist, durably fence recovery,
+     * dispose leaf-to-root without resuming a parent, then publish the matching
+     * root clear and evidence as one durable completion before the controller
+     * may return an executed receipt to its result phase.
+     */
+    const settleUnresolvedEffectAbandonment = async (unresolvedLeaf) => {
+        if (leafFrame() !== unresolvedLeaf) {
+            throw new Error('unresolved-effect abandonment requires the active leaf');
+        }
+        const root = rootFrame();
+        if (root === undefined) {
+            throw new Error('unresolved-effect abandonment requires an active root');
+        }
+        const unresolvedEffects = freezeTurnUnresolvedEffects();
+        if (unresolvedEffects.length === 0) {
+            throw new Error('unresolved-effect abandonment requires nonempty effect evidence');
+        }
+        if (unresolvedEffectSettlement === undefined) {
+            throw new Error('unresolved-effect abandonment requires durable host settlement');
+        }
+        const rootPlaybookId = root.entry.id;
+        const settlement = Object.freeze({
+            rootPlaybookId,
+            unresolvedEffects,
+        });
+        await runEffect(() => unresolvedEffectSettlement.begin(settlement));
+        await runEffect(() => disposeStack('unresolved-effect'));
+        pendingRetentionUpdates.set(rootPlaybookId, {
+            kind: 'clear',
+            rootPlaybookId,
+        });
+        await runEffect(() => unresolvedEffectSettlement.complete(settlement));
+    };
     const callResultFor = (frame, result) => {
+        if (result.outcome === 'unresolved-effect') {
+            throw new Error(`playbook ${frame.entry.id} unresolved-effect result cannot resume a parent`);
+        }
         if (result.outcome === 'terminal') {
             return {
                 status: 'ok',
@@ -2240,6 +3304,9 @@ export function createPlaybookCaptainShell(options, deps = {}) {
         if (leafFrame() !== frame) {
             throw new Error('only the active leaf may receive Boss input');
         }
+        if (retainedEffectReconciliation !== undefined) {
+            throw new Error('retained repository-effect reconciliation is required before Boss input');
+        }
         // CAPTAIN-35: the leaf check, the visibility request, and the mode change
         // are shell control work performed on the way to the runtime, not the
         // effect. Only the call below is the effect, so only it is inside the
@@ -2257,6 +3324,9 @@ export function createPlaybookCaptainShell(options, deps = {}) {
         if (!parentLink)
             throw new Error('root playbook has no caller');
         const parent = parentLink.frame;
+        if (retainedEffectReconciliation !== undefined) {
+            throw new Error('retained repository-effect reconciliation is required before parent resumption');
+        }
         const invocationSignal = child.invocationSignal;
         let effectiveResult = callResult;
         let ownsReturn = false;
@@ -2325,6 +3395,16 @@ export function createPlaybookCaptainShell(options, deps = {}) {
         }, context);
     }
     async function processFrameResult(frame, result, context) {
+        if (result.outcome === 'unresolved-effect') {
+            // Task 10 exposes the runtime-owned abandonment signal without
+            // translating it into a nested result or claiming workflow completion.
+            // Task 11 owns the durable host settlement and complete-stack disposal.
+            assertRetainableResult(frame, result);
+            if (leafFrame() === frame) {
+                await setMode('engaged.parked', 'turn:unresolved-effect');
+            }
+            return;
+        }
         if (result.outcome === 'terminal') {
             if (frame.parent) {
                 await resumeParent(frame, callResultFor(frame, result), context);
@@ -2336,6 +3416,7 @@ export function createPlaybookCaptainShell(options, deps = {}) {
                 // output remains runtime-to-runtime data and never becomes Captain
                 // evidence (CAPPLAY-10).
                 activeTurn?.settlementFacts.push(rootCompletionFact(frame, result));
+                recordTerminalRetention(frame, result);
                 await runEffect(() => disposeStack('final'));
             }
             return;
@@ -2515,7 +3596,14 @@ export function createPlaybookCaptainShell(options, deps = {}) {
         const policy = frame.entry.summaryPolicy;
         const counts = { interruptions: 0, copyPastes: 0 };
         const stateCounts = new Map();
-        activeTurnSummary = policy ? { owner: frame, counts, stateCounts } : undefined;
+        activeTurnSummary = policy
+            ? {
+                owner: frame,
+                counts,
+                stateCounts,
+                acceptedOutcomeTraceKeys: new Set(),
+            }
+            : undefined;
         let result;
         let error;
         try {
@@ -2580,12 +3668,58 @@ export function createPlaybookCaptainShell(options, deps = {}) {
             ...entries.map(([key, value]) => digestLine `- ${key}: ${JSON.stringify(value)}`),
         ];
     };
+    const retainedResumptionDigest = () => {
+        if (rootFrame() !== undefined) {
+            return 'Retained resumptions: unavailable while a playbook is engaged.';
+        }
+        const offers = [...retainedGenerationOffers].sort(([left], [right]) => left.localeCompare(right));
+        if (offers.length === 0)
+            return 'Retained resumptions: none.';
+        const lines = ['Retained resumptions:'];
+        for (const [rootPlaybookId, offer] of offers) {
+            const enablement = enablementById.get(rootPlaybookId);
+            lines.push(digestLine `- ${rootPlaybookId} (/${enablement.command}): ${offer.generation.rootStateDescription ??
+                '(no published root-state description was retained)'}`);
+        }
+        return lines.join('\n');
+    };
     const controlViewDigest = () => {
         const leaf = leafFrame();
         const lines = [digestLine `Active path: ${activePathDigest()}`];
         if (!leaf) {
             lines.push('The shell is idle: no leaf state, no pending question.');
             lines.push('Advertised actions: none.');
+            lines.push(retainedResumptionDigest());
+            return lines.join('\n');
+        }
+        refreshRetainedEffectFence();
+        if (retainedEffectReconciliation !== undefined) {
+            let reconciliationActions = [];
+            if (typeof leaf.runtime.describe === 'function' &&
+                typeof leaf.runtime.apply === 'function') {
+                try {
+                    reconciliationActions = leaf.runtime
+                        .describe()
+                        .actions.filter(({ id }) => id === UNRESOLVED_EFFECT_RECONCILIATION_ACTION_ID ||
+                        id === UNRESOLVED_EFFECT_ABANDONMENT_ACTION_ID);
+                }
+                catch {
+                    // An unreadable control surface cannot open a fail-closed fence.
+                }
+            }
+            for (const action of reconciliationActions) {
+                recordSuppliedIdentifier(action.id);
+            }
+            lines.push(`Leaf ${frameLabel(leaf)} is parked for repository-effect reconciliation.`);
+            lines.push('Pending Boss questions: withheld until reconciliation.');
+            lines.push(reconciliationActions.length === 0
+                ? 'Advertised actions: none.'
+                : [
+                    'Advertised actions:',
+                    ...reconciliationActions.map((action) => digestLine `- ${action.id}: ${action.label}`),
+                ].join('\n'));
+            lines.push('Ordinary delivery, switching, dismissal, and runtime actions are unavailable while retained effect evidence is unresolved. Only the advertised unresolved-effect controls may run. Conversation is unaffected: `respond` stays valid for any turn.');
+            lines.push(retainedResumptionDigest());
             return lines.join('\n');
         }
         let view;
@@ -2634,6 +3768,7 @@ export function createPlaybookCaptainShell(options, deps = {}) {
             lines.push(describeFailure === undefined
                 ? 'This leaf advertises no runtime action, so plain text delivery is the only machine verb against it and a `runtime` selection is invalid. Conversation is unaffected: `respond` stays valid for any turn.'
                 : 'No runtime action can be validated while the control view is unreadable, so plain text delivery is the only machine verb against it this turn and a `runtime` selection is invalid. Conversation is unaffected: `respond` stays valid for any turn.');
+            lines.push(retainedResumptionDigest());
             return lines.join('\n');
         }
         // CAPTAIN-9: the guarded set is what the digest supplies *for selection* —
@@ -2672,6 +3807,7 @@ export function createPlaybookCaptainShell(options, deps = {}) {
                 'Advertised actions:',
                 ...view.actions.map((action) => digestLine `- ${action.id}: ${action.label}`),
             ].join('\n'));
+        lines.push(retainedResumptionDigest());
         return lines.join('\n');
     };
     // The catalog is registry-authored, not shell-authored: an id, a command,
@@ -2747,9 +3883,13 @@ export function createPlaybookCaptainShell(options, deps = {}) {
         // all of this prose. Preserve the exact attempt before crossing the
         // boundary; the uncertainty record below keeps recovery from pretending
         // delivery was confirmed while still understanding a Boss follow-up.
-        appendJournal('reply', settlement.text);
+        const suffix = turn?.mandatoryPresentationSuffix;
+        const visibleText = suffix === undefined || settlement.text.includes(suffix)
+            ? settlement.text
+            : `${settlement.text.trimEnd()}\n\n${suffix}`;
+        appendJournal('reply', visibleText);
         try {
-            await trackTurnCall(settlement.context.emitReply(settlement.text));
+            await trackTurnCall(settlement.context.emitReply(visibleText));
         }
         catch (error) {
             conversation = { kind: 'needsSeeding' };
@@ -2889,8 +4029,9 @@ export function createPlaybookCaptainShell(options, deps = {}) {
         }
     };
     /**
-     * CAPTAIN-35: the one wrapper an effect runs through — a runtime driven, an
-     * engagement constructed, a stack disposed, an advertised action applied.
+     * CAPTAIN-35: the one wrapper an effect runs through — a runtime driven or
+     * adopted, an engagement constructed, a stack disposed, an advertised
+     * action applied.
      * Attribution is recorded here, at the operation that threw, and nowhere
      * else: an error acquires the mark by escaping this call, so no later
      * failure can inherit it.
@@ -2903,7 +4044,7 @@ export function createPlaybookCaptainShell(options, deps = {}) {
      * instead of settling, so a misfiling costs the Boss their only settlement.
      *
      * Neither can a boundary drawn around a *region* of the turn. `operation` is
-     * therefore always one call expression naming one of those four operations,
+     * therefore always one call expression naming one of those five operations,
      * never a closure that also performs the shell work leading to it: the leaf
      * check, the visibility request, the mode change, and the processing of what
      * the runtime returned are all shell control work, and a boundary wide
@@ -3103,7 +4244,7 @@ export function createPlaybookCaptainShell(options, deps = {}) {
                 ...(kind === 'closingReply' && turn?.report
                     ? [
                         labeledBlock('ControlView digest', controlViewDigest()),
-                        outcomeReportBlock(turn.report),
+                        outcomeReportBlock(turn.report, turn.unresolvedEffects ?? []),
                     ]
                     : []),
                 ...(options.proseRejection === undefined
@@ -3259,6 +4400,9 @@ export function createPlaybookCaptainShell(options, deps = {}) {
         const leaf = leafFrame();
         if (!leaf)
             return 'idle: no playbook is engaged';
+        if (retainedEffectReconciliation !== undefined) {
+            return `${frameLabel(leaf)} parked for repository-effect reconciliation`;
+        }
         if (!leaf.state)
             return `${frameLabel(leaf)} engaged`;
         return `${frameLabel(leaf)} at ${stateDigestLine(leaf.state, leafStateDescription(leaf))}`;
@@ -3305,6 +4449,9 @@ export function createPlaybookCaptainShell(options, deps = {}) {
         if (!root)
             return false;
         const label = frameLabel(root);
+        // Dismissal leaves the procedure unfinished. Persist the latest safe
+        // generation captured for this turn before disposal erases the frames.
+        retainOrClearDisposedRoot(root);
         try {
             await runEffect(() => disposeStack('dismiss'));
             facts.push(`Dismissed the ${label} engagement.`);
@@ -3351,6 +4498,133 @@ export function createPlaybookCaptainShell(options, deps = {}) {
         }
         return { frame, report: outcome.report, failed: false };
     };
+    const adoptRetainedGeneration = async (rootPlaybookId, offer) => {
+        const generation = offer.generation;
+        const currentLedger = assertPlaybookEffectLedger(currentEffectLedger());
+        const requiresEffectReconciliation = offer.requiresEffectReconciliation ||
+            !retainedEffectLedgerCanRebase(generation.effectLedger, currentLedger);
+        const sourceSessionIds = new Set(generation.frames.map((frame) => frame.sessionId));
+        const targetSessionIds = allocateAdoptionSessionIds(generation.frames.length, sourceSessionIds);
+        const targetRootSessionId = targetSessionIds[0];
+        const adoptedFrames = [];
+        for (const [index, sourceFrame] of generation.frames.entries()) {
+            const enablement = enablementById.get(sourceFrame.playbookId);
+            const parent = adoptedFrames.at(-1);
+            adoptedFrames.push({
+                entry: enablement.entry,
+                enablement,
+                runtime: offer.runtimes[index],
+                sessionId: targetSessionIds[index],
+                rootSessionId: targetRootSessionId,
+                depth: index,
+                playerBindings: makePlayerBindings(enablement),
+                ...(parent
+                    ? { parent: { frame: parent, callId: 'playbook-1' } }
+                    : {}),
+                state: sourceFrame.runtime.state,
+                inFlightHostCalls: new Set(),
+            });
+        }
+        retainedGenerationOffers.delete(rootPlaybookId);
+        let installed = false;
+        try {
+            for (const [index, frame] of adoptedFrames.entries()) {
+                const sourceFrame = generation.frames[index];
+                const targetChild = adoptedFrames[index + 1];
+                await runEffect(() => frame.runtime.adopt(frameSession(frame), sourceFrame.runtime, {
+                    sourceSessionId: sourceFrame.sessionId,
+                    sourceGenerationId: generation.frames[0].rootSessionId,
+                    ...(targetChild === undefined
+                        ? {}
+                        : { targetChildSessionId: targetChild.sessionId }),
+                }));
+            }
+            frames.push(...adoptedFrames);
+            installed = true;
+            retainedEffectReconciliation = requiresEffectReconciliation
+                ? {
+                    sourceGenerationId: generation.retainedEffectReconciliation?.sourceGenerationId ??
+                        generation.frames[0].runtime.retainedEffectSourceSessionId ??
+                        generation.frames[0].rootSessionId,
+                    checkpoint: generation.effectLedger,
+                }
+                : undefined;
+            for (const parent of adoptedFrames.slice(0, -1)) {
+                pendingChildParents.add(parent);
+            }
+            const retainedQuestions = generation.frames.at(-1).runtime
+                .pendingBossQuestions;
+            pendingBossQuestions =
+                requiresEffectReconciliation || retainedQuestions.length === 0
+                    ? undefined
+                    : mirroredBossQuestions(retainedQuestions);
+            lastError = undefined;
+            retainedGenerations.delete(rootPlaybookId);
+            ineligibleRetainedGenerations.delete(rootPlaybookId);
+            await setMode('engaged.parked', 'resume', rootPlaybookId, targetRootSessionId);
+            if (requiresEffectReconciliation) {
+                await requireSession().setVisiblePlayers([]);
+            }
+            else {
+                await requestVisibility(adoptedFrames.at(-1));
+            }
+            await requireSession().emitStatus(`◇ /${enablementById.get(rootPlaybookId).command} resumed`);
+            if (activeTurn) {
+                appendMandatoryPresentationSuffix(activeTurn, requiresEffectReconciliation
+                    ? 'The retained work remains parked until its repository-effect evidence is reconciled.'
+                    : RESUMPTION_DUPLICATE_EFFECT_WARNING);
+            }
+            return [
+                generation.rootStateDescription === undefined
+                    ? `Resumed /${enablementById.get(rootPlaybookId).command} from its retained state; no published root-state description was retained.`
+                    : `Resumed /${enablementById.get(rootPlaybookId).command} from the retained state described as ${quoteEvidence(compactEvidence(generation.rootStateDescription))}.`,
+                requiresEffectReconciliation
+                    ? 'The retained work remains parked until its repository-effect evidence is reconciled; no ordinary action was resumed.'
+                    : RESUMPTION_DUPLICATE_EFFECT_WARNING,
+            ];
+        }
+        catch (error) {
+            if (installed) {
+                frames.splice(0);
+                pendingChildParents.clear();
+                retainedEffectReconciliation = undefined;
+                clearLeafLedger();
+            }
+            const cleanupFailures = [];
+            const failedCleanupRuntimes = [];
+            for (const frame of [...adoptedFrames].reverse()) {
+                try {
+                    await disposeFrame(frame);
+                }
+                catch (cleanupError) {
+                    cleanupFailures.push(cleanupError);
+                    failedCleanupRuntimes.push(frame.runtime);
+                }
+            }
+            const rollbackFailures = [];
+            if (installed) {
+                try {
+                    await setMode('chat', 'resume.failed');
+                }
+                catch (rollbackError) {
+                    rollbackFailures.push(rollbackError);
+                }
+            }
+            else {
+                mode = 'chat';
+            }
+            if (cleanupFailures.length > 0 || rollbackFailures.length > 0) {
+                retiredRetainedRuntimes.push(...failedCleanupRuntimes);
+                ineligibleRetainedGenerations.add(rootPlaybookId);
+                terminallyDisposed = true;
+                lifecycle = 'closed';
+                throw new AggregateError([error, ...cleanupFailures, ...rollbackFailures], 'retained-generation adoption and rollback failed');
+            }
+            retainedGenerations.set(rootPlaybookId, generation);
+            ineligibleRetainedGenerations.delete(rootPlaybookId);
+            throw error;
+        }
+    };
     const driveAndProcess = async (frame, text, context, onDriven) => {
         try {
             // CAPTAIN-35: no boundary here. `driveFrame` marks the runtime call and
@@ -3377,11 +4651,36 @@ export function createPlaybookCaptainShell(options, deps = {}) {
             }
         }
     };
+    const containsEffectThrow = (turn, error) => {
+        if (turn.effectThrows.has(error))
+            return true;
+        return (error instanceof AggregateError &&
+            error.errors.some((nested) => containsEffectThrow(turn, nested)));
+    };
     const settleSelection = async (selection, signal) => {
         const turn = activeTurn;
         runFailureFacts = [];
+        let frozenUnresolvedEffects;
+        const freezeControllerEvidence = () => {
+            frozenUnresolvedEffects ??= freezeTurnUnresolvedEffects();
+            const report = unresolvedEffectBossReport(frozenUnresolvedEffects);
+            if (turn !== undefined && report !== undefined) {
+                appendMandatoryPresentationSuffix(turn, report);
+            }
+            return frozenUnresolvedEffects;
+        };
+        const finalizeSettlement = (settlement) => Object.freeze({
+            ...settlement,
+            unresolvedEffects: freezeControllerEvidence(),
+        });
         try {
-            return await executeSelection(selection, signal);
+            // `respond` has no result phase: freeze its no-effect projection before
+            // its decision-call prose crosses the presentation boundary. Acting
+            // selections freeze after their work and before reporting begins.
+            if (selection.action === 'respond')
+                freezeControllerEvidence();
+            const settlement = await executeSelection(selection, signal);
+            return finalizeSettlement(settlement);
         }
         catch (error) {
             if (turn?.presentationError === error)
@@ -3405,7 +4704,7 @@ export function createPlaybookCaptainShell(options, deps = {}) {
                 turn.settlementFacts.push(...runFailureFacts.splice(0));
             }
             const mayHaveApplied = selection.action !== 'respond' &&
-                turn.effectThrows.has(error);
+                containsEffectThrow(turn, error);
             turn.settlementFacts.push(mayHaveApplied
                 ? `The ${selection.action} action failed before its complete outcome could be confirmed and may have changed the session: ${normalized.name}: ${compactEvidence(normalized.message)}. It was not repeated automatically.`
                 : `The ${selection.action} action failed before its complete outcome could be confirmed: ${normalized.name}: ${compactEvidence(normalized.message)}. It was not repeated automatically.`);
@@ -3440,7 +4739,7 @@ export function createPlaybookCaptainShell(options, deps = {}) {
             };
             turn.settled = true;
             lastSettlementStatus = 'failed';
-            return {
+            const settlement = {
                 status: 'failed',
                 facts: [...turn.settlementFacts],
                 ...(turn.report.receipt === undefined
@@ -3448,6 +4747,7 @@ export function createPlaybookCaptainShell(options, deps = {}) {
                     : { receipt: turn.report.receipt }),
                 ...(summary === undefined ? {} : { leafStateSummary: summary }),
             };
+            return finalizeSettlement(settlement);
         }
         finally {
             runFailureFacts = undefined;
@@ -3505,6 +4805,46 @@ export function createPlaybookCaptainShell(options, deps = {}) {
                     : { leafStateSummary: leafStateSummary() }),
             };
         }
+        refreshRetainedEffectFence();
+        const fencedLeaf = leafFrame();
+        const routesRetainedReconciliation = selection.action === 'runtime' &&
+            (selection.actionId === UNRESOLVED_EFFECT_RECONCILIATION_ACTION_ID ||
+                selection.actionId === UNRESOLVED_EFFECT_ABANDONMENT_ACTION_ID) &&
+            fencedLeaf !== undefined;
+        if (retainedEffectReconciliation !== undefined &&
+            !routesRetainedReconciliation) {
+            return rejectSelection(selection, 'retained work must reconcile its repository-effect evidence before an ordinary action can run');
+        }
+        if (selection.action === 'resume') {
+            const entry = byId.get(selection.playbookId);
+            if (entry === undefined) {
+                return rejectSelection(selection, `"${selection.playbookId}" is not an enabled playbook`);
+            }
+            if (rootFrame() !== undefined) {
+                return rejectSelection(selection, 'a playbook is already engaged; its live actions take precedence');
+            }
+            const offer = retainedGenerationOffers.get(entry.id);
+            if (offer === undefined) {
+                return rejectSelection(selection, `/${enablementById.get(entry.id).command} has no resumable retained generation`);
+            }
+            turn.settled = true;
+            journalAction({ action: 'resume', playbookId: entry.id });
+            facts.push(...(await adoptRetainedGeneration(entry.id, offer)));
+            const summary = leafStateSummary();
+            turn.report = {
+                ...emptyReport(),
+                facts,
+                status: 'ok',
+                ...(summary === undefined ? {} : { leafStateSummary: summary }),
+            };
+            journalOutcome([...facts]);
+            lastSettlementStatus = 'ok';
+            return {
+                status: 'ok',
+                facts: [...facts],
+                ...(summary === undefined ? {} : { leafStateSummary: summary }),
+            };
+        }
         if (selection.action === 'start' || selection.action === 'switch') {
             const entry = byId.get(selection.playbookId);
             if (!entry) {
@@ -3726,6 +5066,7 @@ export function createPlaybookCaptainShell(options, deps = {}) {
         if (outcome.error !== undefined)
             throw outcome.error;
         const receipt = outcome.result;
+        refreshRetainedEffectFence();
         let status = receipt.disposition === 'executed'
             ? 'ok'
             : receipt.disposition === 'rejected'
@@ -3745,9 +5086,47 @@ export function createPlaybookCaptainShell(options, deps = {}) {
                 }
                 : {}),
         };
+        const unresolvedAbandonment = receipt.disposition === 'executed' &&
+            actionId === UNRESOLVED_EFFECT_ABANDONMENT_ACTION_ID;
         if (receipt.disposition === 'executed') {
-            facts.push(`Applied "${actionId}" on ${frameLabel(leaf)}.`);
+            if (unresolvedAbandonment &&
+                receipt.run?.outcome !== 'unresolved-effect') {
+                throw new Error('unresolved-effect abandonment returned no unresolved-effect result');
+            }
             const establishedSummary = leafStateSummary();
+            if (unresolvedAbandonment) {
+                try {
+                    await settleUnresolvedEffectAbandonment(leaf);
+                }
+                catch (error) {
+                    abandonmentSettlementUnsafe = true;
+                    const normalized = normalizeErrorCompact(error) ?? {
+                        name: 'Error',
+                        message: String(error),
+                    };
+                    // The runtime action was accepted, but its distinct host-level
+                    // settlement did not complete.  Do not expose an `executed` control
+                    // receipt until both disposal and durable publication have
+                    // succeeded.
+                    turn.report = {
+                        ...outcome.report,
+                        facts: [...facts],
+                        bossFacts: facts.map((fact) => fact
+                            .split(`"${actionId}"`)
+                            .join(`"${compactEvidence(actionLabel)}"`)),
+                        status: 'failed',
+                        receipt: {
+                            disposition: 'failed',
+                            error: normalized,
+                        },
+                        ...(establishedSummary === undefined
+                            ? {}
+                            : { leafStateSummary: establishedSummary }),
+                    };
+                    throw error;
+                }
+            }
+            facts.push(`Applied "${actionId}" on ${frameLabel(leaf)}.`);
             // Execution is now proven. Preserve that receipt and the counts already
             // collected before processing the returned run, because disposal,
             // telemetry, or parent resumption can still fail afterward.
@@ -3763,7 +5142,9 @@ export function createPlaybookCaptainShell(options, deps = {}) {
                     ? {}
                     : { leafStateSummary: establishedSummary }),
             };
-            if (receipt.run !== undefined) {
+            if (!unresolvedAbandonment &&
+                receipt.run !== undefined &&
+                retainedEffectReconciliation === undefined) {
                 // The same rule as the drive path: processing the run the receipt
                 // carried is not itself an effect, and the resume or disposal it may
                 // perform is marked where it happens (CAPTAIN-35).
@@ -3959,6 +5340,25 @@ export function createPlaybookCaptainShell(options, deps = {}) {
             if (!isDeepStrictEqual(frame.roleBindings, configuredBindings)) {
                 throw new TypeError(`Captain shell snapshot frame ${JSON.stringify(frame.playbookId)} role bindings changed`);
             }
+            if (!isDeepStrictEqual(frame.runtime.effectLedger, snapshot.effectLedger)) {
+                throw new TypeError(`Captain shell snapshot frame ${JSON.stringify(frame.playbookId)} effect ledger does not match its artifact schema`);
+            }
+            const runtimeReconciliation = frame.runtime.retainedEffectReconciliation;
+            if (snapshot.retainedEffectReconciliation === undefined) {
+                if (runtimeReconciliation !== undefined) {
+                    throw new TypeError(`Captain shell snapshot frame ${JSON.stringify(frame.playbookId)} carries an unmirrored retained-effect fence`);
+                }
+            }
+            else if (runtimeReconciliation === undefined ||
+                !isDeepStrictEqual(runtimeReconciliation.checkpoint, snapshot.retainedEffectReconciliation.checkpoint)) {
+                throw new TypeError(`Captain shell snapshot frame ${JSON.stringify(frame.playbookId)} does not mirror the root retained-effect fence`);
+            }
+            if (frame.depth === 0 &&
+                snapshot.retainedEffectReconciliation !== undefined &&
+                runtimeReconciliation?.sourceSessionId !==
+                    snapshot.retainedEffectReconciliation.sourceGenerationId) {
+                throw new TypeError('Captain shell snapshot retained-effect root source identity differs from its generation');
+            }
         }
     };
     const safeCapturePoint = () => {
@@ -4013,33 +5413,33 @@ export function createPlaybookCaptainShell(options, deps = {}) {
                             frame.abortListener !== undefined)));
         });
     };
-    const exportShellSnapshot = () => {
-        if (!safeCapturePoint() ||
-            !captainRuntime ||
-            !captainSessionId ||
-            !captainAgent) {
-            return undefined;
-        }
+    const captureFrameSnapshots = (requireRecordedState) => {
+        const captured = [];
         try {
-            if (typeof captainRuntime.exportSnapshot !== 'function' ||
-                typeof captainRuntime.restore !== 'function') {
-                return undefined;
-            }
-            const captainSnapshot = captainRuntime.exportSnapshot();
-            if (captainSnapshot === undefined)
-                return undefined;
-            const frameSnapshots = [];
-            for (const frame of frames) {
+            for (const [index, frame] of frames.entries()) {
                 if (typeof frame.runtime.exportSnapshot !== 'function' ||
                     typeof frame.runtime.restore !== 'function') {
                     return undefined;
                 }
-                const runtime = frame.runtime.exportSnapshot();
-                if (runtime === undefined ||
-                    !isDeepStrictEqual(frame.state, runtime.state)) {
+                const exported = frame.runtime.exportSnapshot();
+                if (exported === undefined)
+                    return undefined;
+                const runtime = assertPlaybookRuntimeSnapshot(exported, frame.entry.id, { allowSuspendedCall: true });
+                if (runtime.state.status !== 'active' ||
+                    !runtime.state.quiescent ||
+                    (requireRecordedState && frame.state === undefined) ||
+                    (frame.state !== undefined &&
+                        !isDeepStrictEqual(frame.state, runtime.state))) {
+                    return undefined;
+                }
+                const isLeaf = index === frames.length - 1;
+                if ((isLeaf &&
+                    (runtime.suspendedCall !== undefined ||
+                        !runtime.state.tags.includes('playbook.parked'))) ||
+                    (!isLeaf && runtime.suspendedCall === undefined)) {
                     return undefined;
                 }
-                frameSnapshots.push({
+                captured.push({
                     playbookId: frame.entry.id,
                     sessionId: frame.sessionId,
                     rootSessionId: frame.rootSessionId,
@@ -4058,8 +5458,198 @@ export function createPlaybookCaptainShell(options, deps = {}) {
                     runtime,
                 });
             }
+            for (let index = 1; index < captured.length; index += 1) {
+                const parent = captured[index - 1];
+                const child = captured[index];
+                if (child.parentSessionId !== parent.sessionId ||
+                    child.parentCallId === undefined ||
+                    parent.runtime.suspendedCall?.callId !== child.parentCallId ||
+                    parent.runtime.suspendedCall.playbookId !== child.playbookId ||
+                    parent.runtime.suspendedCall.childSessionId !== child.sessionId) {
+                    return undefined;
+                }
+            }
+            return captured;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const refreshRetainedEffectFence = (capturedFrames, capturedLedger) => {
+        const fence = retainedEffectReconciliation;
+        if (fence === undefined)
+            return;
+        try {
+            const ledger = capturedLedger ?? assertPlaybookEffectLedger(currentEffectLedger());
+            if (!retainedEffectLedgerCanRebase(fence.checkpoint, ledger)) {
+                return;
+            }
+            const snapshots = capturedFrames ?? captureFrameSnapshots(true);
+            if (snapshots === undefined || snapshots.length !== frames.length)
+                return;
+            for (const frameSnapshot of snapshots) {
+                const runtime = frameSnapshot.runtime;
+                if (!isDeepStrictEqual(runtime.effectLedger, ledger) ||
+                    runtime.retainedEffectSourceSessionId === undefined ||
+                    runtime.retainedEffectReconciliation !== undefined) {
+                    return;
+                }
+            }
+            const retainedQuestions = snapshots.at(-1).runtime.pendingBossQuestions;
+            const restoredQuestions = retainedQuestions.length === 0
+                ? undefined
+                : mirroredBossQuestions(retainedQuestions);
+            pendingBossQuestions = restoredQuestions;
+            retainedEffectReconciliation = undefined;
+        }
+        catch {
+            // Any host-ledger or runtime-snapshot defect leaves the root fence shut.
+        }
+    };
+    const rootStateDescriptionForRetention = (root, retainedState) => {
+        if (typeof root.runtime.describe !== 'function')
+            return undefined;
+        try {
+            const view = root.runtime.describe();
+            if (!isDeepStrictEqual(view.state, retainedState))
+                return undefined;
+            return typeof view.stateDescription === 'string' &&
+                view.stateDescription.trim().length > 0
+                ? view.stateDescription
+                : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const retainedGenerationFromFrames = (root, frameSnapshots) => {
+        const rootStateDescription = rootStateDescriptionForRetention(root, frameSnapshots[0].runtime.state);
+        const checkpoint = retainedEffectReconciliation?.checkpoint ??
+            assertPlaybookEffectLedger(currentEffectLedger());
+        if (checkpoint.boundaries.some(({ physicalReceipt }) => physicalReceipt === undefined)) {
+            throw new TypeError('Captain retained-generation checkpoint contains an incomplete physical boundary');
+        }
+        return snapshotJsonValue({
+            effectLedger: checkpoint,
+            frames: frameSnapshots,
+            ...(retainedEffectReconciliation === undefined
+                ? {}
+                : {
+                    retainedEffectReconciliation: {
+                        sourceGenerationId: retainedEffectReconciliation.sourceGenerationId,
+                    },
+                }),
+            ...(rootStateDescription === undefined
+                ? {}
+                : { rootStateDescription }),
+        }, 'Captain retained generation');
+    };
+    const captureRetainedGeneration = () => {
+        const root = rootFrame();
+        if (!root ||
+            frames.some((frame) => !runtimeRetainsGenerations(frame.runtime))) {
+            return undefined;
+        }
+        const frameSnapshots = captureFrameSnapshots(true);
+        if (frameSnapshots === undefined || frameSnapshots.length === 0) {
+            return undefined;
+        }
+        return retainedGenerationFromFrames(root, frameSnapshots);
+    };
+    const rememberRetainedGeneration = () => {
+        const root = rootFrame();
+        if (!root)
+            return;
+        if (frames.some((frame) => !runtimeRetainsGenerations(frame.runtime))) {
+            retainedGenerationCandidates.set(root.entry.id, {
+                status: 'incapable',
+            });
+            return;
+        }
+        const generation = captureRetainedGeneration();
+        retainedGenerationCandidates.set(root.entry.id, generation === undefined
+            ? { status: 'unsafe' }
+            : { status: 'captured', generation });
+    };
+    const retentionUpdateForPriorGeneration = (root) => {
+        const rootPlaybookId = root.entry.id;
+        if (!runtimeRetainsGenerations(root.runtime)) {
+            return {
+                kind: 'clear',
+                rootPlaybookId,
+            };
+        }
+        const candidate = retainedGenerationCandidates.get(rootPlaybookId);
+        if (candidate?.status === 'incapable') {
+            return undefined;
+        }
+        if (candidate?.status !== 'captured') {
+            throw new Error(`${frameLabel(root)} could not capture its pre-terminal retained generation`);
+        }
+        return {
+            kind: 'retain',
+            rootPlaybookId,
+            generation: candidate.generation,
+        };
+    };
+    const retainOrClearDisposedRoot = (root) => {
+        const update = retentionUpdateForPriorGeneration(root);
+        if (update !== undefined) {
+            pendingRetentionUpdates.set(update.rootPlaybookId, update);
+        }
+    };
+    const recordTerminalRetention = (root, result) => {
+        const rootPlaybookId = root.entry.id;
+        if (!runtimeRetainsGenerations(root.runtime)) {
+            pendingRetentionUpdates.set(rootPlaybookId, {
+                kind: 'clear',
+                rootPlaybookId,
+            });
+            return;
+        }
+        const terminalStateId = result.state.stateId;
+        if (typeof terminalStateId !== 'string' ||
+            terminalStateId.trim().length === 0) {
+            throw new Error(`${frameLabel(root)} terminal result has no stable state id for retention`);
+        }
+        const unfinished = root.runtime.retainedGenerationMetadata.unfinishedFinalStateIds.includes(terminalStateId);
+        if (unfinished) {
+            // A root opened and terminated within this turn has no pre-turn,
+            // work-bearing generation. Leave any earlier store entry untouched.
+            if (!retainedGenerationCandidates.has(rootPlaybookId))
+                return;
+            retainOrClearDisposedRoot(root);
+        }
+        else {
+            pendingRetentionUpdates.set(rootPlaybookId, {
+                kind: 'clear',
+                rootPlaybookId,
+            });
+        }
+    };
+    const exportShellSnapshot = () => {
+        if (!safeCapturePoint() ||
+            !captainRuntime ||
+            !captainSessionId ||
+            !captainAgent) {
+            return undefined;
+        }
+        try {
+            if (typeof captainRuntime.exportSnapshot !== 'function' ||
+                typeof captainRuntime.restore !== 'function') {
+                return undefined;
+            }
+            const captainSnapshot = captainRuntime.exportSnapshot();
+            if (captainSnapshot === undefined)
+                return undefined;
+            const frameSnapshots = captureFrameSnapshots(true);
+            if (frameSnapshots === undefined)
+                return undefined;
+            const effectLedger = assertPlaybookEffectLedger(currentEffectLedger());
+            refreshRetainedEffectFence(frameSnapshots, effectLedger);
             const common = {
-                schemaVersion: 3,
+                schemaVersion: 4,
+                effectLedger,
                 captain: {
                     sessionId: captainSessionId,
                     runtime: captainSnapshot,
@@ -4081,6 +5671,9 @@ export function createPlaybookCaptainShell(options, deps = {}) {
                     ...common,
                     mode: 'engaged.parked',
                     frames: frameSnapshots,
+                    ...(retainedEffectReconciliation === undefined
+                        ? {}
+                        : { retainedEffectReconciliation }),
                     ...(pendingBossQuestions === undefined
                         ? {}
                         : { pendingBossQuestions: pendingBossQuestions }),
@@ -4094,6 +5687,64 @@ export function createPlaybookCaptainShell(options, deps = {}) {
             return undefined;
         }
     };
+    const exportSettlement = () => {
+        if (!retentionSettlementReady || abandonmentSettlementUnsafe) {
+            return undefined;
+        }
+        const snapshot = exportShellSnapshot();
+        if (snapshot === undefined)
+            return undefined;
+        let unresolvedEffects;
+        try {
+            unresolvedEffects =
+                settledTurnUnresolvedEffects ?? currentUnresolvedEffects();
+        }
+        catch {
+            return undefined;
+        }
+        const updates = new Map(pendingRetentionUpdates);
+        for (const rootPlaybookId of retainedGenerationRootClears) {
+            updates.set(rootPlaybookId, { kind: 'clear', rootPlaybookId });
+        }
+        const root = rootFrame();
+        if (root !== undefined) {
+            const rootPlaybookId = root.entry.id;
+            if (frames.every((frame) => runtimeRetainsGenerations(frame.runtime))) {
+                const generation = snapshot.mode === 'engaged.parked'
+                    ? retainedGenerationFromFrames(root, snapshot.frames)
+                    : undefined;
+                if (generation !== undefined) {
+                    updates.set(rootPlaybookId, {
+                        kind: 'retain',
+                        rootPlaybookId,
+                        generation,
+                    });
+                }
+            }
+            else if (!runtimeRetainsGenerations(root.runtime)) {
+                updates.set(rootPlaybookId, { kind: 'clear', rootPlaybookId });
+            }
+            else if (retainedGenerationCandidates.has(rootPlaybookId)) {
+                try {
+                    const update = retentionUpdateForPriorGeneration(root);
+                    if (update !== undefined) {
+                        updates.set(rootPlaybookId, update);
+                    }
+                }
+                catch {
+                    return undefined;
+                }
+            }
+        }
+        for (const update of updates.values()) {
+            applyRetentionUpdateToCatalog(update);
+        }
+        return snapshotJsonValue({
+            snapshot,
+            retentionUpdates: [...updates.values()].sort((left, right) => left.rootPlaybookId.localeCompare(right.rootPlaybookId)),
+            unresolvedEffects,
+        }, 'Captain settlement');
+    };
     const verifyRestoredRuntime = (runtime, expected, playbookId, allowSuspendedCall) => {
         const actual = runtime.exportSnapshot?.();
         if (actual === undefined) {
@@ -4106,6 +5757,9 @@ export function createPlaybookCaptainShell(options, deps = {}) {
             'sequences',
             'pendingBossQuestions',
             'suspendedCall',
+            'effectLedger',
+            'retainedEffectSourceSessionId',
+            'retainedEffectReconciliation',
         ]) {
             if (!isDeepStrictEqual(normalized[key], expected[key])) {
                 throw new Error(`restored ${playbookId} runtime changed snapshot field ${key}`);
@@ -4123,6 +5777,15 @@ export function createPlaybookCaptainShell(options, deps = {}) {
                 cleanupFailures.push(error);
             }
         }
+        const retainedRuntimes = takeRetainedOfferRuntimes();
+        if (retainedRuntimes.length > 0) {
+            try {
+                await disposeRetainedRuntimeSet(retainedRuntimes, 'retained-generation restore cleanup failed');
+            }
+            catch (error) {
+                cleanupFailures.push(error);
+            }
+        }
         if (captainRuntime) {
             shuttingDown = true;
             try {
@@ -4140,11 +5803,20 @@ export function createPlaybookCaptainShell(options, deps = {}) {
         byCommand = new Map();
         byId = new Map();
         enablementById = new Map();
+        hostCapabilitiesById = new Map();
+        pendingHostCapabilities = undefined;
+        currentEffectLedger = () => emptyPlaybookEffectLedger();
         captainAgent = undefined;
         captainAdapter = undefined;
         playerAgents = new Map();
         playerLedger.clear();
         playerTransactions.clear();
+        retainedGenerations.clear();
+        ineligibleRetainedGenerations.clear();
+        retainedGenerationRootClears.clear();
+        retainedGenerationsInstalled = false;
+        retainedGenerationInstallationInProgress = false;
+        retainedGenerationInstallationClosed = false;
         session = undefined;
         sessionEmissionsOpen = false;
         closedGateAttempted = false;
@@ -4152,6 +5824,7 @@ export function createPlaybookCaptainShell(options, deps = {}) {
         captainSessionId = undefined;
         conversation = { kind: 'unopened' };
         mode = 'chat';
+        retainedEffectReconciliation = undefined;
         pendingBossQuestions = undefined;
         lastError = undefined;
         journalSeq = 0;
@@ -4178,7 +5851,13 @@ export function createPlaybookCaptainShell(options, deps = {}) {
         lifecycle = 'restoring';
         try {
             const snapshot = assertPlaybookCaptainShellSnapshot(untrusted);
-            const built = await buildEnablements(options, loadModule);
+            const built = await buildCurrentEnablements();
+            const builtHostCapabilities = new Map(built.hostCapabilitiesById);
+            const readEffectLedger = () => effectLedgerMirrorFromCapabilities(builtHostCapabilities);
+            const hostLedger = readEffectLedger();
+            if (!isDeepStrictEqual(snapshot.effectLedger, hostLedger)) {
+                throw new Error('Captain shell restore effect ledger does not match current-host authority');
+            }
             captainAgent = built.captainAgent;
             captainAdapter = captainAgent.adapter;
             playerAgents = built.playerAgents;
@@ -4188,6 +5867,8 @@ export function createPlaybookCaptainShell(options, deps = {}) {
             byCommand = built.byCommand;
             byId = built.byId;
             enablementById = built.enablementById;
+            hostCapabilitiesById = builtHostCapabilities;
+            currentEffectLedger = readEffectLedger;
             for (const [playerId, saved] of Object.entries(snapshot.playerSessions)) {
                 playerLedger.set(playerId, {
                     adapter: saved.adapter,
@@ -4267,6 +5948,8 @@ export function createPlaybookCaptainShell(options, deps = {}) {
             lastSettlementStatus = snapshot.lastSettlementStatus;
             mode = snapshot.mode;
             if (snapshot.mode === 'engaged.parked') {
+                retainedEffectReconciliation =
+                    snapshot.retainedEffectReconciliation;
                 pendingBossQuestions = snapshot.pendingBossQuestions;
                 lastError = snapshot.lastError;
             }
@@ -4282,6 +5965,57 @@ export function createPlaybookCaptainShell(options, deps = {}) {
             throw error;
         }
     };
+    const installRetainedGenerations = async (generations) => {
+        if (lifecycle !== 'ready' || terminallyDisposed) {
+            throw new Error('retained generations require an initialized or restored Captain shell');
+        }
+        if (retainedGenerationsInstalled ||
+            retainedGenerationInstallationInProgress ||
+            retainedGenerationInstallationClosed ||
+            activeTurnHostCalls !== undefined) {
+            throw new Error('retained generations may be installed exactly once before the first nonempty Boss turn');
+        }
+        const normalized = normalizeInstalledRetainedGenerations(generations);
+        retainedGenerationInstallationInProgress = true;
+        try {
+            retainedGenerations.clear();
+            retainedGenerationOffers.clear();
+            ineligibleRetainedGenerations.clear();
+            retainedGenerationRootClears.clear();
+            for (const [rootPlaybookId, generation] of normalized) {
+                retainedGenerations.set(rootPlaybookId, generation);
+            }
+            await prepareRetainedGenerationOffers();
+            retainedGenerationsInstalled = true;
+        }
+        catch (error) {
+            const preparationCleanupFailed = error instanceof RetainedRuntimeCleanupError;
+            const runtimes = [...retainedGenerationOffers.values()].flatMap((offer) => [...offer.runtimes]);
+            retainedGenerationOffers.clear();
+            retainedGenerations.clear();
+            ineligibleRetainedGenerations.clear();
+            retainedGenerationRootClears.clear();
+            try {
+                await disposeRetainedRuntimeSet(runtimes, 'retained-generation installation cleanup failed');
+            }
+            catch (cleanupError) {
+                if (cleanupError instanceof RetainedRuntimeCleanupError) {
+                    retiredRetainedRuntimes.push(...cleanupError.failedRuntimes);
+                }
+                terminallyDisposed = true;
+                lifecycle = 'closed';
+                throw new AggregateError([error, cleanupError], 'retained-generation installation and cleanup failed');
+            }
+            if (preparationCleanupFailed) {
+                terminallyDisposed = true;
+                lifecycle = 'closed';
+            }
+            throw error;
+        }
+        finally {
+            retainedGenerationInstallationInProgress = false;
+        }
+    };
     return {
         async init(initSession) {
             if (lifecycle !== 'fresh' || terminallyDisposed) {
@@ -4293,11 +6027,16 @@ export function createPlaybookCaptainShell(options, deps = {}) {
             lifecycle = 'initializing';
             try {
                 installSession(initSession, true);
-                const built = await buildEnablements(options, loadModule);
+                const built = await buildCurrentEnablements();
+                const builtHostCapabilities = new Map(built.hostCapabilitiesById);
+                const readEffectLedger = () => effectLedgerMirrorFromCapabilities(builtHostCapabilities);
+                readEffectLedger();
                 entries = built.entries;
                 byCommand = built.byCommand;
                 byId = built.byId;
                 enablementById = built.enablementById;
+                hostCapabilitiesById = builtHostCapabilities;
+                currentEffectLedger = readEffectLedger;
                 captainAgent = built.captainAgent;
                 captainAdapter = captainAgent.adapter;
                 playerAgents = built.playerAgents;
@@ -4322,7 +6061,9 @@ export function createPlaybookCaptainShell(options, deps = {}) {
             }
         },
         exportSnapshot: exportShellSnapshot,
+        exportSettlement,
         restore: restoreShellSnapshot,
+        installRetainedGenerations,
         async handleBossTurn(turn, context) {
             if (lifecycle !== 'ready' || terminallyDisposed) {
                 throw new Error('init must be called first, or restore must complete before handling a Boss turn');
@@ -4334,10 +6075,25 @@ export function createPlaybookCaptainShell(options, deps = {}) {
             if (activeTurnHostCalls !== undefined) {
                 throw new Error('cannot handle concurrent Boss turns');
             }
+            if (retainedGenerationInstallationInProgress) {
+                throw new Error('cannot handle a Boss turn while retained generations are installing');
+            }
             // Empty or whitespace-only input allocates no call, session, or
             // telemetry (CAPTAIN-7).
+            retentionSettlementReady = false;
+            abandonmentSettlementUnsafe = false;
             if (turn.prompt.trim().length === 0)
                 return;
+            settledTurnUnresolvedEffects = undefined;
+            retainedGenerationInstallationClosed = true;
+            for (const update of pendingRetentionUpdates.values()) {
+                applyRetentionUpdateToCatalog(update);
+            }
+            retainedGenerationCandidates.clear();
+            pendingRetentionUpdates.clear();
+            // A terminal or dismissal can remove the whole stack during this turn;
+            // take the latest already-settled generation before controller work.
+            rememberRetainedGeneration();
             const turnHostCalls = new Set();
             activeTurnHostCalls = turnHostCalls;
             activeContext = context;
@@ -4360,6 +6116,8 @@ export function createPlaybookCaptainShell(options, deps = {}) {
             decisionCall = undefined;
             appendJournal('boss', turn.prompt);
             try {
+                await drainRetiredRetainedRuntimes();
+                await prepareRetainedGenerationOffers();
                 const result = await captainRuntime.handleBossInput({
                     text: turn.prompt,
                     signal: context.signal,
@@ -4422,17 +6180,22 @@ export function createPlaybookCaptainShell(options, deps = {}) {
                     activeTurnHostCalls = undefined;
                 }
                 activeContext = undefined;
+                retentionSettlementReady = true;
             }
         },
         async prepareDispose() {
-            if (lifecycle === 'initializing' || lifecycle === 'restoring') {
+            if (lifecycle === 'initializing' ||
+                lifecycle === 'restoring' ||
+                retainedGenerationInstallationInProgress) {
                 throw new Error('cannot dispose while Captain shell setup is in progress');
             }
             activeContext = undefined;
             await teardown();
         },
         async dispose() {
-            if (lifecycle === 'initializing' || lifecycle === 'restoring') {
+            if (lifecycle === 'initializing' ||
+                lifecycle === 'restoring' ||
+                retainedGenerationInstallationInProgress) {
                 throw new Error('cannot dispose while Captain shell setup is in progress');
             }
             activeContext = undefined;
@@ -4451,6 +6214,18 @@ export function createPlaybookCaptainShell(options, deps = {}) {
         catch (error) {
             failure = error;
         }
+        const retainedRuntimes = takeRetainedOfferRuntimes();
+        if (retainedRuntimes.length > 0) {
+            try {
+                await disposeRetainedRuntimeSet(retainedRuntimes, 'retained-generation shell cleanup failed');
+            }
+            catch (error) {
+                failure ??= error;
+            }
+        }
+        retainedGenerations.clear();
+        ineligibleRetainedGenerations.clear();
+        retainedGenerationRootClears.clear();
         const runtime = captainRuntime;
         captainRuntime = undefined;
         if (runtime) {
@@ -4465,6 +6240,9 @@ export function createPlaybookCaptainShell(options, deps = {}) {
         // Quarantine is session-wide by design. Only terminal teardown may drop
         // its ownership after every frame host call and the Captain are drained.
         playerTransactions.clear();
+        hostCapabilitiesById = new Map();
+        pendingHostCapabilities = undefined;
+        currentEffectLedger = () => emptyPlaybookEffectLedger();
         lifecycle = 'closed';
         if (failure !== undefined)
             throw failure;