@sublang/playbook 6.0.0 → 7.0.0

package/README.md

@@ -21,14 +21,14 @@ SubLang Playbook addresses both:
 
 Vocabulary: the **Boss** is you; the **Captain** is the coordinating agent you talk to; **players** are the agents a playbook delegates work to.
 
-Run `playbook` for an interactive tmux UI powered by [cligent](https://github.com/sublang-ai/cligent), or `playbook run` for one-shot scripts and CI.
+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.
 
 ## Quick start
 
 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 interactive starter config uses Claude as both Captain and Coder, and Codex as Reviewer.
+The shared starter config uses Claude as both Captain and Coder, and Codex as Reviewer.
 
 ```sh
 npm install -g @sublang/playbook
@@ -41,10 +41,11 @@ If an SDK is missing or older than cligent supports, Playbook prints the pinned
 Prerequisites:
 
 - Node.js >= 20.6.0
-- `tmux` and [`glow`](https://github.com/charmbracelet/glow#installation) on `PATH`
 - 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.
+
 CODE works in the current directory and can edit and commit autonomously, so use a clean branch or worktree.
 
 ```sh
@@ -57,16 +58,17 @@ 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`.
 
-One-shot runs use separate defaults instead of the interactive lineup.
-Without configured `run` defaults, the Captain and every player use Claude; run standalone REVIEW with a Codex Reviewer using:
+The same config, compiled Captain, enabled playbooks, players, and nested calls power headless turns.
+Run REVIEW explicitly, or pipe a longer request to Captain:
 
 ```sh
-playbook run @sublang/playbook/review/registry "review the latest commit" --player reviewer=codex --json
+playbook run "/review review the latest commit"
+printf '%s\n' 'Implement the approved specification, then review it.' | playbook run
 ```
 
-CODE and DECIDE require interactive `playbook` because the one-shot host does not drive nested calls.
+`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 session resume, [Configuring agents](docs/configuration.md) for lineups, [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](CHANGELOG.md) for releases.
 
 ## Create your own playbook
 
@@ -75,10 +77,12 @@ The separate [SLC compiler](https://github.com/sublang-ai/slc) requires Node.js
 ```sh
 npm install -g @sublang/slc
 slc playbook my-workflow.md
-playbook run ./my-workflow.ts "<your task>"
+# After enabling /absolute/path/to/my-workflow.ts in the shared config:
+playbook run "/my-workflow <your task>"
 ```
 
-SLC writes `my-workflow.ts` beside the source, and the inspectable intermediates and tests under `my-workflow.playbook/`; see the [SLC documentation](https://github.com/sublang-ai/slc#quick-start) for setup and phase commands.
+SLC writes `my-workflow.ts`, a registry entry ready for Playbook, beside the source, and the inspectable intermediates and tests under `my-workflow.playbook/`.
+Enable that entry and bind each role it declares under `playbooks.my-workflow` in the shared config, then invoke `/my-workflow`; see [External playbooks](docs/configuration.md#external-playbooks) and the [SLC documentation](https://github.com/sublang-ai/slc#quick-start).
 
 ## How it compiles
 

package/docs/cli.md

@@ -3,9 +3,10 @@
 
 # Using the CLI
 
-`playbook` has two surfaces: an interactive tmux-play session, and a
-one-shot non-interactive `run`. Agent settings for both come from the
-[config](configuration.md).
+`playbook` has two presentations of one configured Captain session: an
+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.
 
 ## Installing agent SDKs
 
@@ -123,78 +124,122 @@ 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)]).
 
-## Non-interactive
+## Headless
 
-`playbook run <from> [task]` runs one playbook once, without tmux-play
-and without an interactive config entry. For example, run REVIEW
-directly against the latest commit:
+`playbook run [input]` submits one exact Boss turn to the same Captain that
+the interactive pane hosts, without constructing tmux. The shared config
+selects the Captain, enabled playbooks, players, options, provisioning, and
+readiness; a slash command selects a playbook through Captain, and ordinary
+text remains a conversational Captain turn.
 
 ```sh
-playbook run @sublang/playbook/review/registry "review the latest commit" \
-  --player coder=claude --player reviewer=codex --cwd ./my-repo
+cd ./my-repo
+playbook run "/review review the latest commit"
+playbook run "/code implement the approved specification"
+printf '%s\n' 'Summarize the current work and propose the next step.' | playbook run
 ```
 
-`[task]` is read from stdin when omitted — pipe long or multi-line
-intents the same way you would to `claude -p` or `codex exec`.
+When `[input]` is absent, stdin is read to EOF as verbatim UTF-8 text.
+Use `--` before one flag-shaped input. Plain stdout is exactly the one
+Boss-visible Captain reply plus a line feed; status and diagnostics use
+stderr, and `--verbose` adds only telemetry topic names to stderr.
+`--json` instead prints exactly `{"sessionId":"…","reply":"…"}`.
 
 | Flag | Meaning |
 | --- | --- |
-| `--player <role>=<agent>` | bind a required role |
-| `--captain <agent>` | set the captain/judge agent |
-| `--option <key>=<value>` | a registry-defined playbook option (none in the current bundled workflows) |
-| `--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
-model keeps every interior colon (`opencode:ollama/llama3:8b@max`), and
-an unsupported effort is rejected up front naming the adapter's
-supported values. Roles and the captain default to `claude` unless the
-config supplies [run defaults](configuration.md#defaults-for-playbook-run).
-
-Exit codes: `0` terminal, `1` bad argument or module, `2` failure, `3`
-the playbook needs a Boss reply
+| `--with <path>` | overlay the shared config for a new session; 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 |
+| `--continue` | continue the latest durable Captain session |
+| `--session <id>` | continue one durable Captain session explicitly |
+| `--retry-uncertain` | with `--session`, retry its exact recorded uncertain input |
+| `--discard-uncertain` | with `--session`, abandon its uncertain attempt |
+| `--` | end options before one literal input or reply |
+| `-h`, `--help` | print the complete grammar without reading stdin or config |
+
+Exit `0` means the Captain turn and its durable hand-off were presented,
+even when the selected action reported rejection or failure through the
+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)]).
 
-### Engine provisioning
+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.
 
-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
+### Piping a Spex update prompt
+
+`spex scaffold --update` refreshes its scaffold before printing guidance and
+a fenced reconciliation prompt. Force Spex's non-interactive agent-file
+selection, capture its successful output, extract the first fenced prompt,
+and pass only that prompt to Captain:
+
+```sh
+update_output="$(spex scaffold --update </dev/null)" &&
+printf '%s\n' "$update_output" |
+  awk '/^```$/{if (++n==2) exit; next} n==1' |
+  playbook run
+```
+
+The capture prevents a failed Spex command from launching Playbook. Without
+`--lang`, the first fenced block is the sole structure reconciliation or
+legacy-migration prompt; a language switch adds a second translation prompt.
+
+### External playbooks and engine provisioning
+
+Enable an external registry in the shared config and invoke its effective
+slash command; a path-shaped `playbooks.<id>.from` is resolved relative to
+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)).
-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.
+A directory where both imports already resolve is untouched, and
+`--no-provision` disables new links for either fresh front end. If the
+module's directory is a git repository, add `node_modules/` to its
+`.gitignore` so provisioned links never enter player commits.
 
-### Resuming a parked run
+### Continuing a Captain session
 
-When the playbook stops to ask something, the run is parked, not lost:
-the question prints to stdout, the session is saved under
-`${XDG_STATE_HOME:-$HOME/.local/state}/playbook/sessions/`, and stderr
-names the command that continues it.
+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`:
 
 ```sh
-playbook run resume 4f2c…9ab1 "keep the scope small; skip the docs"
-playbook run resume --last   # most recently parked session; reply on stdin
+playbook run --continue "keep the scope small; skip the docs"
+playbook run --session 4f2c0000-0000-4000-8000-000000009ab1
 ```
 
-A resumed run picks up exactly where it parked — same session id, same
-workflow state, and each agent continues its own conversation — then
-prints the final output and exits `0`, or parks again and exits `3`. The
-lineup, options, and working directory are stored with the session, so
-`resume` takes no binding flags. In scripts, capture the session id from
-the `--json` envelope, like Claude Code's `session_id` or
-`codex exec resume`
+A missing reply is read verbatim from stdin. Continuation restores the exact
+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-014](../specs/decisions/014-durable-one-shot-run-sessions.md)).
+[DR-031](../specs/decisions/031-shared-captain-session-front-ends.md)).
+
+### Recovering an uncertain turn
+
+Before model work, the runner takes one exclusive session lease and writes an
+uncertain marker. If the process is interrupted after effects may
+have begun but before settlement is durable, ordinary continuation refuses
+to guess. Choose explicitly:
+
+```sh
+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.

package/docs/configuration.md

@@ -3,7 +3,7 @@
 
 # Configuring agents
 
-`playbook` reads one config at
+`playbook` and every fresh `playbook run` 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.
@@ -16,9 +16,10 @@ $EDITOR "${XDG_CONFIG_HOME:-$HOME/.config}/playbook/playbook.config.yaml"
 
 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), optional
+and the replies you see in the Captain pane or on headless stdout), optional
 `layout` / `notifications` / `theme`, and a `playbooks` map of enabled
-playbooks.
+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`,
@@ -138,6 +139,7 @@ recursively, other values replace):
 
 ```sh
 playbook --with fast-lineup.yaml
+playbook run --with fast-lineup.yaml "/code implement the approved change"
 ```
 
 ```yaml
@@ -165,25 +167,64 @@ 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`.
 
-## Defaults for `playbook run`
+## Shared headless configuration
 
-An optional top-level `run` block supplies the non-interactive host's
-lineup so you stop retyping flags — `run.captain`, `run.players.<role>`,
-and a `run.player` catch-all for any other required role, each an
-`<adapter>[:<model>][@<effort>]` string. Flags win per role, and
-`resume` always keeps the lineup stored with the parked session
-([[playbook-cli-28](../specs/packages/playbook-cli.md#playbook-cli-28)],
-[DR-017](../specs/decisions/017-run-defaults-config.md)).
+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.
+
+## External playbooks
+
+`slc playbook my-workflow.md` emits `my-workflow.ts` beside its artifact
+directory. That file already default-exports the registry manifest Playbook
+requires: `id`, `command`, `intent`, `requiredRoleIds`, `validateOptions`,
+and `createRuntime`. Enable it under `playbooks`, bind every role listed in
+its `requiredRoleIds`, and invoke its effective slash command through Captain:
 
 ```yaml
-run:
-  captain: claude:claude-opus-4-8@high
-  players:
-    coder: claude:claude-opus-4-8[1m]@xhigh
-    reviewer: codex:gpt-5.5@xhigh
+playbooks:
+  my-workflow:
+    from: /absolute/path/to/my-workflow.ts
+    players:
+      worker: claude
 ```
 
+```sh
+playbook run "/my-workflow perform the task"
+```
+
+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.
+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 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>`
+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`
+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)]).
+
 ## Migrating from `profiles`
 
 Configs written before 3.0.0 carried a top-level `profiles` map. The

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sublang/playbook",
-  "version": "6.0.0",
+  "version": "7.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",
@@ -67,7 +67,9 @@
     "reference/sdlc/code.playbook/code.gears.md",
     "reference/sdlc/code.playbook/playbook.config.template.yaml",
     "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/session-store.js",
     "reference/sdlc/code.playbook/bin/provision.js",
     "reference/sdlc/code.playbook/bin/adapter-sdk.js",
     "reference/sdlc/review.playbook/review.gears.md",