@sublang/playbook 7.0.0 → 9.0.0

package/docs/configuration.md

@@ -3,7 +3,7 @@
 
 # Configuring agents
 
-`playbook` and every fresh `playbook run` read one config at
+Fresh launches and ordinary reopens read one config at
 `${XDG_CONFIG_HOME:-$HOME/.config}/playbook/playbook.config.yaml`. The
 first launch seeds it from the bundled starter and prints the path;
 later launches reuse it untouched.
@@ -14,28 +14,35 @@ $EDITOR "${XDG_CONFIG_HOME:-$HOME/.config}/playbook/playbook.config.yaml"
 
 ## Anatomy
 
-The config is top-level (no `config:` wrapper): a `captain` agent (it
-runs the session Captain's hidden control calls, the hidden judge calls,
-and the replies you see in the Captain pane or on headless stdout), optional
-`layout` / `notifications` / `theme`, and a `playbooks` map of enabled
-playbooks. Those three presentation fields apply only to interactive tmux;
-headless runs ignore them.
-
-Each `captain` or `players.<role>` value is either an adapter shorthand
-(`claude`, `codex`) or a block carrying that agent's own `adapter`,
-`model`, `effort`, and `permissions`. Settings are inline per agent, so
-tuning one player never changes another
-([DR-021](../specs/decisions/021-inline-agent-settings.md)). Other
-adapter ids pass through to `tmux-play` with a warning, because
-`playbook` cannot preflight their auth.
-
-Within a `playbooks.<id>` block, `from` (the registry module), `command`
-(an optional slash-command override), and `players` are launcher-owned;
-every other key is that playbook's option slice. The launcher injects
-the rest — you do not write host wiring by hand.
-
-The seeded config runs each Coder on Claude Opus 4.8 1m and each
-Reviewer on GPT-5.5:
+The config is top-level (no `config:` wrapper): a `captain` agent, one flat
+`players` map of stable Captain-session agents, a `playbooks` map of enabled
+workflows and their explicit role bindings, and optional `layout` /
+`notifications` / `theme`. The Captain runs hidden control and judge calls and
+writes the replies you see in the Captain pane or on headless stdout. The three
+presentation fields apply only to interactive tmux; headless runs ignore them.
+
+A **role** is local to a playbook artifact: CODE's `coder` and REVIEW's `coder`
+have the same semantic name but remain separate declarations. A **player** is
+a stable session-wide provider conversation with an exact ID such as
+`dev.coder`. A role uses only the player named by its binding; matching role
+names, nesting, and ancestry never infer a binding.
+
+Each `captain` or `players.<player-id>` value is either an adapter shorthand
+(`claude`, `codex`) or a block carrying that agent's own `adapter`, `model`,
+`effort`, `instruction`, and `permissions`. Settings are inline per stable
+agent ([DR-021](https://github.com/sublang-ai/playbook/blob/main/specs/decisions/021-inline-agent-settings.md)). Dots in a
+player ID are literal characters, not YAML hierarchy. Other adapter IDs pass
+through to `tmux-play` with a warning because `playbook` cannot preflight their
+auth.
+
+Within a `playbooks.<id>` block, `from` (the registry module), `command` (an
+optional slash-command override), and `roles` are launcher-owned; every other
+key is that playbook's option slice. Every manifest role must be present
+exactly once. The launcher injects the rest — you do not write host wiring by
+hand.
+
+The seeded config runs the stable Coder player on Claude Opus 4.8 1m and the
+stable Reviewer player on GPT-5.5:
 
 ```yaml
 captain:
@@ -45,86 +52,116 @@ captain:
   permissions:
     mode: auto # protected auto mode for the Claude Captain
 
+players:
+  dev.coder:
+    adapter: claude
+    model: claude-opus-4-8[1m]
+    effort: xhigh
+    permissions:
+      mode: auto # protected auto mode for the Claude Coder
+
+  dev.reviewer:
+    adapter: codex
+    model: gpt-5.5
+    effort: xhigh
+    permissions:
+      mode: auto
+      writablePaths:
+        - .git # allow git metadata writes under Codex auto mode
+
 playbooks:
   code:
     from: '@sublang/playbook/code/registry'
-    players:
-      coder:
-        adapter: claude
-        model: claude-opus-4-8[1m]
-        effort: xhigh
-        permissions:
-          mode: auto # protected auto mode for the Claude Coder
+    roles:
+      coder: dev.coder
 
   review:
     from: '@sublang/playbook/review/registry'
-    players:
-      coder:
-        adapter: claude
-        model: claude-opus-4-8[1m]
-        effort: xhigh
-        permissions:
-          mode: auto
-      reviewer:
-        adapter: codex
-        model: gpt-5.5
-        effort: xhigh
-        permissions:
-          mode: auto
-          writablePaths:
-            - .git # allow git metadata writes under Codex auto mode
+    roles:
+      coder: dev.coder
+      reviewer: dev.reviewer
 
   decide:
     from: '@sublang/playbook/decide/registry'
-    players:
-      coder:
-        adapter: claude
-        model: claude-opus-4-8[1m]
-        effort: xhigh
-        permissions:
-          mode: auto
-      reviewer:
-        adapter: codex
-        model: gpt-5.5
-        effort: xhigh
-        permissions:
-          mode: auto
-          writablePaths:
-            - .git
+    roles:
+      coder: dev.coder
+      reviewer: dev.reviewer
 ```
 
 The current bundled workflows accept no workflow-specific options.
-Each role's per-run prompt names its pinned `model`, else its `adapter`
-([[playbook-runtime-4](../specs/packages/playbook-runtime.md#playbook-runtime-4)]),
+Each role's per-call prompt names its current `model`, else its player's
+`adapter`
+([[playbook-runtime-4](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook-runtime.md#playbook-runtime-4)]),
 so commit trailers credit the concrete model rather than the adapter
 family.
 
-## Nested roles and sessions
+## Role binding forms
+
+The shortest binding is a scalar stable player ID:
+
+```yaml
+roles:
+  coder: dev.coder
+```
+
+Use a block to override only that role invocation's model or effort:
+
+```yaml
+roles:
+  coder:
+    player: dev.coder
+    model: claude-opus-4-8[1m]
+    effort: false # explicitly reset to this provider's default
+```
+
+Omitting `model` or `effort` inherits that player's top-level default. The
+boolean `false` is different: it selects the provider default explicitly, so a
+resumed conversation cannot accidentally retain an earlier selection. A role
+binding cannot override adapter, instruction, permissions, workspace, or tool
+posture; those define the stable player envelope.
 
-The launcher creates a namespaced fallback player for every configured
-playbook role, but a nested call maps an exact same-name role to the
-nearest ancestor's effective player and backend conversation. CODE's
-nested REVIEW therefore continues CODE's `coder` and uses REVIEW's
-configured `reviewer`; DECIDE's nested REVIEW continues both of
-DECIDE's roles. A standalone REVIEW starts with REVIEW's own configured
-players, and every new root engagement starts fresh
-([DR-030](../specs/decisions/030-shared-mapped-player-continuity.md)).
+## Sharing, isolation, and concurrency
 
-The separate fallback entries are still required because tmux creates
-its roster at launch time. The host changes which existing panes are
-visible as the active nested leaf changes; it does not create a new
-host player or backend agent session for a mapped role.
+Two bindings that name the same player ID deliberately share one sequential
+provider conversation throughout the logical Captain session — across nested
+calls, returns, and later root engagements. CODE's and REVIEW's `coder` roles
+therefore share `dev.coder` in the starter, and DECIDE and its nested REVIEW
+share both starter players. Disposal of one playbook frame does not clear that
+session ledger.
+
+Two distinct player IDs stay isolated even when their agent blocks are
+byte-for-byte equal. To give standalone REVIEW an independent Coder, define a
+second top-level player and change only its binding:
+
+```yaml
+players:
+  review.coder:
+    adapter: claude
+    model: claude-opus-4-8[1m]
+    effort: xhigh
+
+playbooks:
+  review:
+    from: '@sublang/playbook/review/registry'
+    roles:
+      coder: review.coder
+      reviewer: dev.reviewer
+```
+
+Roles a manifest may run concurrently must bind to distinct IDs. DECIDE's
+`coder` and `reviewer` are concurrent, so aliasing both to one player rejects
+before registry import, host creation, or agent work.
 
 ## Choosing the Captain agent
 
 Every session-Captain call and adjudication call is hidden and runs
 tool-free, which is what keeps the Captain deciding and reporting
-instead of doing the work itself. Claude enforces
-that at the provider level. The Codex adapter cannot — it rejects any
-tool list — so a `captain:` on `codex` falls back to a prompt-level
-restriction
-([DR-013](../specs/decisions/013-routing-only-captain-control.md) A1).
-Codex remains a good choice for *players*, where full tools are wanted.
+instead of doing the work itself. Claude and Gemini enforce that at the
+provider level. The Codex, Kimi, and OpenCode adapters cannot — they
+reject any tool list — so a `captain:` using one of them falls back to a
+prompt-level restriction
+([DR-013](https://github.com/sublang-ai/playbook/blob/main/specs/decisions/013-routing-only-captain-control.md) A1).
+Those adapters remain good choices for *players*, where full tools are wanted.
 
 Adapter readiness is intentionally light: `claude` is ready with local
 Claude Code auth or `ANTHROPIC_API_KEY`; `codex` with local Codex CLI
@@ -143,40 +180,52 @@ playbook run --with fast-lineup.yaml "/code implement the approved change"
 ```
 
 ```yaml
-# fast-lineup.yaml — swap the Coder for one run; nothing is written back.
+# fast-lineup.yaml — retune the shared Coder; nothing is written back.
+players:
+  dev.coder:
+    model: claude-opus-4-8
+    effort: medium
+```
+
+Fragments merge into the agent block rather than replacing it, so
+settings the base defines and the fragment omits — here the adapter,
+instruction, and permissions — survive. Retuning a top-level player affects
+every bound role that does not override that field. To retune only one role,
+overlay its binding instead:
+
+```yaml
 playbooks:
   code:
-    players:
+    roles:
       coder:
-        adapter: codex
-        model: gpt-5.5
-        effort: medium
-        permissions:
-          mode: auto
-          # CODE's Coder commits, so Codex needs the `.git` grant to write
-          # repository metadata.
-          writablePaths:
-            - .git
+        player: dev.coder
+        effort: low
 ```
 
-Fragments merge into the agent block rather than replacing it, so
-settings the base defines and the fragment omits — here `mode: auto` —
-survive. Anything the adapter itself requires must still be stated: a
-role switched to `codex` needs its own `writablePaths` grant, because
-the base Claude block had no reason to carry one.
-
 The global file is never modified, and `--with` is not forwarded to
-`tmux-play` ([[playbook-cli-25](../specs/packages/playbook-cli.md#playbook-cli-25)]).
-Overlays apply only when creating a fresh session. A continued headless
-session restores its frozen config and working directory and rejects `--with`.
-
-## Shared headless configuration
-
-Fresh interactive and headless sessions use the same top-level `captain`
-and `playbooks` blocks. A headless session retains the normalized lineup,
-catalog, options, and absolute working directory with every durable turn;
-continuation does not reread the current file. Presentation-only fields are
-inert headlessly.
+`tmux-play` ([[playbook-cli-25](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook-cli.md#playbook-cli-25)]).
+Overlays apply when creating a fresh session and as current-config input for a
+compatible ordinary reopen. A selected session keeps its stored catalog,
+player roster, role bindings, adapter, instruction, permissions, and working
+directory; only model and effort may change. The next call reapplies both
+complete selections. An uncertain retry accepts no tuning overlay and uses the
+exact attempted selections already stored with that turn.
+
+## Durable shared configuration
+
+Fresh interactive and headless sessions use the same top-level Captain,
+players, role bindings, and playbooks. Both persist the same logical-session
+record, shell snapshot, player ledger, normalized catalog, structural agent
+envelopes, last-applied tuning, and absolute working directory. A session
+created by either front end can reopen through either front end with the same
+public UUID. Presentation-only fields are inert headlessly.
+
+An ordinary reopen reads current config and opening overlays, but first
+projects them to the stored playbooks and referenced players. An unrelated new
+entry cannot enter or invalidate the session. Structural drift fails closed;
+compatible model or effort changes apply on the next provider call. Legacy
+record, shell, runtime-snapshot, and trace schemas are rejected rather than
+having role or player identity guessed.
 
 ## External playbooks
 
@@ -187,17 +236,25 @@ and `createRuntime`. Enable it under `playbooks`, bind every role listed in
 its `requiredRoleIds`, and invoke its effective slash command through Captain:
 
 ```yaml
+players:
+  my.worker: claude
+
 playbooks:
   my-workflow:
     from: /absolute/path/to/my-workflow.ts
-    players:
-      worker: claude
+    roles:
+      worker: my.worker
 ```
 
 ```sh
 playbook run "/my-workflow perform the task"
 ```
 
+Importing a `.ts` registry uses Node's native type stripping, available
+unflagged on Node 22.18+ and 23.6+; on the older Node versions this
+package supports (>= 20.6), compile the registry and point `from` at the
+emitted `.js` module instead.
+
 A relative path-shaped `from` is resolved relative to the primary config
 file, not the invocation directory; an absolute path is clearest for an SLC
 entry emitted in a project working tree.
@@ -205,15 +262,60 @@ Before either front end imports a filesystem registry, the shared launcher
 checks and, unless `--no-provision` is set, provisions its runtime engine
 links as described in [Using the CLI](cli.md#external-playbooks-and-engine-provisioning).
 
+## Migrating per-playbook players
+
+The former `playbooks.<id>.players` shape made agent configuration and local
+workflow roles the same thing. It is removed. For example, this legacy config
+gave CODE and REVIEW two separately configured `coder` entries:
+
+```yaml
+playbooks:
+  code:
+    from: '@sublang/playbook/code/registry'
+    players:
+      coder: { adapter: claude, model: claude-opus-4-8[1m] }
+  review:
+    from: '@sublang/playbook/review/registry'
+    players:
+      coder: { adapter: claude, model: claude-opus-4-8[1m] }
+      reviewer: { adapter: codex, model: gpt-5.5 }
+```
+
+Move each provider agent into the flat top-level map, choose stable IDs, and
+bind the local roles explicitly:
+
+```yaml
+players:
+  dev.coder: { adapter: claude, model: claude-opus-4-8[1m] }
+  dev.reviewer: { adapter: codex, model: gpt-5.5 }
+
+playbooks:
+  code:
+    from: '@sublang/playbook/code/registry'
+    roles: { coder: dev.coder }
+  review:
+    from: '@sublang/playbook/review/registry'
+    roles:
+      coder: dev.coder
+      reviewer: dev.reviewer
+```
+
+The launcher intentionally does **not** perform this migration for you. It
+cannot know whether the two old `coder` blocks were meant to share one
+conversation or remain isolated. Reusing `dev.coder` above chooses sharing;
+using `code.coder` and `review.coder` would choose isolation. A surviving
+per-playbook `players` block therefore rejects before profile migration,
+registry preparation, or agent work.
+
 ## Migrating direct runs from 6.x
 
 The top-level `run:` block is deliberately rejected rather than silently
 ignored or rewritten, because doing otherwise could change the agents after
 an upgrade. Re-express `run.captain`, `run.players`, and former `--player`
-bindings as the inline agent blocks above; the old `run.player` catch-all has
-no shared equivalent, so configure every required role explicitly at
-`playbooks.<id>.players.<role>`. Use a fresh `--with` fragment for temporary
-lineup changes. Move former `--option` values into their `playbooks.<id>`
+bindings as top-level stable player blocks and explicit role bindings above;
+the old `run.player` catch-all has no shared equivalent, so configure every
+required role at `playbooks.<id>.roles.<role>`. Use a `--with` fragment for
+temporary compatible tuning changes. Move former `--option` values into their `playbooks.<id>`
 block, run from the desired directory instead of passing `--cwd`, enable a
 former positional `<from>` as a configured registry, and quote or pipe one
 `/command task` Boss message. Replace `resume` and `--last` with `--continue`
@@ -221,9 +323,9 @@ or `--session`.
 
 The JSON response is now exactly `{ "sessionId": "…", "reply": "…" }`.
 Released direct-run session records are not complete Captain sessions and
-cannot be continued by the new host ([[playbook-cli-19](../specs/packages/playbook-cli.md#playbook-cli-19)],
-[[playbook-cli-22](../specs/packages/playbook-cli.md#playbook-cli-22)],
-[[playbook-cli-28](../specs/packages/playbook-cli.md#playbook-cli-28)]).
+cannot be continued by the new host ([[playbook-cli-19](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook-cli.md#playbook-cli-19)],
+[[playbook-cli-22](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook-cli.md#playbook-cli-22)],
+[[playbook-cli-28](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook-cli.md#playbook-cli-28)]).
 
 ## Migrating from `profiles`
 
@@ -237,7 +339,7 @@ do by hand.
 
 For a one-off, pass a raw `tmux-play` config explicitly. This bypasses
 the seed, composition, and readiness gate, forwarding arguments to
-`tmux-play` verbatim ([[playbook-cli-1](../specs/packages/playbook-cli.md#playbook-cli-1)]):
+`tmux-play` verbatim ([[playbook-cli-1](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook-cli.md#playbook-cli-1)]):
 
 ```sh
 playbook --config ./tmux-play.config.yaml

package/docs/embedding.md

@@ -9,15 +9,15 @@ app) is another. This guide shows how to wire a playbook runtime into
 your own host.
 
 > **Release note:** this guide targets the current semver-stable six-port
-> contract; see the [CHANGELOG](../CHANGELOG.md) for migration details.
+> contract; see the [CHANGELOG](https://github.com/sublang-ai/playbook/blob/main/CHANGELOG.md) for migration details.
 
 ## The runtime contract
 
 The port and runtime contracts live in the type-only module
 [`@sublang/playbook/runtime`](../src/runtime.ts) — a public,
 semver-stable surface (`PlayerResult`, `PlaybookPorts`,
-`PlaybookRuntime`, `PlaybookSession`, `PlayerCallOptions`,
-`PlayerSessionStore`, `CaptainCallOptions`, `CaptainResult`,
+`PlaybookRuntime`, `PlaybookSession`, `PlaybookRoleBinding`,
+`PlayerCallOptions`, `PlayerSessionStore`, `CaptainCallOptions`, `CaptainResult`,
 `PlaybookTraceEvent`, and `PlaybookRuntimeFactory`) that imports no CODE
 or FSM types, so a host satisfies it once and inherits every playbook.
 The generated CODE, REVIEW, and DECIDE modules re-export their shared
@@ -31,12 +31,20 @@ nested-playbook bridge.
 
 ## Constructing a runtime against your own ports
 
+`p-queue` is your host's own dependency here — declare it in your
+application's `dependencies` (the same library `@sublang/playbook` itself
+depends on) rather than relying on it resolving through the package's
+tree, which pnpm's strict linking will not allow.
+
 ```ts
 import createPlaybookRuntime from '@sublang/playbook/review/playbook';
 import type {
   CaptainCallOptions,
   CaptainResult,
   PlaybookPorts,
+  PlaybookRoleBinding,
+  PlayerResult,
+  PlayerSessionStore,
 } from '@sublang/playbook/runtime';
 import { randomUUID } from 'node:crypto';
 import PQueue from 'p-queue';
@@ -53,6 +61,33 @@ declare const captainAdapter: {
   ): Promise<CaptainResult>;
 };
 
+declare const playerAdapter: {
+  run(
+    playerId: string,
+    prompt: string,
+    options: { signal: AbortSignal; resume: string | false },
+  ): Promise<PlayerResult>;
+};
+
+// Roles are local workflow identities. Players are stable provider
+// conversations owned by the logical Captain session. `promptIdentity` is
+// the current model name, or the player's adapter when provider-default is
+// selected; rebuild it from current compatible tuning on restore.
+const roleBindings = {
+  coder: {
+    playerId: 'team.coder',
+    promptIdentity: 'claude-opus-4-8[1m]',
+  },
+  reviewer: {
+    playerId: 'team.reviewer',
+    promptIdentity: 'gpt-5.5',
+  },
+} satisfies Readonly<Record<string, PlaybookRoleBinding>>;
+
+// Supply a frame-local role view over your session-wide player ledger.
+// Equal player IDs must select/update the same token; distinct IDs must not.
+declare const playerSessions: PlayerSessionStore;
+
 // Construct one host-wide lane and reuse it for every runtime. Passing each
 // call's signal to both the lane and adapter cancels queued and active work.
 const captainLane = new PQueue({ concurrency: 1 });
@@ -69,10 +104,16 @@ async function runCaptain(
 }
 
 const ports: PlaybookPorts = {
-  callPlayer: async (playerId, prompt, signal, { resume }) => {
+  callPlayer: async (roleId, prompt, signal, { resume }) => {
+    const binding = roleBindings[roleId as keyof typeof roleBindings];
+    if (binding === undefined) throw new Error(`Unknown role: ${roleId}`);
     // `resume === false` starts fresh; a string selects that player's
-    // prior backend conversation. Return the adapter's next token.
-    return { status: 'ok', finalText: 'done', resumeToken: 'next-token' };
+    // prior backend conversation. Return the adapter's next token; the
+    // runtime updates `playerSessions` only after validating this result.
+    return await playerAdapter.run(binding.playerId, prompt, {
+      signal,
+      resume,
+    });
   },
   callCaptain: async (prompt, signal, options) => {
     // Forward every option exactly: omission preserves configured tools, while
@@ -103,10 +144,7 @@ const ports: PlaybookPorts = {
   },
 };
 
-const runtime = createPlaybookRuntime({
-  coderLlm: 'claude-opus-4-8[1m]',
-  reviewerLlm: 'gpt-5.5',
-});
+const runtime = createPlaybookRuntime({});
 
 const playbookSessionId = randomUUID();
 await runtime.init({
@@ -114,6 +152,8 @@ await runtime.init({
   playbookId: 'review',
   rootSessionId: playbookSessionId,
   depth: 0,
+  roleBindings,
+  playerSessions,
   ports,
 });
 await runtime.handleBossInput({
@@ -125,26 +165,37 @@ await runtime.dispose();
 
 ## Sessions and traces
 
-Every init-to-dispose lifecycle is one playbook session. Its
+Every init-to-dispose lifecycle is one playbook session. Schema-3
 `playbook.trace` telemetry carries that immutable ID plus a contiguous
-sequence across exact Boss input, judge/player calls, FSM transitions,
-visible Captain work, nested playbook calls, status, settlement, and
-disposal. Without `PlaybookSession.playerSessions`, a standalone runtime
-starts each player fresh and privately retains the latest opaque
-`resumeToken` its adapter returned.
-
-A composing host can instead supply a frame-local `PlayerSessionStore`
-view over one root-owned continuation map. The host maps each local role
-to its effective binding, so a nested exact same-name role selects and
-updates the ancestor conversation while an unmatched child role gets
-its own binding. Child return or disposal does not clear the root's
-token, and a new root engagement starts fresh. Trace data and tokens
-never enter Boss-visible status text. Because trace observers do receive
-opaque resume tokens, persisted traces should be protected as sensitive
-data.
+sequence across exact Boss input, judge/player calls, FSM transitions, visible
+Captain work, nested playbook calls, status, settlement, and disposal. A
+shell-hosted player boundary keeps both identities: `roleId` says which local
+workflow job made the call, while `playerId` says which stable session
+conversation owned it. A standalone runtime retains the role without
+inventing host player identity.
+
+Without `PlaybookSession.playerSessions`, a standalone runtime starts each
+local role fresh and privately retains the latest opaque `resumeToken` its
+adapter returned. A composing host instead supplies a frame-local
+`PlayerSessionStore` view over one Captain-session ledger and explicit
+`roleBindings`. The store's methods receive local role IDs; the view resolves
+them to the configured stable player IDs. Equal IDs share one token and
+sequential call lane across every frame that names them, while distinct IDs
+remain isolated. Child return, frame disposal, and a later root engagement do
+not clear the session ledger.
+
+Runtime snapshots are schema 3. Their `roleResumeTokens` projection remains
+role-local, while the composing shell's own schema-3 snapshot persists the
+stable player ledger and every frame's exact role bindings. Do not restore
+schema 1 or 2 by guessing identity. On a compatible restore, rebuild
+`promptIdentity` from the current model selection (or adapter for an explicit
+provider-default selection) so the next prompt and trace describe the current
+invocation rather than stale machine state. Trace data and tokens never enter
+Boss-visible status text. Because trace observers do receive opaque resume
+tokens, persisted traces should be protected as sensitive data.
 
 See
-[`code.playbook.test.ts`](../reference/sdlc/code.playbook/code.playbook.test.ts)
+[`code.playbook.test.ts`](https://github.com/sublang-ai/playbook/blob/main/reference/sdlc/code.playbook/code.playbook.test.ts)
 for the full range of port shapes (classifier, judge, abort, interrupt,
 status/telemetry) the runtime is contract-tested against.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sublang/playbook",
-  "version": "7.0.0",
+  "version": "9.0.0",
   "type": "module",
   "description": "Composable XState v5 playbook runtime with compiled Captain, CODE, REVIEW, and DECIDE workflows driven by GEARS specs.",
   "license": "Apache-2.0",
@@ -69,6 +69,7 @@
     "reference/sdlc/code.playbook/bin/playbook.js",
     "reference/sdlc/code.playbook/bin/launch-config.js",
     "reference/sdlc/code.playbook/bin/run.js",
+    "reference/sdlc/code.playbook/bin/interactive-session.js",
     "reference/sdlc/code.playbook/bin/session-store.js",
     "reference/sdlc/code.playbook/bin/provision.js",
     "reference/sdlc/code.playbook/bin/adapter-sdk.js",
@@ -142,7 +143,7 @@
   },
   "scripts": {
     "build": "tsc",
-    "test": "spex lint && vitest run",
+    "test": "spex lint && vitest run --exclude src/cligent-release-capabilities.test.ts && vitest run src/cligent-release-capabilities.test.ts",
     "test:acceptance": "vitest run --config vitest.acceptance.config.ts",
     "smoke:release": "node scripts/release-smoke.mjs",
     "check:links": "node scripts/check-links.mjs",
@@ -153,7 +154,7 @@
     "provenance": true
   },
   "dependencies": {
-    "@sublang/cligent": "^0.19.0",
+    "@sublang/cligent": "^0.22.0",
     "@sublang/spex": "^2.1.1",
     "p-queue": "^9.3.1",
     "xstate": "^5.19.4",