@sublang/playbook 3.0.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,17 @@ 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.0.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,
-> and 3.0.0 replaces the top-level `profiles` map with
-> inline agent settings (existing configs migrate themselves on the next
-> launch). See the [CHANGELOG](CHANGELOG.md).
+> 3.0.0 replaced the top-level `profiles` map with inline agent settings
+> (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
@@ -67,6 +127,7 @@ intents the same way you would to `claude -p` or `codex exec`.
 | `--option <key>=<value>` | a playbook option (CODE's `committer`) |
 | `--cwd <dir>` | the agents' working directory |
 | `--json` | one envelope: `outcome`, `sessionId`, output or questions |
+| `--no-provision` | never create engine links beside a filesystem `<from>` |
 
 `<agent>` is `<adapter>[:<model>][@<effort>]` — `codex:gpt-5.5@xhigh`,
 or `claude@high` for the default model at high reasoning effort. The
@@ -79,6 +140,26 @@ Exit codes: `0` terminal, `1` bad argument or module, `2` failure, `3`
 the playbook needs a Boss reply
 ([PBCLI-18](../specs/user/playbook-cli.md#pbcli-18)).
 
+### Engine provisioning
+
+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
+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
+line naming what it linked
+([PBCLI-36](../specs/user/playbook-cli.md#pbcli-36),
+[DR-024](../specs/decisions/024-runtime-engine-provisioning.md)).
+A directory where the imports already resolve is never touched — a
+project-local install always wins — and `--no-provision` disables the
+mechanism entirely.
+
+If the module's directory is a git repository, add `node_modules/` to
+its `.gitignore` so the provisioned links never land in commits made by
+player agents working there.
+
 ### Resuming a parked run
 
 When the playbook stops to ask something, the run is parked, not lost:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sublang/playbook",
-  "version": "3.0.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",
@@ -67,6 +67,8 @@
     "reference/sdlc/code.playbook/playbook.config.template.yaml",
     "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",
@@ -128,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');
@@ -67,6 +73,17 @@ export async function runPlaybookCli(options = {}) {
       ...(options.createAgent ? { createAgent: options.createAgent } : {}),
       ...(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 }
+        : {}),
     });
   }
 
@@ -143,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 };
   }
@@ -677,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]',
@@ -698,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',