@sublang/playbook 9.0.0 → 11.0.0

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

@@ -2,49 +2,47 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
 
-import { spawn } from 'node:child_process';
-import { randomUUID } from 'node:crypto';
-import {
-  mkdtempSync,
-  realpathSync,
-  rmSync,
-  writeFileSync,
-} from 'node:fs';
-import { homedir, tmpdir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { launchManagedTmuxPlay } from '@sublang/cligent/tmux-play';
-import { stringify as stringifyYaml } from 'yaml';
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { launchManagedTmuxPlay } from "@sublang/cligent/tmux-play";
+import { stringify as stringifyYaml } from "yaml";
 import {
   adapterSdkFailureLines,
   checkAdapterSdks,
   mappedSdksFor,
   probeAdapterSdk,
-} from './adapter-sdk.js';
+} from "./adapter-sdk.js";
 import {
   adaptersFromLaunchPlan,
   extractWithFlags,
   loadLaunchPlan,
   loadSelectedLaunchPlanDataOnly,
   projectTmuxConfig,
+  resolveLaunchSessionsDir,
+  relocateLegacyUserConfig,
+  resolveLegacyUserConfigPath,
   resolveUserConfigPath,
   checkReadiness,
-} from './launch-config.js';
+} from "./launch-config.js";
 import {
   createManagedInteractiveSessionCommand,
   MANAGED_INTERACTIVE_PAYLOAD_KIND,
   MANAGED_INTERACTIVE_PAYLOAD_SCHEMA_VERSION,
-} from './interactive-session.js';
-import { prepareConfiguredRegistries } from './provision.js';
-import {
-  executionConfigFromPlan,
-} from './run.js';
+  publishManagedInteractiveReadinessWitness,
+} from "./interactive-session.js";
+import { prepareConfiguredRegistries } from "./provision.js";
+import { executionConfigFromPlan } from "./run.js";
 import {
   assertCaptainSessionExecutionCompatible,
+  assertCaptainSessionsDirectoryUsable,
   createCaptainSessionStore,
   SESSION_ID_PATTERN,
   validateCaptainSessionRecord,
-} from './session-store.js';
+} from "./session-store.js";
 
 // Preserve the established import surface while the CLI itself delegates to
 // the host-neutral launch-config module.
@@ -64,9 +62,8 @@ export {
   normalizeLaunchPlan,
   projectTmuxConfig,
   resolveAgent,
-  resolveConfigHome,
   resolveUserConfigPath,
-} from './launch-config.js';
+} from "./launch-config.js";
 
 const READINESS_FAILURE_EXIT_CODE = 2;
 const COMPOSITION_FAILURE_EXIT_CODE = 1;
@@ -77,22 +74,26 @@ export async function runPlaybookCli(options = {}) {
   const stdout = options.stdout ?? process.stdout;
   const stderr = options.stderr ?? process.stderr;
   const loadModule = options.loadModule ?? ((specifier) => import(specifier));
-  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-18: `playbook run ...` is the non-interactive presentation of the
   // same generic-config Captain session. It never resolves or launches the
   // tmux presenter, but it receives the launch inputs shared with this host.
-  if (argv[0] === 'run') {
-    const { runPlaybookRun } = await import('./run.js');
+  if (argv[0] === "run") {
+    const { runPlaybookRun } = await import("./run.js");
     return await runPlaybookRun({
       argv: argv.slice(1),
       stdout,
       stderr,
       env,
       homeDir: home,
-      userConfigPath,
+      ...(options.userConfigPath === undefined ? {} : { userConfigPath }),
       ...(options.cwd ? { cwd: options.cwd } : {}),
       ...(options.loadModule ? { loadModule: options.loadModule } : {}),
       ...(options.readStdin ? { readStdin: options.readStdin } : {}),
@@ -115,9 +116,12 @@ export async function runPlaybookCli(options = {}) {
       ...(options.createHostRuntime
         ? { createHostRuntime: options.createHostRuntime }
         : {}),
-      ...(options.sessionStore
-        ? { sessionStore: options.sessionStore }
+      ...(options.createEffectLedgerWriteAhead
+        ? {
+            createEffectLedgerWriteAhead: options.createEffectLedgerWriteAhead,
+          }
         : {}),
+      ...(options.sessionStore ? { sessionStore: options.sessionStore } : {}),
       ...(options.sessionsDir ? { sessionsDir: options.sessionsDir } : {}),
       ...(options.now ? { now: options.now } : {}),
       ...(options.createSessionTempId
@@ -126,6 +130,12 @@ export async function runPlaybookCli(options = {}) {
       ...(options.createAttemptId
         ? { createAttemptId: options.createAttemptId }
         : {}),
+      ...(options.installRetainedGenerationsForLaunch
+        ? {
+            installRetainedGenerationsForLaunch:
+              options.installRetainedGenerationsForLaunch,
+          }
+        : {}),
       ...(options.signal ? { signal: options.signal } : {}),
       // PBCLI-39: the run path gates on SDK availability too.
       ...(options.probeAdapterSdk
@@ -145,7 +155,7 @@ export async function runPlaybookCli(options = {}) {
 
   // PBCLI-6: `--help` / `-h` print help and exit 0 without seeding,
   // composing, or launching.
-  if (argv.includes('--help') || argv.includes('-h')) {
+  if (argv.includes("--help") || argv.includes("-h")) {
     stdout.write(helpText({ userConfigPath }));
     return { code: 0 };
   }
@@ -163,17 +173,17 @@ export async function runPlaybookCli(options = {}) {
   }
   if (withPaths.length > 0 && hasExplicitConfig(argv)) {
     stderr.write(
-      'playbook: --with overlays the top-level config and cannot combine ' +
-        'with a raw --config launch\n',
+      "playbook: --with overlays the top-level config and cannot combine " +
+        "with a raw --config launch\n",
     );
     return { code: COMPOSITION_FAILURE_EXIT_CODE };
   }
-  const noProvision = forwardArgv.includes('--no-provision');
-  forwardArgv = forwardArgv.filter((arg) => arg !== '--no-provision');
+  const noProvision = forwardArgv.includes("--no-provision");
+  forwardArgv = forwardArgv.filter((arg) => arg !== "--no-provision");
   if (noProvision && hasExplicitConfig(argv)) {
     stderr.write(
-      'playbook: --no-provision applies to configured registry preparation ' +
-        'and cannot combine with a raw --config launch\n',
+      "playbook: --no-provision applies to configured registry preparation " +
+        "and cannot combine with a raw --config launch\n",
     );
     return { code: COMPOSITION_FAILURE_EXIT_CODE };
   }
@@ -198,10 +208,49 @@ export async function runPlaybookCli(options = {}) {
     return { code: COMPOSITION_FAILURE_EXIT_CODE };
   }
 
+  // DR-043: only a validated managed launch may relocate the legacy config.
+  // Help and raw --config return above without changing either config path;
+  // the delegated `run` front end applies the same boundary independently.
+  if (options.userConfigPath === undefined) {
+    try {
+      relocateLegacyUserConfig(
+        userConfigPath,
+        resolveLegacyUserConfigPath(env, home),
+        (line) => stderr.write(line),
+      );
+    } catch (error) {
+      stderr.write(`playbook: ${errorMessage(error)}\n`);
+      return { code: COMPOSITION_FAILURE_EXIT_CODE };
+    }
+  }
+
   const launchCwd = resolve(
     options.cwd ?? process.cwd(),
-    interactiveArgs.cwd ?? '.',
+    interactiveArgs.cwd ?? ".",
   );
+  let resolvedSessionsDir;
+  if (options.sessionStore === undefined) {
+    try {
+      resolvedSessionsDir = resolveLaunchSessionsDir({
+        userConfigPath,
+        overlayPaths: withPaths,
+        env,
+        homeDir: home,
+        ...(options.sessionsDir !== undefined
+          ? { sessionsDir: options.sessionsDir }
+          : {}),
+        preparePrimary: interactiveArgs.sessionId === undefined,
+        onNotice: (line) => stderr.write(line),
+      });
+      // PBCLI-78: listing validates the locator but never consumes the store.
+      if (!interactiveArgs.list) {
+        await assertCaptainSessionsDirectoryUsable(resolvedSessionsDir);
+      }
+    } catch (error) {
+      stderr.write(`playbook: ${errorMessage(error)}\n`);
+      return { code: COMPOSITION_FAILURE_EXIT_CODE };
+    }
+  }
   // PBCLI-49: selected planning is deliberately provisional. It narrows the
   // current config before preparation; the pane child later acquires the
   // lease and repeats the authoritative read before any host/import work.
@@ -209,15 +258,49 @@ export async function runPlaybookCli(options = {}) {
   let selectedRecord;
   if (interactiveArgs.sessionId !== undefined) {
     try {
-      store = createInteractiveStore(options, env, home);
+      store = createInteractiveStore(options, env, home, resolvedSessionsDir);
       selectedRecord = validateCaptainSessionRecord(
         await store.read(interactiveArgs.sessionId),
       );
-      if (selectedRecord.state !== 'settled') {
+      const needsAbandonmentRecovery =
+        (selectedRecord.state === "uncertain" &&
+          Object.hasOwn(selectedRecord.uncertain, "abandonment")) ||
+        (selectedRecord.state === "settled" &&
+          Object.hasOwn(selectedRecord, "settledAbandonment"));
+      if (selectedRecord.state !== "settled" && !needsAbandonmentRecovery) {
         throw new Error(
           `Captain session ${JSON.stringify(interactiveArgs.sessionId)} has an uncertain turn; recover it with playbook run before reopening interactively`,
         );
       }
+      if (needsAbandonmentRecovery) {
+        const recoveryLease = await store.acquire(interactiveArgs.sessionId);
+        let recoveryError;
+        try {
+          selectedRecord = validateCaptainSessionRecord(
+            await recoveryLease.recoverUnresolvedEffectAbandonment(),
+          );
+        } catch (error) {
+          recoveryError = error;
+        }
+        try {
+          await recoveryLease.release();
+        } catch (error) {
+          if (recoveryError !== undefined) {
+            throw aggregateOperationalFailures(
+              recoveryError,
+              error,
+              "Captain session abandonment recovery failed and its lease could not be released",
+            );
+          }
+          throw error;
+        }
+        if (recoveryError !== undefined) throw recoveryError;
+        if (selectedRecord.state !== "settled") {
+          throw new Error(
+            `Captain session ${JSON.stringify(interactiveArgs.sessionId)} abandonment recovery did not settle its turn`,
+          );
+        }
+      }
     } catch (error) {
       stderr.write(`playbook: ${errorMessage(error)}\n`);
       return { code: COMPOSITION_FAILURE_EXIT_CODE };
@@ -243,7 +326,7 @@ export async function runPlaybookCli(options = {}) {
               enabled: !noProvision,
               stderr,
               hostRoots: options.hostRoots,
-              commandName: 'playbook',
+              commandName: "playbook",
             }),
           onNotice: (line) => stderr.write(line),
         });
@@ -310,7 +393,7 @@ export async function runPlaybookCli(options = {}) {
         spawnFn,
         [
           tmuxPlayBin,
-          '--config',
+          "--config",
           composedPath,
           ...interactiveArgs.diagnosticArgv,
         ],
@@ -322,7 +405,7 @@ export async function runPlaybookCli(options = {}) {
   }
 
   try {
-    store ??= createInteractiveStore(options, env, home);
+    store ??= createInteractiveStore(options, env, home, resolvedSessionsDir);
   } catch (error) {
     stderr.write(`playbook: ${errorMessage(error)}\n`);
     return { code: COMPOSITION_FAILURE_EXIT_CODE };
@@ -341,7 +424,10 @@ export async function runPlaybookCli(options = {}) {
       );
     } else {
       sessionId = (options.createLogicalSessionId ?? randomUUID)();
-      if (typeof sessionId !== 'string' || !SESSION_ID_PATTERN.test(sessionId)) {
+      if (
+        typeof sessionId !== "string" ||
+        !SESSION_ID_PATTERN.test(sessionId)
+      ) {
         throw new Error(
           `logical session id generator returned a non-UUID value: ${JSON.stringify(sessionId)}`,
         );
@@ -358,6 +444,7 @@ export async function runPlaybookCli(options = {}) {
     projectTmuxConfig(plan),
   );
   let prepared;
+  let managedChildWorkDir;
   try {
     throwIfSignalAborted(options.signal);
     prepared = await awaitManagedPreparation(
@@ -372,13 +459,19 @@ export async function runPlaybookCli(options = {}) {
           ...(options.adapterImports
             ? { adapterImports: options.adapterImports }
             : {}),
-          createSessionCommand: (context) =>
-            createManagedInteractiveSessionCommand(
+          createSessionCommand: (context) => {
+            if (managedChildWorkDir !== undefined) {
+              throw new Error(
+                "managed tmux-play requested more than one session command",
+              );
+            }
+            managedChildWorkDir = context.workDir;
+            return createManagedInteractiveSessionCommand(
               context,
               {
                 schemaVersion: MANAGED_INTERACTIVE_PAYLOAD_SCHEMA_VERSION,
                 kind: MANAGED_INTERACTIVE_PAYLOAD_KIND,
-                mode: selectedRecord ? 'selected' : 'fresh',
+                mode: selectedRecord ? "selected" : "fresh",
                 sessionId,
                 cwd,
                 sessionsDir: store.sessionsDir,
@@ -389,20 +482,43 @@ export async function runPlaybookCli(options = {}) {
                 selfBin:
                   options.managedSessionBin ??
                   fileURLToPath(
-                    new URL('./interactive-session.js', import.meta.url),
+                    new URL("./interactive-session.js", import.meta.url),
                   ),
                 ...(options.execPath ? { execPath: options.execPath } : {}),
               },
-            ),
+            );
+          },
         }),
       options.signal,
     );
     if (prepared?.sessionId !== sessionId) {
       await cancelPreparedAfterFailure(
         prepared,
-        new Error('managed tmux-play prepared a mismatched session id'),
+        new Error("managed tmux-play prepared a mismatched session id"),
       );
     }
+    if (managedChildWorkDir === undefined) {
+      await cancelPreparedAfterFailure(
+        prepared,
+        new Error("managed tmux-play did not request a session command"),
+      );
+    }
+    if (prepared?.workDir !== managedChildWorkDir) {
+      await cancelPreparedAfterFailure(
+        prepared,
+        new Error("managed tmux-play prepared a mismatched work directory"),
+      );
+    }
+    if (!selectedRecord) {
+      try {
+        await (
+          options.publishManagedReadinessWitness ??
+          publishManagedInteractiveReadinessWitness
+        )(managedChildWorkDir, sessionId);
+      } catch (error) {
+        await cancelPreparedAfterFailure(prepared, error);
+      }
+    }
     try {
       await writeStream(
         stderr,
@@ -421,7 +537,9 @@ export async function runPlaybookCli(options = {}) {
     });
     return { code: 0 };
   } catch (error) {
-    stderr.write(`playbook: failed to launch managed session: ${errorMessage(error)}\n`);
+    stderr.write(
+      `playbook: failed to launch managed session: ${errorMessage(error)}\n`,
+    );
     return { code: COMPOSITION_FAILURE_EXIT_CODE };
   } finally {
     rmSync(tempDir, { recursive: true, force: true });
@@ -429,21 +547,23 @@ export async function runPlaybookCli(options = {}) {
 }
 
 export function parseInteractiveArgs(argv) {
-  if (argv.includes('--theme-diagnostics')) {
-    if (argv.filter((arg) => arg === '--theme-diagnostics').length > 1) {
-      throw new Error('--theme-diagnostics was repeated');
+  if (argv.includes("--theme-diagnostics")) {
+    if (argv.filter((arg) => arg === "--theme-diagnostics").length > 1) {
+      throw new Error("--theme-diagnostics was repeated");
     }
-    if (argv.some((arg) => arg === '--session' || arg.startsWith('--session='))) {
-      throw new Error('--session cannot combine with --theme-diagnostics');
+    if (
+      argv.some((arg) => arg === "--session" || arg.startsWith("--session="))
+    ) {
+      throw new Error("--session cannot combine with --theme-diagnostics");
     }
-    if (argv.includes('--list')) {
-      throw new Error('--list cannot combine with --theme-diagnostics');
+    if (argv.includes("--list")) {
+      throw new Error("--list cannot combine with --theme-diagnostics");
     }
     const recoveryArg = argv.find(
       (arg) =>
-        arg === '--continue' ||
-        arg === '--retry-uncertain' ||
-        arg === '--discard-uncertain',
+        arg === "--continue" ||
+        arg === "--retry-uncertain" ||
+        arg === "--discard-uncertain",
     );
     if (recoveryArg !== undefined) {
       throw new Error(
@@ -464,32 +584,34 @@ export function parseInteractiveArgs(argv) {
   let list = false;
   for (let index = 0; index < argv.length; index += 1) {
     const arg = argv[index];
-    if (arg === '--list') {
-      if (list) throw new Error('--list was repeated');
+    if (arg === "--list") {
+      if (list) throw new Error("--list was repeated");
       list = true;
       continue;
     }
-    if (arg === '--session' || arg.startsWith('--session=')) {
+    if (arg === "--session" || arg.startsWith("--session=")) {
       if (sessionId !== undefined) {
-        throw new Error('interactive --session selector was repeated or combined');
+        throw new Error(
+          "interactive --session selector was repeated or combined",
+        );
       }
-      sessionId = optionValue(argv, index, '--session');
-      if (arg === '--session') index += 1;
+      sessionId = optionValue(argv, index, "--session");
+      if (arg === "--session") index += 1;
       if (!SESSION_ID_PATTERN.test(sessionId)) {
-        throw new Error('--session requires a canonical lowercase UUID');
+        throw new Error("--session requires a canonical lowercase UUID");
       }
       continue;
     }
-    if (arg === '--cwd' || arg.startsWith('--cwd=')) {
-      if (cwd !== undefined) throw new Error('interactive --cwd was repeated');
-      cwd = optionValue(argv, index, '--cwd');
-      if (arg === '--cwd') index += 1;
+    if (arg === "--cwd" || arg.startsWith("--cwd=")) {
+      if (cwd !== undefined) throw new Error("interactive --cwd was repeated");
+      cwd = optionValue(argv, index, "--cwd");
+      if (arg === "--cwd") index += 1;
       continue;
     }
     if (
-      arg === '--continue' ||
-      arg === '--retry-uncertain' ||
-      arg === '--discard-uncertain'
+      arg === "--continue" ||
+      arg === "--retry-uncertain" ||
+      arg === "--discard-uncertain"
     ) {
       throw new Error(
         `${arg} is headless recovery syntax; use playbook run with an explicit session`,
@@ -501,14 +623,16 @@ export function parseInteractiveArgs(argv) {
   }
   if (sessionId !== undefined && cwd !== undefined) {
     throw new Error(
-      'interactive --cwd cannot combine with --session; the stored working directory is authoritative',
+      "interactive --cwd cannot combine with --session; the stored working directory is authoritative",
     );
   }
   if (sessionId !== undefined && list) {
-    throw new Error('--session cannot combine with --list');
+    throw new Error("--session cannot combine with --list");
   }
   if (list && cwd !== undefined) {
-    throw new Error('--cwd applies to a fresh launch and cannot combine with --list');
+    throw new Error(
+      "--cwd applies to a fresh launch and cannot combine with --list",
+    );
   }
   return Object.freeze({
     sessionId,
@@ -529,7 +653,7 @@ export function parseInteractiveArgs(argv) {
 export async function runPlaybookCliEntry(options = {}) {
   const processLike = options.processLike ?? process;
   const entryArgv = options.argv ?? processLike.argv?.slice(2) ?? [];
-  if (entryArgv[0] !== 'run' && !isManagedInteractiveInvocation(entryArgv)) {
+  if (entryArgv[0] !== "run" && !isManagedInteractiveInvocation(entryArgv)) {
     return runPlaybookCli(options);
   }
   const controller = new AbortController();
@@ -541,7 +665,7 @@ export async function runPlaybookCliEntry(options = {}) {
       processLike.off(signal, handler);
     }
   };
-  for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+  for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
     handlers[signal] = () => {
       if (receivedSignal !== undefined) {
         removeHandlers();
@@ -575,33 +699,33 @@ export async function runPlaybookCliEntry(options = {}) {
 
 function isManagedInteractiveInvocation(argv) {
   return (
-    !argv.includes('--help') &&
-    !argv.includes('-h') &&
-    !argv.includes('--list') &&
-    !argv.includes('--theme-diagnostics') &&
+    !argv.includes("--help") &&
+    !argv.includes("-h") &&
+    !argv.includes("--list") &&
+    !argv.includes("--theme-diagnostics") &&
     !hasExplicitConfig(argv)
   );
 }
 
 function writeComposedConfig(composed) {
-  const dir = mkdtempSync(join(tmpdir(), 'playbook-'));
-  const path = join(dir, 'tmux-play.config.yaml');
+  const dir = mkdtempSync(join(tmpdir(), "playbook-"));
+  const path = join(dir, "tmux-play.config.yaml");
   writeFileSync(path, stringifyYaml(composed));
   return { dir, path };
 }
 
 function hasExplicitConfig(argv) {
-  return argv.some((arg) => arg === '--config' || arg.startsWith('--config='));
+  return argv.some((arg) => arg === "--config" || arg.startsWith("--config="));
 }
 
 function assertRawConfigHasNoManagedSelector(argv) {
   const managed = argv.find(
     (arg) =>
-      arg === '--session' ||
-      arg.startsWith('--session=') ||
-      arg === '--continue' ||
-      arg === '--retry-uncertain' ||
-      arg === '--discard-uncertain',
+      arg === "--session" ||
+      arg.startsWith("--session=") ||
+      arg === "--continue" ||
+      arg === "--retry-uncertain" ||
+      arg === "--discard-uncertain",
   );
   if (managed !== undefined) {
     throw new Error(
@@ -612,21 +736,20 @@ function assertRawConfigHasNoManagedSelector(argv) {
 
 function optionValue(argv, index, name) {
   const arg = argv[index];
-  const value =
-    arg === name ? argv[index + 1] : arg.slice(`${name}=`.length);
-  if (typeof value !== 'string' || value.length === 0) {
+  const value = arg === name ? argv[index + 1] : arg.slice(`${name}=`.length);
+  if (typeof value !== "string" || value.length === 0) {
     throw new Error(`${name} requires a value`);
   }
   return value;
 }
 
-function createInteractiveStore(options, env, home) {
+function createInteractiveStore(options, env, home, sessionsDir) {
   return (
     options.sessionStore ??
     createCaptainSessionStore({
       env,
       homeDir: home,
-      ...(options.sessionsDir ? { sessionsDir: options.sessionsDir } : {}),
+      sessionsDir,
       ...(options.now ? { now: options.now } : {}),
       ...(options.createSessionTempId
         ? { createTempId: options.createSessionTempId }
@@ -638,12 +761,12 @@ function createInteractiveStore(options, env, home) {
 async function writeStream(stream, text, signal) {
   throwIfSignalAborted(signal);
   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 cleanup = () => {
-      stream.off?.('drain', onDrain);
-      stream.off?.('error', onError);
-      signal?.removeEventListener('abort', onAbort);
+      stream.off?.("drain", onDrain);
+      stream.off?.("error", onError);
+      signal?.removeEventListener("abort", onAbort);
     };
     const onDrain = () => {
       cleanup();
@@ -655,11 +778,11 @@ async function writeStream(stream, text, signal) {
     };
     const onAbort = () => {
       cleanup();
-      rejectPromise(signal.reason ?? new Error('operation aborted'));
+      rejectPromise(signal.reason ?? new Error("operation aborted"));
     };
-    stream.once('drain', onDrain);
-    stream.once('error', onError);
-    signal?.addEventListener('abort', onAbort, { once: true });
+    stream.once("drain", onDrain);
+    stream.once("error", onError);
+    signal?.addEventListener("abort", onAbort, { once: true });
     if (signal?.aborted) onAbort();
   });
 }
@@ -671,22 +794,22 @@ async function awaitManagedPreparation(start, signal) {
 
   let onAbort;
   const aborted = new Promise((resolvePromise) => {
-    onAbort = () => resolvePromise({ type: 'aborted' });
-    signal.addEventListener('abort', onAbort, { once: true });
+    onAbort = () => resolvePromise({ type: "aborted" });
+    signal.addEventListener("abort", onAbort, { once: true });
     if (signal.aborted) onAbort();
   });
   const outcome = await Promise.race([
     launch.then(
-      (value) => ({ type: 'prepared', value }),
-      (error) => ({ type: 'failed', error }),
+      (value) => ({ type: "prepared", value }),
+      (error) => ({ type: "failed", error }),
     ),
     aborted,
   ]);
-  signal.removeEventListener('abort', onAbort);
-  if (outcome.type === 'prepared') return outcome.value;
-  if (outcome.type === 'failed') throw outcome.error;
+  signal.removeEventListener("abort", onAbort);
+  if (outcome.type === "prepared") return outcome.value;
+  if (outcome.type === "failed") throw outcome.error;
 
-  const abortError = signal.reason ?? new Error('operation aborted');
+  const abortError = signal.reason ?? new Error("operation aborted");
   let latePrepared;
   try {
     latePrepared = await launch;
@@ -694,7 +817,7 @@ async function awaitManagedPreparation(start, signal) {
     throw aggregateOperationalFailures(
       abortError,
       launchError,
-      'managed tmux-play preparation failed while retiring an aborted launch',
+      "managed tmux-play preparation failed while retiring an aborted launch",
     );
   }
   await cancelPreparedAfterFailure(latePrepared, abortError);
@@ -704,14 +827,16 @@ async function cancelPreparedIfAborted(prepared, signal) {
   if (!signal?.aborted) return;
   await cancelPreparedAfterFailure(
     prepared,
-    signal.reason ?? new Error('operation aborted'),
+    signal.reason ?? new Error("operation aborted"),
   );
 }
 
 async function cancelPreparedAfterFailure(prepared, primary) {
   try {
-    if (typeof prepared?.cancel !== 'function') {
-      throw new Error('managed tmux-play preparation has no cancellation boundary');
+    if (typeof prepared?.cancel !== "function") {
+      throw new Error(
+        "managed tmux-play preparation has no cancellation boundary",
+      );
     }
     await prepared.cancel();
   } catch (cancelError) {
@@ -733,7 +858,7 @@ function aggregateOperationalFailures(primary, secondary, summary) {
 
 function throwIfSignalAborted(signal) {
   if (signal?.aborted) {
-    throw signal.reason ?? new Error('operation aborted');
+    throw signal.reason ?? new Error("operation aborted");
   }
 }
 
@@ -744,76 +869,77 @@ function helpText({
 }) {
   const failures =
     failingAdapters.length > 0
-      ? [`Adapters not ready: ${failingAdapters.join(', ')}`, '']
+      ? [`Adapters not ready: ${failingAdapters.join(", ")}`, ""]
       : [];
   return [
     // PBCLI-40: the SDK remedy leads, because an unusable adapter cannot be
     // fixed by the credential advice further down.
     ...sdkFailureLines,
     ...failures,
-    'Usage:',
-    '  playbook [--with <path>]... [--no-provision] [--cwd <path>]',
-    '  playbook --session <id> [--with <path>]... [--no-provision]',
-    '  playbook --list [--with <path>]... [--no-provision]',
-    '  playbook --theme-diagnostics [--with <path>]... [--cwd <path>]',
-    '  playbook --config <path> [tmux-play arguments...]',
-    '  playbook run [--with <path>]... [--no-provision] [--json]',
-    '               [--verbose] [--] [input]',
-    '  playbook run (--continue | --session <id>) [reply]',
-    '  playbook run --session <id> --retry-uncertain',
-    '  playbook run --session <id> --discard-uncertain',
-    '  playbook --help',
-    '',
+    "Usage:",
+    "  playbook [--with <path>]... [--no-provision] [--cwd <path>]",
+    "  playbook --session <id> [--with <path>]... [--no-provision]",
+    "  playbook --list [--with <path>]... [--no-provision]",
+    "  playbook --theme-diagnostics [--with <path>]... [--cwd <path>]",
+    "  playbook --config <path> [tmux-play arguments...]",
+    "  playbook run [--with <path>]... [--no-provision] [--json]",
+    "               [--verbose] [--] [input]",
+    "  playbook run (--continue | --session <id>) [reply]",
+    "  playbook run --session <id> --retry-uncertain",
+    "  playbook run --session <id> --discard-uncertain",
+    "  playbook --help",
+    "",
     `Default config: ${userConfigPath}`,
-    '',
-    '  Only a fresh managed launch accepts --cwd. It creates a durable logical',
-    '  Captain session and reports `playbook: session <id>` before attach.',
-    '  Reopen that same session with `playbook --session <id>` or submit one',
-    '  headless turn with `playbook run --session <id> [reply]`; selected',
-    '  sessions always retain their stored working directory.',
-    '  --with <path> overlays a top-level config fragment (same format as',
-    '  the default config) for a fresh launch or compatible ordinary reopen —',
-    '  maps merge recursively, other values replace, later files win, and the',
-    '  default config file is never modified.',
-    '  --no-provision keeps configured filesystem registries read-only;',
-    '  any missing engine links remain a launch error.',
-    '  `playbook run --verbose` prints Captain telemetry topics to stderr.',
-    '  `playbook run --help` prints complete continuation and recovery usage.',
-    '  Raw --config and --theme-diagnostics use cligent\'s stock tmux-play',
-    '  process boundary and do not create or select a durable Captain session.',
-    '',
-    'Adapter setup:',
-    '  claude: npm install -g @anthropic-ai/claude-agent-sdk, then run',
-    '    Claude Code once or set ANTHROPIC_API_KEY.',
-    '  codex: npm install -g @openai/codex-sdk, then run Codex CLI once',
-    '    or set OPENAI_API_KEY.',
-    '  Each SDK is an optional peer dependency, so you install only the',
-    '  vendors your config actually names.',
-    '',
-    'Agent swap recipe:',
-    '  - set the top-level captain and each stable players.<id> to an',
-    '    adapter shorthand (claude, codex) or an inline agent block',
-    '  - bind every playbooks.<id>.roles.<role> explicitly to a player id;',
-    '    a scalar names the id, while { player, model?, effort? } may retune',
-    '    one role; boolean false selects the provider default explicitly',
-    '  - reusing one id deliberately shares that provider conversation;',
-    '    distinct ids stay isolated even when their agent blocks are equal',
-    '  - the launcher injects captain.from and retains referenced player ids',
-    '    verbatim',
-    '',
-    'Migration warning:',
-    '  playbooks.<id>.players is removed and is not auto-migrated. Move each',
-    '  agent to top-level players, choose ids for sharing or isolation, and',
-    '  bind every local role under playbooks.<id>.roles.',
-    '',
-  ].join('\n');
+    "",
+    "  Only a fresh managed launch accepts --cwd. It creates a durable logical",
+    "  Captain session and reports `playbook: session <id>` before attach.",
+    "  Reopen that same session with `playbook --session <id>` or submit one",
+    "  headless turn with `playbook run --session <id> [reply]`; selected",
+    "  sessions always retain their stored working directory.",
+    "  --with <path> overlays a top-level config fragment (same format as",
+    "  the default config) for a fresh launch or compatible ordinary reopen —",
+    "  maps merge recursively, other values replace, later files win, and the",
+    "  default config file is never modified.",
+    "  --no-provision keeps configured filesystem registries read-only;",
+    "  any missing engine links remain a launch error.",
+    "  `playbook run --verbose` prints Captain telemetry topics to stderr.",
+    "  `playbook run --help` prints complete continuation and recovery usage.",
+    "  Raw --config and --theme-diagnostics use cligent's stock tmux-play",
+    "  process boundary and do not create or select a durable Captain session.",
+    "",
+    "Adapter setup:",
+    "  claude: npm install -g @anthropic-ai/claude-agent-sdk, then run",
+    "    Claude Code once or set ANTHROPIC_API_KEY.",
+    "  codex: npm install -g @openai/codex-sdk, then run Codex CLI once",
+    "    or set OPENAI_API_KEY.",
+    "  Each SDK is an optional peer dependency, so you install only the",
+    "  vendors your config actually names.",
+    "",
+    "Agent swap recipe:",
+    "  - set the top-level captain and each stable players.<id> to an",
+    "    adapter shorthand (claude, codex) or an inline agent block",
+    "  - bind every playbooks.<id>.roles.<role> explicitly to a player id;",
+    "    a scalar names the id, while { player, model?, effort?, fastMode? }",
+    "    may retune one role; false selects provider-default model/effort,",
+    "    while fastMode false is a literal disabled request",
+    "  - reusing one id deliberately shares that provider conversation;",
+    "    distinct ids stay isolated even when their agent blocks are equal",
+    "  - the launcher injects captain.from and retains referenced player ids",
+    "    verbatim",
+    "",
+    "Migration warning:",
+    "  playbooks.<id>.players is removed and is not auto-migrated. Move each",
+    "  agent to top-level players, choose ids for sharing or isolation, and",
+    "  bind every local role under playbooks.<id>.roles.",
+    "",
+  ].join("\n");
 }
 
 async function launchTmuxPlay(spawnFn, childArgs, stderr) {
   return await new Promise((resolveResult) => {
     let child;
     try {
-      child = spawnFn(process.execPath, childArgs, { stdio: 'inherit' });
+      child = spawnFn(process.execPath, childArgs, { stdio: "inherit" });
     } catch (error) {
       stderr.write(
         `playbook: failed to launch tmux-play: ${errorMessage(error)}\n`,
@@ -827,13 +953,13 @@ async function launchTmuxPlay(spawnFn, childArgs, stderr) {
       settled = true;
       resolveResult(result);
     };
-    child.on('error', (err) => {
+    child.on("error", (err) => {
       stderr.write(
         `playbook: failed to launch tmux-play: ${errorMessage(err)}\n`,
       );
       settle({ code: 127 });
     });
-    child.on('exit', (code, signal) => {
+    child.on("exit", (code, signal) => {
       if (signal) settle({ signal });
       else settle({ code: code ?? 0 });
     });
@@ -841,8 +967,8 @@ async function launchTmuxPlay(spawnFn, childArgs, stderr) {
 }
 
 function resolveTmuxPlayBin() {
-  const tmuxPlayIndexUrl = import.meta.resolve('@sublang/cligent/tmux-play');
-  return join(dirname(fileURLToPath(tmuxPlayIndexUrl)), 'cli.js');
+  const tmuxPlayIndexUrl = import.meta.resolve("@sublang/cligent/tmux-play");
+  return join(dirname(fileURLToPath(tmuxPlayIndexUrl)), "cli.js");
 }
 
 function errorMessage(error) {