@sublang/playbook 3.1.0 → 4.0.0

package/README.md

@@ -34,10 +34,30 @@ or `ANTHROPIC_API_KEY`, and signed-in
 [Codex CLI](https://github.com/openai/codex) or `OPENAI_API_KEY`.
 
 ```sh
-npm install -g @sublang/playbook
+npm install -g @sublang/playbook @anthropic-ai/claude-agent-sdk @openai/codex-sdk
 playbook
 ```
 
+The agent SDKs are optional, so you install only the vendors your
+config names — install one and the package stays around 14 MB rather
+than pulling every stack. Name each SDK as its own top-level install
+root, exactly as above: an SDK nested inside another package's subtree
+is not reachable from the adapter that loads it. Which versions work
+is cligent's knowledge and ships with it: if a runtime is missing — or
+installed below the version cligent supports — `playbook` says so
+before it launches anything, naming the installed and required
+versions and printing cligent's pinned install command
+([DR-026](specs/decisions/026-optional-adapter-sdks.md),
+[DR-027](specs/decisions/027-runtime-compatibility-from-cligent.md)).
+
+Upgrading from 3.1.0 or earlier? Use the same full line — npm removes
+the SDK copies those releases bundled when it upgrades the package, so
+upgrading `@sublang/playbook` alone leaves no agent SDK installed.
+Running via `npx` instead? Name each SDK as a sibling package of the
+same invocation (`npx -y -p @sublang/playbook -p <sdk> playbook`) — no
+install command reaches npx's ephemeral tree; see
+[docs/cli.md](docs/cli.md).
+
 The first launch seeds a commented config at
 `${XDG_CONFIG_HOME:-$HOME/.config}/playbook/playbook.config.yaml`,
 composes a `tmux-play` config, checks the declared adapters, and opens
@@ -70,14 +90,16 @@ playbook run @sublang/playbook/code/registry "add a test for parseArgs" --json
 - **[docs/embedding.md](docs/embedding.md)** — the six-port runtime
   contract for hosts other than `tmux-play`.
 
-> **Current release:** 3.1.0. The composed system — the compiled default
+> **Current release:** 4.0.0. The composed system — the compiled default
 > Captain, CODE and DISCUSS, nested playbook calls, script actors and the
 > GEARS optimize pass, the semver-stable six-port runtime contract, and
 > non-interactive `playbook run` with parked-session resume — landed in
 > 1.0.0. Since then, `playbook run` gained defaults in the user config,
 > 3.0.0 replaced the top-level `profiles` map with inline agent settings
-> (existing configs migrate themselves on the next launch), and 3.1.0
-> added the linked-artifact/engine compatibility check. See the
+> (existing configs migrate themselves on the next launch), 3.1.0
+> added the linked-artifact/engine compatibility check, and 4.0.0 made
+> the agent SDKs optional — an install carries only the vendors you name
+> — with which versions work now owned and published by cligent. See the
 > [CHANGELOG](CHANGELOG.md).
 
 ## How it compiles

package/docs/cli.md

@@ -7,6 +7,51 @@
 one-shot non-interactive `run`. Agent settings for both come from the
 [config](configuration.md).
 
+## Installing agent SDKs
+
+Each adapter is backed by a vendor runtime that installing
+`@sublang/playbook` never downloads for you, so no install carries an
+agent stack you did not ask for. Which versions each adapter supports
+is [cligent](https://github.com/sublang-ai/cligent)'s knowledge and
+ships with it
+([DR-027](../specs/decisions/027-runtime-compatibility-from-cligent.md));
+the commands below install the latest, which cligent accepts from its
+supported floor up. Install the SDKs your config names, each as its
+own top-level install root:
+
+```sh
+npm install -g @sublang/playbook @anthropic-ai/claude-agent-sdk   # claude
+npm install -g @sublang/playbook @openai/codex-sdk                # codex
+npm install -g @sublang/playbook @opencode-ai/sdk opencode-ai     # opencode (SDK + CLI)
+```
+
+The `gemini` adapter needs no SDK install — its transport ships inside
+cligent — only the `gemini` CLI on `PATH`, at a version cligent
+supports; the preflight gates it like the SDKs.
+
+**Upgrading from ≤ 3.1.0:** run the same full line. The old releases
+bundled the SDKs inside `@sublang/playbook`'s own tree, and npm
+removes that bundled copy when it upgrades to a version that no
+longer declares them — an in-place `npm install -g @sublang/playbook`
+alone leaves no SDK behind.
+
+The "own top-level root" part matters. The adapter that imports the SDK
+lives at `@sublang/playbook/node_modules/@sublang/cligent/`, and Node
+finds a bare specifier by walking *up* from there — which reaches the
+install prefix's own `node_modules`, but never into a sibling package's
+subtree. An SDK that landed inside some other package is invisible to
+the adapter even though it is on disk
+([DR-026](../specs/decisions/026-optional-adapter-sdks.md)).
+
+Both surfaces check this before doing any work: a declared adapter
+whose runtime is not loadable — or is installed below the version
+cligent supports — blocks the launch and names the adapter. An absent
+runtime is reported as not installed; a stale one with its installed
+and required versions, never as absent. Either way the remedy printed
+is cligent's pinned install, `npm install -g <package>@<version>`, so
+following it cannot install a version the gate refuses again
+([PBCLI-40](../specs/user/playbook-cli.md#pbcli-40)).
+
 ## Interactive
 
 ```sh
@@ -15,7 +60,22 @@ playbook --list     # ids, slash commands, and intents; no launch
 playbook --help     # config path, auth pointers, agent-swap recipe
 ```
 
-Without a global install, `npx @sublang/playbook` runs the same bin.
+Without a global install, `npx` runs the same bin — but name each
+agent SDK as a sibling package of the same invocation:
+
+```sh
+npx -y -p @sublang/playbook -p @anthropic-ai/claude-agent-sdk playbook
+```
+
+A bare `npx @sublang/playbook` cannot be repaired by any install
+command: npx materializes the run in an ephemeral cache tree whose
+ancestor walk touches no global prefix, so an SDK installed with
+`npm install -g` is invisible to it. The preflight detects this case
+and prints the multi-package re-run instead of an install line, naming
+every SDK your config needs at cligent's pinned version — including any
+already present, since each distinct package set is a distinct tree —
+and replaying your original arguments, so the printed command works in
+one hop.
 
 The command resolves its config (seeding it on first run), composes a
 `tmux-play` config, checks adapter readiness, and launches. It exits
@@ -85,7 +145,7 @@ the playbook needs a Boss reply
 A compiled playbook module imports `xstate` and
 `@sublang/playbook/xstate-runtime` from its own directory. When a
 filesystem `<from>` cannot resolve them — typically under a global
-`npm install -g @sublang/playbook` with no project-local packages —
+install with no project-local packages —
 `playbook run` provisions them automatically before loading: it creates
 `node_modules/xstate` and `node_modules/@sublang/playbook` beside the
 module as symlinks to the running host's own packages and prints one

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sublang/playbook",
-  "version": "3.1.0",
+  "version": "4.0.0",
   "type": "module",
   "description": "Composable XState v5 playbook runtime with compiled Captain, CODE, and DISCUSS workflows driven by GEARS specs.",
   "license": "Apache-2.0",
@@ -68,6 +68,7 @@
     "reference/sdlc/code.playbook/bin/playbook.js",
     "reference/sdlc/code.playbook/bin/run.js",
     "reference/sdlc/code.playbook/bin/provision.js",
+    "reference/sdlc/code.playbook/bin/adapter-sdk.js",
     "reference/sdlc/discuss.playbook/discuss.gears.md",
     "reference/sdlc/discuss.playbook/discuss.fsm.ts",
     "reference/sdlc/discuss.playbook/discuss.fsm.js",
@@ -129,15 +130,15 @@
     "provenance": true
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.3.154",
-    "@openai/codex-sdk": "^0.139.0",
-    "@sublang/cligent": "^0.16.0",
+    "@sublang/cligent": "^0.18.0",
     "@sublang/spex": "^0.3.0",
     "p-queue": "^9.3.1",
     "xstate": "^5.19.4",
     "yaml": "^2.9.0"
   },
   "devDependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.3.221",
+    "@openai/codex-sdk": "^0.146.0",
     "@types/node": "^22.0.0",
     "typescript": "^5.8.0",
     "vitest": "^3.0.0"

package/reference/sdlc/captain.playbook/captain.playbook.js

@@ -9,7 +9,7 @@
 import PQueue from 'p-queue';
 import { createActor, fromPromise } from 'xstate';
 import { captainMachine, } from './captain.fsm.js';
-import { assertJsonSafe, combineAbortSignals, createNestedPlaybookBridge, normalizeError, normalizePlaybookSnapshot, snapshotJsonValue, snapshotPlaybookSession, validateCaptainResult, waitForPlaybookQuiescence, } from '../../../src/xstate-runtime.js';
+import { assertJsonSafe, combineAbortSignals, createNestedPlaybookBridge, defaultBuildCaptainJudgePrompt, normalizeError, normalizePlaybookSnapshot, snapshotJsonValue, snapshotPlaybookSession, validateCaptainResult, waitForPlaybookQuiescence, } from '../../../src/xstate-runtime.js';
 const CAPTAIN_OPTIONS = {
     visibility: 'visible',
     resume: false,
@@ -207,19 +207,16 @@ function requiredOutputFields(description) {
     return fields;
 }
 function makeJudgePrompt(input, visibleText) {
+    return defaultBuildCaptainJudgePrompt(input, visibleText);
+}
+// CAPPLAY-18: a structurally malformed adjudication reply gets exactly one
+// corrective re-ask carrying the rejection reason and the restated shape.
+function makeJudgeRetryPrompt(judgePrompt, rejection) {
     return [
-        'Adjudicate the direct Captain output for this FSM state.',
-        `State id: ${input.stateId}`,
-        `Source item: ${input.sourceItem}`,
-        '',
-        'Visible Captain output:',
-        visibleText,
+        judgePrompt,
         '',
-        'Result keys and descriptions:',
-        ...Object.entries(input.result).map(([key, description]) => `- ${key}: ${description}`),
-        '',
-        'Return one JSON object with exactly one declared guard.',
-        'For direct Captain question or response guards, do not include question or response; the runtime injects the visible text.',
+        `Your previous control reply was rejected: ${normalizeError(rejection).message}.`,
+        'Reply again with exactly one JSON object naming one declared `guard` key and only its required structural fields, with no prose.',
     ].join('\n');
 }
 function adjudicateCaptainOutput(input, visibleText, judgeText) {
@@ -714,7 +711,18 @@ class CaptainPlaybookRuntime {
             }
             const judgePrompt = makeJudgePrompt(input, result.finalText);
             const judgeText = await this.callJudge('captain-output-adjudication', judgePrompt, signal, input.stateId);
-            return adjudicateCaptainOutput(input, result.finalText, judgeText);
+            try {
+                return adjudicateCaptainOutput(input, result.finalText, judgeText);
+            }
+            catch (rejection) {
+                // One corrective re-ask on a malformed control reply (CAPPLAY-18);
+                // a judge transport failure above never reaches this catch.
+                if (signal.aborted)
+                    throw signal.reason;
+                const retryPrompt = makeJudgeRetryPrompt(judgePrompt, rejection);
+                const retryText = await this.callJudge('captain-output-adjudication', retryPrompt, signal, input.stateId);
+                return adjudicateCaptainOutput(input, result.finalText, retryText);
+            }
         }
         catch (error) {
             if (!signal.aborted)

package/reference/sdlc/captain.playbook/captain.playbook.ts

@@ -36,6 +36,7 @@ import {
   assertJsonSafe,
   combineAbortSignals,
   createNestedPlaybookBridge,
+  defaultBuildCaptainJudgePrompt,
   normalizeError,
   normalizePlaybookSnapshot,
   snapshotJsonValue,
@@ -291,19 +292,17 @@ function requiredOutputFields(description: string): readonly string[] {
 }
 
 function makeJudgePrompt(input: CaptainInput, visibleText: string): string {
+  return defaultBuildCaptainJudgePrompt(input, visibleText);
+}
+
+// CAPPLAY-18: a structurally malformed adjudication reply gets exactly one
+// corrective re-ask carrying the rejection reason and the restated shape.
+function makeJudgeRetryPrompt(judgePrompt: string, rejection: unknown): string {
   return [
-    'Adjudicate the direct Captain output for this FSM state.',
-    `State id: ${input.stateId}`,
-    `Source item: ${input.sourceItem}`,
-    '',
-    'Visible Captain output:',
-    visibleText,
-    '',
-    'Result keys and descriptions:',
-    ...Object.entries(input.result).map(([key, description]) => `- ${key}: ${description}`),
+    judgePrompt,
     '',
-    'Return one JSON object with exactly one declared guard.',
-    'For direct Captain question or response guards, do not include question or response; the runtime injects the visible text.',
+    `Your previous control reply was rejected: ${normalizeError(rejection).message}.`,
+    'Reply again with exactly one JSON object naming one declared `guard` key and only its required structural fields, with no prose.',
   ].join('\n');
 }
 
@@ -780,7 +779,16 @@ class CaptainPlaybookRuntime implements PlaybookRuntime {
       }
       const judgePrompt = makeJudgePrompt(input, result.finalText);
       const judgeText = await this.callJudge('captain-output-adjudication', judgePrompt, signal, input.stateId);
-      return adjudicateCaptainOutput(input, result.finalText, judgeText);
+      try {
+        return adjudicateCaptainOutput(input, result.finalText, judgeText);
+      } catch (rejection) {
+        // One corrective re-ask on a malformed control reply (CAPPLAY-18);
+        // a judge transport failure above never reaches this catch.
+        if (signal.aborted) throw signal.reason;
+        const retryPrompt = makeJudgeRetryPrompt(judgePrompt, rejection);
+        const retryText = await this.callJudge('captain-output-adjudication', retryPrompt, signal, input.stateId);
+        return adjudicateCaptainOutput(input, result.finalText, retryText);
+      }
     } catch (error) {
       if (!signal.aborted) this.latchControlError(error);
       throw error;

package/reference/sdlc/code.playbook/bin/adapter-sdk.js

@@ -0,0 +1,247 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+
+// PBCLI-39/40 (DR-027): the agent runtimes are cligent's to know. This
+// module keeps only cligent module-path knowledge — which subpath exports
+// which adapter class — and derives every runtime identity, supported
+// floor, and repair from cligent's shipped descriptor, so a cligent
+// upgrade alone moves the compatibility policy. A runtime's absence or
+// staleness has to be a named gate failure rather than a mid-turn adapter
+// error, which is what this probe provides for both the interactive
+// launcher and `run`.
+
+import { readFileSync } from 'node:fs';
+import { sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { classifyRuntime } from '@sublang/cligent';
+import { AGENT_RUNTIME_TARGETS } from '@sublang/cligent/runtime-targets';
+
+// PBCLI-39: adapter shorthand -> the cligent module that constructs it.
+// This is API-shape knowledge, not version knowledge; versions, floors,
+// and repairs come from the descriptor. Adapters absent from cligent's
+// descriptor are excluded from the gate and stay covered by PBCLI-12's
+// unknown-adapter warning.
+export const ADAPTER_MODULES = {
+  claude: {
+    module: '@sublang/cligent/adapters/claude-code',
+    export: 'ClaudeCodeAdapter',
+  },
+  codex: {
+    module: '@sublang/cligent/adapters/codex',
+    export: 'CodexAdapter',
+  },
+  // DR-027 ends gemini's exemption: its missing-SDK rationale was true but
+  // incomplete — the CLI can be absent or below cligent's floor, and the
+  // descriptor names both.
+  gemini: {
+    module: '@sublang/cligent/adapters/gemini',
+    export: 'GeminiAdapter',
+  },
+  kimi: {
+    module: '@sublang/cligent/adapters/kimi',
+    export: 'KimiAdapter',
+  },
+  opencode: {
+    module: '@sublang/cligent/adapters/opencode',
+    export: 'OpenCodeAdapter',
+  },
+};
+
+// PBCLI-39: probe through cligent's own adapter rather than by resolution.
+// `isAvailable()` performs the same load the adapter performs at run time,
+// from cligent's installed module scope — and since cligent enforces its
+// version floors inside that same loader, a passing probe cannot disagree
+// with a failing run, for absence and for staleness alike.
+export async function probeAdapterSdk(adapter) {
+  const entry = ADAPTER_MODULES[adapter];
+  if (entry === undefined) return true;
+  try {
+    const AdapterClass = (await import(entry.module))[entry.export];
+    return await new AdapterClass().isAvailable();
+  } catch {
+    // An adapter module that cannot be imported at all is unavailable,
+    // not an internal error — the remedy is the same install line.
+    return false;
+  }
+}
+
+// The descriptor rows for one adapter shorthand, in declaration order.
+function runtimeTargetsFor(adapter) {
+  return adapter in ADAPTER_MODULES
+    ? (AGENT_RUNTIME_TARGETS[adapter] ?? [])
+    : [];
+}
+
+// PBCLI-39: probe each distinct gated adapter at most once, and classify
+// an unavailable adapter's runtimes through cligent's structured verdict.
+// Only the runtimes at fault are reported: an `opencode` whose CLI is
+// present and in range names the SDK alone, because the two halves have
+// different repairs and naming a healthy one sends the user to install
+// what is already there.
+export async function checkAdapterSdks(
+  adapters,
+  probe = probeAdapterSdk,
+  classify = classifyRuntime,
+) {
+  const known = [...new Set(adapters)].filter(
+    (a) => runtimeTargetsFor(a).length > 0,
+  );
+  const results = await Promise.all(known.map((a) => probe(a)));
+  const unusableAdapters = [];
+  known.forEach((adapter, i) => {
+    if (results[i]) return;
+    const verdicts = runtimeTargetsFor(adapter).map((target) =>
+      classify(target, false),
+    );
+    const unsupported = verdicts.filter((v) => v.state === 'unsupported');
+    const missing = verdicts.filter(
+      (v) => v.state === 'missing' && v.installed === undefined,
+    );
+    // When neither explains the failure (e.g. the cligent module itself
+    // failed to import), fall back to every runtime so the gate still
+    // blocks with a usable remedy.
+    const culprits =
+      unsupported.length > 0 || missing.length > 0
+        ? [...unsupported, ...missing]
+        : verdicts;
+    unusableAdapters.push({ adapter, verdicts: culprits });
+  });
+  return { unusableAdapters };
+}
+
+// PBCLI-40: a run under `npx` / `npm exec` lives in npm's ephemeral cache
+// tree. No `npm install` invocation reaches that tree — a global SDK install
+// is not on its directory-ancestor walk — so the only honest remedy is to
+// re-run with each SDK named as a sibling package of the same exec.
+export function detectEphemeralNpxInstall(moduleUrl = import.meta.url) {
+  return fileURLToPath(moduleUrl).split(sep).includes('_npx');
+}
+
+// PBCLI-39: the pinned repair specifiers of every descriptor-backed peer
+// SDK in a lineup, deduplicated in descriptor order. The ephemeral re-run
+// must be built from this full set: a fresh exec tree starts empty, so a
+// re-run named after only the currently missing SDKs drops the ones this
+// tree does have and alternates between vendors forever. Pinned specs also
+// mean the re-run installs versions the gate accepts.
+export function mappedSdksFor(adapters) {
+  const distinct = new Set(adapters);
+  const specs = [];
+  for (const [adapter, targets] of Object.entries(AGENT_RUNTIME_TARGETS)) {
+    if (!distinct.has(adapter) || !(adapter in ADAPTER_MODULES)) continue;
+    for (const target of targets) {
+      if (target.kind === 'peer' && !specs.includes(target.repairSpec)) {
+        specs.push(target.repairSpec);
+      }
+    }
+  }
+  return specs;
+}
+
+// Minimal POSIX quoting so a preserved argument survives copy-paste; matches
+// cligent's shared shellQuote. tmux-play is POSIX-only, so no cmd.exe form.
+export function shellQuote(value) {
+  if (/^[a-zA-Z0-9_./:=@-]+$/.test(value)) {
+    return value;
+  }
+  return "'" + value.replace(/'/g, "'\\''") + "'";
+}
+
+// The running package's own spec, so the re-run reinstalls exactly this
+// version rather than whatever dist-tag `npx` would resolve today.
+function selfPackageSpec() {
+  try {
+    const manifest = JSON.parse(
+      readFileSync(new URL('../../../../package.json', import.meta.url), 'utf8'),
+    );
+    if (typeof manifest.name === 'string' && typeof manifest.version === 'string') {
+      return `${manifest.name}@${manifest.version}`;
+    }
+  } catch {
+    // Fall through to the unpinned name.
+  }
+  return '@sublang/playbook';
+}
+
+// One clause describing a runtime verdict. `unsupported` carries versions,
+// because "not installed" for a runtime that is installed sends the user
+// hunting for something already present (PBCLI-40).
+function describeVerdict(verdict) {
+  const named = verdict.target.bundles ?? verdict.target.package;
+  if (verdict.state === 'unsupported') {
+    return `${named} ${verdict.installed} installed, >=${verdict.target.supportedFrom} required`;
+  }
+  return `${named} not installed`;
+}
+
+// PBCLI-40: name every unusable adapter with its per-runtime verdicts and,
+// for each runtime at fault, the exact pinned command that supplies it.
+// External CLIs are found through PATH, which an exec tree inherits, so
+// their global install lines hold in both cases.
+//
+// options.requiredSdks: the full mapped-spec set of the lineup (see
+// mappedSdksFor) — the ephemeral re-run is built from it, not from the
+// missing subset. options.invocation: the original CLI arguments, preserved
+// on the re-run so the printed command is executable as printed.
+export function adapterSdkFailureLines(unusableAdapters, options = {}) {
+  if (unusableAdapters.length === 0) return [];
+  const ephemeralNpx = options.ephemeralNpx ?? detectEphemeralNpxInstall();
+  const lines = [
+    `Adapter runtimes not usable: ${unusableAdapters
+      .map(
+        ({ adapter, verdicts }) =>
+          `${adapter} (${verdicts.map(describeVerdict).join('; ')})`,
+      )
+      .join(', ')}`,
+  ];
+  // External CLIs are found through PATH, which persists across exec trees
+  // and installed prefixes alike, so their pinned global installs are keyed
+  // to the runtimes actually at fault and hold in both branches. A CLI's
+  // one-time steps (e.g. a login) follow its install.
+  const cliInstalls = unusableAdapters.flatMap(({ verdicts }) =>
+    verdicts
+      .filter((v) => v.target.kind === 'cli')
+      .flatMap((v) => [`npm install -g ${v.repair.spec}`, ...v.repair.steps]),
+  );
+  const peerInstalls = unusableAdapters.flatMap(({ verdicts }) =>
+    verdicts
+      .filter((v) => v.target.kind === 'peer')
+      .map((v) => `npm install -g ${v.repair.spec}`),
+  );
+  if (ephemeralNpx) {
+    const sdks =
+      options.requiredSdks ??
+      unusableAdapters.flatMap(({ verdicts }) =>
+        verdicts
+          .filter((v) => v.target.kind === 'peer')
+          .map((v) => v.repair.spec),
+      );
+    const args = (options.invocation ?? [])
+      .map((arg) => ` ${shellQuote(arg)}`)
+      .join('');
+    lines.push(
+      '  This npx / npm exec run is ephemeral: no npm install reaches its tree.',
+    );
+    if (cliInstalls.length > 0) {
+      // Prerequisites first: the re-run probes the CLI again, so following
+      // the output top-to-bottom must install it before re-running.
+      lines.push(
+        '  First install the required CLI (it persists on PATH):',
+        ...cliInstalls.map((command) => `    ${command}`),
+      );
+    }
+    lines.push(
+      `  ${cliInstalls.length > 0 ? 'Then re-run' : 'Re-run'} with every SDK your config needs named alongside the package:`,
+      `    npx -y -p ${selfPackageSpec()}${sdks
+        .map((sdk) => ` -p ${sdk}`)
+        .join('')} playbook${args}`,
+    );
+  } else {
+    lines.push(
+      ...peerInstalls.map((command) => `  ${command}`),
+      ...cliInstalls.map((command) => `  ${command}`),
+    );
+  }
+  lines.push('');
+  return lines;
+}

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

@@ -22,6 +22,12 @@ import {
   parseDocument as parseYamlDocument,
   stringify as stringifyYaml,
 } from 'yaml';
+import {
+  adapterSdkFailureLines,
+  checkAdapterSdks,
+  mappedSdksFor,
+  probeAdapterSdk,
+} from './adapter-sdk.js';
 
 const here = dirname(fileURLToPath(import.meta.url));
 const templatePath = resolve(here, '..', 'playbook.config.template.yaml');
@@ -68,6 +74,16 @@ export async function runPlaybookCli(options = {}) {
       ...(options.readStdin ? { readStdin: options.readStdin } : {}),
       ...(options.sessionsDir ? { sessionsDir: options.sessionsDir } : {}),
       ...(options.hostRoots ? { hostRoots: options.hostRoots } : {}),
+      // PBCLI-39: the run path gates on SDK availability too.
+      ...(options.probeAdapterSdk
+        ? { probeAdapterSdk: options.probeAdapterSdk }
+        : {}),
+      ...(options.classifyRuntime
+        ? { classifyRuntime: options.classifyRuntime }
+        : {}),
+      ...(options.ephemeralNpx !== undefined
+        ? { ephemeralNpx: options.ephemeralNpx }
+        : {}),
     });
   }
 
@@ -144,19 +160,37 @@ export async function runPlaybookCli(options = {}) {
   }
 
   // PBCLI-12: readiness reads the adapters of the composed config.
-  const readiness = checkReadiness(
-    adaptersFromComposedConfig(composed.config),
-    env,
-    home,
+  const declaredAdapters = adaptersFromComposedConfig(composed.config);
+  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
+  // only the first would send the user round the loop twice.
+  const { unusableAdapters } = await checkAdapterSdks(
+    declaredAdapters,
+    options.probeAdapterSdk ?? probeAdapterSdk,
+    ...(options.classifyRuntime ? [options.classifyRuntime] : []),
   );
   for (const adapter of readiness.unknownAdapters) {
     stderr.write(
       `playbook: warning: no readiness check for adapter "${adapter}"\n`,
     );
   }
-  if (readiness.failingAdapters.length > 0) {
+  if (readiness.failingAdapters.length > 0 || unusableAdapters.length > 0) {
     stderr.write(
-      helpText({ userConfigPath, failingAdapters: readiness.failingAdapters }),
+      helpText({
+        userConfigPath,
+        failingAdapters: readiness.failingAdapters,
+        // PBCLI-40: the ephemeral re-run must carry the lineup's full mapped
+        // SDK set and the user's own arguments, so it completes in one hop
+        // and is executable exactly as printed.
+        sdkFailureLines: adapterSdkFailureLines(unusableAdapters, {
+          requiredSdks: mappedSdksFor(declaredAdapters),
+          invocation: argv,
+          ...(options.ephemeralNpx !== undefined
+            ? { ephemeralNpx: options.ephemeralNpx }
+            : {}),
+        }),
+      }),
     );
     return { code: READINESS_FAILURE_EXIT_CODE };
   }
@@ -678,12 +712,19 @@ function hasExplicitConfig(argv) {
   return argv.some((arg) => arg === '--config' || arg.startsWith('--config='));
 }
 
-function helpText({ userConfigPath, failingAdapters = [] }) {
+function helpText({
+  userConfigPath,
+  failingAdapters = [],
+  sdkFailureLines = [],
+}) {
   const failures =
     failingAdapters.length > 0
       ? [`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 [--list] [--with <path>]... [--config <path>] [tmux-play options]',
@@ -699,8 +740,12 @@ function helpText({ userConfigPath, failingAdapters = [] }) {
     '  default config file is never modified.',
     '',
     'Adapter setup:',
-    '  claude: run Claude Code once or set ANTHROPIC_API_KEY.',
-    '  codex: run Codex CLI once or set OPENAI_API_KEY.',
+    '  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 each agent inline: the top-level captain and every',

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

@@ -29,6 +29,12 @@ import {
 } from '@sublang/cligent';
 import { parse as parseYaml } from 'yaml';
 import { hiddenControlEnvelope } from '../../../../src/xstate-runtime.js';
+import {
+  adapterSdkFailureLines,
+  checkAdapterSdks,
+  mappedSdksFor,
+  probeAdapterSdk,
+} from './adapter-sdk.js';
 import { provisionEngine } from './provision.js';
 
 // PBCLI-19: adapter shorthands the run host can construct.
@@ -77,6 +83,15 @@ export async function runPlaybookRun(options = {}) {
     readStdin,
     sessionsDir,
     userConfigPath,
+    // PBCLI-39: the adapter SDK probe and the runtime classifier, injectable
+    // like createAgent so tests can drive an unavailable or below-floor
+    // runtime without uninstalling or downgrading one.
+    probeAdapterSdk: options.probeAdapterSdk ?? probeAdapterSdk,
+    classifyRuntime: options.classifyRuntime,
+    // PBCLI-40: the original invocation, preserved on the ephemeral re-run;
+    // this module receives argv with the leading `run` already consumed.
+    rawArgv: ['run', ...argv],
+    ephemeralNpx: options.ephemeralNpx,
     // PBCLI-37: injected host package roots let tests provision against
     // synthetic trees, like the injected session store.
     hostRoots: options.hostRoots,
@@ -159,6 +174,18 @@ async function runFirst(args, ctx) {
     return { code: EXIT.arg };
   }
 
+  // PBCLI-39/40: an optional-peer SDK that is not installed fails here,
+  // before the runtime exists and before any agent call — never mid-turn.
+  const sdkError = await adapterSdksDiagnostic(
+    [...roleSpecs.values(), captainSpec],
+    ctx,
+    stdinReplayArgs(args, task),
+  );
+  if (sdkError !== undefined) {
+    stderr.write(sdkError);
+    return { code: EXIT.arg };
+  }
+
   let runtime;
   try {
     runtime = entry.createRuntime({
@@ -290,6 +317,18 @@ async function runResume(args, ctx) {
     return { code: EXIT.arg };
   }
 
+  // PBCLI-39: a resume rebuilds the stored lineup, so it needs the same
+  // SDKs — an install that lost one must not resume into a mid-turn error.
+  const sdkError = await adapterSdksDiagnostic(
+    [...roleSpecs.values(), record.captain],
+    ctx,
+    stdinReplayArgs(args, reply),
+  );
+  if (sdkError !== undefined) {
+    stderr.write(sdkError);
+    return { code: EXIT.arg };
+  }
+
   let runtime;
   try {
     runtime = entry.createRuntime({
@@ -639,6 +678,50 @@ function specsDiagnostic(specs) {
   return undefined;
 }
 
+// PBCLI-40: the replay tail for input the command consumed from stdin —
+// the pipe that carried it will not exist when the printed command runs.
+// The value rides behind a `--` end-of-options terminator, because quoting
+// alone cannot keep a flag-shaped value (`--json`, `--last`, a `-`-leading
+// bullet) from being read as an option; where the original invocation
+// already activated a terminator of its own, that one is reused — a second
+// `--` after the first would itself be positional data on the replay,
+// turning a `--json` task into `-- --json`.
+function stdinReplayArgs(args, resolved) {
+  if (args.task !== undefined) return [];
+  return args.terminated ? [resolved] : ['--', resolved];
+}
+
+// PBCLI-39/40: returns the ready-to-write stderr block naming every bound
+// adapter whose optional-peer SDK is not installed, or undefined when every
+// one of them loads. Runs only after specsDiagnostic has accepted the
+// adapter names, so every spec here carries a known adapter.
+async function adapterSdksDiagnostic(specs, ctx, stdinArgs = []) {
+  const adapters = specs.map((spec) => spec.adapter);
+  const { unusableAdapters } = await checkAdapterSdks(
+    adapters,
+    ctx.probeAdapterSdk,
+    ...(ctx.classifyRuntime ? [ctx.classifyRuntime] : []),
+  );
+  if (unusableAdapters.length === 0) return undefined;
+  const [header, ...commands] = adapterSdkFailureLines(unusableAdapters, {
+    // PBCLI-40: the ephemeral re-run carries the lineup's full mapped SDK
+    // set and the original arguments, so it completes in one hop and runs
+    // exactly as printed. stdinArgs arrive terminator-ready from
+    // stdinReplayArgs — appended verbatim here, because whether a `--` is
+    // needed depends on the original invocation's own parse state.
+    requiredSdks: mappedSdksFor(adapters),
+    invocation: [...ctx.rawArgv, ...stdinArgs],
+    ...(ctx.ephemeralNpx !== undefined
+      ? { ephemeralNpx: ctx.ephemeralNpx }
+      : {}),
+  }).filter((line) => line !== '');
+  // Only the header takes the command prefix; the install lines stay
+  // copy-pasteable.
+  return [`playbook run: ${header}`, ...commands]
+    .map((line) => `${line}\n`)
+    .join('');
+}
+
 function isAgentSpec(spec) {
   return (
     typeof spec === 'object' &&
@@ -892,10 +975,23 @@ export function parseRunArgs(argv) {
     verbose: false,
     noProvision: false,
     help: false,
+    terminated: false,
   };
   const positionals = [];
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
+    // PBCLI-40: end-of-options — everything after `--` is positional, so a
+    // flag-shaped task or reply (a stdin-derived `--json`, a `- bullet`
+    // line) survives the ephemeral re-run round trip instead of being
+    // reinterpreted as an option. `terminated` records that this branch
+    // fired — only a `--` the walk itself treats as the terminator counts,
+    // never one consumed as an option's value (`--cwd --`) — so the re-run
+    // builder can reuse an active terminator instead of doubling it.
+    if (arg === '--') {
+      args.terminated = true;
+      positionals.push(...argv.slice(i + 1));
+      break;
+    }
     if (arg === '--help' || arg === '-h') args.help = true;
     else if (arg === '--json') args.json = true;
     else if (arg === '--verbose') args.verbose = true;
@@ -1036,6 +1132,7 @@ function runHelpText() {
     '  <from>   registry module specifier (package subpath, path, or file: URL)',
     '  [task]   Boss intent; read from stdin when omitted',
     '  [reply]  Boss reply to a parked session; read from stdin when omitted',
+    '  --       end of options; use before a task or reply that starts with -',
     '',
     'Options:',
     '  --player <role>=<agent>   bind a required role (repeatable)',

package/reference/sdlc/code.playbook/playbook-captain.js

@@ -919,9 +919,30 @@ export function createPlaybookCaptainShell(options, deps = {}) {
         if (visibilityControlError !== undefined)
             throw visibilityControlError;
     }
+    // CAPTAIN-34/35: a parentless internal Captain frame holds no recoverable
+    // work, so any rejected boundary call disposes the stack instead of
+    // stranding a frame that would refuse every later registered command. A
+    // parentless external root keeps its frame for Boss recovery.
+    async function failParentlessBoundary(frame, error) {
+        if (!frame.internal || !frames.includes(frame))
+            throw error;
+        if (!disposing) {
+            try {
+                await disposeStack('failure');
+            }
+            catch {
+                // The boundary failure wins; disposal detail stays on telemetry.
+            }
+        }
+        const commands = [...enablementById.values()]
+            .map((enablement) => `/${enablement.command} <task>`)
+            .join(' or ');
+        throw new Error('Captain could not finish that turn and the engagement was reset. ' +
+            `Send the request again${commands ? `, or start a playbook directly with ${commands}` : ''}.`, { cause: error });
+    }
     async function returnBoundaryFailure(frame, error, context) {
         if (!frame.parent)
-            throw error;
+            await failParentlessBoundary(frame, error);
         await resumeParent(frame, {
             status: context.signal.aborted ? 'aborted' : 'error',
             playbookId: frame.entry.id,
@@ -1126,7 +1147,7 @@ export function createPlaybookCaptainShell(options, deps = {}) {
                 completed = true;
             }
             else {
-                throw error;
+                await failParentlessBoundary(frame, error);
             }
         }
         finally {

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

@@ -103,7 +103,7 @@ class VisibilityControlError extends Error {
   }
 }
 
-type DisposalReason = 'dismiss' | 'final' | 'dispose';
+type DisposalReason = 'dismiss' | 'final' | 'dispose' | 'failure';
 
 interface ControlLedger {
   activePlaybookId?: string;
@@ -1275,12 +1275,38 @@ export function createPlaybookCaptainShell(
     if (visibilityControlError !== undefined) throw visibilityControlError;
   }
 
+  // CAPTAIN-34/35: a parentless internal Captain frame holds no recoverable
+  // work, so any rejected boundary call disposes the stack instead of
+  // stranding a frame that would refuse every later registered command. A
+  // parentless external root keeps its frame for Boss recovery.
+  async function failParentlessBoundary(
+    frame: EngagementFrame,
+    error: unknown,
+  ): Promise<never> {
+    if (!frame.internal || !frames.includes(frame)) throw error;
+    if (!disposing) {
+      try {
+        await disposeStack('failure');
+      } catch {
+        // The boundary failure wins; disposal detail stays on telemetry.
+      }
+    }
+    const commands = [...enablementById.values()]
+      .map((enablement) => `/${enablement.command} <task>`)
+      .join(' or ');
+    throw new Error(
+      'Captain could not finish that turn and the engagement was reset. ' +
+        `Send the request again${commands ? `, or start a playbook directly with ${commands}` : ''}.`,
+      { cause: error },
+    );
+  }
+
   async function returnBoundaryFailure(
     frame: EngagementFrame,
     error: unknown,
     context: CaptainContext,
   ): Promise<void> {
-    if (!frame.parent) throw error;
+    if (!frame.parent) await failParentlessBoundary(frame, error);
     await resumeParent(
       frame,
       {
@@ -1524,7 +1550,7 @@ export function createPlaybookCaptainShell(
         await returnBoundaryFailure(frame, error, context);
         completed = true;
       } else {
-        throw error;
+        await failParentlessBoundary(frame, error);
       }
     } finally {
       activeTurnSummary = undefined;

package/reference/sdlc/code.playbook/playbook.config.template.yaml

@@ -10,6 +10,13 @@
 # settings inline: an adapter shorthand (claude, codex) or a block with
 # adapter/model/effort/permissions. Retuning one agent never changes
 # another.
+
+# Each adapter needs its vendor SDK installed as its own top-level
+# install root — they are optional peer dependencies, so you pay only
+# for the vendors named below:
+#   claude -> npm install -g @anthropic-ai/claude-agent-sdk
+#   codex  -> npm install -g @openai/codex-sdk
+# Drop an adapter from this file and you can skip its SDK entirely.
 # Every seeded agent runs in cligent's protected auto mode
 # (permissions.mode: auto): claude maps it to permissionMode auto, codex to
 # on-request + auto_review. Codex roles also grant writablePaths: ['.git']

package/src/xstate-playbook-runtime.d.ts

@@ -203,6 +203,16 @@ export interface PlayerBridgeSpec {
     resumableStateIds: ReadonlySet<string>;
 }
 export declare function createPlayerBridge(spec: PlayerBridgeSpec, ports: PlaybookPorts, getActiveSignal?: () => AbortSignal | undefined, boundary?: RuntimeBoundaryCalls, onControlPlaneError?: (error: unknown) => void): PromiseActorLogic<PlaybookActorOutput, PlaybookPlayerInput>;
+/**
+ * Default direct-Captain adjudicator prompt (DR-025). The single statement of
+ * the `{ guard, …structuralPayloadFields }` reply contract, shared with the
+ * compiled default Captain artifact so the wording cannot drift.
+ */
+export declare function defaultBuildCaptainJudgePrompt(input: {
+    readonly stateId: string;
+    readonly sourceItem: string;
+    readonly result: Readonly<Record<string, string>>;
+}, finalText: string): string;
 /** Targets of the FSM's `awaitBossReply` BOSS_REPLY transitions. */
 export declare function resumableStateIdsFromMachine(machine: AnyStateMachine): ReadonlySet<string>;
 /**

package/src/xstate-playbook-runtime.js

@@ -454,7 +454,12 @@ export function createPlayerBridge(spec, ports, getActiveSignal, boundary, onCon
 // `response` and rejects a judge reply that supplies either presentation
 // field as an undeclared extra key.
 // ---------------------------------------------------------------------------
-function buildCaptainJudgePrompt(input, finalText) {
+/**
+ * Default direct-Captain adjudicator prompt (DR-025). The single statement of
+ * the `{ guard, …structuralPayloadFields }` reply contract, shared with the
+ * compiled default Captain artifact so the wording cannot drift.
+ */
+export function defaultBuildCaptainJudgePrompt(input, finalText) {
     const lines = [];
     lines.push('Adjudicate the direct Captain output for this FSM state.');
     lines.push(`State id: ${input.stateId}`);
@@ -1382,7 +1387,7 @@ export function createXStatePlaybookRuntime(machine, spec) {
                     if (result.status !== 'ok' || !result.finalText) {
                         throw new Error('captainActor: boundary returned an unvalidated Captain result');
                     }
-                    const judgePrompt = buildCaptainJudgePrompt(input, result.finalText);
+                    const judgePrompt = defaultBuildCaptainJudgePrompt(input, result.finalText);
                     const raw = await boundary.callJudge('captain-output-adjudication', input.stateId, judgePrompt, active);
                     const output = adjudicateCaptainOutput(extractFields, input, result.finalText, raw);
                     validateBossReplyOutput(input, output, resumableStateIds);

package/src/xstate-playbook-runtime.ts

@@ -799,8 +799,17 @@ export function createPlayerBridge(
 // field as an undeclared extra key.
 // ---------------------------------------------------------------------------
 
-function buildCaptainJudgePrompt(
-  input: PlaybookCaptainInput,
+/**
+ * Default direct-Captain adjudicator prompt (DR-025). The single statement of
+ * the `{ guard, …structuralPayloadFields }` reply contract, shared with the
+ * compiled default Captain artifact so the wording cannot drift.
+ */
+export function defaultBuildCaptainJudgePrompt(
+  input: {
+    readonly stateId: string;
+    readonly sourceItem: string;
+    readonly result: Readonly<Record<string, string>>;
+  },
   finalText: string,
 ): string {
   const lines: string[] = [];
@@ -2042,7 +2051,7 @@ export function createXStatePlaybookRuntime<TOptions>(
                 'captainActor: boundary returned an unvalidated Captain result',
               );
             }
-            const judgePrompt = buildCaptainJudgePrompt(
+            const judgePrompt = defaultBuildCaptainJudgePrompt(
               input,
               result.finalText,
             );