@sublang/playbook 6.0.0 → 8.0.0

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

@@ -3,13 +3,9 @@
 // SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
 
 import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
 import {
-  constants,
-  copyFileSync,
-  existsSync,
-  mkdirSync,
   mkdtempSync,
-  readFileSync,
   realpathSync,
   rmSync,
   writeFileSync,
@@ -17,34 +13,61 @@ import {
 import { homedir, tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import {
-  parse as parseYaml,
-  parseDocument as parseYamlDocument,
-  stringify as stringifyYaml,
-} from 'yaml';
+import { launchManagedTmuxPlay } from '@sublang/cligent/tmux-play';
+import { stringify as stringifyYaml } from 'yaml';
 import {
   adapterSdkFailureLines,
   checkAdapterSdks,
   mappedSdksFor,
   probeAdapterSdk,
 } from './adapter-sdk.js';
+import {
+  adaptersFromLaunchPlan,
+  extractWithFlags,
+  loadLaunchPlan,
+  loadSelectedLaunchPlanDataOnly,
+  projectTmuxConfig,
+  resolveUserConfigPath,
+  checkReadiness,
+} 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';
+import {
+  assertCaptainSessionExecutionCompatible,
+  createCaptainSessionStore,
+  SESSION_ID_PATTERN,
+  validateCaptainSessionRecord,
+} from './session-store.js';
+
+// Preserve the established import surface while the CLI itself delegates to
+// the host-neutral launch-config module.
+export {
+  PLAYBOOK_CAPTAIN_MODULE,
+  adaptersFromComposedConfig,
+  adaptersFromLaunchPlan,
+  canonicalizeRegistrySpecifier,
+  checkReadiness,
+  composeGenericConfig,
+  deriveLaunchReadiness,
+  extractWithFlags,
+  loadLaunchPlan,
+  loadOverlayFragment,
+  mergeConfigs,
+  migrateRetiredProfiles,
+  normalizeLaunchPlan,
+  projectTmuxConfig,
+  resolveAgent,
+  resolveConfigHome,
+  resolveUserConfigPath,
+} from './launch-config.js';
 
-const here = dirname(fileURLToPath(import.meta.url));
-const templatePath = resolve(here, '..', 'playbook.config.template.yaml');
-
-// PBCLI-1/8: the launcher composes a tmux-play config whose Captain is the
-// Playbook Captain shell adapter module.
-export const PLAYBOOK_CAPTAIN_MODULE = '@sublang/playbook/playbook-captain';
-// PBCLI-12: known adapter shorthands — the adapters with readiness
-// predicates.
-const ADAPTER_SHORTHANDS = ['claude', 'codex'];
-// PBCLI-8: launcher-owned keys inside a `playbooks.<id>` block; every other
-// key belongs to that playbook's option slice.
-const PLAYBOOK_LAUNCHER_KEYS = ['from', 'command', 'players'];
-const RESERVED_CAPTAIN_PLAYBOOK_ID = 'captain';
-// PBCLI-9: the bare `captain` id names the tmux-play host Captain, so no
-// playbook-local role may take it.
-const RESERVED_CAPTAIN_ROLE_ID = 'captain';
 const READINESS_FAILURE_EXIT_CODE = 2;
 const COMPOSITION_FAILURE_EXIT_CODE = 1;
 
@@ -58,22 +81,52 @@ export async function runPlaybookCli(options = {}) {
   const userConfigPath =
     options.userConfigPath ?? resolveUserConfigPath(env, home);
 
-  // PBCLI-18: `playbook run ...` is the non-interactive one-shot path; it
-  // never seeds, composes, resolves tmux-play, or launches it.
+  // 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');
     return await runPlaybookRun({
       argv: argv.slice(1),
       stdout,
       stderr,
-      // PBCLI-29: the run host reads the same user config as the launcher,
-      // honoring any injected env, home, or explicit path.
+      env,
+      homeDir: home,
       userConfigPath,
+      ...(options.cwd ? { cwd: options.cwd } : {}),
       ...(options.loadModule ? { loadModule: options.loadModule } : {}),
-      ...(options.createAgent ? { createAgent: options.createAgent } : {}),
       ...(options.readStdin ? { readStdin: options.readStdin } : {}),
-      ...(options.sessionsDir ? { sessionsDir: options.sessionsDir } : {}),
       ...(options.hostRoots ? { hostRoots: options.hostRoots } : {}),
+      ...(options.prepareRegistryModule
+        ? { prepareRegistryModule: options.prepareRegistryModule }
+        : {}),
+      ...(options.adapterImports
+        ? { adapterImports: options.adapterImports }
+        : {}),
+      ...(options.createCaptainRuntime
+        ? { createCaptainRuntime: options.createCaptainRuntime }
+        : {}),
+      ...(options.createCaptainSessionId
+        ? { createCaptainSessionId: options.createCaptainSessionId }
+        : {}),
+      ...(options.createLogicalSessionId
+        ? { createLogicalSessionId: options.createLogicalSessionId }
+        : {}),
+      ...(options.createHostRuntime
+        ? { createHostRuntime: options.createHostRuntime }
+        : {}),
+      ...(options.sessionStore
+        ? { sessionStore: options.sessionStore }
+        : {}),
+      ...(options.sessionsDir ? { sessionsDir: options.sessionsDir } : {}),
+      ...(options.now ? { now: options.now } : {}),
+      ...(options.createSessionTempId
+        ? { createSessionTempId: options.createSessionTempId }
+        : {}),
+      ...(options.createAttemptId
+        ? { createAttemptId: options.createAttemptId }
+        : {}),
+      ...(options.signal ? { signal: options.signal } : {}),
       // PBCLI-39: the run path gates on SDK availability too.
       ...(options.probeAdapterSdk
         ? { probeAdapterSdk: options.probeAdapterSdk }
@@ -115,36 +168,85 @@ export async function runPlaybookCli(options = {}) {
     );
     return { code: COMPOSITION_FAILURE_EXIT_CODE };
   }
+  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',
+    );
+    return { code: COMPOSITION_FAILURE_EXIT_CODE };
+  }
 
   // PBCLI-1: explicit `--config <path>` launches that raw tmux-play config
   // directly, bypassing seeding, composition, and the readiness gate.
   if (hasExplicitConfig(argv)) {
+    try {
+      assertRawConfigHasNoManagedSelector(argv);
+    } catch (error) {
+      stderr.write(`playbook: ${errorMessage(error)}\n`);
+      return { code: COMPOSITION_FAILURE_EXIT_CODE };
+    }
     return await launchTmuxPlay(spawnFn, [tmuxPlayBin, ...argv], stderr);
   }
 
-  seedUserConfigIfMissing(userConfigPath, stderr);
-
-  // DR-021 §3: an existing profiles-based config is rewritten in place once,
-  // with the original kept beside it, so the user launches without editing.
+  let interactiveArgs;
   try {
-    migrateUserConfigIfRetired(userConfigPath, stderr);
+    interactiveArgs = parseInteractiveArgs(forwardArgv);
   } catch (error) {
     stderr.write(`playbook: ${errorMessage(error)}\n`);
     return { code: COMPOSITION_FAILURE_EXIT_CODE };
   }
 
-  let composed;
-  try {
-    let top = parseYaml(readFileSync(userConfigPath, 'utf8')) ?? {};
-    if (withPaths.length > 0 && !isObject(top)) {
-      throw new Error(
-        `the top-level config at ${userConfigPath} must be a YAML map before --with can overlay it`,
+  const launchCwd = resolve(
+    options.cwd ?? process.cwd(),
+    interactiveArgs.cwd ?? '.',
+  );
+  // 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.
+  let store;
+  let selectedRecord;
+  if (interactiveArgs.sessionId !== undefined) {
+    try {
+      store = createInteractiveStore(options, env, home);
+      selectedRecord = validateCaptainSessionRecord(
+        await store.read(interactiveArgs.sessionId),
       );
+      if (selectedRecord.state !== 'settled') {
+        throw new Error(
+          `Captain session ${JSON.stringify(interactiveArgs.sessionId)} has an uncertain turn; recover it with playbook run before reopening interactively`,
+        );
+      }
+    } catch (error) {
+      stderr.write(`playbook: ${errorMessage(error)}\n`);
+      return { code: COMPOSITION_FAILURE_EXIT_CODE };
     }
-    for (const overlayPath of withPaths) {
-      top = mergeConfigs(top, loadOverlayFragment(overlayPath));
-    }
-    composed = await composeGenericConfig(top, loadModule, userConfigPath);
+  }
+
+  let plan;
+  try {
+    plan = selectedRecord
+      ? await loadSelectedLaunchPlanDataOnly({
+          userConfigPath,
+          overlayPaths: withPaths,
+          structuralProjection: selectedRecord.structuralProjection,
+          onNotice: (line) => stderr.write(line),
+        })
+      : await loadLaunchPlan({
+          userConfigPath,
+          overlayPaths: withPaths,
+          loadModule,
+          prepareRegistryModule:
+            options.prepareRegistryModule ??
+            prepareConfiguredRegistries({
+              enabled: !noProvision,
+              stderr,
+              hostRoots: options.hostRoots,
+              commandName: 'playbook',
+            }),
+          onNotice: (line) => stderr.write(line),
+        });
   } catch (error) {
     stderr.write(`playbook: ${errorMessage(error)}\n`);
     return { code: COMPOSITION_FAILURE_EXIT_CODE };
@@ -152,15 +254,16 @@ export async function runPlaybookCli(options = {}) {
 
   // PBCLI-5: `--list` prints each configured playbook's id, effective
   // command, and intent without launching tmux-play.
-  if (argv.includes('--list')) {
-    for (const pb of composed.playbooks) {
+  if (interactiveArgs.list) {
+    for (const pb of Object.values(plan.catalog)) {
       stdout.write(`/${pb.command}  ${pb.id}  —  ${pb.intent}\n`);
     }
     return { code: 0 };
   }
 
-  // PBCLI-12: readiness reads the adapters of the composed config.
-  const declaredAdapters = adaptersFromComposedConfig(composed.config);
+  // PBCLI-12/46: readiness derives from the same normalized execution plan
+  // that both front ends consume, independent of its tmux projection.
+  const declaredAdapters = adaptersFromLaunchPlan(plan);
   const readiness = checkReadiness(declaredAdapters, env, home);
   // PBCLI-39/40: SDK availability is an independent check with its own
   // remedy — a credential and an SDK can be missing at once, and reporting
@@ -195,521 +298,443 @@ export async function runPlaybookCli(options = {}) {
     return { code: READINESS_FAILURE_EXIT_CODE };
   }
 
+  // tmux-play's diagnostics command is an explicit presentation escape hatch,
+  // not a managed logical session. Preserve its established direct child
+  // status/signal behavior and do not allocate a durable UUID or lease.
+  if (interactiveArgs.themeDiagnostics) {
+    const { dir: tempDir, path: composedPath } = writeComposedConfig(
+      projectTmuxConfig(plan),
+    );
+    try {
+      return await launchTmuxPlay(
+        spawnFn,
+        [
+          tmuxPlayBin,
+          '--config',
+          composedPath,
+          ...interactiveArgs.diagnosticArgv,
+        ],
+        stderr,
+      );
+    } finally {
+      rmSync(tempDir, { recursive: true, force: true });
+    }
+  }
+
+  try {
+    store ??= createInteractiveStore(options, env, home);
+  } catch (error) {
+    stderr.write(`playbook: ${errorMessage(error)}\n`);
+    return { code: COMPOSITION_FAILURE_EXIT_CODE };
+  }
+
+  let sessionId;
+  let executionProjection;
+  let cwd;
+  try {
+    if (selectedRecord) {
+      sessionId = selectedRecord.sessionId;
+      cwd = selectedRecord.cwd;
+      executionProjection = assertCaptainSessionExecutionCompatible(
+        selectedRecord.structuralProjection,
+        executionConfigFromPlan(plan),
+      );
+    } else {
+      sessionId = (options.createLogicalSessionId ?? randomUUID)();
+      if (typeof sessionId !== 'string' || !SESSION_ID_PATTERN.test(sessionId)) {
+        throw new Error(
+          `logical session id generator returned a non-UUID value: ${JSON.stringify(sessionId)}`,
+        );
+      }
+      cwd = launchCwd;
+      executionProjection = executionConfigFromPlan(plan);
+    }
+  } catch (error) {
+    stderr.write(`playbook: ${errorMessage(error)}\n`);
+    return { code: COMPOSITION_FAILURE_EXIT_CODE };
+  }
+
   const { dir: tempDir, path: composedPath } = writeComposedConfig(
-    composed.config,
+    projectTmuxConfig(plan),
   );
+  let prepared;
   try {
-    return await launchTmuxPlay(
-      spawnFn,
-      [tmuxPlayBin, '--config', composedPath, ...forwardArgv],
-      stderr,
+    throwIfSignalAborted(options.signal);
+    prepared = await awaitManagedPreparation(
+      () =>
+        (options.launchManagedTmuxPlay ?? launchManagedTmuxPlay)({
+          sessionId,
+          configPath: composedPath,
+          cwd,
+          stdout,
+          stderr,
+          ...(options.attach !== undefined ? { attach: options.attach } : {}),
+          ...(options.adapterImports
+            ? { adapterImports: options.adapterImports }
+            : {}),
+          createSessionCommand: (context) =>
+            createManagedInteractiveSessionCommand(
+              context,
+              {
+                schemaVersion: MANAGED_INTERACTIVE_PAYLOAD_SCHEMA_VERSION,
+                kind: MANAGED_INTERACTIVE_PAYLOAD_KIND,
+                mode: selectedRecord ? 'selected' : 'fresh',
+                sessionId,
+                cwd,
+                sessionsDir: store.sessionsDir,
+                noProvision,
+                executionProjection,
+              },
+              {
+                selfBin:
+                  options.managedSessionBin ??
+                  fileURLToPath(
+                    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'),
+      );
+    }
+    try {
+      await writeStream(
+        stderr,
+        `playbook: session ${sessionId}\n`,
+        options.signal,
+      );
+    } catch (error) {
+      await cancelPreparedAfterFailure(prepared, error);
+    }
+    await cancelPreparedIfAborted(prepared, options.signal);
+    await prepared.attach({
+      ...(options.signal ? { signal: options.signal } : {}),
+      ...(options.onBeforeManagedAttach
+        ? { beforeNativeAttach: options.onBeforeManagedAttach }
+        : {}),
+    });
+    return { code: 0 };
+  } catch (error) {
+    stderr.write(`playbook: failed to launch managed session: ${errorMessage(error)}\n`);
+    return { code: COMPOSITION_FAILURE_EXIT_CODE };
   } finally {
     rmSync(tempDir, { recursive: true, force: true });
   }
 }
 
-// PBCLI-26: split `--with <path>` pairs out of the argument vector so
-// they are consumed by the launcher rather than forwarded to tmux-play.
-function extractWithFlags(argv) {
-  const withPaths = [];
-  const rest = [];
-  for (let i = 0; i < argv.length; i += 1) {
-    const arg = argv[i];
-    if (arg === '--with') {
-      const value = argv[i + 1];
-      if (value === undefined || value === '') {
-        throw new Error('--with needs a value');
-      }
-      withPaths.push(value);
-      i += 1;
-    } else if (arg.startsWith('--with=')) {
-      const value = arg.slice('--with='.length);
-      if (!value) throw new Error('--with needs a value');
-      withPaths.push(value);
-    } else {
-      rest.push(arg);
+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.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');
     }
+    const recoveryArg = argv.find(
+      (arg) =>
+        arg === '--continue' ||
+        arg === '--retry-uncertain' ||
+        arg === '--discard-uncertain',
+    );
+    if (recoveryArg !== undefined) {
+      throw new Error(
+        `${recoveryArg} is headless recovery syntax; use playbook run with an explicit session`,
+      );
+    }
+    return Object.freeze({
+      sessionId: undefined,
+      cwd: undefined,
+      list: false,
+      themeDiagnostics: true,
+      diagnosticArgv: Object.freeze([...argv]),
+    });
   }
-  return { withPaths, rest };
-}
 
-// PBCLI-25: an overlay fragment is a top-level-format YAML map.
-function loadOverlayFragment(overlayPath) {
-  const resolved = resolve(overlayPath);
-  let text;
-  try {
-    text = readFileSync(resolved, 'utf8');
-  } catch (error) {
+  let sessionId;
+  let cwd;
+  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');
+      list = true;
+      continue;
+    }
+    if (arg === '--session' || arg.startsWith('--session=')) {
+      if (sessionId !== undefined) {
+        throw new Error('interactive --session selector was repeated or combined');
+      }
+      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');
+      }
+      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;
+      continue;
+    }
+    if (
+      arg === '--continue' ||
+      arg === '--retry-uncertain' ||
+      arg === '--discard-uncertain'
+    ) {
+      throw new Error(
+        `${arg} is headless recovery syntax; use playbook run with an explicit session`,
+      );
+    }
     throw new Error(
-      `cannot read --with overlay ${overlayPath}: ${errorMessage(error)}`,
+      `unsupported managed interactive option ${JSON.stringify(arg)}`,
     );
   }
-  let fragment;
-  try {
-    fragment = parseYaml(text);
-  } catch (error) {
+  if (sessionId !== undefined && cwd !== undefined) {
     throw new Error(
-      `cannot parse --with overlay ${overlayPath}: ${errorMessage(error)}`,
+      'interactive --cwd cannot combine with --session; the stored working directory is authoritative',
     );
   }
-  if (!isObject(fragment)) {
-    throw new Error(`--with overlay ${overlayPath} must be a YAML map`);
-  }
-  return fragment;
-}
-
-// PBCLI-25/26: recursive merge for plain maps, replacement for every
-// other value; neither input is mutated. Object.fromEntries defines own
-// data properties, so a hostile fragment key such as __proto__ cannot
-// reach the prototype.
-function mergeConfigs(base, overlay) {
-  return Object.fromEntries([
-    ...Object.entries(base),
-    ...Object.entries(overlay).map(([key, value]) => [
-      key,
-      isObject(base[key]) && isObject(value)
-        ? mergeConfigs(base[key], value)
-        : value,
-    ]),
-  ]);
-}
-
-export function resolveConfigHome(env = process.env, home = homedir()) {
-  return env.XDG_CONFIG_HOME || join(home, '.config');
-}
-
-export function resolveUserConfigPath(env = process.env, home = homedir()) {
-  return join(resolveConfigHome(env, home), 'playbook', 'playbook.config.yaml');
-}
-
-// PBCLI-8 (DR-021): a scalar `captain` / `players.<role>` value is an
-// adapter shorthand; a full block is a self-contained tmux-play agent block
-// carrying its own adapter/model/effort/permissions. There is no profile
-// indirection, so retuning one agent cannot change another.
-export function resolveAgent(value, path) {
-  if (typeof value === 'string') return { adapter: value };
-  if (isObject(value)) return { ...value };
-  throw new Error(`${path} must be an adapter shorthand or an agent block`);
-}
-
-// DR-021 §3: migrate the user's config on disk, once, keeping the original.
-// The backup is written before the rewrite and never overwrites an existing
-// file, so a prior backup — or a user's own .bak — cannot be lost.
-function migrateUserConfigIfRetired(userConfigPath, stderr) {
-  let text;
-  try {
-    text = readFileSync(userConfigPath, 'utf8');
-  } catch {
-    return;
+  if (sessionId !== undefined && list) {
+    throw new Error('--session cannot combine with --list');
   }
-  let migrated;
-  try {
-    migrated = migrateRetiredProfiles(text);
-  } catch (error) {
-    throw new Error(
-      `cannot migrate the retired profiles config at ${userConfigPath}: ` +
-        `${errorMessage(error)} — edit it by hand: each agent takes its own ` +
-        'adapter, model, effort, and permissions',
-    );
+  if (list && cwd !== undefined) {
+    throw new Error('--cwd applies to a fresh launch and cannot combine with --list');
   }
-  if (migrated === undefined) return;
-  const backupPath = freeBackupPath(userConfigPath);
-  writeFileSync(backupPath, text, { mode: 0o600 });
-  writeFileSync(userConfigPath, migrated);
-  stderr.write(
-    `playbook: migrated ${userConfigPath} to inline agent settings ` +
-      `(the top-level "profiles" map was removed in 3.0.0); ` +
-      `the original is at ${backupPath}\n`,
-  );
+  return Object.freeze({
+    sessionId,
+    cwd,
+    list,
+    themeDiagnostics: false,
+    diagnosticArgv: Object.freeze([]),
+  });
 }
 
-function freeBackupPath(userConfigPath) {
-  const first = `${userConfigPath}.bak`;
-  if (!existsSync(first)) return first;
-  for (let n = 2; ; n += 1) {
-    const candidate = `${userConfigPath}.bak.${n}`;
-    if (!existsSync(candidate)) return candidate;
+// PBCLI-23/24/49: the executable converts termination signals into an abort of
+// an active headless turn or a not-yet-attached managed launch, waits for its
+// uncertain marker and lease cleanup, then asks the caller to re-raise the
+// original signal. Cligent invokes the supplied synchronous hand-off only
+// after input activation and immediately before starting the native tmux
+// client; that exact boundary transfers signal ownership to native terminal
+// semantics without leaving an unowned activation interval.
+export async function runPlaybookCliEntry(options = {}) {
+  const processLike = options.processLike ?? process;
+  const entryArgv = options.argv ?? processLike.argv?.slice(2) ?? [];
+  if (entryArgv[0] !== 'run' && !isManagedInteractiveInvocation(entryArgv)) {
+    return runPlaybookCli(options);
   }
-}
-
-// DR-021 §3: rewrite a config written for the retired profiles model in
-// place, inlining each agent's settings and keeping the original beside it.
-// Edits go through the YAML Document API so the user's comments survive;
-// only the profiles block and its own commentary are removed. Returns the
-// migrated text, or undefined when there is nothing to migrate.
-export function migrateRetiredProfiles(text) {
-  const doc = parseYamlDocument(text);
-  const contents = doc.contents;
-  if (!contents || !Array.isArray(contents.items)) return undefined;
-  const profiles = doc.get('profiles');
-  const agentPaths = [['captain']];
-  const playbooks = doc.get('playbooks');
-  if (playbooks && Array.isArray(playbooks.items)) {
-    for (const entry of playbooks.items) {
-      const id = String(entry.key);
-      const players = doc.getIn(['playbooks', id, 'players']);
-      if (!players || !Array.isArray(players.items)) continue;
-      for (const player of players.items) {
-        agentPaths.push(['playbooks', id, 'players', String(player.key)]);
-      }
+  const controller = new AbortController();
+  let receivedSignal;
+  let signalOwnershipTransferred = false;
+  const handlers = {};
+  const removeHandlers = () => {
+    for (const [signal, handler] of Object.entries(handlers)) {
+      processLike.off(signal, handler);
     }
-  }
-
-  const profileSettings = (name) =>
-    profiles && typeof profiles.get === 'function'
-      ? profiles.get(name)
-      : undefined;
-
-  let changed = false;
-  for (const path of agentPaths) {
-    const node = doc.getIn(path, true);
-    if (node && typeof node.value === 'string' && !Array.isArray(node.items)) {
-      // A scalar that named a profile; a bare adapter shorthand stays.
-      const settings = profileSettings(node.value);
-      if (settings === undefined) continue;
-      const inlined = settings.clone();
-      // The scalar carried any comment on that line, and replacing the node
-      // would drop it. Re-attach it above the block that replaces it.
-      carryScalarComment(node, inlined);
-      doc.setIn(path, inlined);
-      changed = true;
-    } else if (node && Array.isArray(node.items)) {
-      const named = node.get?.('profile');
-      if (named === undefined) continue;
-      const settings = profileSettings(named);
-      if (settings === undefined) {
-        throw new Error(
-          `${path.join('.')}.profile names "${String(named)}", which no ` +
-            'profiles entry defines',
-        );
-      }
-      // Fill the block from its profile in place — never rebuild it — so
-      // the user's own keys, ordering, and comments survive untouched. The
-      // block's own fields stay authoritative, so only absent keys are added.
-      node.delete('profile');
-      for (const item of settings.items) {
-        if (node.has(String(item.key))) continue;
-        // Append the whole pair, not a rebuilt key/value: a comment above a
-        // setting rides on that setting's key node, so stringifying the key
-        // would drop it.
-        node.add(item.clone());
+  };
+  for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+    handlers[signal] = () => {
+      if (receivedSignal !== undefined) {
+        removeHandlers();
+        processLike.kill(processLike.pid, signal);
+        return;
       }
-      changed = true;
-    }
+      receivedSignal = signal;
+      controller.abort(new Error(`received ${signal}`));
+    };
   }
-
-  if (profiles !== undefined) {
-    // The comment block above `profiles` usually carries the file's own
-    // header, which must outlive the removed section: keep every paragraph
-    // except the last, which documents profiles themselves.
-    const index = contents.items.findIndex(
-      (item) => String(item.key) === 'profiles',
-    );
-    const lead = index === -1 ? undefined : contents.items[index]?.key
-      ?.commentBefore;
-    doc.delete('profiles');
-    const header = keptHeaderComment(lead);
-    const next = contents.items[0];
-    if (header !== undefined && next?.key) {
-      next.key.commentBefore =
-        next.key.commentBefore === undefined
-          ? header
-          : `${header}\n\n${next.key.commentBefore}`;
-    }
-    changed = true;
+  for (const [signal, handler] of Object.entries(handlers)) {
+    processLike.on(signal, handler);
+  }
+  try {
+    const result = await runPlaybookCli({
+      ...options,
+      signal: controller.signal,
+      onBeforeManagedAttach: () => {
+        signalOwnershipTransferred = true;
+        removeHandlers();
+        options.onBeforeManagedAttach?.();
+      },
+    });
+    return receivedSignal === undefined || signalOwnershipTransferred
+      ? result
+      : { signal: receivedSignal };
+  } finally {
+    removeHandlers();
   }
-  if (!changed) return undefined;
-  // Say what happened at the top of the file the user will open next:
-  // some of their remaining comments describe the retired model.
-  doc.commentBefore = MIGRATION_NOTE;
-  return doc.toString();
 }
 
-const MIGRATION_NOTE =
-  ' Migrated by playbook 3.0.0: the top-level `profiles` map was removed and\n' +
-  ' each agent now carries its settings inline. The pre-migration file is\n' +
-  ' kept beside this one as a .bak. Comments below may still describe the\n' +
-  ' retired profiles model.';
-
-// Move a scalar agent's own comments onto the block that replaces it, so
-// `captain: base # the judge` keeps its note. The pair's key comments are
-// untouched by the replacement and need no carrying.
-function carryScalarComment(node, inlined) {
-  const parts = [node.commentBefore, node.comment].filter(
-    (part) => typeof part === 'string' && part.trim() !== '',
+function isManagedInteractiveInvocation(argv) {
+  return (
+    !argv.includes('--help') &&
+    !argv.includes('-h') &&
+    !argv.includes('--list') &&
+    !argv.includes('--theme-diagnostics') &&
+    !hasExplicitConfig(argv)
   );
-  if (parts.length === 0) return;
-  const first = inlined.items?.[0]?.key;
-  if (!first) return;
-  // A flow map carrying a comment renders as a multi-line brace block; the
-  // ordinary block form is what the rest of the config looks like.
-  inlined.flow = false;
-  const carried = parts.join('\n');
-  first.commentBefore =
-    first.commentBefore === undefined
-      ? carried
-      : `${carried}\n${first.commentBefore}`;
 }
 
-// Drop the trailing paragraph — the one describing the profiles block —
-// and keep the rest of the leading comment (SPDX header, file overview).
-function keptHeaderComment(comment) {
-  if (typeof comment !== 'string' || comment.trim() === '') return undefined;
-  const paragraphs = comment.split('\n\n');
-  const kept = paragraphs.slice(0, -1).join('\n\n');
-  return kept.trim() === '' ? undefined : kept;
+function writeComposedConfig(composed) {
+  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='));
 }
 
-// A `profile` key that survives migration — introduced by a `--with`
-// overlay rather than the user's own config — is still rejected.
-function assertNoRetiredProfiles(top, configPath) {
-  const where = configPath ? ` in ${configPath}` : '';
-  if (top.profiles !== undefined) {
+function assertRawConfigHasNoManagedSelector(argv) {
+  const managed = argv.find(
+    (arg) =>
+      arg === '--session' ||
+      arg.startsWith('--session=') ||
+      arg === '--continue' ||
+      arg === '--retry-uncertain' ||
+      arg === '--discard-uncertain',
+  );
+  if (managed !== undefined) {
     throw new Error(
-      `top-level "profiles" was removed${where}: write each agent's settings ` +
-        'inline under captain and each playbooks.<id>.players.<role> ' +
-        '(adapter, model, effort, permissions)',
+      `${managed} selects a managed Captain session and cannot combine with a raw --config launch`,
     );
   }
-  const blocks = [['captain', top.captain]];
-  const playbooksCfg = isObject(top.playbooks) ? top.playbooks : {};
-  for (const [id, block] of Object.entries(playbooksCfg)) {
-    const playersMap = isObject(block) && isObject(block.players)
-      ? block.players
-      : {};
-    for (const [role, agent] of Object.entries(playersMap)) {
-      blocks.push([`playbooks.${id}.players.${role}`, agent]);
-    }
-  }
-  for (const [path, block] of blocks) {
-    if (isObject(block) && block.profile !== undefined) {
-      throw new Error(
-        `${path}.profile was removed${where}: write the agent's settings ` +
-          'inline in that block (adapter, model, effort, permissions)',
-      );
-    }
+}
+
+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) {
+    throw new Error(`${name} requires a value`);
   }
+  return value;
 }
 
-function isValidRegistryEntry(value) {
-  if (!isObject(value)) return false;
+function createInteractiveStore(options, env, home) {
   return (
-    typeof value.id === 'string' &&
-    typeof value.command === 'string' &&
-    typeof value.intent === 'string' &&
-    Array.isArray(value.requiredRoleIds) &&
-    typeof value.validateOptions === 'function' &&
-    typeof value.createRuntime === 'function'
+    options.sessionStore ??
+    createCaptainSessionStore({
+      env,
+      homeDir: home,
+      ...(options.sessionsDir ? { sessionsDir: options.sessionsDir } : {}),
+      ...(options.now ? { now: options.now } : {}),
+      ...(options.createSessionTempId
+        ? { createTempId: options.createSessionTempId }
+        : {}),
+    })
   );
 }
 
-// PBCLI-8/9/10: normalize the top-level `playbooks` config into
-// a tmux-play config (Captain = the shell adapter; `captain.options.playbooks`
-// the normalized enablement; a launch-time namespaced `<id>-<role>` roster;
-// launcher-owned `layout.initialVisible`).
-export async function composeGenericConfig(top, loadModule, configPath) {
-  assertNoRetiredProfiles(top, configPath);
-
-  const playbooksCfg = requireObject(top.playbooks, 'playbooks');
-  const ids = Object.keys(playbooksCfg);
-  if (ids.length === 0) {
-    throw new Error('playbooks must enable at least one playbook');
-  }
-
-  const captain = {
-    from: PLAYBOOK_CAPTAIN_MODULE,
-    ...resolveAgent(top.captain, 'captain'),
-  };
-  if (captain.adapter === undefined) {
-    throw new Error('captain must resolve an adapter');
-  }
-
-  const optionsPlaybooks = {};
-  const roster = [];
-  const listing = [];
-  const seenCommands = new Map();
-  const seenIds = new Set();
-  let firstVisible;
-
-  for (const id of ids) {
-    if (id === RESERVED_CAPTAIN_PLAYBOOK_ID) {
-      throw new Error(
-        `playbooks.${id} collides with the reserved internal Captain id`,
-      );
-    }
-    const block = requireObject(playbooksCfg[id], `playbooks.${id}`);
-    const from = block.from;
-    if (typeof from !== 'string' || from.length === 0) {
-      throw new Error(`playbooks.${id}.from must be a module specifier`);
-    }
-    let mod;
-    try {
-      mod = await loadModule(from);
-    } catch (cause) {
-      throw new Error(
-        `playbooks.${id}.from "${from}" failed to import: ${errorMessage(cause)}`,
-      );
-    }
-    const entry = mod?.default;
-    if (!isValidRegistryEntry(entry)) {
-      throw new Error(
-        `playbooks.${id}.from "${from}" exposes no valid registry entry`,
-      );
-    }
-    if (entry.id !== id) {
-      throw new Error(
-        `playbooks.${id} key must equal the module manifest id "${entry.id}"`,
-      );
-    }
-    if (seenIds.has(entry.id)) {
-      throw new Error(`duplicate playbook id "${entry.id}"`);
-    }
-    seenIds.add(entry.id);
-
-    const command =
-      typeof block.command === 'string' && block.command.length > 0
-        ? block.command
-        : entry.command;
-    if (command === RESERVED_CAPTAIN_PLAYBOOK_ID) {
-      throw new Error(
-        `playbooks.${id}.command collides with the reserved internal Captain command`,
-      );
-    }
-    if (seenCommands.has(command)) {
-      throw new Error(`duplicate effective command "${command}"`);
-    }
-    seenCommands.set(command, id);
+async function writeStream(stream, text, signal) {
+  throwIfSignalAborted(signal);
+  const ready = stream.write(text);
+  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);
+    };
+    const onDrain = () => {
+      cleanup();
+      resolvePromise();
+    };
+    const onError = (error) => {
+      cleanup();
+      rejectPromise(error);
+    };
+    const onAbort = () => {
+      cleanup();
+      rejectPromise(signal.reason ?? new Error('operation aborted'));
+    };
+    stream.once('drain', onDrain);
+    stream.once('error', onError);
+    signal?.addEventListener('abort', onAbort, { once: true });
+    if (signal?.aborted) onAbort();
+  });
+}
 
-    // PBCLI-9: reject the reserved role before the coverage checks below, so
-    // an entry requiring `captain` names the real fault rather than a missing
-    // players entry.
-    if (entry.requiredRoleIds.includes(RESERVED_CAPTAIN_ROLE_ID)) {
-      throw new Error(
-        `playbooks.${id} requires local role "${RESERVED_CAPTAIN_ROLE_ID}", ` +
-          'which is reserved for the tmux-play Captain',
-      );
-    }
+async function awaitManagedPreparation(start, signal) {
+  throwIfSignalAborted(signal);
+  const launch = Promise.resolve().then(start);
+  if (signal === undefined) return launch;
 
-    const playersMap = requireObject(block.players, `playbooks.${id}.players`);
-    const roles = Object.keys(playersMap);
-    if (roles.includes(RESERVED_CAPTAIN_ROLE_ID)) {
-      throw new Error(
-        `playbooks.${id}.players.${RESERVED_CAPTAIN_ROLE_ID} binds local ` +
-          `role "${RESERVED_CAPTAIN_ROLE_ID}", which is reserved for the ` +
-          'tmux-play Captain',
-      );
-    }
-    if (roles.length === 0) {
-      throw new Error(`playbooks.${id} resolves no visible local role`);
-    }
-    for (const required of entry.requiredRoleIds) {
-      if (!roles.includes(required)) {
-        throw new Error(
-          `playbooks.${id} required role "${required}" has no players entry`,
-        );
-      }
-    }
-    const generated = [];
-    for (const role of roles) {
-      const agent = resolveAgent(
-        playersMap[role],
-        `playbooks.${id}.players.${role}`,
-      );
-      if (agent.adapter === undefined) {
-        throw new Error(
-          `playbooks.${id}.players.${role} must resolve an adapter`,
-        );
-      }
-      const hostId = `${id}-${role}`;
-      roster.push({ id: hostId, ...agent });
-      generated.push(hostId);
-    }
-    if (firstVisible === undefined) firstVisible = generated;
+  let onAbort;
+  const aborted = new Promise((resolvePromise) => {
+    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 }),
+    ),
+    aborted,
+  ]);
+  signal.removeEventListener('abort', onAbort);
+  if (outcome.type === 'prepared') return outcome.value;
+  if (outcome.type === 'failed') throw outcome.error;
 
-    const optionSlice = {};
-    for (const key of Object.keys(block)) {
-      if (!PLAYBOOK_LAUNCHER_KEYS.includes(key)) {
-        optionSlice[key] = block[key];
-      }
-    }
-    optionsPlaybooks[id] = {
-      from,
-      ...(typeof block.command === 'string' && block.command.length > 0
-        ? { command: block.command }
-        : {}),
-      options: optionSlice,
-    };
-    listing.push({ id, command, intent: entry.intent });
+  const abortError = signal.reason ?? new Error('operation aborted');
+  let latePrepared;
+  try {
+    latePrepared = await launch;
+  } catch (launchError) {
+    throw aggregateOperationalFailures(
+      abortError,
+      launchError,
+      'managed tmux-play preparation failed while retiring an aborted launch',
+    );
   }
-
-  // DR-013 A1: the shell cannot see its own captain's adapter through the
-  // tmux-play CaptainContext, so the launcher — which resolved it — passes it
-  // through. The shell needs it to decide whether an explicit empty tool
-  // allowlist can be enforced or must degrade to prompt-level restriction.
-  captain.options = {
-    playbooks: optionsPlaybooks,
-    ...(typeof captain.adapter === 'string' && captain.adapter.length > 0
-      ? { captainAdapter: captain.adapter }
-      : {}),
-  };
-  const config = { captain, players: roster };
-  // PBCLI-10: carry the user's tmux-play layout window/weight fields through;
-  // the launcher owns `layout.initialVisible` (first enabled playbook).
-  const layout = isObject(top.layout) ? { ...top.layout } : {};
-  layout.initialVisible = firstVisible;
-  config.layout = layout;
-  if (top.notifications !== undefined) config.notifications = top.notifications;
-  if (top.theme !== undefined) config.theme = top.theme;
-  return { config, playbooks: listing };
+  await cancelPreparedAfterFailure(latePrepared, abortError);
 }
 
-export function adaptersFromComposedConfig(config) {
-  const adapters = new Set();
-  if (config?.captain?.adapter) adapters.add(config.captain.adapter);
-  for (const player of config?.players ?? []) {
-    if (player?.adapter) adapters.add(player.adapter);
-  }
-  return [...adapters];
+async function cancelPreparedIfAborted(prepared, signal) {
+  if (!signal?.aborted) return;
+  await cancelPreparedAfterFailure(
+    prepared,
+    signal.reason ?? new Error('operation aborted'),
+  );
 }
 
-export function checkReadiness(adapters, env = process.env, home = homedir()) {
-  const failingAdapters = [];
-  const unknownAdapters = [];
-  for (const adapter of adapters) {
-    if (adapter === 'claude') {
-      if (!env.ANTHROPIC_API_KEY && !existsSync(join(home, '.claude'))) {
-        failingAdapters.push(adapter);
-      }
-      continue;
-    }
-    if (adapter === 'codex') {
-      if (!env.OPENAI_API_KEY && !existsSync(join(home, '.codex'))) {
-        failingAdapters.push(adapter);
-      }
-      continue;
+async function cancelPreparedAfterFailure(prepared, primary) {
+  try {
+    if (typeof prepared?.cancel !== 'function') {
+      throw new Error('managed tmux-play preparation has no cancellation boundary');
     }
-    unknownAdapters.push(adapter);
+    await prepared.cancel();
+  } catch (cancelError) {
+    throw aggregateOperationalFailures(
+      primary,
+      cancelError,
+      `managed session operation failed (${errorMessage(primary)}) and cancellation could not prove ownership retirement`,
+    );
   }
-  return { failingAdapters, unknownAdapters };
-}
-
-function writeComposedConfig(composed) {
-  const dir = mkdtempSync(join(tmpdir(), 'playbook-'));
-  const path = join(dir, 'tmux-play.config.yaml');
-  writeFileSync(path, stringifyYaml(composed));
-  return { dir, path };
+  throw primary;
 }
 
-function seedUserConfigIfMissing(userConfigPath, stderr) {
-  if (existsSync(userConfigPath)) return;
-  mkdirSync(dirname(userConfigPath), { recursive: true });
-  copyFileSync(templatePath, userConfigPath, constants.COPYFILE_EXCL);
-  stderr.write(`playbook: created config at ${userConfigPath}\n`);
+function aggregateOperationalFailures(primary, secondary, summary) {
+  return new AggregateError(
+    [primary, secondary],
+    `${summary}: ${errorMessage(secondary)}`,
+  );
 }
 
-function hasExplicitConfig(argv) {
-  return argv.some((arg) => arg === '--config' || arg.startsWith('--config='));
+function throwIfSignalAborted(signal) {
+  if (signal?.aborted) {
+    throw signal.reason ?? new Error('operation aborted');
+  }
 }
 
 function helpText({
@@ -727,17 +752,35 @@ function helpText({
     ...sdkFailureLines,
     ...failures,
     'Usage:',
-    '  playbook [--list] [--with <path>]... [--config <path>] [tmux-play options]',
-    '  playbook run <from> [task] [options]   # non-interactive one-shot',
-    '  playbook run resume <session-id> [reply]   # answer a parked run',
+    '  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) over the default config for this launch only —',
-    '  maps merge recursively, other values replace, later files win. The',
+    '  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',
@@ -748,11 +791,20 @@ function helpText({
     '  vendors your config actually names.',
     '',
     'Agent swap recipe:',
-    '  - set each agent inline: the top-level captain and every',
-    '    playbooks.<id>.players.<role> takes an adapter shorthand',
-    '    (claude, codex) or a block with adapter/model/effort/permissions',
-    '  - the launcher injects captain.from and the namespaced <id>-<role>',
-    '    host players',
+    '  - 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');
 }
@@ -793,21 +845,6 @@ function resolveTmuxPlayBin() {
   return join(dirname(fileURLToPath(tmuxPlayIndexUrl)), 'cli.js');
 }
 
-function isObject(value) {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
-function hasOwn(value, key) {
-  return Object.prototype.hasOwnProperty.call(value, key);
-}
-
-function requireObject(value, path) {
-  if (!isObject(value)) {
-    throw new Error(`${path} must be an object`);
-  }
-  return value;
-}
-
 function errorMessage(error) {
   return error instanceof Error ? error.message : String(error);
 }
@@ -822,7 +859,8 @@ function isCliEntry(argv1 = process.argv[1], moduleUrl = import.meta.url) {
 }
 
 if (isCliEntry()) {
-  const result = await runPlaybookCli();
+  const result = await runPlaybookCliEntry();
   if (result.signal) process.kill(process.pid, result.signal);
-  else process.exit(result.code ?? 0);
+  // Let Node drain a long piped Captain reply or diagnostic naturally.
+  else process.exitCode = result.code ?? 0;
 }