@sublang/playbook 7.0.0 → 9.0.0

package/README.md

@@ -19,7 +19,11 @@ SubLang Playbook addresses both:
 
 ![Venn diagram: Skill is flexible, Workflow is deterministic, and Playbook sits in the intersection as both.](docs/assets/playbook-venn.svg)
 
-Vocabulary: the **Boss** is you; the **Captain** is the coordinating agent you talk to; **players** are the agents a playbook delegates work to.
+Vocabulary: the **Boss** is you; the **Captain** is the coordinating agent you
+talk to; a **role** is a playbook-local job such as `coder`; and a **player** is
+a stable Captain-session agent and provider conversation to which one or more
+roles bind. Roles describe the workflow, while player IDs decide which work
+shares conversation continuity.
 
 Run `playbook` for an interactive tmux UI powered by [cligent](https://github.com/sublang-ai/cligent), or `playbook run` for the same Captain session without tmux in scripts and CI.
 
@@ -28,7 +32,10 @@ Run `playbook` for an interactive tmux UI powered by [cligent](https://github.co
 Out of the box, Playbook includes **CODE** for implementation, **REVIEW** for commit-based review and fixes, and **DECIDE** for independently proposed and reviewed specification decisions.
 CODE and DECIDE call REVIEW as a nested playbook.
 
-The shared starter config uses Claude as both Captain and Coder, and Codex as Reviewer.
+The shared starter config uses Claude as both Captain and the `dev.coder`
+player, and Codex as `dev.reviewer`. CODE, REVIEW, and DECIDE bind their local
+roles explicitly to those two stable players, so nested and later engagements
+share a conversation only where their bindings name the same player ID.
 
 ```sh
 npm install -g @sublang/playbook
@@ -44,7 +51,7 @@ Prerequisites:
 - Authenticated [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) or `ANTHROPIC_API_KEY`
 - Authenticated [Codex CLI](https://github.com/openai/codex) or `OPENAI_API_KEY`
 
-Interactive `playbook` additionally needs `tmux` and [`glow`](https://github.com/charmbracelet/glow#installation) on `PATH`; headless `playbook run` does not.
+Interactive `playbook` additionally needs tmux 3.3 or newer and [`glow`](https://github.com/charmbracelet/glow#installation) on `PATH`; headless `playbook run` does not.
 
 CODE works in the current directory and can edit and commit autonomously, so use a clean branch or worktree.
 
@@ -58,17 +65,23 @@ Type a task, enter `/code <task>` for implementation, or enter
 
 On first launch, Playbook writes its config to `${XDG_CONFIG_HOME:-$HOME/.config}/playbook/playbook.config.yaml`.
 
-The same config, compiled Captain, enabled playbooks, players, and nested calls power headless turns.
+The same config, compiled Captain, enabled playbooks, stable players, and
+nested calls power headless turns. Both front ends create the same durable
+logical session: copy the reported session ID to reopen an interactive session
+headlessly or a headless session interactively.
 Run REVIEW explicitly, or pipe a longer request to Captain:
 
 ```sh
 playbook run "/review review the latest commit"
 printf '%s\n' 'Implement the approved specification, then review it.' | playbook run
+# Later, either presentation can reopen the returned/reported session id:
+playbook --session 4f2c0000-0000-4000-8000-000000009ab1
+playbook run --session 4f2c0000-0000-4000-8000-000000009ab1 "continue"
 ```
 
 `playbook run` prints the one Boss-visible Captain reply to stdout and operational status to stderr; CODE and DECIDE can complete their nested REVIEW calls there too.
 
-See [Using the CLI](docs/cli.md) for flags and durable continuation, [Configuring agents](docs/configuration.md) for the shared lineup, [Embedding](docs/embedding.md) for custom hosts, and the [changelog](CHANGELOG.md) for releases.
+See [Using the CLI](docs/cli.md) for flags and durable continuation, [Configuring agents](docs/configuration.md) for the shared lineup, [Embedding](docs/embedding.md) for custom hosts, and the [changelog](https://github.com/sublang-ai/playbook/blob/main/CHANGELOG.md) for releases.
 
 ## Create your own playbook
 
@@ -116,8 +129,8 @@ pnpm playbook   # drive a Boss turn against the source tree
 ```
 
 Playbook is itself spec-driven: the compiler phases are specs in [`slc/`](slc), and the reference playbooks are regenerated from their prose sources.
-Edit a source, regenerate its GEARS, FSM, and runtime artifacts, sync the tests and downstream specs until `pnpm test` passes, and commit with co-author trailers per [`specs/packages/git.md`](specs/packages/git.md).
-The gears↔FSM contract ([the playbook package](specs/packages/playbook.md)) and runtime contract ([the playbook-runtime package](specs/packages/playbook-runtime.md)) are pinned in [`specs/packages/`](specs/packages) and verified by the test suite.
+Edit a source, regenerate its GEARS, FSM, and runtime artifacts, sync the tests and downstream specs until `pnpm test` passes, and commit with co-author trailers per [`specs/packages/git.md`](https://github.com/sublang-ai/playbook/blob/main/specs/packages/git.md).
+The gears↔FSM contract ([the playbook package](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook.md)) and runtime contract ([the playbook-runtime package](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook-runtime.md)) are pinned in [`specs/packages/`](https://github.com/sublang-ai/playbook/tree/main/specs/packages) and verified by the test suite.
 
 ## License
 

package/docs/cli.md

@@ -8,6 +8,9 @@ interactive tmux-play UI and a headless `playbook run` turn for scripts and
 CI. Both use the same compiled Captain, enabled catalog, players, nested
 stack, and [config](configuration.md); only presentation differs.
 
+The interactive form requires tmux 3.3 or newer and `glow` on `PATH`;
+the headless form requires neither presentation tool.
+
 ## Installing agent SDKs
 
 Each adapter is backed by a vendor runtime that installing
@@ -15,7 +18,7 @@ Each adapter is backed by a vendor runtime that installing
 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));
+([DR-027](https://github.com/sublang-ai/playbook/blob/main/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:
@@ -42,7 +45,7 @@ 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)).
+([DR-026](https://github.com/sublang-ai/playbook/blob/main/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
@@ -51,14 +54,16 @@ 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
-([[playbook-cli-40](../specs/packages/playbook-cli.md#playbook-cli-40)]).
+([[playbook-cli-40](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook-cli.md#playbook-cli-40)]).
 
 ## Interactive
 
 ```sh
-playbook            # launch the configured playbooks in tmux-play
-playbook --list     # ids, slash commands, and intents; no launch
-playbook --help     # config path, auth pointers, agent-swap recipe
+playbook                         # fresh durable session in this directory
+playbook --cwd /path/to/repo     # fresh session in an explicit directory
+playbook --session <id>          # reopen either front end's settled session
+playbook --list                  # ids, slash commands, and intents; no launch
+playbook --help                  # config path, auth pointers, binding recipe
 ```
 
 Without a global install, `npx` runs the same bin — but name each
@@ -78,12 +83,23 @@ 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
-with tmux-play's status, re-raises a terminating signal on itself, and
-exits `127` when it cannot launch at all
-([[playbook-cli-1](../specs/packages/playbook-cli.md#playbook-cli-1)],
-[[playbook-cli-2](../specs/packages/playbook-cli.md#playbook-cli-2)]).
+For a managed launch, the outer command resolves current config (seeding it on
+first use), prepares the complete stored catalog and presenter, waits for the
+pane child to acquire the session lease and publish its settled turn-zero
+record, prints the verified session ID, and then attaches. A normal outer
+detach exits `0`; the pane child keeps owning the durable session and accepting
+turns until it shuts down. Preparation, attachment, or required cleanup
+failure prints its diagnostics and exits nonzero.
+
+Before native-client hand-off, SIGHUP, SIGINT, or SIGTERM aborts activation,
+joins the child, retires the lease, and only then re-raises the signal. At the
+synchronous native-client hand-off, ownership transfers before tmux starts, so
+later signals use native client detach or termination semantics and do not
+retire the pane child's session. Only `--config` and composed
+`--theme-diagnostics` use the stock subprocess boundary: those forms mirror
+its exit status or signal and exit `127` when it cannot be spawned
+([[playbook-cli-1](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook-cli.md#playbook-cli-1)],
+[[playbook-cli-2](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook-cli.md#playbook-cli-2)]).
 
 ### Running a Boss turn
 
@@ -102,27 +118,29 @@ currently offers. It never does the specialized work itself, and a
 conversational turn — including a progress or status question — leaves
 the engagement, its parked state, and any pending player question
 untouched
-([[playbook-captain-1](../specs/packages/playbook-captain.md#playbook-captain-1)],
-[[playbook-captain-2](../specs/packages/playbook-captain.md#playbook-captain-2)]).
+([[playbook-captain-1](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook-captain.md#playbook-captain-1)],
+[[playbook-captain-2](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook-captain.md#playbook-captain-2)]).
 
 The current CODE, REVIEW, and DECIDE workflows take their deterministic
-initial event from the selecting Boss turn. CODE and DECIDE then call
-REVIEW as a nested playbook: an exact same-name child role continues the
-ancestor's player pane and backend conversation, while any additional
-role uses REVIEW's configured fallback. When a player surfaces a
+initial event from the selecting Boss turn. CODE and DECIDE then call REVIEW
+as a nested playbook. Local role names do not imply continuity: each frame
+uses the exact stable player IDs configured under its `roles` map. Equal IDs
+share one pane and provider conversation across nested and later root
+engagements; distinct IDs remain isolated even when their agent settings are
+identical. When a player surfaces a
 clarifying question the FSM parks, the pane shows the question, and a
 judge classifies your next turn as its reply or a fresh directive that
 abandons it
-([[playbook-runtime-2](../specs/packages/playbook-runtime.md#playbook-runtime-2)]).
+([[playbook-runtime-2](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook-runtime.md#playbook-runtime-2)]).
 
 The Captain pane shows start/stop/finished status with `◇` lines and
 streams progress with captain-speech classification and questions
-([[playbook-runtime-3](../specs/packages/playbook-runtime.md#playbook-runtime-3)]), while player
+([[playbook-runtime-3](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook-runtime.md#playbook-runtime-3)]), while player
 prompts ride their own panes. A turn that actually did something ends
 with one Captain reply summarizing what changed, composed only from that
 turn's reported outcome; a turn that changed nothing ends with an
 ordinary reply and no saved-counts line
-([[playbook-captain-19](../specs/packages/playbook-captain.md#playbook-captain-19)]).
+([[playbook-captain-19](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook-captain.md#playbook-captain-19)]).
 
 ## Headless
 
@@ -147,7 +165,7 @@ stderr, and `--verbose` adds only telemetry topic names to stderr.
 
 | Flag | Meaning |
 | --- | --- |
-| `--with <path>` | overlay the shared config for a new session; repeatable |
+| `--with <path>` | overlay current config for a fresh session or compatible ordinary reopen; repeatable |
 | `--no-provision` | do not create missing engine links for configured filesystem registries |
 | `--json` | print exactly one `sessionId` / `reply` object |
 | `--verbose` | add Captain telemetry topic names to stderr |
@@ -164,13 +182,18 @@ Captain reply. Argument, config, catalog, readiness, or pre-turn setup errors
 exit `1`; a started-turn, persistence, lease-release, or presentation failure
 exits `2` with stdout empty. SIGINT, SIGTERM, and SIGHUP preserve the
 uncertain boundary, withhold stdout, and are re-raised after lease retirement
-([[playbook-cli-18](../specs/packages/playbook-cli.md#playbook-cli-18)]).
+([[playbook-cli-18](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook-cli.md#playbook-cli-18)]).
 
 The former positional `<from>`, `resume`, `--player`, `--captain`,
 `--option`, `--cwd`, `--last`, run-only `--config`, and top-level `run:`
-config are removed. Enable a registry under `playbooks`, tune its inline
-agents and options there or in a fresh `--with` overlay, invoke its effective
-`/command`, and run from the working directory you want agents to use.
+config are removed from `playbook run`. Enable a registry under `playbooks`,
+declare provider agents once under top-level `players`, bind every local role
+under `playbooks.<id>.roles`, tune compatible model and effort in a `--with`
+overlay, invoke the effective `/command`, and run from the working directory
+you want agents to use. Legacy `playbooks.<id>.players` blocks are rejected and
+are not auto-migrated because choosing equal or distinct new player IDs chooses
+conversation sharing or isolation; see [Migrating per-playbook
+players](configuration.md#migrating-per-playbook-players).
 
 ### Piping a Spex update prompt
 
@@ -198,8 +221,8 @@ the primary config file. Before either front end imports a configured
 filesystem registry, the shared launcher checks whether that module can
 resolve `xstate` and `@sublang/playbook/xstate-runtime`. When needed, it
 creates engine symlinks beside the module and prints one provisioning line
-([[playbook-cli-36](../specs/packages/playbook-cli.md#playbook-cli-36)],
-[DR-024](../specs/decisions/024-runtime-engine-provisioning.md)).
+([[playbook-cli-36](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook-cli.md#playbook-cli-36)],
+[DR-024](https://github.com/sublang-ai/playbook/blob/main/specs/decisions/024-runtime-engine-provisioning.md)).
 
 A directory where both imports already resolve is untouched, and
 `--no-provision` disables new links for either fresh front end. If the
@@ -208,23 +231,38 @@ module's directory is a git repository, add `node_modules/` to its
 
 ### Continuing a Captain session
 
-Every successfully presented headless turn is stored under
-`${XDG_STATE_HOME:-$HOME/.local/state}/playbook/sessions/` before stdout.
-Continue the newest logical session, or select the id returned by `--json`:
+Interactive and headless commands write the same logical-session records under
+`${XDG_STATE_HOME:-$HOME/.local/state}/playbook/sessions/`. A fresh interactive
+child persists turn zero before printing `playbook: session <id>` and opening
+Boss input; a fresh headless turn returns the same kind of ID in `--json`.
+After the current writer exits or explicitly hands off, either presentation
+can reopen either origin:
 
 ```sh
+# Reopen the latest settled session headlessly:
 playbook run --continue "keep the scope small; skip the docs"
+
+# Reopen one exact session in either presentation:
+playbook --session 4f2c0000-0000-4000-8000-000000009ab1
 playbook run --session 4f2c0000-0000-4000-8000-000000009ab1
 ```
 
-A missing reply is read verbatim from stdin. Continuation restores the exact
+A missing headless reply is read verbatim from stdin. Reopening restores the
 compiled Captain conversation, engagement stack, nested child boundary,
-mapped-player conversations, normalized execution config, and absolute
-working directory. It does not reread current config, does not repeat a
-settled or pending child start, and rejects `--with` because an existing
-session's lineup is frozen
-([[playbook-cli-22](../specs/packages/playbook-cli.md#playbook-cli-22)],
-[DR-031](../specs/decisions/031-shared-captain-session-front-ends.md)).
+stable-player ledger, and absolute working directory without replaying a
+settled or pending child start. One exclusive writer owns the session, so a
+detached interactive pane child remains the owner until it shuts down; a
+competing front end fails closed instead of forking the history.
+
+An ordinary reopen reads current config and any opening `--with` fragments,
+projects them to the stored catalog and player roster, and requires the stored
+role bindings plus every structural setting to remain exact. Compatible
+current `model` and `effort` selections apply to the next call, including an
+explicit boolean `false` provider-default reset. The retained provider token
+is never silently replaced by a fresh conversation if that selection is not
+supported
+([[playbook-cli-22](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook-cli.md#playbook-cli-22)],
+[DR-032](https://github.com/sublang-ai/playbook/blob/main/specs/decisions/032-explicit-roles-session-players.md)).
 
 ### Recovering an uncertain turn
 
@@ -238,8 +276,15 @@ playbook run --session 4f2c0000-0000-4000-8000-000000009ab1 --retry-uncertain
 playbook run --session 4f2c0000-0000-4000-8000-000000009ab1 --discard-uncertain
 ```
 
-Retry reads no input and reuses the byte-exact recorded turn; it may duplicate
-external effects. Discard reads no input and runs no model: it restores the
-exact prior settled boundary, or deletes a never-settled fresh session, while
-abandoning the attempted work. Session files written by the removed direct
-v6 runner are not shared-Captain sessions and cannot be continued.
+Retry reads no input and reuses the byte-exact recorded turn and its exact
+attempted Captain, player, and per-role model/effort selections; current config
+cannot retune that attempt, and retry may duplicate external effects. Discard
+reads no input and runs no model: it restores the exact prior settled boundary,
+or deletes a never-settled fresh session, while abandoning the attempted work.
+An interrupted interactive turn uses the same uncertain record and is
+recovered with these headless commands. Session files written by the removed
+direct v6 runner and legacy record schemas are not shared schema-3 Captain
+sessions and cannot be continued. Explicit selection rejects them. Implicit
+`--continue` reports and skips released schema-2 Captain records, naming each
+session and path; move them outside the sessions directory or remove them to
+silence the warning. Malformed records and unknown schemas still fail closed.