@sublang/playbook 17.3.0 → 17.4.0

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

@@ -7,6 +7,8 @@ import { isAgentCallSettingsError, } from '@sublang/cligent/tmux-play';
 import { assertPlaybookFailureCause } from '@sublang/playbook/runtime';
 import { assertPlaybookRuntimeSnapshot, assertPlaybookEffectLedger, emptyPlaybookEffectLedger, hiddenControlEnvelope, isPlaybookEffectLedgerMonotonicExtension, normalizeError, parseJudgeJson, registerPlaybookAbortCleanup, snapshotJsonValue, validatePlayerResult, } from '../../../src/xstate-runtime.js';
 import createDefaultCaptainRuntime from '../captain.playbook/captain.playbook.js';
+import { validateAssetRef, validateAssetRefs } from './session-assets.js';
+import { QUOTED_EVIDENCE_LIMIT, workerReportExcerpt, workerReportBlock } from './worker-evidence.js';
 function retainedEffectLedgerCanRebase(checkpoint, current) {
     if (checkpoint.boundaries.some(({ physicalReceipt }) => physicalReceipt === undefined)) {
         return false;
@@ -124,7 +126,6 @@ function quoteEvidence(text) {
 // into a fact and still knows it is foreign — never at the digest renderer,
 // which sees an opaque payload and cannot tell quoted output from the Boss
 // text, captain speech, or settlement facts the shell authored itself.
-const QUOTED_EVIDENCE_LIMIT = 400;
 // The same guard for strings the shell interpolates into a single-line fact:
 // control characters collapse to spaces so a quoted message can never open a
 // new line — and therefore never a new labeled block — inside a report.
@@ -1685,6 +1686,7 @@ export function assertPlaybookCaptainShellSnapshot(value) {
         'issuedSessionIds',
         'sequences',
         'journal',
+        'pendingAttachments',
         'lastAction',
         'lastSettlementStatus',
         'mode',
@@ -1858,6 +1860,7 @@ export function assertPlaybookCaptainShellSnapshot(value) {
         issuedSessionIds: issued,
         sequences: { turn: turnSequence, journal: journalSequence },
         journal: normalizedJournal,
+        ...(snapshot.pendingAttachments === undefined ? {} : { pendingAttachments: validateAssetRefs(snapshot.pendingAttachments) }),
         ...(lastAction === undefined ? {} : { lastAction }),
         ...(lastSettlementStatus === undefined
             ? {}
@@ -1892,6 +1895,7 @@ export function assertPlaybookCaptainShellSnapshot(value) {
             'parentCallId',
             'request',
             'inputs',
+            'attachments',
             'options',
             'roleBindings',
             'runtime',
@@ -1922,6 +1926,7 @@ export function assertPlaybookCaptainShellSnapshot(value) {
             ...(parentCallId === undefined ? {} : { parentCallId }),
             ...(frame.request === undefined ? {} : { request: frame.request }),
             ...(frame.inputs === undefined ? {} : { inputs: frame.inputs }),
+            ...(frame.attachments === undefined ? {} : { attachments: validateAssetRefs(frame.attachments) }),
             options,
             roleBindings,
             runtime,
@@ -2114,6 +2119,7 @@ function snapshotSessionAgent(value, path) {
         'fastMode',
         'subagentModel',
         'subagentEffort',
+        'browser',
         'instruction',
         'permissions',
     ], path);
@@ -2121,7 +2127,8 @@ function snapshotSessionAgent(value, path) {
         key !== 'effort' &&
         key !== 'fastMode' &&
         key !== 'subagentModel' &&
-        key !== 'subagentEffort')), path);
+        key !== 'subagentEffort' &&
+        key !== 'browser')), path);
     return {
         adapter: fixed.adapter,
         ...(fixed.instruction === undefined
@@ -2130,6 +2137,7 @@ function snapshotSessionAgent(value, path) {
         ...(fixed.permissions === undefined
             ? {}
             : { permissions: livePermissions(fixed.permissions) }),
+        ...(agent.browser === undefined ? {} : { browser: snapshotFastMode(agent.browser, `${path}.browser`) }),
         model: snapshotTuningSelection(agent.model, `${path}.model`),
         effort: snapshotEffortSelection(agent.effort, `${path}.effort`),
         ...(agent.fastMode === undefined
@@ -2163,6 +2171,7 @@ function callSettings(agent, tuning = agent) {
     return {
         model: tuning.model,
         effort: tuning.effort,
+        browser: agent.browser ?? false,
         ...(tuning.fastMode === undefined ? {} : { fastMode: tuning.fastMode }),
         ...(tuning.subagentModel === undefined
             ? {}
@@ -2174,6 +2183,9 @@ function callSettings(agent, tuning = agent) {
         ...(agent.permissions === undefined ? {} : { permissions: agent.permissions }),
     };
 }
+function controlCallSettings(agent) {
+    return { ...callSettings(agent), browser: false, mcpServers: {} };
+}
 function promptIdentity(binding) {
     return binding.model.kind === 'value'
         ? binding.model.value
@@ -2545,6 +2557,19 @@ export function createPlaybookCaptainShell(options, deps = {}) {
     const createCaptainRuntime = deps.createCaptainRuntime ?? createDefaultCaptainRuntime;
     const unresolvedEffectSettlement = deps.unresolvedEffectSettlement;
     const continuity = deps.continuity;
+    const resolveAttachments = deps.resolveAttachments;
+    const beginPreparationMedia = deps.beginPreparationMedia;
+    const onTurnAttachments = deps.onTurnAttachments;
+    let nextTurnAttachments = [];
+    let pendingAttachments = [];
+    const mergeAttachments = (...groups) => [...new Map(groups.flat().map((reference) => [reference.assetId, reference])).values()];
+    const attachmentPaths = async (references, signal) => {
+        if (!references?.length)
+            return undefined;
+        if (!resolveAttachments)
+            throw new Error('The session host cannot materialize required attachments');
+        return resolveAttachments(references, signal);
+    };
     const abortPreparation = deps.abortPreparation;
     let pendingHostCapabilities = deps.hostCapabilities;
     let currentEffectLedger = () => emptyPlaybookEffectLedger();
@@ -2866,6 +2891,7 @@ export function createPlaybookCaptainShell(options, deps = {}) {
                     'parentCallId',
                     'request',
                     'inputs',
+                    'attachments',
                     'options',
                     'roleBindings',
                     'runtime',
@@ -2951,6 +2977,7 @@ export function createPlaybookCaptainShell(options, deps = {}) {
                     ...(parentCallId === undefined ? {} : { parentCallId }),
                     ...(frame.request === undefined ? {} : { request: frame.request }),
                     ...(frame.inputs === undefined ? {} : { inputs: frame.inputs }),
+                    ...(frame.attachments === undefined ? {} : { attachments: validateAssetRefs(frame.attachments) }),
                     options,
                     roleBindings,
                     runtime,
@@ -3324,12 +3351,20 @@ export function createPlaybookCaptainShell(options, deps = {}) {
         turnCalls?.add(tracked);
         return tracked;
     };
-    const callCaptainQueued = (frame, context, prompt, options, signal) => {
+    const callCaptainQueued = (frame, context, prompt, options, signal, media) => {
         const queued = captainQueue.add(async () => {
             signal.throwIfAborted();
-            const result = await trackHostCall(frame, context.callCaptain(prompt, options));
+            const attachments = media?.attachments?.length ? await attachmentPaths(media.attachments, signal) : undefined;
             signal.throwIfAborted();
-            return result;
+            const endMedia = media?.preparation ? beginPreparationMedia?.(frame.sessionId) : undefined;
+            try {
+                const result = await trackHostCall(frame, context.callCaptain(prompt, { ...options, ...(attachments === undefined ? {} : { attachments }) }));
+                signal.throwIfAborted();
+                return result;
+            }
+            finally {
+                endMedia?.();
+            }
         });
         return trackHostCall(frame, queued);
     };
@@ -3398,9 +3433,17 @@ export function createPlaybookCaptainShell(options, deps = {}) {
             !Number.isSafeInteger(trace.turnId) ||
             trace.turnId <= 0 ||
             !Number.isSafeInteger(trace.sequence) ||
-            trace.sequence <= 0 ||
-            summary === undefined ||
-            !summaryIncludes(frame)) {
+            trace.sequence <= 0) {
+            return;
+        }
+        if (trace.type === 'player.call.finished') {
+            const call = payloadRecord(trace.payload);
+            if (typeof trace.callId === 'string' && call?.status === 'ok' &&
+                typeof call.roleId === 'string' && typeof call.playerId === 'string' &&
+                frame.playerBindings.get(call.roleId)?.playerId === call.playerId &&
+                typeof call.stateId === 'string' && typeof call.finalText === 'string') {
+                turn.workerCalls.set(`${frame.sessionId}:${trace.callId}`, { frame, callId: trace.callId, roleId: call.roleId, playerId: call.playerId, stateId: call.stateId, finalText: call.finalText });
+            }
             return;
         }
         if (trace.type !== 'outcome.accepted')
@@ -3419,6 +3462,24 @@ export function createPlaybookCaptainShell(options, deps = {}) {
             receipt.acceptedOutcome.trim().length === 0) {
             return;
         }
+        const ledger = currentEffectLedger();
+        const previous = turn.progressBase?.effectLedger;
+        for (const call of turn.workerCalls.values()) {
+            if (call.frame !== frame || call.stateId !== receipt.source)
+                continue;
+            const boundary = [...ledger.boundaries].reverse().find((entry) => entry.playbookId === frame.entry.id &&
+                entry.runtimeSessionId === (frame.effectOwnerSessionId ?? frame.sessionId) &&
+                entry.callId === call.callId && entry.roleId === call.roleId &&
+                entry.sourceStateId === call.stateId && entry.finalText === call.finalText &&
+                !isDeepStrictEqual(entry, previous?.boundaries[entry.sequence - 1]));
+            if (!boundary || turn.workerReports.has(boundary.boundaryId))
+                continue;
+            const report = workerReportExcerpt(boundary, call.playerId, receipt.acceptedOutcome);
+            if (report !== undefined)
+                turn.workerReports.set(boundary.boundaryId, report);
+        }
+        if (summary === undefined || !summaryIncludes(frame))
+            return;
         const traceKey = `${frame.sessionId}:${trace.sequence}`;
         if (summary.acceptedOutcomeTraceKeys.has(traceKey))
             return;
@@ -3438,7 +3499,27 @@ export function createPlaybookCaptainShell(options, deps = {}) {
     const createPorts = (frame) => ({
         ...(recordProgress === undefined ? {} : { recordStep: async (step, position) => {
                 journalledFrames.add(frame);
-                await saveProgress(step.result === undefined ? { frame, position } : undefined, { ...step, runtimeSessionId: frame.sessionId, playbookId: frame.entry.id });
+                const turn = activeTurn;
+                if (step.kind === 'player' && step.result === undefined) {
+                    turn?.workerStepStarts.set(step.id, new Set(turn.workerCalls.keys()));
+                }
+                let workerEvidence;
+                const guard = payloadRecord(step.result)?.guard;
+                const before = turn?.workerStepStarts.get(step.id);
+                if (step.kind === 'player' && typeof guard === 'string' && before !== undefined && turn) {
+                    const candidates = [...turn.workerCalls.entries()].flatMap(([key, call]) => {
+                        if (before.has(key) || call.frame !== frame || call.stateId !== step.stateId)
+                            return [];
+                        return currentEffectLedger().boundaries.filter((boundary) => boundary.playbookId === frame.entry.id && boundary.sourceStateId === step.stateId &&
+                            boundary.runtimeSessionId === (frame.effectOwnerSessionId ?? frame.sessionId) &&
+                            boundary.callId === call.callId && boundary.roleId === call.roleId && boundary.finalText === call.finalText &&
+                            !isDeepStrictEqual(boundary, turn.progressBase?.effectLedger.boundaries[boundary.sequence - 1]) &&
+                            workerReportExcerpt(boundary, call.playerId, guard) !== undefined).map((boundary) => ({ boundaryId: boundary.boundaryId, playerId: call.playerId }));
+                    });
+                    if (candidates.length === 1)
+                        workerEvidence = candidates[0];
+                }
+                await saveProgress(step.result === undefined ? { frame, position } : undefined, { ...step, runtimeSessionId: frame.sessionId, playbookId: frame.entry.id, ...(workerEvidence === undefined ? {} : { workerEvidence }) });
             } }),
         callPlayer: async (roleId, prompt, signal, options) => {
             admitHostBoundary();
@@ -3465,6 +3546,7 @@ export function createPlaybookCaptainShell(options, deps = {}) {
                 throw new Error(`session player ${JSON.stringify(binding.playerId)} already has a call in flight`);
             }
             const settings = callSettings(binding.agent, binding);
+            const attachments = await attachmentPaths(frame.attachments, signal);
             const calling = {
                 phase: 'calling',
                 frame,
@@ -3489,7 +3571,7 @@ export function createPlaybookCaptainShell(options, deps = {}) {
                     const call = async (resume) => {
                         await continuity?.beforeCall(binding.playerId);
                         signal.throwIfAborted();
-                        const raw = await trackHostCall(frame, classifySettingsCall(() => context.callPlayer(binding.playerId, resume === false ? options.freshPrompt ?? prompt : prompt, { resume, settings })));
+                        const raw = await trackHostCall(frame, classifySettingsCall(() => context.callPlayer(binding.playerId, resume === false ? options.freshPrompt ?? prompt : prompt, { resume, settings, ...(attachments === undefined ? {} : { attachments }) })));
                         hostResolved = true;
                         return raw;
                     };
@@ -3611,8 +3693,9 @@ export function createPlaybookCaptainShell(options, deps = {}) {
             const result = await callCaptainQueued(frame, activeContext, prompt, {
                 visibility: options.visibility,
                 resume: options.resume,
+                settings: options.allowedTools?.length === 0 ? controlCallSettings(captainAgent) : callSettings(captainAgent),
                 ...forwardedToolOptions(options.allowedTools, captainAdapter),
-            }, signal);
+            }, signal, { attachments: options.allowedTools?.length === 0 ? undefined : frame.attachments });
             const output = {
                 status: result.status,
                 ...(result.finalText !== undefined
@@ -3630,6 +3713,7 @@ export function createPlaybookCaptainShell(options, deps = {}) {
                 throw new Error('callJudge invoked outside a Boss turn');
             }
             const result = await callCaptainQueued(frame, activeContext, hiddenJudgeEnvelope(prompt), {
+                settings: controlCallSettings(captainAgent),
                 visibility: 'hidden',
                 resume: false,
                 ...controlCallToolOptions(captainAdapter),
@@ -3764,6 +3848,7 @@ export function createPlaybookCaptainShell(options, deps = {}) {
             runtime,
             sessionId,
             rootSessionId: parent?.frame.rootSessionId ?? sessionId,
+            ...((parent?.frame.attachments ?? activeTurn?.selectedAttachments ?? activeTurn?.attachments)?.length ? { attachments: [...(parent?.frame.attachments ?? activeTurn?.selectedAttachments ?? activeTurn.attachments)] } : {}),
             depth: parent ? parent.frame.depth + 1 : 0,
             playerBindings,
             ...(parent ? { parent } : {}),
@@ -3779,12 +3864,14 @@ export function createPlaybookCaptainShell(options, deps = {}) {
             enablement,
             runtime,
             sessionId: snapshot.sessionId,
+            effectOwnerSessionId: snapshot.runtime.retainedEffectSourceSessionId ?? snapshot.sessionId,
             rootSessionId: snapshot.rootSessionId,
             depth: snapshot.depth,
             playerBindings,
             ...(parent ? { parent } : {}),
             ...(snapshot.request === undefined ? {} : { request: snapshot.request }),
             ...(snapshot.inputs === undefined ? {} : { inputs: [...snapshot.inputs] }),
+            ...(snapshot.attachments === undefined ? {} : { attachments: [...snapshot.attachments] }),
             state: snapshot.runtime.state,
             inFlightHostCalls: new Set(),
         };
@@ -4065,6 +4152,8 @@ export function createPlaybookCaptainShell(options, deps = {}) {
             finally {
                 if (leafFrame() === frame) {
                     frames.pop();
+                    if (!frame.parent)
+                        pendingAttachments = [];
                     if (frame.parent) {
                         pendingChildParents.delete(frame.parent.frame);
                     }
@@ -5328,11 +5417,11 @@ export function createPlaybookCaptainShell(options, deps = {}) {
             await continuity?.beforeCall('captain');
             context.signal.throwIfAborted();
             attempt.providerBoundaryEntered = true;
-            const result = await classifySettingsCall(() => context.callCaptain(prompt, {
+            const result = await classifySettingsCall(() => context.callCaptain(pendingAttachments.length || activeTurn?.attachments.length || activeTurn?.evidence?.length || leafFrame()?.attachments?.length ? `${prompt}\n\nAttachment context (metadata only; do not claim to have viewed these bytes): ${JSON.stringify({ current: activeTurn?.attachments ?? [], pending: pendingAttachments, engagement: leafFrame()?.attachments ?? [], evidence: activeTurn?.evidence ?? [] })}` : prompt, {
                 visibility: 'hidden',
                 resume,
                 ...controlCallToolOptions(captainAdapter),
-                settings: callSettings(captainAgent),
+                settings: controlCallSettings(captainAgent),
             }));
             context.signal.throwIfAborted();
             return result;
@@ -5497,6 +5586,9 @@ export function createPlaybookCaptainShell(options, deps = {}) {
                 ...(kind === 'decision'
                     ? [labeledBlock('Catalog digest', catalogDigest())]
                     : []),
+                ...(kind === 'closingReply' && turn?.workerReports.size
+                    ? [workerReportBlock([...turn.workerReports.values()])]
+                    : []),
                 ...(kind === 'closingReply' && turn?.report
                     ? [
                         labeledBlock('ControlView digest', controlViewDigest()),
@@ -5821,6 +5913,7 @@ export function createPlaybookCaptainShell(options, deps = {}) {
                 enablement,
                 runtime: offer.runtimes[index],
                 sessionId: targetSessionIds[index],
+                effectOwnerSessionId: sourceFrame.runtime.retainedEffectSourceSessionId ?? sourceFrame.sessionId,
                 rootSessionId: targetRootSessionId,
                 depth: index,
                 playerBindings: makePlayerBindings(enablement),
@@ -5829,6 +5922,7 @@ export function createPlaybookCaptainShell(options, deps = {}) {
                     : {}),
                 ...(sourceFrame.request === undefined ? {} : { request: sourceFrame.request }),
                 ...(sourceFrame.inputs === undefined ? {} : { inputs: [...sourceFrame.inputs] }),
+                ...(sourceFrame.attachments === undefined ? {} : { attachments: [...sourceFrame.attachments] }),
                 state: sourceFrame.runtime.state,
                 inFlightHostCalls: new Set(),
             });
@@ -6383,6 +6477,12 @@ export function createPlaybookCaptainShell(options, deps = {}) {
                     return rejectSelection(selection, `/${enablementById.get(entry.id).command} is already on the active path`);
                 }
             }
+            const selectedIds = selection.attachmentIds;
+            const available = new Map(mergeAttachments(pendingAttachments, turn.attachments, leafFrame()?.attachments ?? []).map((reference) => [reference.assetId, reference]));
+            if (selectedIds?.some((id) => !available.has(id)) || (selectedIds && new Set(selectedIds).size !== selectedIds.length))
+                return rejectSelection(selection, 'the request selects unavailable attachment evidence');
+            turn.selectedAttachments = selectedIds === undefined ? turn.attachments : selectedIds.map((id) => available.get(id));
+            pendingAttachments = [];
             turn.settled = true;
             journalAction({
                 action: selection.action,
@@ -6515,7 +6615,7 @@ export function createPlaybookCaptainShell(options, deps = {}) {
                         `Later Boss input (context only): ${JSON.stringify(laterInputs)}`,
                         `Existing instructions: ${JSON.stringify(instructions)}`,
                         `Pending questions (quoted evidence): ${JSON.stringify(before.pendingQuestions.map(({ question }) => question))}`,
-                    ].join('\n')), { visibility: 'hidden', resume: false, ...controlCallToolOptions(captainAdapter), settings: callSettings(captainAgent) }, signal);
+                    ].join('\n')), { visibility: 'hidden', resume: false, ...controlCallToolOptions(captainAdapter), settings: controlCallSettings(captainAgent) }, signal);
                     const answer = result.status === 'ok' ? controlReplyJson(result.finalText) : undefined;
                     const index = answer && typeof answer === 'object' && !Array.isArray(answer) && Object.keys(answer).join(',') === 'instructionIndex'
                         ? answer.instructionIndex : undefined;
@@ -6573,7 +6673,7 @@ export function createPlaybookCaptainShell(options, deps = {}) {
                 try {
                     claim = await capability.acquire({ signal: preparationSignal });
                     await claim.assertOwner();
-                    const result = await runEffect(() => callCaptainQueued(leaf, context, preparationPrompt, { visibility: 'hidden', resume: false, settings: callSettings(captainAgent) }, preparationSignal));
+                    const result = await runEffect(() => callCaptainQueued(leaf, context, preparationPrompt, { visibility: 'hidden', resume: false, settings: callSettings(captainAgent) }, preparationSignal, { attachments: leaf.attachments, preparation: true }));
                     preparationSignal.throwIfAborted();
                     await claim.assertOwner();
                     if (result.status !== 'ok') {
@@ -6616,6 +6716,13 @@ export function createPlaybookCaptainShell(options, deps = {}) {
                 : { action: 'runtime', actionId: offer.continuation.actionId };
         }
         if (selection.action === 'deliver') {
+            const available = new Map(mergeAttachments(pendingAttachments, turn.attachments, leaf.attachments ?? []).map((reference) => [reference.assetId, reference]));
+            if (selection.attachmentIds?.some((id) => !available.has(id)) || (selection.attachmentIds && new Set(selection.attachmentIds).size !== selection.attachmentIds.length))
+                return rejectSelection(selection, 'the request selects unavailable attachment evidence');
+            const selected = selection.attachmentIds === undefined ? turn.attachments : selection.attachmentIds.map((id) => available.get(id));
+            const nextAttachments = mergeAttachments(leaf.attachments ?? [], selected);
+            if (nextAttachments.length)
+                leaf.attachments = nextAttachments;
             // CAPTAIN-8: delivery carries text only, and the shell is authoritative
             // for that text — any text carried on the selection is ignored.
             turn.settled = true;
@@ -7154,6 +7261,7 @@ export function createPlaybookCaptainShell(options, deps = {}) {
                         : {}),
                     ...(frame.request === undefined ? {} : { request: frame.request }),
                     ...(frame.inputs === undefined ? {} : { inputs: [...frame.inputs] }),
+                    ...(frame.attachments === undefined ? {} : { attachments: [...frame.attachments] }),
                     options: frame.enablement.options,
                     roleBindings: Object.fromEntries([...frame.playerBindings].map(([role, binding]) => [
                         role,
@@ -7365,6 +7473,7 @@ export function createPlaybookCaptainShell(options, deps = {}) {
                 issuedSessionIds: [...issuedSessionIds],
                 sequences: { turn: turnSequence, journal: journalSeq },
                 journal,
+                ...(pendingAttachments.length ? { pendingAttachments } : {}),
                 ...(lastAction === undefined ? {} : { lastAction }),
                 ...(lastSettlementStatus === undefined
                     ? {}
@@ -7659,6 +7768,7 @@ export function createPlaybookCaptainShell(options, deps = {}) {
             for (const id of snapshot.issuedSessionIds)
                 issuedSessionIds.add(id);
             journal.push(...snapshot.journal);
+            pendingAttachments = [...(snapshot.pendingAttachments ?? [])];
             journalSeq = snapshot.sequences.journal;
             turnSequence = snapshot.sequences.turn;
             conversation = snapshot.captain.conversation;
@@ -7790,10 +7900,29 @@ export function createPlaybookCaptainShell(options, deps = {}) {
         selectInterruptedReport(input, report) {
             if (activeTurn)
                 throw new Error('A Captain turn is already active');
-            if (!input.trim() || !report.text.trim())
+            if ((!input.trim() && nextTurnAttachments.length === 0) || !report.text.trim())
                 throw new Error('Interruption report requires its recorded input and explanation');
             pendingHostSelection = { kind: 'report', text: input, report };
         },
+        recordMediaEvidence(reference, runtimeSessionId) {
+            const asset = validateAssetRef(reference);
+            if (!activeTurn)
+                throw new Error('Media evidence arrived outside an active turn');
+            activeTurn.evidence = mergeAttachments(activeTurn.evidence ?? [], [asset]);
+            const producingIndex = frames.findIndex((candidate) => candidate.sessionId === runtimeSessionId);
+            // Observed output belongs to this engagement's reasoning context: a
+            // resumed parent may inspect its child's figure. Boss input additions
+            // still target only the addressed leaf, and a new root inherits none.
+            for (const frame of frames.slice(0, producingIndex + 1)) {
+                frame.attachments = mergeAttachments(frame.attachments ?? [], [asset]);
+            }
+        },
+        setTurnAttachments(references) {
+            if (activeTurn || activeTurnHostCalls)
+                throw new Error('A Captain turn is already active');
+            nextTurnAttachments = validateAssetRefs(references);
+            onTurnAttachments?.(nextTurnAttachments);
+        },
         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');
@@ -7812,7 +7941,9 @@ export function createPlaybookCaptainShell(options, deps = {}) {
             // telemetry (CAPTAIN-7).
             retentionSettlementReady = false;
             abandonmentSettlementUnsafe = false;
-            if (turn.prompt.trim().length === 0)
+            const attachments = nextTurnAttachments;
+            nextTurnAttachments = [];
+            if (turn.prompt.trim().length === 0 && attachments.length === 0)
                 return;
             const progressBase = exportShellSnapshot();
             settledTurnUnresolvedEffects = undefined;
@@ -7840,6 +7971,10 @@ export function createPlaybookCaptainShell(options, deps = {}) {
             const hostGiveUp = decided?.kind === 'give-up' ? true : undefined;
             const parsed = decided === undefined ? resolveCommandTurn(turn.prompt) : undefined;
             activeTurn = {
+                attachments,
+                workerReports: new Map(),
+                workerStepStarts: new Map(),
+                workerCalls: new Map(),
                 appliedActionCount: 0,
                 stoppedFrames: new Set(),
                 ...(progressBase === undefined ? {} : { progressBase }),
@@ -7873,7 +8008,8 @@ export function createPlaybookCaptainShell(options, deps = {}) {
                 }
             }
             decisionCall = undefined;
-            appendJournal('boss', turn.prompt);
+            appendJournal('boss', attachments.length ? { text: turn.prompt, attachments } : turn.prompt);
+            pendingAttachments = mergeAttachments(pendingAttachments, attachments);
             try {
                 await drainRetiredRetainedRuntimes();
                 await prepareRetainedGenerationOffers();
@@ -7882,6 +8018,11 @@ export function createPlaybookCaptainShell(options, deps = {}) {
                     await settleSelection({ action: 'respond', text: activeTurn.interruptedReport.text }, context.signal);
                     return;
                 }
+                if (!turn.prompt.trim() && attachments.length) {
+                    markConversationCatchUp();
+                    await settleSelection({ action: 'respond', text: 'What would you like me to do with the attached material?' }, context.signal);
+                    return;
+                }
                 const result = await captainRuntime.handleBossInput({
                     text: turn.prompt,
                     signal: context.signal,