@sublang/playbook 15.1.0 → 17.0.0

package/README.md

@@ -83,6 +83,8 @@ 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.
 
+If a step fails or needs preparation before your answer, ask Captain to fix the prerequisite and resume; see [Preparing a stopped step](docs/cli.md#preparing-a-stopped-step).
+
 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

package/docs/cli.md

@@ -144,17 +144,16 @@ 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
+clarifying question, the playbook pauses and Captain explains the complete question briefly.
+Answer or ask for clarification through Captain; reading a player pane is unnecessary.
+A request to explain preserves the pending question, while an answer or explicit player follow-up reaches the waiting player
 ([[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
+streams progress; Captain relays pending questions in its reply
 ([[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
+with one Captain reply summarizing what changed, grounded in that turn's reported outcome and current pending questions; a turn that changed nothing ends with an
 ordinary reply and no saved-counts line
 ([[playbook-captain-19](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook-captain.md#playbook-captain-19)]).
 
@@ -187,8 +186,8 @@ stderr, and `--verbose` adds only telemetry topic names to stderr.
 | `--verbose` | add Captain telemetry topic names to stderr |
 | `--continue` | continue the newest Captain session stored for this working directory, or the reported global fallback |
 | `--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 |
+| `--retry-uncertain` | with `--session`, restore and report interrupted work; then choose a continuation |
+| `--discard-uncertain` | with `--session`, discard an attempt only if no work was recorded |
 | `--` | end options before one literal input or reply |
 | `-h`, `--help` | print the complete grammar without reading stdin or config |
 
@@ -196,8 +195,7 @@ 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
+exits `2` with stdout empty. SIGINT, SIGTERM, and SIGHUP withhold stdout, preserve uncertainty unless stopped recovery can save its current work, and are re-raised after lease retirement
 ([[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`,
@@ -369,27 +367,47 @@ abandonment disposes the complete engagement without claiming an authored
 workflow outcome. The same restricted recovery survives process restart
 ([DR-040](https://github.com/sublang-ai/playbook/blob/main/specs/decisions/040-outcome-authority-effect-reconciliation.md)).
 
+### Preparing a stopped step
+
+Captain automatically tries to prepare and resume a step stopped by an operation in the current turn. You can also supply a missing answer or ask for a repair:
+
+```sh
+playbook run --session <id> "Install the missing dependency and continue."
+```
+
+This also works in the interactive Boss pane. Captain may inspect prerequisites, prepare local tools, put generated files aside, and adjust local ignore settings. It preserves user work and the task's scope. It cannot do the remaining specialist work, change saved session data, invent a result, or skip a step.
+
+The runtime checks the continuation. It retries the interrupted step, keeps earlier commits, and uses saved output when only its assessment was interrupted. If a read-only check left unwanted files, retry requires restoring its original files and HEAD; the original failure stays recorded. A waiting player's repository checkpoint must remain intact.
+
+Captain asks Boss for a real missing decision, uncertain permission, or a missing or contradictory playbook transition. Repository checks alone cannot prove that publishing or another outside action is safe to repeat; Captain must check that separately.
+
+Preparation allows at most two automatic attempts, each following a stop produced by work in this turn. Resuming saved work or refusing new text does not start preparation. Each preparation has a 150-second deadline. When a turn with recorded progress throws and its calls drain safely, the latest stopped step is saved and accepts a new instruction; the interactive pane stays open. Before every player, script or preparation step, the runner saves its position; it saves the result before advancing. After process loss, Retry only restores and reports. Boss chooses what happens next. Custom hosts must provide cancellation before preparation is available.
+
+Custom runtimes can provide the same recovery offer: step prompt, optional preparation conditions and evidence, and a continuation they will validate. Captain needs no list of repair tools or error strings. Failed checkpoints without an invocation position have no step retry; restarting the whole playbook could repeat completed work.
+
+Captain may answer a player from the original task when it already answers the question. It reports what it reused, respects later Boss instructions and never sends that original answer twice automatically.
+
+If a process loses the exact stopping point, retry settles the attempt in chat without repeating player work. Files and recorded evidence remain; unrelated saved workflows remain available. This also works when the attempt began from chat or used a custom runtime.
+
+All applications sharing a session store, including Spex and the CLI, must upgrade together before running this version: every step writes the new progress fields, and every saved shell snapshot carries `presentedEffectPrefix`. Hosts through 16.0.x reject those fields as unknown, so they cannot open any session this version saves.
+
 ### 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:
+to guess. Retry restores the saved position and reports what happened, without running any work. Discard is a separate explicit request:
 
 ```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 and its exact
-attempted Captain, player, and per-role model, effort, and fast-mode settings;
-current config cannot retune that attempt, and retry may duplicate external
-effects. Discard
+Retry reads no input and restores the recorded attempt only to report it. It runs no model work. Later turns use the current compatible configuration. A completed step can use its saved result without running again. Before repeating an unfinished step, Boss must confirm that the old worker has stopped and check any outside actions; unchanged files do not prove nothing happened. A runtime that cannot save its position returns to Captain with the work preserved. 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 these
-headless recovery commands. Discard preserves the attempt's replay history and
-refuses if the effect ledger has advanced beyond the prior checkpoint.
+An interrupted interactive turn that could not save a normal pause uses the same uncertain record and these headless recovery commands. Discard preserves the attempt's replay history and
+refuses if the effect ledger has advanced beyond the prior checkpoint or any step was recorded. It does not undo files or commits. Captain never selects discard automatically.
 
 Stop old writers before upgrading. When using the ordinary `~/.spex/sessions`
 default, the CLI imports sessions from

package/docs/configuration.md

@@ -215,15 +215,18 @@ 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 and Gemini enforce that at the
+Ordinary Captain decisions, replies, question checks and adjudication are hidden and tool-free.
+Claude and Gemini enforce the tool restriction 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.
 
+Recovery preparation is separate: Captain may use its configured tools and permissions to repair prerequisites for the paused step, within the existing task.
+It may not finish the specialist’s task or invent a decision; discarding work or rewriting history requires your explicit instruction.
+Preparation has a 150-second limit.
+
 Adapter readiness is intentionally light: `claude` is ready with local
 Claude Code auth or `ANTHROPIC_API_KEY`; `codex` with local Codex CLI
 auth or `OPENAI_API_KEY`. A known adapter that is not ready blocks the
@@ -271,8 +274,7 @@ compatible ordinary reopen. A selected session keeps its stored catalog,
 player roster, role bindings, adapter, instruction, permissions, and working
 directory; only model, effort, and fast mode may change. The next call reapplies
 both complete model and effort selections and the optional effective fast-mode
-boolean. An uncertain retry accepts no tuning overlay and uses the exact
-attempted settings already stored with that turn.
+boolean. An uncertain retry accepts no tuning overlay and only restores and reports the recorded attempt. Later turns use the current compatible settings.
 
 ## Session storage
 

package/docs/embedding.md

@@ -38,7 +38,7 @@ tree, which pnpm's strict linking will not allow.
 
 ```ts
 import createPlaybookRuntime, {
-  type ReviewPlaybookHostCapabilities,
+  type PlaybookHostCapabilities,
 } from '@sublang/playbook/review/playbook';
 import type {
   CaptainCallOptions,
@@ -156,7 +156,7 @@ const playbookSessionId = randomUUID();
 // machine input, or a persisted snapshot. A host outside the CLI constructs
 // the repository and effect-ledger members through the facade described in
 // "Constructing worktree host capabilities" below.
-declare const hostCapabilities: ReviewPlaybookHostCapabilities;
+declare const hostCapabilities: PlaybookHostCapabilities;
 
 const runtime = createPlaybookRuntime({
   configuredOptions: {},
@@ -258,7 +258,7 @@ const inert = createPlaybookRuntime({
 ```
 
 `createWorktreeHostCapabilities()` requires only that `cwd` exist and returns
-exactly `repository: { identity, observe, runExclusive, runDeferred }` and
+exactly `repository: { identity, observe, acquire, runExclusive, runDeferred }` and
 `effectLedger: { snapshot, writeAhead }`. The governed worktree is bound at
 every governed call and observation rather than fixed at construction: it is
 the canonical root of the nearest Git worktree containing `cwd`, or — when
@@ -279,6 +279,7 @@ CLI uses (process-local until the repository exists, since there is no `.git`
 to publish it in), observe before and after the operation, apply the engine's
 correction-budget `writeAhead` mid-completion, and bind, park, continue, and
 restore deferred Boss questions with the engine's exact checkpoint semantics.
+`acquire({signal})` holds that same worktree claim for preparation checks; call `assertOwner()` before checking and `release()` in `finally`.
 Overlapping calls on one worktree run one at a time, in no guaranteed order.
 A write the ledger rejects after a boundary has started leaves the worktree
 claim quarantined, exactly as it would under `playbook run`: treat that
@@ -413,10 +414,30 @@ Automatic discovery belongs only to the ordinary
 `~/.spex/sessions` profile with no `SPEX_HOME` or `sessions` override; custom
 profiles require an explicit migration request.
 
-For an uncertain session, reopen with `mode:'retry'` and call `retry()`. It uses
-the exact recorded input and attempted configuration. Module-free
-`discardSessionUncertain(shared, sessionId)` restores the prior recovery only
-when no effect-ledger advancement prevents discard.
+Captain may answer a player from the original task when it already answers the question. It reports what it reused, respects later Boss instructions and never sends that original answer twice automatically.
+
+If a process loses the exact stopping point, retry settles the attempt in chat without repeating player work. Files and recorded evidence remain; unrelated saved workflows remain available. This also works when the attempt began from chat or used a custom runtime.
+
+All applications sharing a session store, including Spex and the CLI, must upgrade together before running this version. Every saved shell snapshot carries `presentedEffectPrefix`, which hosts through 16.0.x reject as unknown, so they cannot open any session this version saves.
+
+A single recovery entry point handles either a paused step or an uncertain attempt:
+
+```ts
+const controller = await openSessionHost({ store: shared, sessionId, mode: 'recover' });
+try {
+  const record = await controller.read();
+  await controller.recover(record?.state === 'uncertain' ? undefined : bossInstruction);
+} finally { await controller.dispose(); }
+```
+
+For uncertainty it restores the saved position and reports the recorded work using the attempted settings. It runs no player, script or preparation. Boss then chooses an available action or supplies input. Completed results are reused; before repeating unfinished work, Boss must stop any old worker and check outside actions. A runtime without a saved position returns to Captain with work preserved. It never chooses discard. For an already settled pause, `recover(bossInstruction)` requires Boss's instruction or answer and passes it through the same Captain turn as CLI input; an ordinary answer does not force preparation. New input cannot replace an uncertain instruction before recovery.
+
+If a turn fails and leaves this open controller uncertain, dispose it and reopen with `mode:'recover'` before calling `recover()` without new input.
+
+Explicit `mode:'retry'` and `retry()` remain supported. Module-free
+`discardSessionUncertain(shared, sessionId)` restores the prior recovery, or
+deletes a never-settled fresh session and resolves `undefined`,
+only when `isUncertainTurnDiscardable(record)` returns true: no abandonment, no recorded steps, and a ledger equal to the pre-turn snapshot. Use the same exported predicate to enable a Discard control.
 
 `readHistory()` returns readable history and a damaged boundary, including a
 clearly marked synthetic projection when a validated legacy journal has no

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sublang/playbook",
-  "version": "15.1.0",
+  "version": "17.0.0",
   "type": "module",
   "description": "Composable XState v5 playbook runtime with compiled Captain, CODE, REVIEW, DECIDE, DEV, BRANCH, and PR workflows driven by GEARS specs.",
   "license": "Apache-2.0",
@@ -243,15 +243,15 @@
     "provenance": true
   },
   "dependencies": {
-    "@sublang/cligent": "^0.26.0",
+    "@sublang/cligent": "^0.27.0",
     "@sublang/spex": "^3.0.0",
     "p-queue": "^9.3.1",
     "xstate": "^5.19.4",
     "yaml": "^2.9.0"
   },
   "devDependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.3.223",
-    "@openai/codex-sdk": "^0.146.0",
+    "@anthropic-ai/claude-agent-sdk": "^0.3.283",
+    "@openai/codex-sdk": "^0.157.1",
     "@types/node": "^22.0.0",
     "typescript": "^5.8.0",
     "vitest": "^3.0.0"

package/reference/sdlc/branch.playbook/branch.fsm.d.ts

@@ -1,34 +1,46 @@
 export type BranchStateId = 'createBranch';
 export type BranchSourceItem = 'BRANCH-1';
+/**
+ * Stable working-leaf ids that may suspend on a Boss question and be resumed
+ * by `BOSS_REPLY`. The machine has at most one active player task, so the
+ * scalar Boss-reply form applies.
+ */
+declare const RESUMABLE_STATE_IDS: readonly ["createBranch"];
+export type ResumableStateId = (typeof RESUMABLE_STATE_IDS)[number];
+/** JSON-safe normalization of a rejected invocation, retained for inspection. */
+export type NormalizedError = {
+    readonly name: string;
+    readonly message: string;
+    readonly stack?: string;
+};
+/** Question record raised by the suspended Coder working leaf. */
 export type PendingBossQuestion = {
-    readonly questionId: 'createBranch';
-    readonly resumeStateId: 'createBranch';
-    readonly sourceItem: 'BRANCH-1';
+    readonly questionId: ResumableStateId;
+    readonly resumeStateId: ResumableStateId;
+    readonly sourceItem: BranchSourceItem;
     readonly asker: {
         readonly kind: 'role';
         readonly roleId: 'coder';
     };
     readonly question: string;
 };
+/** Typed input for the delegated `player` actor. */
 export type PlayerInput = {
     readonly stateId: 'createBranch';
     readonly role: 'coder';
     readonly sourceItem: 'BRANCH-1';
     readonly prompt: string;
     readonly result: Readonly<Record<string, string>>;
+    /** Backs the prompt's `<caller-input>` placeholder with the exact caller input. */
     readonly callerInput: string;
     readonly pendingBossQuestion?: PendingBossQuestion;
     readonly bossReply?: string;
 };
+/** Discriminated result contract of the delegated `player` actor. */
 export type PlayerOutput = {
     readonly guard: 'branched';
     readonly branch: string;
-    /**
-     * Receipt-owned effect evidence (DR-045): the branching call's
-     * `unchanged` receipt observes the commit the branch was created from
-     * as HEAD, so the linked runtime injects it and never takes it from
-     * Coder's prose.
-     */
+    /** Exact base revision from repository authority, not from Coder's prose. */
     readonly baseRevision: string;
     readonly issueSummary: string;
 } | {
@@ -38,47 +50,55 @@ export type PlayerOutput = {
     readonly guard: 'needsBossReply';
     readonly question: string;
 };
+/**
+ * Terminal result: exactly the packaged `branch` workflow's public output
+ * interface (workflow-contracts.json), derived from typed context.
+ */
 export type BranchPlaybookOutput = {
     readonly status: 'branched';
-    /** Exact name of the new branch now checked out. */
+    /** Exact new branch name. */
     readonly branch: string;
-    /** Exact receipt-observed revision the branch was created from. */
+    /** Exact receipt-observed repository revision the branch was created from. */
     readonly baseRevision: string;
-    /** Coder's concise summary of the issue and its comments, or of the request. */
+    /** Concise issue-and-comments or request summary. */
     readonly issueSummary: string;
 } | {
     readonly status: 'refused';
-    /** Coder's complete report carrying the reason no branch was created. */
+    /** Complete refusal report. */
     readonly coderOutput: string;
 };
-export type BranchInput = Readonly<Record<string, never>>;
+/** The machine reads no input: the caller input arrives on `START_BRANCH`. */
+export type BranchInput = Readonly<Record<never, never>>;
+export type BranchCompletion = 'branched' | 'refused';
 export type BranchContext = {
     readonly callerInput?: string;
     readonly branch?: string;
-    /** Observed HEAD of the branching call's unchanged receipt (DR-045). */
     readonly baseRevision?: string;
     readonly issueSummary?: string;
     readonly coderOutput?: string;
-    readonly completion?: 'branched' | 'refused';
-    readonly lastError?: unknown;
+    readonly completion?: BranchCompletion;
+    readonly lastError?: NormalizedError;
     readonly pendingBossQuestion?: PendingBossQuestion;
     readonly bossReply?: string;
 };
+/** Typed Boss surfaces: the caller's entry event and the Boss reply. */
 export type BranchEvent = {
     readonly type: 'START_BRANCH';
     readonly callerInput: string;
 } | {
     readonly type: 'BOSS_REPLY';
     readonly answer: string;
-    readonly questionId?: 'createBranch';
+    readonly questionId?: ResumableStateId;
 };
+/** No parallel group in this playbook. */
+export declare const concurrentRoleSets: readonly (readonly string[])[];
 export declare const branchMachine: import("xstate").StateMachine<BranchContext, {
     readonly type: "START_BRANCH";
     readonly callerInput: string;
 } | {
     readonly type: "BOSS_REPLY";
     readonly answer: string;
-    readonly questionId?: "createBranch";
+    readonly questionId?: ResumableStateId;
 }, {
     [x: string]: import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<PlayerOutput, PlayerInput, import("xstate").EventObject>> | undefined;
 }, {
@@ -96,16 +116,22 @@ export declare const branchMachine: import("xstate").StateMachine<BranchContext,
     type: "rememberActorError";
     params: import("xstate").NonReducibleUnknown;
 } | {
-    type: "rememberPendingQuestion";
+    type: "rememberMalformedPlayerOutput";
     params: import("xstate").NonReducibleUnknown;
 } | {
-    type: "rememberBossReply";
+    type: "clearBossReplyContext";
     params: import("xstate").NonReducibleUnknown;
 } | {
-    type: "rememberEmptyBossReplyError";
+    type: "setPendingBossQuestion";
+    params: {
+        readonly stateId: ResumableStateId;
+        readonly sourceItem: BranchSourceItem;
+    };
+} | {
+    type: "rememberMalformedBossReply";
     params: import("xstate").NonReducibleUnknown;
 } | {
-    type: "rememberMalformedPlayerOutput";
+    type: "acceptBossReply";
     params: import("xstate").NonReducibleUnknown;
 } | {
     type: "startBranch";
@@ -118,9 +144,16 @@ export declare const branchMachine: import("xstate").StateMachine<BranchContext,
     params: import("xstate").NonReducibleUnknown;
 }, {
     type: "needsBossReply";
-    params: unknown;
+    params: {
+        readonly stateId: ResumableStateId;
+    };
 } | {
-    type: "emptyBossReply";
+    type: "canResume";
+    params: {
+        readonly stateId: ResumableStateId;
+    };
+} | {
+    type: "givesRequest";
     params: unknown;
 } | {
     type: "isBranched";
@@ -128,20 +161,17 @@ export declare const branchMachine: import("xstate").StateMachine<BranchContext,
 } | {
     type: "isRefused";
     params: unknown;
-} | {
-    type: "resumesCreateBranch";
-    params: unknown;
-}, never, "failed" | "ready" | "awaitBossReply" | "refused" | "createBranch" | "branched", string, Readonly<Record<string, never>>, {
+}, never, "failed" | "ready" | "awaitBossReply" | "refused" | "createBranch" | "branched", string, Readonly<Record<never, never>>, {
     readonly status: "branched";
-    /** Exact name of the new branch now checked out. */
+    /** Exact new branch name. */
     readonly branch: string;
-    /** Exact receipt-observed revision the branch was created from. */
+    /** Exact receipt-observed repository revision the branch was created from. */
     readonly baseRevision: string;
-    /** Coder's concise summary of the issue and its comments, or of the request. */
+    /** Concise issue-and-comments or request summary. */
     readonly issueSummary: string;
 } | {
     readonly status: "refused";
-    /** Coder's complete report carrying the reason no branch was created. */
+    /** Complete refusal report. */
     readonly coderOutput: string;
 }, import("xstate").EventObject, import("xstate").MetaObject, {
     id: "branch";