@sublang/playbook 17.2.0 → 17.4.0

package/reference/sdlc/code.playbook/bin/session-host.js

@@ -2,6 +2,7 @@
 // SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
 
 import { randomUUID } from 'node:crypto';
+import { normalizeSessionTurnInput } from '../session-assets.js';
 import { createCaptainSessionStore, isUncertainTurnDiscardable, projectCaptainSessionStructure } from './session-store.js';
 import { createCaptainSessionHost, executionConfigFromPlan, installRetainedGenerationsForLaunch, validateFrozenExecutionConfig } from './run.js';
 import { createReplayRecordObserver } from './replay-observer.js';
@@ -33,9 +34,10 @@ export async function openSessionHost(options) {
     if (record !== undefined) await lease.assertContinuable({ cwd, executionProjection: selected });
     const config = await validateFrozenExecutionConfig(structure, selected, { loadModule, prepareRegistryModule: options.prepareRegistryModule });
     const replay = createReplayRecordObserver({ lease, onIncomplete: options.onIncomplete ?? (() => {}), onStored: options.onStoredRecord });
-    let terminal, replies = [];
+    let terminal, replies = [], submittedAttachments = [];
     const observe = {
       async onRecord(value) {
+        if (value.type === 'turn_started' && submittedAttachments.length) value = { ...value, turn: { ...value.turn, attachments: submittedAttachments } };
         if (value.type === "turn_finished" || value.type === "turn_aborted") terminal = value;
         if (value.type === "captain_reply") replies.push(value);
         await replay.observer.onRecord(value);
@@ -53,14 +55,21 @@ export async function openSessionHost(options) {
     const execute = async (input, retry, actionId, shellActionId) => {
       assertIdle();
       let attemptId;
+      let attachments = [];
       const operation = (async () => {
         let prior = await lease.read();
         if (retry) {
           if (prior?.state !== 'uncertain') throw new Error('session has no uncertain turn to retry');
           input = prior.uncertain.input;
+          attachments = prior.uncertain.attachments ?? [];
           if (!retryPending) throw new Error(RECOVERY_REOPEN);
         } else if (prior?.state !== 'settled') throw new Error(RECOVERY_REOPEN);
-        if (actionId === undefined && shellActionId === undefined && (typeof input !== 'string' || input.trim().length === 0)) throw new Error('session input must be nonempty');
+        if (actionId === undefined && shellActionId === undefined) {
+          const normalized = normalizeSessionTurnInput(retry ? { text: input, attachments } : input);
+          input = normalized.text; attachments = normalized.attachments;
+          if (!input.trim() && attachments.length === 0) throw new Error('session input must contain text or attachments');
+          if (attachments.length) await lease.resolveAttachments(attachments, { signal: options.signal });
+        }
         await created.reconcileRepositoryEffects();
         // The selection is made after reconciliation, so the advertised
         // reading it is validated against is the one this turn settles
@@ -74,11 +83,13 @@ export async function openSessionHost(options) {
         }
         terminal = undefined; replies = [];
         attemptId = options.createAttemptId?.() ?? randomUUID();
-        const marked = retry ? await lease.beginRetry({ expectedAttemptId: prior.uncertain.attemptId, nextAttemptId: attemptId }) : await lease.beginTurn({ input, attemptId, attemptedExecutionProjection: config });
+        const marked = retry ? await lease.beginRetry({ expectedAttemptId: prior.uncertain.attemptId, nextAttemptId: attemptId }) : await lease.beginTurn({ input, attachments, attemptId, attemptedExecutionProjection: config });
         retryPending = false;
         await replay.flushStoredRecords();
         await options.onCheckpoint?.(marked);
         await lease.assertOwner();
+        submittedAttachments = attachments;
+        created.shell.setTurnAttachments?.(attachments);
         await created.host.runBossTurn(input);
         if (terminal?.type !== "turn_finished" || replies.length !== 1 || typeof replies[0].text !== "string" || replies[0].text.trim().length === 0) throw new Error("Captain turn did not finish with one reply; session remains uncertain");
         const settlement = created.shell.exportSettlement();
@@ -101,12 +112,13 @@ export async function openSessionHost(options) {
         throw error;
       });
       active = operation;
-      try { return await operation; } finally { active = undefined; }
+      try { return await operation; } finally { active = undefined; submittedAttachments = []; }
     };
 
     const dispose = () => {
       if (closed) return Promise.resolve();
       if (closing) return closing;
+      created.cancelPendingApprovals();
       closing = (async () => {
         try { await active; } catch { /* Preserve the durable uncertain marker. */ }
         await created.host.dispose();

package/reference/sdlc/code.playbook/bin/session-media.js

@@ -0,0 +1,46 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+
+import { randomUUID } from 'node:crypto';
+import { externalizeAgentEvent } from '../session-assets.js';
+
+/** Externalize authentic observed media before the opaque replay writer sees it. */
+export function createSessionMediaProjector({ lease, onEvidence }) {
+  const players = new Map();
+  let preparation;
+  const seen = new Map();
+  const beginPreparation = (runtimeSessionId) => {
+    if (preparation) throw new Error('a preparation media scope is already active');
+    const scope = { callId: randomUUID(), origin: { kind: 'preparation', actorId: 'captain', runtimeSessionId } };
+    preparation = scope;
+    return () => { if (preparation === scope) preparation = undefined; seen.delete(scope.callId); };
+  };
+  const project = async (record) => {
+    if (record.type === 'captain_telemetry' && record.topic === 'playbook.trace') {
+      const trace = record.payload;
+      if (trace?.schemaVersion === 4 && trace.type === 'player.call.started' && typeof trace.callId === 'string' && typeof trace.sessionId === 'string' && typeof trace.payload?.playerId === 'string') {
+        players.set(trace.payload.playerId, { callId: trace.callId, origin: { kind: 'player', actorId: trace.payload.playerId, runtimeSessionId: trace.sessionId } });
+      }
+    }
+    if (record.type === 'player_prompt' && !players.has(record.playerId)) players.set(record.playerId, { callId: randomUUID(), origin: { kind: 'player', actorId: record.playerId } });
+    if (record.type === 'player_finished') { const scope = players.get(record.playerId); if (scope) seen.delete(scope.callId); players.delete(record.playerId); }
+    if (record.type !== 'player_event' && record.type !== 'captain_event') return [record];
+    const event = record.event;
+    const scope = record.type === 'player_event' ? players.get(record.playerId) : preparation;
+    try {
+      const { event: projected, asset } = await externalizeAgentEvent(lease, event);
+      const stored = projected === event ? record : { ...record, event: projected };
+      if (!asset || !scope || typeof record.turnId !== 'number') return [stored];
+      let emitted = seen.get(scope.callId);
+      if (!emitted) { emitted = new Set(); seen.set(scope.callId, emitted); }
+      if (emitted.has(asset.assetId)) return [stored];
+      emitted.add(asset.assetId);
+      const origin = { ...scope.origin, ...(event.payload.toolUseId ? { toolUseId: event.payload.toolUseId } : {}) };
+      await onEvidence?.(asset, origin);
+      return [stored, { type: 'playbook_evidence', timestamp: record.timestamp, turnId: record.turnId, callId: scope.callId, origin, asset }];
+    } catch (error) {
+      return [{ type: 'runtime_error', timestamp: record.timestamp, turnId: record.turnId, sourceRecordType: record.type, message: `Media could not be saved: ${error instanceof Error ? error.message : String(error)}` }];
+    }
+  };
+  return Object.freeze({ project, beginPreparation });
+}

package/reference/sdlc/code.playbook/bin/session-store.js

@@ -7,6 +7,7 @@
 // complete retained-generation map under guarded source-first publication.
 
 import { createHash, randomUUID } from 'node:crypto';
+import { createAssetStore, parseAssetUri, validateAssetRef, validateAssetRefs } from '../session-assets.js';
 import {
   SESSION_MANIFEST_VERSION, EMPTY_REPLAY_SHA256, sha256,
   validateSessionManifest, recoveryFromManifest, manifestFromRecovery,
@@ -637,6 +638,12 @@ export function createCaptainSessionStore(options = {}) {
   const replayReadCursors = new Map();
   const replayReadQueues = new Map();
   const portableWriters = new Map();
+  const assetStores = new Map();
+  const assetStoreFor = (sessionId) => {
+    assertSessionId(sessionId);
+    if (!assetStores.has(sessionId)) assetStores.set(sessionId, createAssetStore({ directory: join(sessionsDir, `${sessionId}.assets`), ...(options.maxAssetBytes === undefined ? {} : { maxAssetBytes: options.maxAssetBytes }) }));
+    return assetStores.get(sessionId);
+  };
 
   if (!isAbsolute(sessionsDir)) {
     throw new Error('Captain session store path must be absolute');
@@ -758,7 +765,11 @@ export function createCaptainSessionStore(options = {}) {
     if (value.sessionId !== sessionId) throw new Error('session manifest identity does not match its filename');
     return value.schemaVersion === 7 ? validateSessionManifest(value) : value;
   };
-  const prepare = () => prepareSessionPermissions(sessionsDir, fs);
+  const prepare = async () => {
+    await prepareSessionPermissions(sessionsDir, fs);
+    let names; try { names = await fs.readdir(sessionsDir); } catch (cause) { if (cause?.code === 'ENOENT') return; throw cause; }
+    for (const name of names) if (name.endsWith('.assets') && SESSION_ID_PATTERN.test(name.slice(0, -7))) await assetStoreFor(name.slice(0, -7)).prepare();
+  };
   const readHistory = async (sessionId, options = {}) => {
     assertSessionId(sessionId);
     const history = await readSessionHistory({ sessionsDir, path: recordsPathFor(sessionId), fs, afterSeq: options.afterSeq ?? 0 });
@@ -771,6 +782,35 @@ export function createCaptainSessionStore(options = {}) {
     } catch { return history; }
     return legacyJournalHistory(legacy, options.afterSeq ?? 0, history);
   };
+  // Only our typed reference locations participate; opaque tool/text data is history.
+  const assertAssetInventory = (manifest, entries) => {
+    const declared = new Map((manifest.assets?.entries ?? []).map((reference) => [reference.assetId, reference]));
+    const check = (reference) => {
+      const valid = validateAssetRef(reference);
+      if (declared.get(valid.assetId)?.byteLength !== valid.byteLength) throw new Error(`session asset reference is absent from its checkpoint inventory: ${valid.assetId}`);
+    };
+    const checkRefs = (references) => { for (const reference of references ?? []) check(reference); };
+    const snapshot = (value) => {
+      if (!value) return;
+      checkRefs(value.pendingAttachments);
+      for (const frame of value.frames ?? []) checkRefs(frame.attachments);
+      for (const item of value.journal ?? []) if (item.kind === 'boss' && typeof item.payload === 'object' && item.payload !== null) checkRefs(item.payload.attachments);
+    };
+    snapshot(manifest.snapshot); snapshot(manifest.uncertain?.progress?.snapshot);
+    checkRefs(manifest.uncertain?.attachments);
+    for (const generation of Object.values(manifest.retainedGenerations ?? {})) for (const frame of generation.frames ?? []) checkRefs(frame.attachments);
+    for (const { record } of entries) {
+      if (record.type === 'turn_started') checkRefs(record.turn?.attachments);
+      else if (record.type === 'playbook_evidence') check(record.asset);
+      else if (record.type === 'player_event' || record.type === 'captain_event') {
+        const event = record.event;
+        if (event?.type === 'media' && event.payload?.source?.type === 'uri') {
+          const id = parseAssetUri(event.payload.source.uri);
+          if (id && !declared.has(id)) throw new Error(`session media asset is absent from its checkpoint inventory: ${id}`);
+        } else if (event?.type === 'tool_result' && event.payload?.output?.type === 'asset_reference') check(event.payload.output.asset);
+      }
+    }
+  };
   const validate = async (sessionId, context = {}) => {
     const manifest = await readManifest(sessionId);
     const history = await readHistory(sessionId);
@@ -790,6 +830,12 @@ export function createCaptainSessionStore(options = {}) {
         integrityValid = false;
         reasons.push('session replay contains provider continuation fields');
       }
+      try { assertAssetInventory(manifest, history.entries.filter(({ seq }) => seq <= manifest.replay.seq)); }
+      catch (cause) { integrityValid = false; reasons.push(errorMessage(cause)); }
+      for (const reference of manifest.assets?.entries ?? []) {
+        try { const reader = await assetStoreFor(sessionId).openAsset(reference); await reader.close(); }
+        catch (cause) { integrityValid = false; reasons.push(`session asset is unavailable: ${errorMessage(cause)}`); }
+      }
       if (manifest.state === 'history-only') reasons.push(manifest.reason);
       if (manifest.replay.incomplete || history.incomplete) reasons.push('session replay is incomplete');
       if (history.digests[manifest.replay.seq] !== manifest.replay.sha256) { integrityValid = false; reasons.push('session replay checkpoint digest does not match'); }
@@ -1111,6 +1157,18 @@ export function createCaptainSessionStore(options = {}) {
   };
 
   const deleteRecord = async (sessionId) => {
+    const assetsDirectory = join(sessionsDir, `${sessionId}.assets`);
+    try {
+      await assertPrivateDirectory(assetsDirectory, fs);
+      const names = await fs.readdir(assetsDirectory);
+      for (const name of names) {
+        if (!/^(?:[0-9a-f]{64}(?:\.json)?|\.import-[0-9a-f-]+\.tmp)$/.test(name)) throw new Error('unknown session asset entry prevents deletion');
+        await assertPrivateRegularPath(join(assetsDirectory, name), 0o600, fs, 'session asset');
+      }
+      for (const name of names) await fs.unlink(join(assetsDirectory, name));
+      await fs.rmdir(assetsDirectory);
+      await syncDirectory(sessionsDir, fs);
+    } catch (cause) { if (cause?.code !== 'ENOENT') throw cause; }
     for (const suffix of ['.records.jsonl', '.hints.json', '.spex.json', '.json']) {
       const path = join(sessionsDir, `${sessionId}${suffix}`);
       try { await assertPrivateRegularPath(path, 0o600, fs, 'session file'); await fs.unlink(path); await syncDirectory(sessionsDir, fs); }
@@ -1396,6 +1454,7 @@ export function createCaptainSessionStore(options = {}) {
   const acquire = async (sessionId, management = false) => {
     assertSessionId(sessionId);
     await prepareSessionPermissions(sessionsDir, fs, sessionId);
+    await assetStoreFor(sessionId).prepare();
     let stage;
     let stagePublished = false;
     try {
@@ -1451,6 +1510,7 @@ export function createCaptainSessionStore(options = {}) {
         readHistory,
         validateSession: validate,
         portableWriters,
+        assetStore: assetStoreFor(sessionId),
         writeRecord,
         syncRecordDirectory: () => syncDirectory(sessionsDir, fs),
         deleteRecord,
@@ -1684,8 +1744,39 @@ export function createCaptainSessionStore(options = {}) {
     finally { await lease.release(); }
   };
 
+  const exportBundle = async (sessionId) => {
+    assertSessionId(sessionId);
+    for (let attempt = 0; attempt < 3; attempt++) {
+      const manifestText = await readPrivateRegularFile(recordPathFor(sessionId), 0o600, fs, 'record');
+      const manifest = validateSessionManifest(JSON.parse(manifestText));
+      const replayBytes = Buffer.from(await readPrivateRegularFile(recordsPathFor(sessionId), 0o600, fs, 'replay stream'), 'utf8');
+      let end = 0;
+      for (let seq = 0; seq < manifest.replay.seq; seq++) {
+        const next = replayBytes.indexOf(10, end);
+        if (next === -1) throw new Error('session bundle is missing its checkpoint replay prefix');
+        end = next + 1;
+      }
+      const replay = replayBytes.subarray(0, end);
+      if (sha256(replay) !== manifest.replay.sha256 || manifest.replay.incomplete) throw new Error('session bundle replay checkpoint is incomplete or corrupt');
+      assertAssetInventory(manifest, parseSessionHistory(replay).entries);
+      const assets = [];
+      for (const reference of manifest.assets?.entries ?? []) {
+        const reader = await assetStoreFor(sessionId).openAsset(reference); await reader.close();
+        const hash = reference.assetId.slice(7);
+        assets.push(Object.freeze({ assetId: reference.assetId, path: hash, metadataPath: `${hash}.json`, byteLength: reference.byteLength }));
+      }
+      if (manifestText !== await readPrivateRegularFile(recordPathFor(sessionId), 0o600, fs, 'record')) continue;
+      return Object.freeze({ sessionId, manifest: Buffer.from(manifestText, 'utf8'), replay, assets: Object.freeze(assets) });
+    }
+    throw new Error('session changed while exporting its bundle; retry');
+  };
+
   return Object.freeze({
     sessionsDir,
+    readAsset: (sessionId, reference, options) => assetStoreFor(sessionId).readAsset(reference, options),
+    openAsset: (sessionId, reference, options) => assetStoreFor(sessionId).openAsset(reference, options),
+    describeAsset: (sessionId, assetId) => assetStoreFor(sessionId).describeAsset(assetId),
+    exportBundle,
     prepare,
     migrate,
     migrateLegacyDefault,
@@ -2540,6 +2631,7 @@ async function createLease({
   readHistory,
   validateSession,
   portableWriters,
+  assetStore,
   writeRecord,
   syncRecordDirectory,
   deleteRecord,
@@ -2636,7 +2728,9 @@ async function createLease({
     const seq = history.digests[durableSeq] === undefined ? previousManifest?.replay?.seq ?? 0 : durableSeq;
     const digest = history.digests[seq] ?? previousManifest?.replay?.sha256 ?? EMPTY_REPLAY_SHA256;
     const replay = { seq, sha256: digest, incomplete: previousManifest?.replay?.incomplete === true || status.incomplete || history.incomplete || history.digests[seq] === undefined };
-    const manifest = manifestFromRecovery(recovery, replay, contextSeq);
+    const entries = await assetStore.listAssets();
+    const assets = entries.length === 0 ? undefined : { version: 1, entries: await Promise.all(entries.map(({ assetId }) => assetStore.describeAsset(assetId))) };
+    const manifest = manifestFromRecovery(recovery, replay, contextSeq, assets);
     return manifest;
   };
   portableWriters.set(sessionId, { checkpoint, sync: replayWriter.checkpoint, published: (manifest) => { previousManifest = manifest; } });
@@ -2928,6 +3022,8 @@ async function createLease({
             source.effectLedger,
           );
 
+          const inheritedAssets = new Map(Object.values(retainedGenerations).flatMap((generation) => generation.frames.flatMap((frame) => frame.attachments ?? [])).map((reference) => [reference.assetId, reference]));
+          for (const reference of inheritedAssets.values()) await assetStore.copyAsset(sourceLease, reference);
           await sourceLease.assertOwner();
           await assertOwnerUnchecked();
           let sourcePublished = false;
@@ -3026,11 +3122,12 @@ async function createLease({
 
   const beginTurn = ({
     input,
+    attachments,
     attemptId,
     attemptedExecutionProjection,
   } = {}) =>
     runExclusive(async () => {
-      assertAcceptedInput(input);
+      assertAcceptedInput(input, attachments);
       assertUuid(attemptId, 'Captain session attempt id');
       const attempted = validateCaptainSessionExecutionProjection(
         attemptedExecutionProjection,
@@ -3065,6 +3162,7 @@ async function createLease({
         uncertain: {
           baseUpdatedAt: prior.updatedAt,
           input,
+          ...(attachments?.length ? { attachments: validateAssetRefs(attachments) } : {}),
           attemptId,
           attemptNumber: 1,
           markedAt: timestamp,
@@ -3119,6 +3217,7 @@ async function createLease({
           baseUpdatedAt: prior.uncertain.baseUpdatedAt,
           ...(prior.uncertain.progress === undefined ? {} : { progress: prior.uncertain.progress }),
           input: prior.uncertain.input,
+          ...(prior.uncertain.attachments === undefined ? {} : { attachments: prior.uncertain.attachments }),
           attemptId: nextAttemptId,
           attemptNumber: prior.uncertain.attemptNumber + 1,
           markedAt: timestamp,
@@ -3637,11 +3736,11 @@ async function createLease({
         if (Object.hasOwn(step, 'result') && !['completion', 'answer'].includes(step.kind)) throw new Error('A step result requires its saved start');
         progress.steps.push(step);
       } else {
-        const { result, ...start } = step;
+        const { result, workerEvidence, ...start } = step;
         const saved = progress.steps[index];
-        const { result: priorResult, ...priorStart } = saved;
+        const { result: priorResult, workerEvidence: priorEvidence, ...priorStart } = saved;
         if (!isDeepStrictEqual(start, priorStart) ||
-            (priorResult !== undefined && !isDeepStrictEqual(priorResult, result))) {
+            (priorResult !== undefined && (!isDeepStrictEqual(priorResult, result) || !isDeepStrictEqual(priorEvidence, workerEvidence)))) {
           throw new Error('A saved step cannot be replaced');
         }
         progress.steps[index] = step;
@@ -3728,6 +3827,11 @@ async function createLease({
     sessionId,
     ownerToken: owner.ownerToken,
     append,
+    importAsset: (input) => runExclusive(async () => { await assertOwnerUnchecked(); return assetStore.importAsset(input); }),
+    resolveAttachments: (references, options) => runExclusive(async () => { await assertOwnerUnchecked(); if (!Array.isArray(references)) throw new TypeError('attachments must be an array'); return Promise.all(references.map((reference) => assetStore.resolveAttachment(reference, options))); }),
+    readAsset: (reference, options) => assetStore.readAsset(reference, options),
+    openAsset: (reference, options) => assetStore.openAsset(reference, options),
+    describeAsset: (assetId) => assetStore.describeAsset(assetId),
     recordContext,
     consumeHints,
     acknowledgeHint,
@@ -4089,7 +4193,7 @@ function validateCanonicalCaptainSessionRecord(
     exactOptionalKeys(
       uncertain,
       UNCERTAIN_KEYS,
-      ['abandonment', 'progress'],
+      ['abandonment', 'progress', 'attachments'],
       'Captain session record uncertain',
     );
     if (uncertain.baseUpdatedAt !== null) {
@@ -4110,7 +4214,7 @@ function validateCanonicalCaptainSessionRecord(
         );
       }
     }
-    assertAcceptedInput(uncertain.input);
+    assertAcceptedInput(uncertain.input, uncertain.attachments);
     assertUuid(uncertain.attemptId, 'Captain session attempt id');
     if (
       !Number.isSafeInteger(uncertain.attemptNumber) ||
@@ -4172,8 +4276,9 @@ function validateCanonicalCaptainSessionRecord(
       exactOptionalKeys(progress, ['snapshot', 'steps'], ['positionStepId'], 'Captain progress');
       if (!Array.isArray(progress.steps)) throw new Error('Captain steps must be an array');
       const ids = new Set();
+      const workerBoundaryIds = new Set();
       for (const step of progress.steps) {
-        exactOptionalKeys(requireRecord(step, 'Captain step'), ['id', 'kind', 'stateId', 'runtimeSessionId', 'playbookId'], ['result'], 'Captain step');
+        exactOptionalKeys(requireRecord(step, 'Captain step'), ['id', 'kind', 'stateId', 'runtimeSessionId', 'playbookId'], ['result', 'workerEvidence'], 'Captain step');
         assertUuid(step.id, 'Captain step id');
         assertUuid(step.runtimeSessionId, 'Captain step runtime');
         if (ids.has(step.id)) throw new Error('Captain step ids must be unique');
@@ -4209,6 +4314,22 @@ function validateCanonicalCaptainSessionRecord(
         }
         requireCanonicalNonblank(step.stateId, 'Captain step state');
         if (!Object.hasOwn(structural.catalog, step.playbookId)) throw new Error('Captain step names an unknown playbook');
+        if (step.workerEvidence !== undefined) {
+          const evidence = requireRecord(step.workerEvidence, 'Worker evidence');
+          exactOptionalKeys(evidence, ['boundaryId', 'playerId'], [], 'Worker evidence');
+          assertUuid(evidence.boundaryId, 'Worker evidence boundary');
+          requireCanonicalNonblank(evidence.playerId, 'Worker evidence player');
+          const boundary = record.effectLedger.boundaries.find((entry) => entry.boundaryId === evidence.boundaryId);
+          if (step.kind !== 'player' || !step.result || typeof step.result !== 'object' || Array.isArray(step.result) ||
+              !boundary || boundary.playbookId !== step.playbookId || boundary.sourceStateId !== step.stateId ||
+              workerBoundaryIds.has(evidence.boundaryId) || isDeepStrictEqual(boundary, record.snapshot.effectLedger.boundaries[boundary.sequence - 1]) ||
+              !boundary.physicalReceipt || !boundary.finalText?.trim() ||
+              boundary.semanticCandidate?.guard !== step.result.guard || typeof step.result.guard !== 'string' || step.result.guard === 'needsBossReply' ||
+              structural.catalog[step.playbookId]?.roles?.[boundary.roleId]?.playerId !== evidence.playerId) {
+            throw new Error('Worker evidence must name its accepted player boundary');
+          }
+          workerBoundaryIds.add(evidence.boundaryId);
+        }
       }
       if (progress.positionStepId !== undefined && progress.positionStepId !== null && !ids.has(progress.positionStepId)) throw new Error('Captain progress positionStepId must name a recorded step');
       if (progress.snapshot === null && progress.positionStepId != null) throw new Error('Captain progress positionStepId requires a saved position');
@@ -5312,7 +5433,7 @@ function assertReleasedSchema2CaptainSessionRecord(record) {
       );
     }
   }
-  assertAcceptedInput(uncertain.input);
+  assertAcceptedInput(uncertain.input, uncertain.attachments);
   assertUuid(uncertain.attemptId, 'Captain session attempt id');
   if (
     !Number.isSafeInteger(uncertain.attemptNumber) ||
@@ -5402,7 +5523,14 @@ function validateCaptainSessionProjection(
         : ['id', 'adapter', 'model', 'effort'],
       structural
         ? ['instruction', 'permissions']
-        : ['instruction', 'permissions', 'fastMode', 'subagentModel'],
+        : [
+            'instruction',
+            'permissions',
+            'fastMode',
+            'subagentModel',
+            'subagentEffort',
+            'browser',
+          ],
       playerPath,
     );
     assertPlayerId(player.id, `${playerPath}.id`);
@@ -5503,16 +5631,13 @@ function validateCaptainSessionProjection(
         structural
           ? ['playerId']
           : ['playerId', 'model', 'effort'],
-        structural ? [] : ['fastMode', 'subagentModel'],
+        structural ? [] : ['fastMode', 'subagentModel', 'subagentEffort'],
         bindingPath,
       );
       assertPlayerId(binding.playerId, `${bindingPath}.playerId`);
       if (!structural) {
         validateProjectedFastMode(binding, `${bindingPath}.fastMode`);
-        validateProjectedSubagentModel(
-          binding,
-          `${bindingPath}.subagentModel`,
-        );
+        validateProjectedSubagentTuning(binding, bindingPath);
         validateTuningSelection(binding.model, `${bindingPath}.model`);
         const player = projection.players.find(
           (candidate) => candidate.id === binding.playerId,
@@ -5560,10 +5685,14 @@ function validateProjectedFastMode(record, path) {
   }
 }
 
-// Like fast mode, absence is the canonical provider default (DR-075).
-function validateProjectedSubagentModel(record, path) {
-  if (Object.hasOwn(record, 'subagentModel')) {
-    requireNonblank(record.subagentModel, path);
+// Like fast mode, absence is the canonical provider default (DR-075); the
+// subagent model may be the literal `inherit`, and an absent subagent effort
+// leaves each subagent's effort to the agent (DR-076).
+function validateProjectedSubagentTuning(record, path) {
+  for (const field of ['subagentModel', 'subagentEffort']) {
+    if (Object.hasOwn(record, field)) {
+      requireNonblank(record[field], `${path}.${field}`);
+    }
   }
 }
 
@@ -5571,7 +5700,8 @@ function validateProjectedAgent(value, path, { structural, hasId = false }) {
   const agent = requireRecord(value, path);
   if (!structural) {
     validateProjectedFastMode(agent, `${path}.fastMode`);
-    validateProjectedSubagentModel(agent, `${path}.subagentModel`);
+    if (agent.browser !== undefined && typeof agent.browser !== 'boolean') throw new Error(`${path}.browser must be a boolean`);
+    validateProjectedSubagentTuning(agent, path);
   }
   if (!hasId) {
     exactOptionalKeys(
@@ -5579,7 +5709,14 @@ function validateProjectedAgent(value, path, { structural, hasId = false }) {
       structural ? ['adapter'] : ['adapter', 'model', 'effort'],
       structural
         ? ['instruction', 'permissions']
-        : ['instruction', 'permissions', 'fastMode', 'subagentModel'],
+        : [
+            'instruction',
+            'permissions',
+            'fastMode',
+            'subagentModel',
+            'subagentEffort',
+            'browser',
+          ],
       path,
     );
   }
@@ -6131,9 +6268,10 @@ function validateRetainedGenerationFrame(
       'roleBindings',
       'runtime',
     ],
-    ['parentSessionId', 'parentCallId', 'request', 'inputs'],
+    ['parentSessionId', 'parentCallId', 'request', 'inputs', 'attachments'],
     path,
   );
+  if (frame.attachments !== undefined) validateAssetRefs(frame.attachments);
   if (frame.request !== undefined) {
     if (index !== 0) throw new Error(`${path}.request belongs only to the root`);
     requireNonblank(frame.request, `${path}.request`);
@@ -6356,8 +6494,9 @@ async function requireUncertainRecord(record, attemptId) {
   return record;
 }
 
-function assertAcceptedInput(value) {
-  if (typeof value !== 'string' || value.trim().length === 0) {
+function assertAcceptedInput(value, attachments) {
+  if (attachments !== undefined) validateAssetRefs(attachments);
+  if (typeof value !== 'string' || (value.trim().length === 0 && !attachments?.length)) {
     throw new Error('Captain session input must be a non-empty string');
   }
 }

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

@@ -3,21 +3,28 @@ import type { Effort, PermissionPolicy } from '@sublang/cligent';
 import type { JsonValue, PlaybookEffectLedger, PlaybookEffectLedgerCommandBatch, PlaybookControlAction, PlaybookFailureCause, PlaybookRuntime, PlaybookRuntimeSnapshot, PlaybookStepRecord } from '@sublang/playbook/runtime';
 import { type CaptainControllerPort } from '../captain.playbook/captain.playbook.js';
 import type { PlaybookSummaryPolicy } from './code.registry.js';
+import type { Attachment } from '@sublang/cligent';
+import type { SessionAssetRef } from './session-assets.js';
 interface SessionAgent {
+    /** Mutable next-turn execution capability; never structural identity. */
+    readonly browser?: boolean;
     readonly adapter: string;
     readonly model: TuningSelection;
     readonly effort: TuningSelection<Effort>;
     /** Adapter-scoped fast mode. Absence is the provider default; `false` is a
      * literal request, so this carries no provider-default sentinel. */
     readonly fastMode?: boolean;
-    /** The model every subagent of this agent runs on (DR-075). Absence is the
-     * provider default. */
+    /** The model every subagent of this agent runs on (DR-075), or `inherit`
+     * for the agent's own model (DR-076). Absence is the provider default. */
     readonly subagentModel?: string;
+    /** The effort every subagent of this agent runs at (DR-076). Absence leaves
+     * each subagent's effort to the agent. */
+    readonly subagentEffort?: string;
     readonly instruction?: string;
     readonly permissions?: PermissionPolicy;
 }
 /** Per-call tuning: erased from every structural envelope and snapshot. */
-type TuningKey = 'model' | 'effort' | 'fastMode' | 'subagentModel';
+type TuningKey = 'model' | 'effort' | 'fastMode' | 'subagentModel' | 'subagentEffort';
 interface PlayerLedgerEntry {
     readonly adapter: string;
     readonly instruction?: string;
@@ -37,7 +44,7 @@ interface PlaybookCaptainUnresolvedEffectSettlementInput {
     readonly rootPlaybookId: string;
     readonly unresolvedEffects: readonly PlaybookCaptainUnresolvedEffect[];
 }
-type SnapshotAgentEnvelope = DeepReadonly<Omit<SessionAgent, TuningKey>>;
+type SnapshotAgentEnvelope = DeepReadonly<Omit<SessionAgent, TuningKey | 'browser'>>;
 type PlayerLedgerSnapshotEntry = DeepReadonly<PlayerLedgerEntry>;
 export interface ProgressChange {
     snapshot?: PlaybookCaptainShellSnapshot | null;
@@ -45,6 +52,10 @@ export interface ProgressChange {
         kind: PlaybookStepRecord['kind'] | 'preparation' | 'completion' | 'answer';
         runtimeSessionId: string;
         playbookId: string;
+        workerEvidence?: {
+            boundaryId: string;
+            playerId: string;
+        };
     };
 }
 export interface InterruptedReport {
@@ -54,6 +65,9 @@ export interface InterruptedReport {
     unresolvedEffects?: readonly PlaybookCaptainUnresolvedEffect[];
 }
 export interface PlaybookCaptainDeps {
+    onTurnAttachments?: (references: readonly SessionAssetRef[]) => void;
+    beginPreparationMedia?: (runtimeSessionId: string) => () => void;
+    resolveAttachments?: (references: readonly SessionAssetRef[], signal: AbortSignal) => Promise<readonly Attachment[]>;
     /** Stop the host's active turn, including admitted tool calls, on preparation expiry or a required save failure. */
     abortPreparation?: (reason?: string) => void;
     recordProgress?: (change: ProgressChange) => Promise<void>;
@@ -161,6 +175,7 @@ export interface PlaybookCaptainFrameSnapshot {
     readonly parentCallId?: string;
     readonly request?: string;
     readonly inputs?: readonly string[];
+    readonly attachments?: readonly SessionAssetRef[];
     readonly options: JsonValue;
     readonly roleBindings: Readonly<Record<string, string>>;
     readonly runtime: DeepReadonly<PlaybookRuntimeSnapshot>;
@@ -183,6 +198,7 @@ interface PlaybookCaptainShellSnapshotFields {
         readonly journal: number;
     };
     readonly journal: readonly PlaybookCaptainJournalRecord[];
+    readonly pendingAttachments?: readonly SessionAssetRef[];
     readonly lastAction?: 'respond' | 'start' | 'switch' | 'resume' | 'dismiss' | 'deliver' | 'runtime' | 'recover';
     readonly lastSettlementStatus?: 'ok' | 'rejected' | 'failed';
 }
@@ -238,6 +254,9 @@ export interface PlaybookCaptainSettlement {
 }
 /** tmux and headless front ends share this one durable Captain shell API. */
 export interface PlaybookCaptainShell extends Captain {
+    /** Bind already-owned evidence to the next visible Boss turn without changing its text. */
+    setTurnAttachments(references: readonly SessionAssetRef[]): void;
+    recordMediaEvidence(reference: SessionAssetRef, runtimeSessionId?: string): void;
     installRetainedGenerations(generations: Readonly<Record<string, PlaybookCaptainRetainedGeneration>>): Promise<void>;
     exportSnapshot(): PlaybookCaptainShellSnapshot | undefined;
     exportSettlement(): PlaybookCaptainSettlement | undefined;