@sublang/playbook 10.0.0 → 12.0.0

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

@@ -6,65 +6,75 @@
 // in tmux. The core below uses cligent's ordinary tmux-play runtime without a
 // presenter; it does not construct a registry runtime or PlaybookPorts itself.
 
-import { randomUUID } from 'node:crypto';
-import { homedir } from 'node:os';
-import { resolve } from 'node:path';
-import { isDeepStrictEqual } from 'node:util';
-import { createTmuxPlayRuntime } from '@sublang/cligent/tmux-play';
+import { randomUUID } from "node:crypto";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { assertFastModeSupported } from "@sublang/cligent";
+import { createTmuxPlayRuntime } from "@sublang/cligent/tmux-play";
 import {
   assertPlaybookEffectLedger,
   emptyPlaybookEffectLedger,
-} from '../../../../src/xstate-runtime.js';
+} from "../../../../src/xstate-runtime.js";
 import {
   assertPlaybookCaptainShellSnapshot,
   createPlaybookCaptainShell,
-} from '../playbook-captain.js';
+} from "../playbook-captain.js";
 import {
   adapterSdkFailureLines,
   checkAdapterSdks,
   mappedSdksFor,
   probeAdapterSdk,
-} from './adapter-sdk.js';
+} from "./adapter-sdk.js";
 import {
   checkReadiness,
   invalidRegistryEntryReason,
   loadLaunchPlan,
   projectHostAgent,
+  resolveLaunchSessionsDir,
+  relocateLegacyUserConfig,
+  resolveLegacyUserConfigPath,
   resolveUserConfigPath,
   snapshotRegistryEntry,
-} from './launch-config.js';
-import { prepareConfiguredRegistries } from './provision.js';
+} from "./launch-config.js";
+import { prepareConfiguredRegistries } from "./provision.js";
+import {
+  createReplayRecordObserver,
+  replayIncompleteMessage,
+} from "./replay-observer.js";
 import {
   createRepositoryEffectCapabilities,
   refreshRepositoryEffectCapabilities,
   recoverIncompleteRepositoryEffects,
-} from './repository-effects.js';
+} from "./repository-effects.js";
 import {
   assertCaptainSessionExecutionCompatible,
+  assertCaptainSessionsDirectoryUsable,
   captainSessionSelectedMembers,
   createCaptainSessionStore,
   projectCaptainSessionStructure,
   SESSION_ID_PATTERN,
   validateCaptainSessionExecutionProjection,
   validateCaptainSessionRecord,
-} from './session-store.js';
+} from "./session-store.js";
 
 const EXIT = { ok: 0, argument: 1, turn: 2 };
 const UUID_PATTERN = SESSION_ID_PATTERN;
+const HEADLESS_REPLAY_CHANNELS = new WeakMap();
 class HeadlessHostSetupError extends Error {
   constructor(cause) {
     super(message(cause));
-    this.name = 'HeadlessHostSetupError';
+    this.name = "HeadlessHostSetupError";
     this.cause = cause;
   }
 }
 const RETIRED_FLAGS = new Set([
-  '--player',
-  '--captain',
-  '--option',
-  '--cwd',
-  '--last',
-  '--config',
+  "--player",
+  "--captain",
+  "--option",
+  "--cwd",
+  "--last",
+  "--config",
 ]);
 
 export async function runPlaybookRun(options = {}) {
@@ -81,15 +91,25 @@ export async function runPlaybookRun(options = {}) {
   }
   if (args.help) {
     const env = options.env ?? process.env;
-    const home = options.homeDir ?? env.HOME ?? homedir();
+    const home =
+      options.homeDir ??
+      (typeof env.HOME === "string" && env.HOME.trim().length > 0
+        ? env.HOME
+        : homedir());
     const userConfigPath =
       options.userConfigPath ?? resolveUserConfigPath(env, home);
+    // PBCLI-17: help resolves the path but writes nothing, so it neither
+    // seeds nor relocates.
     await writeStream(stdout, runHelpText(userConfigPath));
     return { code: EXIT.ok };
   }
 
   const env = options.env ?? process.env;
-  const home = options.homeDir ?? env.HOME ?? homedir();
+  const home =
+    options.homeDir ??
+    (typeof env.HOME === "string" && env.HOME.trim().length > 0
+      ? env.HOME
+      : homedir());
   const recovering = args.retryUncertain || args.discardUncertain;
   const continuing = args.continue || args.sessionId !== undefined;
   let input = args.input;
@@ -104,6 +124,47 @@ export async function runPlaybookRun(options = {}) {
     input = resolvedInput.input;
   }
 
+  const userConfigPath =
+    options.userConfigPath ?? resolveUserConfigPath(env, home);
+  // DR-043: move a pre-relocation config to the canonical path before any
+  // read, seed, or plan work observes its absence.
+  if (options.userConfigPath === undefined) {
+    try {
+      relocateLegacyUserConfig(
+        userConfigPath,
+        resolveLegacyUserConfigPath(env, home),
+        (line) => stderr.write(line),
+      );
+    } catch (error) {
+      await writeStream(stderr, `playbook run: ${message(error)}\n`);
+      return { code: EXIT.argument };
+    }
+  }
+  const bootstrapConfigNotices = [];
+  let resolvedSessionsDir;
+  if (options.sessionStore === undefined) {
+    try {
+      resolvedSessionsDir = resolveLaunchSessionsDir({
+        userConfigPath,
+        overlayPaths: args.withPaths,
+        env,
+        homeDir: home,
+        ...(options.sessionsDir !== undefined
+          ? { sessionsDir: options.sessionsDir }
+          : {}),
+        preparePrimary: !continuing,
+        onNotice: (line) => bootstrapConfigNotices.push(line),
+      });
+      await assertCaptainSessionsDirectoryUsable(resolvedSessionsDir);
+    } catch (error) {
+      for (const line of bootstrapConfigNotices) {
+        await writeStream(stderr, line);
+      }
+      await writeStream(stderr, `playbook run: ${message(error)}\n`);
+      return { code: EXIT.argument };
+    }
+  }
+
   let store;
   try {
     store =
@@ -111,7 +172,7 @@ export async function runPlaybookRun(options = {}) {
       createCaptainSessionStore({
         env,
         homeDir: home,
-        ...(options.sessionsDir ? { sessionsDir: options.sessionsDir } : {}),
+        sessionsDir: resolvedSessionsDir,
         ...(options.now ? { now: options.now } : {}),
         ...(options.createSessionTempId
           ? { createTempId: options.createSessionTempId }
@@ -128,6 +189,7 @@ export async function runPlaybookRun(options = {}) {
   let config;
   let cwd;
   let restoreSnapshot;
+  let replayChannel;
   const loadModule = memoizedModuleLoader(
     options.loadModule ?? ((specifier) => import(specifier)),
   );
@@ -144,8 +206,8 @@ export async function runPlaybookRun(options = {}) {
               onLegacyRecord: (record) =>
                 reportSkippedCaptainSession(
                   stderr,
-                  'playbook run',
-                  'legacy',
+                  "playbook run",
+                  "legacy",
                   record,
                 ),
             }),
@@ -164,9 +226,15 @@ export async function runPlaybookRun(options = {}) {
       }
       throwIfAborted(options.signal);
       lease = await store.acquire(sessionId);
+      replayChannel = createHeadlessReplayChannel({
+        lease,
+        sessionId,
+        stderr,
+      });
+      await reportHeadlessReplay(replayChannel);
       throwIfAborted(options.signal);
       const authoritative =
-        typeof lease.recoverUnresolvedEffectAbandonment === 'function'
+        typeof lease.recoverUnresolvedEffectAbandonment === "function"
           ? await lease.recoverUnresolvedEffectAbandonment()
           : await lease.read();
       throwIfAborted(options.signal);
@@ -190,7 +258,7 @@ export async function runPlaybookRun(options = {}) {
       return { code: EXIT.argument };
     }
 
-    if (priorRecord.state === 'uncertain') {
+    if (priorRecord.state === "uncertain") {
       if (args.discardUncertain) {
         try {
           throwIfAborted(options.signal);
@@ -271,10 +339,8 @@ export async function runPlaybookRun(options = {}) {
   }
 
   if (!continuing || !args.retryUncertain) {
-    const userConfigPath =
-      options.userConfigPath ?? resolveUserConfigPath(env, home);
     let plan;
-    const configNotices = [];
+    const configNotices = [...bootstrapConfigNotices];
     try {
       throwIfAborted(options.signal);
       plan = await loadLaunchPlan({
@@ -316,7 +382,7 @@ export async function runPlaybookRun(options = {}) {
         );
       } else {
         sessionId = (options.createLogicalSessionId ?? randomUUID)();
-        if (typeof sessionId !== 'string' || !UUID_PATTERN.test(sessionId)) {
+        if (typeof sessionId !== "string" || !UUID_PATTERN.test(sessionId)) {
           throw new Error(
             `logical session id generator returned a non-UUID value: ${JSON.stringify(sessionId)}`,
           );
@@ -419,6 +485,12 @@ export async function runPlaybookRun(options = {}) {
     try {
       throwIfAborted(options.signal);
       lease = await store.acquire(sessionId);
+      replayChannel = createHeadlessReplayChannel({
+        lease,
+        sessionId,
+        stderr,
+      });
+      await reportHeadlessReplay(replayChannel);
       throwIfAborted(options.signal);
     } catch (error) {
       const releaseError = await releaseLease(lease);
@@ -459,6 +531,7 @@ export async function runPlaybookRun(options = {}) {
       sessionId,
       cwd,
       sessionLease: lease,
+      replayObserver: replayChannel?.observer,
       loadModule,
       stderr,
       verbose: args.verbose,
@@ -476,16 +549,11 @@ export async function runPlaybookRun(options = {}) {
         : {}),
       ...(options.createEffectLedgerWriteAhead
         ? {
-            createEffectLedgerWriteAhead:
-              options.createEffectLedgerWriteAhead,
+            createEffectLedgerWriteAhead: options.createEffectLedgerWriteAhead,
           }
         : {}),
-      ...(restoreSnapshot !== undefined
-        ? { restoreSnapshot }
-        : {}),
-      ...(args.retryUncertain
-        ? { reconcileUncertainTurnReplay: true }
-        : {}),
+      ...(restoreSnapshot !== undefined ? { restoreSnapshot } : {}),
+      ...(args.retryUncertain ? { reconcileUncertainTurnReplay: true } : {}),
       ...(options.signal ? { signal: options.signal } : {}),
       beforeBossTurn: async (
         baselineSnapshot,
@@ -503,8 +571,7 @@ export async function runPlaybookRun(options = {}) {
             ? {
                 freshBoundary: {
                   cwd,
-                  structuralProjection:
-                    projectCaptainSessionStructure(config),
+                  structuralProjection: projectCaptainSessionStructure(config),
                   executionProjection: config,
                   snapshot: baselineSnapshot,
                 },
@@ -514,15 +581,15 @@ export async function runPlaybookRun(options = {}) {
                 onLegacyRecord: (record) =>
                   reportSkippedCaptainSession(
                     stderr,
-                    'playbook run',
-                    'legacy',
+                    "playbook run",
+                    "legacy",
                     record,
                   ),
                 onInvalidRecord: (record) =>
                   reportSkippedCaptainSession(
                     stderr,
-                    'playbook run',
-                    'invalid',
+                    "playbook run",
+                    "invalid",
                     record,
                   ),
               }
@@ -544,7 +611,9 @@ export async function runPlaybookRun(options = {}) {
       },
       assertBeforeBossTurn: () => lease.assertOwner(),
     });
+    await reportHeadlessReplay(replayChannel);
   } catch (error) {
+    await reportHeadlessReplay(replayChannel);
     const cleanupIncomplete = isCaptainSessionHostCleanupIncomplete(error);
     let abandonmentError;
     if (
@@ -565,7 +634,7 @@ export async function runPlaybookRun(options = {}) {
     if (cleanupIncomplete) {
       await writeStream(
         stderr,
-        'playbook run: writer lease retained until process exit because host cleanup was incomplete\n',
+        "playbook run: writer lease retained until process exit because host cleanup was incomplete\n",
       );
     }
     if (releaseError !== undefined) {
@@ -599,7 +668,9 @@ export async function runPlaybookRun(options = {}) {
       unresolvedEffects: settled.unresolvedEffects,
       retentionUpdates: settled.retentionUpdates,
     });
+    await reportHeadlessReplay(replayChannel);
   } catch (error) {
+    await reportHeadlessReplay(replayChannel);
     let cleanupError;
     try {
       await settled.dispose();
@@ -615,13 +686,10 @@ export async function runPlaybookRun(options = {}) {
         [error, cleanupError],
         `Captain session settlement failed (${message(error)}) and host cleanup also failed: ${message(cleanupError)}`,
       );
+      await writeStream(stderr, `playbook run: ${message(cleanupFailure)}\n`);
       await writeStream(
         stderr,
-        `playbook run: ${message(cleanupFailure)}\n`,
-      );
-      await writeStream(
-        stderr,
-        'playbook run: writer lease retained until process exit because host cleanup was incomplete\n',
+        "playbook run: writer lease retained until process exit because host cleanup was incomplete\n",
       );
       return { code: EXIT.turn };
     }
@@ -647,7 +715,7 @@ export async function runPlaybookRun(options = {}) {
   if (options.signal?.aborted) {
     await writeStream(
       stderr,
-      'playbook run: Captain turn was interrupted; reply withheld\n',
+      "playbook run: Captain turn was interrupted; reply withheld\n",
     );
     return { code: EXIT.turn, sessionId, record: durableRecord };
   }
@@ -686,6 +754,7 @@ export async function driveHeadlessCaptainTurn({
   sessionId,
   cwd,
   sessionLease,
+  replayObserver,
   loadModule,
   stderr,
   verbose = false,
@@ -716,15 +785,16 @@ export async function driveHeadlessCaptainTurn({
         observers: [
           {
             async onRecord(record) {
-              if (record.type === 'captain_reply') {
+              if (record.type === "captain_reply") {
                 replies.push(record.text);
-              } else if (record.type === 'captain_status') {
+              } else if (record.type === "captain_status") {
                 await writeStream(stderr, `${record.message}\n`);
-              } else if (verbose && record.type === 'captain_telemetry') {
+              } else if (verbose && record.type === "captain_telemetry") {
                 await writeStream(stderr, `\u00b7 ${record.topic}\n`);
               }
             },
           },
+          ...(replayObserver === undefined ? [] : [replayObserver]),
         ],
         ...(signal ? { signal } : {}),
         ...(adapterImports ? { adapterImports } : {}),
@@ -750,13 +820,13 @@ export async function driveHeadlessCaptainTurn({
     }
     await assertBeforeBossTurn?.();
     if (signal?.aborted) {
-      throw signal.reason ?? new Error('Captain turn aborted');
+      throw signal.reason ?? new Error("Captain turn aborted");
     }
     await host.runBossTurn(input);
     throwIfAborted(signal);
     if (
       replies.length !== 1 ||
-      typeof replies[0] !== 'string' ||
+      typeof replies[0] !== "string" ||
       replies[0].trim().length === 0
     ) {
       throw new Error(
@@ -764,11 +834,13 @@ export async function driveHeadlessCaptainTurn({
       );
     }
     if (shell === undefined) {
-      throw new Error('Captain shell host initialized without a shell');
+      throw new Error("Captain shell host initialized without a shell");
     }
     const settlement = shell.exportSettlement();
     if (settlement === undefined) {
-      throw new Error('Captain turn settled without an exportable session settlement');
+      throw new Error(
+        "Captain turn settled without an exportable session settlement",
+      );
     }
     const { snapshot, unresolvedEffects, retentionUpdates } = settlement;
     if (
@@ -776,7 +848,7 @@ export async function driveHeadlessCaptainTurn({
       snapshot.issuedSessionIds?.includes(sessionId)
     ) {
       throw new Error(
-        'logical session id collided with an internal Captain session id',
+        "logical session id collided with an internal Captain session id",
       );
     }
     return {
@@ -815,8 +887,8 @@ export async function driveHeadlessCaptainTurn({
 export class CaptainSessionHostCleanupError extends AggregateError {
   constructor(errors, messageText) {
     super(errors, messageText);
-    this.name = 'CaptainSessionHostCleanupError';
-    this.code = 'PLAYBOOK_CAPTAIN_HOST_CLEANUP_INCOMPLETE';
+    this.name = "CaptainSessionHostCleanupError";
+    this.code = "PLAYBOOK_CAPTAIN_HOST_CLEANUP_INCOMPLETE";
   }
 }
 
@@ -855,7 +927,7 @@ function effectLedgerSnapshotFromCapabilities(hostCapabilities) {
       )
     ) {
       throw new Error(
-        'schema-3 current-host capabilities disagree on their effect ledger',
+        "schema-3 current-host capabilities disagree on their effect ledger",
       );
     }
   }
@@ -877,33 +949,29 @@ function reconcileWholeTurnReplaySnapshot(snapshot, ledger, catalog) {
   const currentPrefix = current.boundaries.slice(0, checkpointBoundaryCount);
   if (!isDeepStrictEqual(currentPrefix, checkpoint.boundaries)) {
     throw new Error(
-      'Captain uncertain turn repository-effect reconciliation cannot restore a changed pre-turn boundary',
+      "Captain uncertain turn repository-effect reconciliation cannot restore a changed pre-turn boundary",
     );
   }
   if (
-    !isDeepStrictEqual(
-      current.logicalOperations,
-      checkpoint.logicalOperations,
-    )
+    !isDeepStrictEqual(current.logicalOperations, checkpoint.logicalOperations)
   ) {
     throw new Error(
-      'Captain uncertain turn repository-effect reconciliation found deferred logical-operation progress and cannot replay the Boss turn',
+      "Captain uncertain turn repository-effect reconciliation found deferred logical-operation progress and cannot replay the Boss turn",
     );
   }
   const suffix = current.boundaries.slice(checkpointBoundaryCount);
   const blocking = suffix.find(
-    (boundary) =>
-      boundary.physicalReceipt?.classification !== 'unchanged',
+    (boundary) => boundary.physicalReceipt?.classification !== "unchanged",
   );
   if (blocking !== undefined) {
     const classification =
-      blocking.physicalReceipt?.classification ?? 'incomplete';
+      blocking.physicalReceipt?.classification ?? "incomplete";
     throw new Error(
       `Captain uncertain turn repository-effect boundary ${JSON.stringify(blocking.boundaryId)} is ${classification}; whole-turn replay remains parked for reconciliation`,
     );
   }
   const frames =
-    snapshot.mode !== 'engaged.parked'
+    snapshot.mode !== "engaged.parked"
       ? undefined
       : snapshot.frames.map((frame) => {
           if (catalog[frame.playbookId]?.artifactSchema !== 3) {
@@ -973,20 +1041,17 @@ export async function createCaptainSessionHost({
     !isDeepStrictEqual(sourceSnapshot.effectLedger, currentEffectLedger())
   ) {
     const recovered =
-      typeof sessionLease.read === 'function'
+      typeof sessionLease.read === "function"
         ? await sessionLease.read()
         : undefined;
     if (
-      recovered?.state === 'settled' &&
+      recovered?.state === "settled" &&
       isDeepStrictEqual(recovered.snapshot.effectLedger, currentEffectLedger())
     ) {
       sourceSnapshot = recovered.snapshot;
     }
   }
-  if (
-    sourceSnapshot !== undefined &&
-    reconcileUncertainTurnReplay
-  ) {
+  if (sourceSnapshot !== undefined && reconcileUncertainTurnReplay) {
     sourceSnapshot = reconcileWholeTurnReplaySnapshot(
       sourceSnapshot,
       currentEffectLedger(),
@@ -997,15 +1062,14 @@ export async function createCaptainSessionHost({
     !isDeepStrictEqual(sourceSnapshot.effectLedger, currentEffectLedger())
   ) {
     throw new Error(
-      'Captain session effect ledger requires reconciliation before source-state restoration',
+      "Captain session effect ledger requires reconciliation before source-state restoration",
     );
   }
   const shell = createPlaybookCaptainShell(captainOptionsFromConfig(config), {
     loadModule,
     hostCapabilities,
     unresolvedEffectSettlement: {
-      begin: (input) =>
-        sessionLease.beginUnresolvedEffectAbandonment(input),
+      begin: (input) => sessionLease.beginUnresolvedEffectAbandonment(input),
       complete: (input) =>
         sessionLease.completeUnresolvedEffectAbandonment(input),
     },
@@ -1021,7 +1085,7 @@ export async function createCaptainSessionHost({
       captain,
       captainConfig: projectHostAgent(
         config.captain,
-        'Captain execution config.captain',
+        "Captain execution config.captain",
       ),
       players: config.players.map(({ id, ...agent }) => ({
         id,
@@ -1035,11 +1099,14 @@ export async function createCaptainSessionHost({
     const snapshot = shell.exportSnapshot();
     if (snapshot === undefined) {
       throw new Error(
-        'Captain shell initialized without an exportable session snapshot',
+        "Captain shell initialized without an exportable session snapshot",
       );
     }
-    if (sourceSnapshot !== undefined && !isDeepStrictEqual(snapshot, sourceSnapshot)) {
-      throw new Error('restored Captain snapshot changed before the Boss turn');
+    if (
+      sourceSnapshot !== undefined &&
+      !isDeepStrictEqual(snapshot, sourceSnapshot)
+    ) {
+      throw new Error("restored Captain snapshot changed before the Boss turn");
     }
     if (sessionId !== undefined) {
       assertLogicalSessionIdDistinct({ sessionId, snapshot });
@@ -1147,6 +1214,7 @@ export async function validateFrozenExecutionConfig(
     structuralProjection,
     executionProjection,
   );
+  assertFrozenFastModesSupported(config);
   const catalogItems = Object.entries(config.catalog);
 
   // Preserve the complete-catalog preparation transaction: prepare every
@@ -1162,7 +1230,9 @@ export async function validateFrozenExecutionConfig(
         authoredFrom: item.from,
       });
     } catch (cause) {
-      throw new Error(`stored playbook ${JSON.stringify(id)} failed to prepare: ${message(cause)}`);
+      throw new Error(
+        `stored playbook ${JSON.stringify(id)} failed to prepare: ${message(cause)}`,
+      );
     }
     if (prepared !== undefined && prepared !== item.from) {
       throw new Error(
@@ -1176,10 +1246,14 @@ export async function validateFrozenExecutionConfig(
     try {
       entry = snapshotRegistryEntry((await loadModule(item.from))?.default);
     } catch (cause) {
-      throw new Error(`stored playbook ${JSON.stringify(id)} failed to import: ${message(cause)}`);
+      throw new Error(
+        `stored playbook ${JSON.stringify(id)} failed to import: ${message(cause)}`,
+      );
     }
     if (invalidRegistryEntryReason(entry) !== undefined) {
-      throw new Error(`stored playbook ${JSON.stringify(id)} exposes no valid registry entry`);
+      throw new Error(
+        `stored playbook ${JSON.stringify(id)} exposes no valid registry entry`,
+      );
     }
     if (
       entry.id !== id ||
@@ -1187,10 +1261,7 @@ export async function validateFrozenExecutionConfig(
       entry.intent !== item.intent ||
       entry.artifactSchema !== item.artifactSchema ||
       !isDeepStrictEqual(entry.requiredRoleIds, item.requiredRoleIds) ||
-      !isDeepStrictEqual(
-        entry.concurrentRoleSets,
-        item.concurrentRoleSets,
-      )
+      !isDeepStrictEqual(entry.concurrentRoleSets, item.concurrentRoleSets)
     ) {
       throw new Error(
         `stored playbook ${JSON.stringify(id)} no longer matches its recorded manifest identity`,
@@ -1200,6 +1271,44 @@ export async function validateFrozenExecutionConfig(
   return config;
 }
 
+function assertFrozenFastModesSupported(config) {
+  if (config.captain.fastMode !== undefined) {
+    assertFastModeSupported(
+      config.captain.adapter,
+      "stored Captain fastMode",
+    );
+  }
+
+  const playerAdapters = new Map();
+  for (const player of config.players) {
+    playerAdapters.set(player.id, player.adapter);
+    if (player.fastMode !== undefined) {
+      assertFastModeSupported(
+        player.adapter,
+        `stored player ${JSON.stringify(player.id)} fastMode`,
+      );
+    }
+  }
+
+  for (const [playbookId, item] of Object.entries(config.catalog)) {
+    for (const [roleId, binding] of Object.entries(item.roles)) {
+      if (binding.fastMode === undefined) continue;
+      const adapter = playerAdapters.get(binding.playerId);
+      if (adapter === undefined) {
+        throw new Error(
+          `stored playbook ${JSON.stringify(playbookId)} role ` +
+            `${JSON.stringify(roleId)} names an unknown player`,
+        );
+      }
+      assertFastModeSupported(
+        adapter,
+        `stored playbook ${JSON.stringify(playbookId)} role ` +
+          `${JSON.stringify(roleId)} fastMode`,
+      );
+    }
+  }
+}
+
 function adaptersFromExecutionConfig(config) {
   return [
     ...new Set([
@@ -1216,7 +1325,7 @@ function assertLogicalSessionIdDistinct(record) {
       record.snapshot.issuedSessionIds.includes(record.sessionId))
   ) {
     throw new Error(
-      'logical session id collides with an internal Captain session id',
+      "logical session id collides with an internal Captain session id",
     );
   }
 }
@@ -1225,7 +1334,10 @@ function memoizedModuleLoader(loadModule) {
   const modules = new Map();
   return (specifier) => {
     if (!modules.has(specifier)) {
-      modules.set(specifier, Promise.resolve().then(() => loadModule(specifier)));
+      modules.set(
+        specifier,
+        Promise.resolve().then(() => loadModule(specifier)),
+      );
     }
     return modules.get(specifier);
   };
@@ -1250,7 +1362,7 @@ export function captainOptionsFromConfig(config) {
         config.players.map(({ id, ...agent }) => [id, cloneJson(agent)]),
       ),
     },
-    ...(typeof config.captain.adapter === 'string' &&
+    ...(typeof config.captain.adapter === "string" &&
     config.captain.adapter.length > 0
       ? { captainAdapter: config.captain.adapter }
       : {}),
@@ -1284,65 +1396,65 @@ export function parseRunArgs(argv) {
   const positionals = [];
   for (let index = 0; index < argv.length; index += 1) {
     const arg = argv[index];
-    if (arg === '--') {
+    if (arg === "--") {
       parsed.terminated = true;
       positionals.push(...argv.slice(index + 1));
       break;
     }
-    if (arg === '--help' || arg === '-h') parsed.help = true;
-    else if (arg === '--json') parsed.json = true;
-    else if (arg === '--verbose') parsed.verbose = true;
-    else if (arg === '--no-provision') parsed.noProvision = true;
-    else if (arg === '--retry-uncertain') {
+    if (arg === "--help" || arg === "-h") parsed.help = true;
+    else if (arg === "--json") parsed.json = true;
+    else if (arg === "--verbose") parsed.verbose = true;
+    else if (arg === "--no-provision") parsed.noProvision = true;
+    else if (arg === "--retry-uncertain") {
       if (parsed.retryUncertain) {
-        throw new Error('--retry-uncertain may be specified only once');
+        throw new Error("--retry-uncertain may be specified only once");
       }
       parsed.retryUncertain = true;
-    } else if (arg === '--discard-uncertain') {
+    } else if (arg === "--discard-uncertain") {
       if (parsed.discardUncertain) {
-        throw new Error('--discard-uncertain may be specified only once');
+        throw new Error("--discard-uncertain may be specified only once");
       }
       parsed.discardUncertain = true;
-    }
-    else if (arg === '--continue') {
-      if (parsed.continue) throw new Error('--continue may be specified only once');
+    } else if (arg === "--continue") {
+      if (parsed.continue)
+        throw new Error("--continue may be specified only once");
       parsed.continue = true;
-    } else if (arg === '--session') {
+    } else if (arg === "--session") {
       const value = argv[index + 1];
-      if (value === undefined || value === '') {
-        throw new Error('--session needs a UUID value');
+      if (value === undefined || value === "") {
+        throw new Error("--session needs a UUID value");
       }
       if (parsed.sessionId !== undefined) {
-        throw new Error('--session may be specified only once');
+        throw new Error("--session may be specified only once");
       }
       parsed.sessionId = value;
       index += 1;
-    } else if (arg.startsWith('--session=')) {
-      const value = arg.slice('--session='.length);
-      if (value === '') throw new Error('--session needs a UUID value');
+    } else if (arg.startsWith("--session=")) {
+      const value = arg.slice("--session=".length);
+      if (value === "") throw new Error("--session needs a UUID value");
       if (parsed.sessionId !== undefined) {
-        throw new Error('--session may be specified only once');
+        throw new Error("--session may be specified only once");
       }
       parsed.sessionId = value;
-    } else if (arg === '--with') {
+    } else if (arg === "--with") {
       const value = argv[index + 1];
-      if (value === undefined || value === '') {
-        throw new Error('--with needs a value');
+      if (value === undefined || value === "") {
+        throw new Error("--with needs a value");
       }
       parsed.withPaths.push(value);
       index += 1;
-    } else if (arg.startsWith('--with=')) {
-      const value = arg.slice('--with='.length);
-      if (value === '') throw new Error('--with needs a value');
+    } else if (arg.startsWith("--with=")) {
+      const value = arg.slice("--with=".length);
+      if (value === "") throw new Error("--with needs a value");
       parsed.withPaths.push(value);
     } else if (
       RETIRED_FLAGS.has(arg) ||
       [...RETIRED_FLAGS].some((flag) => arg.startsWith(`${flag}=`))
     ) {
       throw new Error(
-        `${arg.split('=')[0]} was removed; configure the shared Captain session in playbook.config.yaml or a --with overlay`,
+        `${arg.split("=")[0]} was removed; configure the shared Captain session in playbook.config.yaml or a --with overlay`,
       );
-    } else if (arg.startsWith('-')) {
+    } else if (arg.startsWith("-")) {
       throw new Error(`unknown option ${arg}`);
     } else {
       positionals.push(arg);
@@ -1350,15 +1462,15 @@ export function parseRunArgs(argv) {
   }
   if (positionals.length > 1) {
     throw new Error(
-      'expected at most one [input] argument; quote multi-word input as one shell argument',
+      "expected at most one [input] argument; quote multi-word input as one shell argument",
     );
   }
   if (parsed.continue && parsed.sessionId !== undefined) {
-    throw new Error('--continue and --session are mutually exclusive');
+    throw new Error("--continue and --session are mutually exclusive");
   }
   if (parsed.retryUncertain && parsed.discardUncertain) {
     throw new Error(
-      '--retry-uncertain and --discard-uncertain are mutually exclusive',
+      "--retry-uncertain and --discard-uncertain are mutually exclusive",
     );
   }
   if (
@@ -1366,7 +1478,7 @@ export function parseRunArgs(argv) {
     parsed.sessionId === undefined
   ) {
     throw new Error(
-      '--retry-uncertain and --discard-uncertain require --session <id>',
+      "--retry-uncertain and --discard-uncertain require --session <id>",
     );
   }
   if (
@@ -1374,7 +1486,7 @@ export function parseRunArgs(argv) {
     (parsed.continue || positionals.length > 0)
   ) {
     throw new Error(
-      'uncertain-turn recovery accepts only an explicit --session and no input',
+      "uncertain-turn recovery accepts only an explicit --session and no input",
     );
   }
   if (
@@ -1382,20 +1494,20 @@ export function parseRunArgs(argv) {
     (parsed.json || parsed.verbose || parsed.noProvision)
   ) {
     throw new Error(
-      '--discard-uncertain does not accept --json, --verbose, or --no-provision',
+      "--discard-uncertain does not accept --json, --verbose, or --no-provision",
     );
   }
   if (
     (parsed.retryUncertain || parsed.discardUncertain) &&
     parsed.withPaths.length > 0
   ) {
-    throw new Error('--with is unavailable during uncertain-turn recovery');
+    throw new Error("--with is unavailable during uncertain-turn recovery");
   }
   if (
     parsed.sessionId !== undefined &&
     !SESSION_ID_PATTERN.test(parsed.sessionId)
   ) {
-    throw new Error('--session needs a canonical UUID value');
+    throw new Error("--session needs a canonical UUID value");
   }
   parsed.input = positionals[0];
   return parsed;
@@ -1418,18 +1530,15 @@ async function reportReadinessFailure({
     const [first, ...rest] = lines;
     await writeStream(
       stderr,
-      [
-        ...(first ? [`playbook run: ${first}`] : []),
-        ...rest,
-      ]
+      [...(first ? [`playbook run: ${first}`] : []), ...rest]
         .map((line) => `${line}\n`)
-        .join(''),
+        .join(""),
     );
   }
   if (failingAdapters.length > 0) {
     await writeStream(
       stderr,
-      `playbook run: adapters not ready: ${failingAdapters.join(', ')}\n`,
+      `playbook run: adapters not ready: ${failingAdapters.join(", ")}\n`,
     );
   }
 }
@@ -1453,7 +1562,7 @@ async function resolveBossInput(input, options, stderr) {
   if (resolved.trim().length === 0) {
     await writeStream(
       stderr,
-      'playbook run: empty input; pass one argument or pipe a Boss message on stdin\n',
+      "playbook run: empty input; pass one argument or pipe a Boss message on stdin\n",
     );
     return { ok: false };
   }
@@ -1462,22 +1571,22 @@ async function resolveBossInput(input, options, stderr) {
 
 async function awaitWithAbort(value, signal) {
   if (signal === undefined) return value;
-  if (signal.aborted) throw signal.reason ?? new Error('operation aborted');
+  if (signal.aborted) throw signal.reason ?? new Error("operation aborted");
   let onAbort;
   const aborted = new Promise((_, reject) => {
-    onAbort = () => reject(signal.reason ?? new Error('operation aborted'));
-    signal.addEventListener('abort', onAbort, { once: true });
+    onAbort = () => reject(signal.reason ?? new Error("operation aborted"));
+    signal.addEventListener("abort", onAbort, { once: true });
   });
   try {
     return await Promise.race([value, aborted]);
   } finally {
-    signal.removeEventListener('abort', onAbort);
+    signal.removeEventListener("abort", onAbort);
   }
 }
 
 function throwIfAborted(signal) {
   if (signal?.aborted) {
-    throw signal.reason ?? new Error('operation aborted');
+    throw signal.reason ?? new Error("operation aborted");
   }
 }
 
@@ -1488,14 +1597,14 @@ function registryPreparer(args, options, stderr) {
       enabled: !args.noProvision,
       stderr,
       hostRoots: options.hostRoots,
-      commandName: 'playbook run',
+      commandName: "playbook run",
     })
   );
 }
 
 function createAttemptId(options) {
   const attemptId = (options.createAttemptId ?? randomUUID)();
-  if (typeof attemptId !== 'string' || !UUID_PATTERN.test(attemptId)) {
+  if (typeof attemptId !== "string" || !UUID_PATTERN.test(attemptId)) {
     throw new Error(
       `uncertain turn attempt id generator returned a non-UUID value: ${JSON.stringify(attemptId)}`,
     );
@@ -1505,36 +1614,80 @@ function createAttemptId(options) {
 
 async function releaseLease(lease) {
   if (lease === undefined) return undefined;
+  const replayChannel = HEADLESS_REPLAY_CHANNELS.get(lease);
   try {
-    await lease.release();
+    const status = await lease.release();
+    await reportHeadlessReplay(replayChannel, status);
+    HEADLESS_REPLAY_CHANNELS.delete(lease);
     return undefined;
   } catch (error) {
+    await reportHeadlessReplay(replayChannel);
     return error;
   }
 }
 
+function createHeadlessReplayChannel({ lease, sessionId, stderr }) {
+  if (
+    typeof lease?.append !== "function" ||
+    typeof lease?.streamStatus !== "function"
+  ) {
+    return undefined;
+  }
+  let warningPending = false;
+  let warningAttempted = false;
+  const replay = createReplayRecordObserver({
+    lease,
+    onIncomplete() {
+      warningPending = true;
+    },
+  });
+  const channel = Object.freeze({
+    ...replay,
+    async flushWarning() {
+      if (!warningPending || warningAttempted) return;
+      warningAttempted = true;
+      try {
+        await writeStream(
+          stderr,
+          `playbook run: ${replayIncompleteMessage(sessionId)}\n`,
+        );
+      } catch {
+        // The bounded warning is best-effort and never changes run outcome.
+      }
+    },
+  });
+  HEADLESS_REPLAY_CHANNELS.set(lease, channel);
+  return channel;
+}
+
+async function reportHeadlessReplay(channel, status) {
+  if (channel === undefined) return;
+  await channel.reportIfIncomplete(status);
+  await channel.flushWarning();
+}
+
 async function reportUncertainSession(stderr, sessionId) {
   await writeStream(
     stderr,
     [
       `playbook run: Captain session ${JSON.stringify(sessionId)} has an uncertain turn and will not be replayed automatically`,
-      'Retry may duplicate external effects from the interrupted attempt; discard abandons that attempted turn.',
+      "Retry may duplicate external effects from the interrupted attempt; discard abandons that attempted turn.",
       `playbook run --session ${sessionId} --retry-uncertain`,
       `playbook run --session ${sessionId} --discard-uncertain`,
-      '',
-    ].join('\n'),
+      "",
+    ].join("\n"),
   );
 }
 
 function legacyCaptainSessionReason(schemaVersion) {
   if (schemaVersion === 2) {
-    return 'schema 2 has incompatible player identity';
+    return "schema 2 has incompatible player identity";
   }
   if (schemaVersion === 3 || schemaVersion === 4) {
     return `schema ${JSON.stringify(schemaVersion)} predates the artifact-schema-3 effect-authority cutover and is not resumable`;
   }
   if (schemaVersion === 5) {
-    return 'schema 5 predates the canonical schema-6 unresolved-effect settlement boundary for the artifact-schema-3 effect-authority cutover and is not resumable';
+    return "schema 5 predates the canonical schema-6 unresolved-effect settlement boundary for the artifact-schema-3 effect-authority cutover and is not resumable";
   }
   return `schema ${JSON.stringify(schemaVersion)} is unsupported`;
 }
@@ -1546,9 +1699,7 @@ export async function reportSkippedCaptainSession(
   { sessionId, path, schemaVersion, reason },
 ) {
   const explanation =
-    kind === 'legacy'
-      ? legacyCaptainSessionReason(schemaVersion)
-      : reason;
+    kind === "legacy" ? legacyCaptainSessionReason(schemaVersion) : reason;
   await writeStream(
     stderr,
     `${commandName}: skipping ${kind} Captain session ${JSON.stringify(sessionId)} at ${JSON.stringify(path)} because ${explanation}; move it outside the sessions directory or remove it to silence this warning\n`,
@@ -1557,12 +1708,12 @@ export async function reportSkippedCaptainSession(
 
 function replayInvocation(argv, args, input) {
   if (args.retryUncertain || args.discardUncertain) {
-    return ['run', ...argv];
+    return ["run", ...argv];
   }
-  if (args.input !== undefined) return ['run', ...argv];
+  if (args.input !== undefined) return ["run", ...argv];
   return args.terminated
-    ? ['run', ...argv, input]
-    : ['run', ...argv, '--', input];
+    ? ["run", ...argv, input]
+    : ["run", ...argv, "--", input];
 }
 
 function cloneJson(value) {
@@ -1574,69 +1725,70 @@ async function readAllStdin() {
   for await (const chunk of process.stdin) {
     chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
   }
-  return Buffer.concat(chunks).toString('utf8');
+  return Buffer.concat(chunks).toString("utf8");
 }
 
 async function writeStream(stream, text) {
   const ready = stream.write(text);
-  if (ready !== false || typeof stream.once !== 'function') return;
+  if (ready !== false || typeof stream.once !== "function") return;
   await new Promise((resolvePromise, rejectPromise) => {
     const onDrain = () => {
-      stream.off?.('error', onError);
+      stream.off?.("error", onError);
       resolvePromise();
     };
     const onError = (error) => {
-      stream.off?.('drain', onDrain);
+      stream.off?.("drain", onDrain);
       rejectPromise(error);
     };
-    stream.once('drain', onDrain);
-    stream.once('error', onError);
+    stream.once("drain", onDrain);
+    stream.once("error", onError);
   });
 }
 
 function runHelpText(userConfigPath) {
   return [
-    'Usage:',
-    '  playbook run [--with <path>]... [--no-provision] [--json]',
-    '               [--verbose] [--] [input]',
-    '  playbook run (--continue | --session <id>) [--with <path>]...',
-    '               [--no-provision] [--json] [--verbose] [--] [reply]',
-    '  playbook run --session <id> --retry-uncertain [--no-provision]',
-    '  playbook run --session <id> --discard-uncertain',
-    '',
-    '  [input]  one exact Boss message; read verbatim from stdin when omitted',
-    '  --        end options so a flag-shaped input remains Boss text',
-    '',
+    "Usage:",
+    "  playbook run [--with <path>]... [--no-provision] [--json]",
+    "               [--verbose] [--] [input]",
+    "  playbook run (--continue | --session <id>) [--with <path>]...",
+    "               [--no-provision] [--json] [--verbose] [--] [reply]",
+    "  playbook run --session <id> --retry-uncertain [--no-provision]",
+    "  playbook run --session <id> --discard-uncertain",
+    "",
+    "  [input]  one exact Boss message; read verbatim from stdin when omitted",
+    "  --        end options so a flag-shaped input remains Boss text",
+    "",
     `Default config: ${userConfigPath}`,
-    '',
-    'A new run uses the same configured Captain, enabled playbooks, players,',
-    'options, overlays, provisioning, and readiness gate as interactive',
-    '`playbook`. Enable an external registry in that config, then invoke its',
-    'effective /command through Captain. The former positional registry,',
-    'resume, and run-only binding surfaces have been removed.',
-    'Stable agents live under top-level players; every playbook-local role',
-    'binds explicitly under playbooks.<id>.roles. Equal player ids share one',
-    'provider conversation; distinct ids remain isolated.',
-    'Legacy playbooks.<id>.players is rejected and is not auto-migrated,',
-    'because choosing new ids decides sharing versus isolation.',
-    'Bare continuation prefers the newest session stored for the invoking',
-    'working directory and reports when it uses the global newest fallback.',
-    'An ordinary continued run restores that stored structure and working',
-    'directory, then reads current config and overlays for model and effort.',
-    'Uncertain retry instead uses its exact recorded input and settings.',
-    '',
-    'Options:',
-    '  --with <path>    overlay a generic config fragment (repeatable)',
-    '  --no-provision   do not provision thin filesystem registry engines',
-    '  --continue       prefer this working directory, else global newest',
-    '  --session <id>   reply to one durable Captain session UUID',
-    '  --retry-uncertain retry that session\'s exact recorded uncertain input',
-    '  --discard-uncertain discard that session\'s uncertain attempt',
+    "",
+    "A new run uses the same configured Captain, enabled playbooks, players,",
+    "options, overlays, provisioning, and readiness gate as interactive",
+    "`playbook`. Enable an external registry in that config, then invoke its",
+    "effective /command through Captain. The former positional registry,",
+    "resume, and run-only binding surfaces have been removed.",
+    "Stable agents live under top-level players; every playbook-local role",
+    "binds explicitly under playbooks.<id>.roles. Equal player ids share one",
+    "provider conversation; distinct ids remain isolated.",
+    "Legacy playbooks.<id>.players is rejected and is not auto-migrated,",
+    "because choosing new ids decides sharing versus isolation.",
+    "Bare continuation prefers the newest session stored for the invoking",
+    "working directory and reports when it uses the global newest fallback.",
+    "An ordinary continued run restores that stored structure and working",
+    "directory, then reads current config and overlays for model, effort,",
+    "and fast mode.",
+    "Uncertain retry instead uses its exact recorded input and settings.",
+    "",
+    "Options:",
+    "  --with <path>    overlay a generic config fragment (repeatable)",
+    "  --no-provision   do not provision thin filesystem registry engines",
+    "  --continue       prefer this working directory, else global newest",
+    "  --session <id>   reply to one durable Captain session UUID",
+    "  --retry-uncertain retry that session's exact recorded uncertain input",
+    "  --discard-uncertain discard that session's uncertain attempt",
     '  --json           print exactly {"sessionId", "reply"}',
-    '  --verbose        print Captain telemetry topics to stderr',
-    '  -h, --help       print this help without reading input or config',
-    '',
-  ].join('\n');
+    "  --verbose        print Captain telemetry topics to stderr",
+    "  -h, --help       print this help without reading input or config",
+    "",
+  ].join("\n");
 }
 
 function message(error) {