@sublang/playbook 17.3.0 → 17.4.1

package/reference/sdlc/code.md

@@ -12,7 +12,7 @@ The caller supplies a coding request together with any relevant context.
 
 A new coding intent follows either one direct implementation phase or an IR sequence consisting of a new-IR phase followed by one phase for each IR task.
 An existing IR follows one IR-task phase for each remaining unfinished task, starting with its next unfinished task.
-Each phase ends with one new Coder commit (owned by `code`).
+Each completed phase ends with one new Coder commit (owned by `code`).
 After each `code`-owned commit, Captain shall call the `review` playbook and wait until it passes with no unsettled findings.
 Playbook `review` owns every review round and every review-fix commit.
 Do not rewrite any existing commit.
@@ -40,22 +40,37 @@ Plan affected spec updates before, with, or after their corresponding code chang
 For an existing IR, read the identified IR and implement exactly its next unfinished task, including corresponding tests or specs if any.
 Do not implement a later task in this phase.
 Mark the IR's progress and deliverables when relevant.
+After implementing an IR task, identify it and state whether any IR task still has unfinished Coder work; if so identify the next unfinished task, otherwise state this was the final IR task's Coder work.
+Report pending independent REVIEW, owner acceptance and later delivery/workshop steps separately; they imply an unfinished IR task only when the IR assigns that work to a remaining task.
+Report only what the IR and completed work establish, in ordinary prose without a required marker.
 If the IR will be finished after this phase, double-check that all acceptance criteria are met.
 
 Consult @specs/map.md for relevant context and @specs/meta.md for spec requirements, if needed.
 ```
 
-At the start of every later IR-task phase, Captain shall relay to Coder the original caller input, the IR identity, and any relevant run results in quotes (`>`), along with the following instruction:
+On each successful nested REVIEW, Captain shall freeze the previous phase review as one record from the canonical child result and the phase's accepted receipt-owned scope: exact phase kind (direct, new intent or IR task), phase outcome, CODE scope commit, REVIEW evaluated revision, and IR/task identity when present.
+CODE scope commit and evaluated revision remain distinct because REVIEW may create fix commits.
+No caller option, player prose or repository status text supplies this record.
+The record survives permitted restoration and the current task's Boss-answer continuation, and a fresh run or explicit Boss interruption clears it.
+
+At the start of every later IR-task phase, Captain shall relay to Coder the original caller input, the IR identity, any relevant run results, and that previous phase review as quoted evidence in quotes (`>`), along with the following instruction; when absent, the record reads "No accepted prior-phase review is available.":
 
 > Original request: <caller-input>
 > IR number: <ir-number>
 > Run results: <run-results>
+> Previous phase review: <previous-phase-review>
 
 ```markdown
 Read the identified IR and implement exactly its next unfinished task, including corresponding tests or specs if any.
 Do not implement a later task in this phase.
 Mark the IR's progress and deliverables when relevant.
+After implementing an IR task, identify it and state whether any IR task still has unfinished Coder work; if so identify the next unfinished task, otherwise state this was the final IR task's Coder work.
+Report pending independent REVIEW, owner acceptance and later delivery/workshop steps separately; they imply an unfinished IR task only when the IR assigns that work to a remaining task.
+Report only what the IR and completed work establish, in ordinary prose without a required marker.
 If the IR will be finished after this phase, double-check that all acceptance criteria are met.
+Use the quoted previous-phase review only for its exact recorded scope; committed pending-review text may predate that canonical result.
+Before treating it as current review evidence, verify clean current HEAD equals its evaluatedRevision; a mismatch is not approval.
+It does not replace independent review of this task or any new owner or release decision.
 ```
 
 At the start of *every* phase, Captain shall append the following instruction:
@@ -63,7 +78,10 @@ At the start of *every* phase, Captain shall append the following instruction:
 ```markdown
 Keep to the original intent and follow what it asks.
 Do not re-run tests or builds whose inputs have not changed since any previous reported run.
-Make the phase's minimal changes and then one new commit, following @specs/packages/git.md; never amend an existing commit.
+If a required Boss answer prevents completion of the current phase or IR task, ask that question and return without committing.
+Preserve permitted uncommitted work for the deferred continuation; do not create a partial or blocker-only commit to meet the one-commit requirement.
+After the answer allows completion, make exactly one phase-owned commit before REVIEW.
+When the phase is complete, make its minimal changes and then one new commit, following @specs/packages/git.md; never amend an existing commit.
 Make the commit message explain concisely what changed and why, including relevant verification.
 Identify every new commit you make.
 Credit every AI that contributed to this commit: Coder <coder-llm>.
@@ -73,9 +91,11 @@ Every new-intent phase has two semantic outcomes: direct implementation and new
 Every IR-task phase, including the first phase for an existing IR, identifies the IR and the implemented task, and has two semantic outcomes: more tasks and final task.
 The first phase therefore has four semantic outcomes — direct implementation, new IR, more tasks, and final task — plus the Boss question when the continued IR is ambiguous.
 Each semantic outcome requires affirmative support in Coder's result, but no phase transition shall depend on a fixed presentation format of Coder's reply.
+The Boss-question outcome means that, at the end of this call, Coder has an unanswered clarifying question for Boss whose answer is required to complete the current coding phase. Earlier interim questions resolved or superseded by later affirmative current-phase completion, and prerequisites only for later review, acceptance or release stages, do not establish this outcome.
+A commit statement alone does not establish semantic completion, and contradictory or insufficient evidence supports no forced commit outcome.
 Captain shall use the repository-effect receipt as the authoritative identity of the phase's new commit.
 
-At the end of every phase, Captain shall call playbook `review` and input the following in quotes (`>`):
+At the end of every completed phase, Captain shall call playbook `review` and input the following in quotes (`>`):
 
 > Original intent: \<caller-input\>
 > Review scope: the commit \<code-commit\> from this coding phase and its resulting repository state.

package/reference/sdlc/code.playbook/asset-types.d.ts

@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+
+/** Cancellation only needs the standard synchronous abort check. */
+export interface AssetAbortSignal { throwIfAborted(): void; }
+export type AssetId = `sha256:${string}`;
+export interface SessionAssetRef {
+  readonly assetId: AssetId;
+  readonly byteLength: number;
+  readonly mimeType: string;
+  readonly name?: string;
+}
+export type AssetImport = (
+  | { readonly bytes: Uint8Array; readonly path?: never }
+  | { readonly path: string; readonly bytes?: never }
+) & { readonly mimeType: string; readonly name?: string; readonly signal?: AssetAbortSignal };
+export interface AssetFile {
+  readonly assetId: AssetId;
+  /** Relative filename within this owner's asset directory. */
+  readonly path: string;
+  readonly byteLength: number;
+  readonly metadataPath: string;
+}
+export interface AssetReader {
+  readonly reference: SessionAssetRef;
+  read(options: { readonly offset: number; readonly length: number; readonly signal?: AssetAbortSignal }): Promise<Uint8Array>;
+  close(): Promise<void>;
+}
+export interface SessionTurnInput {
+  readonly text: string;
+  readonly attachments?: readonly SessionAssetRef[];
+}

package/reference/sdlc/code.playbook/bin/launch-config.js

@@ -2149,6 +2149,7 @@ function sessionAgentFromHostAgent(agent, path) {
   }
   return {
     adapter: agent.adapter,
+    ...(agent.browser === undefined ? {} : { browser: fastModeSelection(agent.browser, `${path}.browser`) }),
     model: tuningSelection(agent.model, `${path}.model`),
     effort: tuningSelection(agent.effort, `${path}.effort`),
     ...(agent.fastMode === undefined
@@ -2186,6 +2187,7 @@ export function projectHostAgent(agent, path = "agent") {
   const normalized = cloneJson(agent, path);
   return {
     adapter: normalized.adapter,
+    ...(normalized.browser === undefined ? {} : { browser: fastModeSelection(normalized.browser, `${path}.browser`) }),
     ...(normalized.model?.kind === "value"
       ? { model: normalized.model.value }
       : {}),

package/reference/sdlc/code.playbook/bin/portable-codec.js

@@ -2,6 +2,7 @@
 // SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
 
 import { createHash } from 'node:crypto';
+import { validateAssetRef } from '../session-assets.js';
 import { posix, win32 } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
 import {
@@ -16,7 +17,7 @@ export const EMPTY_REPLAY_SHA256 = createHash('sha256').digest('hex');
 export const sha256 = (bytes) => createHash('sha256').update(bytes).digest('hex');
 const COMMON = ['schemaVersion', 'kind', 'sessionId', 'cwd', 'createdAt', 'updatedAt', 'state', 'replay', 'contextSeq'];
 const RECOVERY = ['structuralProjection', 'lastAppliedExecutionProjection', 'snapshot', 'effectLedger', 'unresolvedEffects'];
-const OPTIONAL = ['retainedGenerations', 'settledAbandonment'];
+const OPTIONAL = ['retainedGenerations', 'settledAbandonment', 'assets'];
 const HEX = /^[0-9a-f]{64}$/;
 const clone = (value) => structuredClone(value);
 const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
@@ -44,11 +45,17 @@ export function validateReplayCheckpoint(value) {
 export function validateSessionManifest(value) {
   if (!object(value) || value.schemaVersion !== 7) throw new Error(`unsupported session manifest schema ${value?.schemaVersion}`);
   const history = value.state === 'history-only';
-  exact(value, [...COMMON, ...(history ? ['reason'] : RECOVERY), ...(value.state === 'uncertain' ? ['uncertain'] : [])], history ? [] : OPTIONAL);
+  exact(value, [...COMMON, ...(history ? ['reason'] : RECOVERY), ...(value.state === 'uncertain' ? ['uncertain'] : [])], history ? ['assets'] : OPTIONAL);
   if (value.kind !== 'captain-session' || !SESSION_ID_PATTERN.test(value.sessionId) || !isRecordedAbsolutePath(value.cwd)) throw new Error('invalid session manifest identity');
   iso(value.createdAt); iso(value.updatedAt);
   if (Date.parse(value.updatedAt) < Date.parse(value.createdAt)) throw new Error('session update precedes creation');
   validateReplayCheckpoint(value.replay);
+  if (value.assets !== undefined) {
+    exact(value.assets, ['version', 'entries']);
+    if (value.assets.version !== 1 || !Array.isArray(value.assets.entries)) throw new Error('unsupported session asset manifest');
+    const ids = new Set();
+    for (const item of value.assets.entries) { const reference = validateAssetRef(item); if (ids.has(reference.assetId)) throw new Error('duplicate session asset reference'); ids.add(reference.assetId); }
+  }
   if (!(history && value.contextSeq === null) && (!Number.isSafeInteger(value.contextSeq) || value.contextSeq <= 0 || value.contextSeq > value.replay.seq)) throw new Error('invalid session context reference');
   if (history) {
     if (!nonempty(value.reason)) throw new Error('history-only session needs a reason');
@@ -60,7 +67,7 @@ export function validateSessionManifest(value) {
   return clone(value);
 }
 function recoveryFromManifestUnchecked(value) {
-  const { replay, contextSeq, ...recovery } = value;
+  const { replay, contextSeq, assets, ...recovery } = value;
   return { ...recovery, schemaVersion: 6 };
 }
 export function recoveryFromManifest(value) {
@@ -68,9 +75,9 @@ export function recoveryFromManifest(value) {
   if (manifest.state === 'history-only') throw new Error(manifest.reason);
   return validateCaptainSessionRecord(recoveryFromManifestUnchecked(manifest));
 }
-export function manifestFromRecovery(value, replay, contextSeq) {
+export function manifestFromRecovery(value, replay, contextSeq, assets) {
   const recovery = projectRecovery(validateCaptainSessionRecord(value));
-  return validateSessionManifest({ ...recovery, schemaVersion: 7, replay, contextSeq });
+  return validateSessionManifest({ ...recovery, schemaVersion: 7, replay, contextSeq, ...(assets === undefined ? {} : { assets }) });
 }
 export function projectRecovery(value) {
   const source = clone(value);

package/reference/sdlc/code.playbook/bin/run.js

@@ -7,6 +7,8 @@
 // presenter; it does not construct a registry runtime or PlaybookPorts itself.
 
 import { randomUUID } from "node:crypto";
+import { workerReportExcerpt, workerRecoveryReportBlock } from "../worker-evidence.js";
+import { createSessionMediaProjector } from "./session-media.js";
 import { attachSessionHints, validateSessionContext } from "./portable-codec.js";
 import { homedir } from "node:os";
 import { resolve } from "node:path";
@@ -995,6 +997,13 @@ export function restoreInterruptedProgress(record, ledger) {
       : `Captain preparation for ${name}: ${step.result.summary}`;
     return `${name} ${step.kind} call: ${step.result === undefined ? 'started; no result was saved' : step.result?.status === undefined ? 'result saved' : `returned ${step.result.status}`}.`;
   });
+  const workerReports = changedBoundaries.flatMap((boundary) => {
+    const completedStep = steps.find((step) => step.kind === 'player' &&
+      step.workerEvidence?.boundaryId === boundary.boundaryId);
+    if (!completedStep) return [];
+    const report = workerReportExcerpt(boundary, completedStep.workerEvidence.playerId, completedStep.result.guard);
+    return report === undefined ? [] : [report];
+  });
   const completedRoots = steps.filter((step) => step.kind === 'completion' && step.result.retention !== 'keep').map((step) => ({ kind: 'clear', rootPlaybookId: step.playbookId }));
   const report = {
     retentionUpdates: completedRoots,
@@ -1008,7 +1017,7 @@ export function restoreInterruptedProgress(record, ledger) {
         ? completion && !saved.frames?.length
           ? 'The completed run is restored; no work was repeated.'
           : 'The run stopped. Its saved position is restored; no work was repeated. Choose how to continue. Before repeating unfinished work, confirm that the earlier worker has stopped and check any outside actions it may have taken.'
-        : 'The exact stopping point was not saved. Files and repository evidence are preserved; no work was repeated. Check the saved work and stop any earlier worker before starting another attempt.', ...facts].join('\n\n'),
+        : 'The exact stopping point was not saved. Files and repository evidence are preserved; no work was repeated. Check the saved work and stop any earlier worker before starting another attempt.', ...facts, ...(workerReports.length ? [workerRecoveryReportBlock(workerReports)] : [])].join('\n\n'),
   };
   if (noWork) return { snapshot: base, report };
   if (saved) {
@@ -1068,6 +1077,7 @@ export async function createCaptainSessionHost({
   signal,
   graphs = [],
   initialVisible = [],
+  approvalHandler,
 }) {
   if (restoreSnapshot !== undefined) await sessionLease.assertContinuable({ cwd, executionProjection: config });
   const hostCapabilities = await createRepositoryEffectCapabilities({
@@ -1115,23 +1125,30 @@ export async function createCaptainSessionHost({
   if (sourceSnapshot !== undefined && !interrupted && typeof sessionLease.consumeHints === "function") {
     sourceSnapshot = attachSessionHints(sourceSnapshot, await sessionLease.consumeHints());
   }
+  let presentationAttachments = [];
+  const mediaProjector = createSessionMediaProjector({ lease: sessionLease, onEvidence: (asset, origin) => shell.recordMediaEvidence(asset, origin.runtimeSessionId) });
   const bufferedRecords = [];
   let presentationReady = false;
   const presentationTurnOffset = restoreSnapshot?.sequences.turn ?? 0;
+  const approvals = createHostApprovalScope(approvalHandler, presentationTurnOffset);
   const forwardRecord = async (record) => {
+    if (record.type === 'turn_started' && presentationAttachments.length) record = { ...record, turn: { ...record.turn, attachments: presentationAttachments } };
     const projected = presentationTurnOffset > 0 && typeof record.turnId === "number"
       ? { ...record, turnId: record.turnId + presentationTurnOffset, ...(record.type === "turn_started" ? { turn: { ...record.turn, id: record.turn.id + presentationTurnOffset } } : {}) }
       : record;
-    for (const observer of observers ?? []) await observer.onRecord?.(projected);
+    for (const value of await mediaProjector.project(projected)) for (const observer of observers ?? []) await observer.onRecord?.(value);
   };
   const bufferedObservers = [{ async onRecord(record) {
     if (!presentationReady) bufferedRecords.push(record);
     else await forwardRecord(record);
   } }];
   const shell = createPlaybookCaptainShell(captainOptionsFromConfig(config), {
+    onTurnAttachments: (references) => { presentationAttachments = references; },
+    beginPreparationMedia: (runtimeSessionId) => mediaProjector.beginPreparation(runtimeSessionId),
     abortPreparation: (reason) => host?.abortActiveTurn(typeof reason === 'string' ? reason : 'Captain preparation exceeded its 150-second limit'),
     loadModule,
     hostCapabilities,
+    ...(typeof sessionLease.resolveAttachments === 'function' ? { resolveAttachments: (references, signal) => sessionLease.resolveAttachments(references, { signal }) } : {}),
     ...(typeof sessionLease.recordProgress === 'function' ? {
       recordProgress: (change) => sessionLease.recordProgress(change),
     } : {}),
@@ -1166,6 +1183,7 @@ export async function createCaptainSessionHost({
       })),
       cwd,
       observers: bufferedObservers,
+      ...(approvals.handler ? { approvalHandler: approvals.handler } : {}),
       ...(signal ? { signal } : {}),
       ...(adapterImports ? { adapterImports } : {}),
     });
@@ -1193,9 +1211,13 @@ export async function createCaptainSessionHost({
     }
     presentationReady = true;
     for (const record of bufferedRecords) await forwardRecord(record);
-    if (interruptedReport) shell.selectInterruptedReport(interrupted.uncertain.input, interruptedReport);
-    return { shell, host, snapshot, reconcileRepositoryEffects, getInterruptedSettlement: (attemptId) => attemptId !== undefined && interruptedSettlement?.attemptId === attemptId ? interruptedSettlement.record : undefined };
+    if (interruptedReport) {
+      shell.setTurnAttachments(interrupted.uncertain.attachments ?? []);
+      shell.selectInterruptedReport(interrupted.uncertain.input, interruptedReport);
+    }
+    return { shell, host, snapshot, reconcileRepositoryEffects, cancelPendingApprovals: approvals.close, getInterruptedSettlement: (attemptId) => attemptId !== undefined && interruptedSettlement?.attemptId === attemptId ? interruptedSettlement.record : undefined };
   } catch (error) {
+    approvals.close();
     let cleanupError;
     try {
       if (host !== undefined) await host.dispose();
@@ -1213,6 +1235,48 @@ export async function createCaptainSessionHost({
   }
 }
 
+// Callback liveness belongs to the host, independently of durable turn state.
+// Closing this scope denies waits without cancelling ordinary graceful work.
+function createHostApprovalScope(handler, turnOffset) {
+  const lifetime = new AbortController();
+  return {
+    close: () => lifetime.abort('session host closing'),
+    handler: typeof handler !== 'function' ? undefined : (envelope, { signal }) => {
+      if (lifetime.signal.aborted || signal.aborted) return Promise.resolve('deny');
+      const controller = new AbortController();
+      return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (decision) => {
+          if (settled) return;
+          settled = true;
+          signal.removeEventListener('abort', cancel);
+          lifetime.signal.removeEventListener('abort', cancel);
+          if (!envelope.request.choices.includes(decision)) controller.abort('Invalid approval decision');
+          resolve(decision);
+        };
+        const fail = (error) => {
+          if (settled) return;
+          settled = true;
+          signal.removeEventListener('abort', cancel);
+          lifetime.signal.removeEventListener('abort', cancel);
+          controller.abort(error);
+          reject(error);
+        };
+        const cancel = () => {
+          controller.abort(signal.aborted ? signal.reason : lifetime.signal.reason);
+          finish('deny');
+        };
+        signal.addEventListener('abort', cancel, { once: true });
+        lifetime.signal.addEventListener('abort', cancel, { once: true });
+        Promise.resolve().then(() => {
+          if (settled) return 'deny';
+          return handler({ ...envelope, turnId: envelope.turnId + turnOffset }, { signal: controller.signal });
+        }).then(finish, fail);
+      });
+    },
+  };
+}
+
 // PBCLI-55: both presentations install one authoritative retention map at the
 // same post-shell, pre-turn boundary. Fresh-session guarded initialization
 // publishes either the intentional empty boundary or the transferred map.

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 });
+}