@sublang/playbook 9.0.0 → 11.0.0

package/README.md

@@ -63,7 +63,7 @@ playbook
 Type a task, enter `/code <task>` for implementation, or enter
 `/decide <question>` for an independently proposed and reviewed decision.
 
-On first launch, Playbook writes its config to `${XDG_CONFIG_HOME:-$HOME/.config}/playbook/playbook.config.yaml`.
+On first launch, Playbook writes its config to `${SPEX_HOME:-$HOME/.spex}/playbook/playbook.config.yaml`. A config left at the former `${XDG_CONFIG_HOME:-$HOME/.config}/playbook/playbook.config.yaml` is moved there on the next launch, unless a relative primary locator would change targets; that case is rejected unchanged with absolute replacements.
 
 The same config, compiled Captain, enabled playbooks, stable players, and
 nested calls power headless turns. Both front ends create the same durable

package/docs/cli.md

@@ -169,7 +169,7 @@ stderr, and `--verbose` adds only telemetry topic names to stderr.
 | `--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 |
+| `--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 |
@@ -188,7 +188,7 @@ The former positional `<from>`, `resume`, `--player`, `--captain`,
 `--option`, `--cwd`, `--last`, run-only `--config`, and top-level `run:`
 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`
+under `playbooks.<id>.roles`, tune compatible model, effort, and fast mode 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
@@ -231,15 +231,16 @@ module's directory is a git repository, add `node_modules/` to its
 
 ### Continuing a Captain session
 
-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:
+Interactive and headless commands write the same logical-session records in
+the configured [`sessions` directory](configuration.md#session-storage), whose
+default is `${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:
+# Reopen the newest session stored for this working directory headlessly:
 playbook run --continue "keep the scope small; skip the docs"
 
 # Reopen one exact session in either presentation:
@@ -247,6 +248,14 @@ playbook --session 4f2c0000-0000-4000-8000-000000009ab1
 playbook run --session 4f2c0000-0000-4000-8000-000000009ab1
 ```
 
+Bare `--continue` prefers the newest durable record whose stored working
+directory equals the directory where the command is invoked. If none matches,
+it reports that absence on stderr and selects the globally newest record,
+naming that session and its stored working directory. Use `--session <id>` to
+select one exact session without applying the directory preference. The
+uncertainty rules below still apply to whichever record is selected
+([DR-041](https://github.com/sublang-ai/playbook/blob/main/specs/decisions/041-working-directory-aware-continuation.md)).
+
 A missing headless reply is read verbatim from stdin. Reopening restores the
 compiled Captain conversation, engagement stack, nested child boundary,
 stable-player ledger, and absolute working directory without replaying a
@@ -257,13 +266,78 @@ 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
+current `model`, `effort`, and optional `fastMode` settings apply to the next
+call. Boolean `false` explicitly resets model or effort to the provider
+default, but `fastMode: false` is a literal disabled request; omission selects
+the fast-mode provider default or inherits the player value at a role binding.
+The retained provider token is never silently replaced by a fresh conversation
+if a requested setting 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)).
 
+### Following replay history
+
+Beside each `<session-id>.json` manifest, both front ends tee every observed
+host record in order to `<session-id>.records.jsonl`. Each complete line is a
+version-1 envelope with a writer-assigned sequence contiguous from `1`, the
+opaque record, and an optional local playbook role where the trace establishes
+one unambiguously. The stream is a mode-`0600` regular non-symlink file inside
+the private sessions directory. Readers consume only the complete
+newline-terminated prefix; a final partial line is not presented as a record.
+
+The replay projection recursively removes provider `resumeToken` fields and
+string-valued `resume` selections while preserving `resume: false`. It is
+therefore useful for following and presentation, but it cannot resume an agent
+conversation and does not replace the private canonical manifest. External
+hosts can follow this stream without taking the writer lease through the
+published [`@sublang/playbook/session-store`
+facade](embedding.md#sharing-the-cli-session-store).
+
+Streams are unbounded in this version: neither front end prunes them, and
+retention remains tied to the deferred session-deletion policy. Removing
+provider credentials does not make the remaining replay content non-sensitive;
+protect the prompts, replies, tool calls, events, and timestamps it contains as
+sensitive session data.
+
+Replay recording is fail-soft after the canonical session lease is valid. If
+initialization, sanitization, append, repair, publication synchronization, or a
+checkpoint fails, recording stops for that lease without changing the agent
+turn, durable session settlement, reply, or exit outcome. The headless command
+attempts this warning once on stderr:
+
+```text
+playbook run: warning: replay history for session "<session-id>" may be incomplete; recording has stopped
+```
+
+The interactive child instead presents one Captain status with the same
+`warning: replay history ...` text and writes no raw stderr diagnostic. A later
+lease gets its own warning only if its replay writer independently becomes
+incomplete. The public facade emits no warning; an embedding host decides how
+to present the `incomplete` status it receives
+([[playbook-cli-84](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook-cli.md#playbook-cli-84)]).
+
+### Reconciling possible repository effects
+
+For each governed player call, Playbook records a Git baseline before the call
+and a durable receipt afterward. CODE and DECIDE commit arms, and REVIEW's
+Coder commit arm, accept a commit only when the receipt proves exactly one
+descendant commit with no residual repository change; REVIEW's Reviewer calls
+and DECIDE's proposal calls require the repository to remain exact. The
+player's prose, including any `Commit:` line, is presentation rather than
+proof.
+
+If interruption, missing semantic evidence, concurrent work, or an ambiguous
+repository delta prevents those facts from agreeing, the workflow parks
+without replaying the player. Captain reports whether a change was observed or
+could not be excluded, with the available baseline, after-HEAD, and proven
+commit identity but no repository paths. While parked, ask Captain either to
+retry reconciliation from the retained evidence or to abandon the unresolved
+attempt. Reconciliation may complete the saved evidence or restore an exact
+deferred Boss-question checkpoint, but it starts no replacement player call;
+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)).
+
 ### Recovering an uncertain turn
 
 Before model work, the runner takes one exclusive session lease and writes an
@@ -277,14 +351,28 @@ 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 selections; current config
-cannot retune that attempt, and retry may duplicate external effects. Discard
+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
 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.
+recovered with these headless commands. Current sessions use Captain-session
+record schema 6. Records from the removed direct v6 runner and released record
+schema 2 have incompatible player identity; Playbook 9 record schema 3, the
+historical schema-4 retention shape, and both pre-release schema-5 shapes
+predate the canonical schema-6 record boundary; the earlier schema-5 shape also
+lacks `unresolvedEffects` and cannot prove whether governed work may replay.
+Explicit selection rejects
+all of them before registry construction or governed work with the applicable
+cutover explanation. Implicit `--continue` reports and skips each fully
+validated nonresumable record with its session id, path, applicable reason, and
+an archive-or-remove remedy while leaving the file intact. Fresh-session
+discovery likewise leaves and reports nonresumable, malformed, unsafe, or
+unknown-schema files. A fully validated nonresumable record participates in
+settled same-directory predecessor ordering: it declines adoption only when it
+is newest, while an older or different-directory record does not block a newer
+resumable predecessor. A record whose directory or order cannot be validated
+publishes an empty fresh boundary without falling through. Those invalid
+records still fail closed when explicitly selected or encountered by
+`--continue`; no path converts or restores them.

package/docs/configuration.md

@@ -4,22 +4,35 @@
 # Configuring agents
 
 Fresh launches and ordinary reopens read one config at
-`${XDG_CONFIG_HOME:-$HOME/.config}/playbook/playbook.config.yaml`. The
+`${SPEX_HOME:-$HOME/.spex}/playbook/playbook.config.yaml`. The
 first launch seeds it from the bundled starter and prints the path;
 later launches reuse it untouched.
 
+On the first launching command after upgrading Playbook, it moves a config from the
+former `${XDG_CONFIG_HOME:-$HOME/.config}/playbook/playbook.config.yaml` path
+when the canonical path is absent. The one-time move preserves bytes and
+permissions and leaves no compatibility alias, so running an older Spex host
+afterward could seed a second file at the former path.
+
+The current guard rejects relocation when a legacy relative `sessions` value
+or relative filesystem `playbooks.<id>.from` would resolve differently below
+the new directory. It leaves the former file unchanged and names every
+target-preserving absolute replacement. Apply those replacements and retry;
+Playbook does not rewrite the user-authored file.
+
 ```sh
-$EDITOR "${XDG_CONFIG_HOME:-$HOME/.config}/playbook/playbook.config.yaml"
+$EDITOR "${SPEX_HOME:-$HOME/.spex}/playbook/playbook.config.yaml"
 ```
 
 ## Anatomy
 
 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.
+workflows and their explicit role bindings, an optional `sessions` storage
+locator, 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
@@ -29,11 +42,12 @@ 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.
+`effort`, `fastMode`, `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
@@ -41,34 +55,35 @@ 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:
+The seeded config runs the stable Coder player on GPT-5.6 Sol with fast mode
+enabled and the stable Reviewer player on Claude Opus 5:
 
 ```yaml
 captain:
   adapter: claude
-  model: claude-opus-4-8
+  model: claude-opus-5
   effort: high
   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
+    model: gpt-5.6-sol
+    effort: ultra
+    fastMode: true
     permissions:
       mode: auto
       writablePaths:
         - .git # allow git metadata writes under Codex auto mode
 
+  dev.reviewer:
+    adapter: claude
+    model: claude-opus-5
+    effort: xhigh
+    permissions:
+      mode: auto # protected auto mode for the Claude Reviewer
+
 playbooks:
   code:
     from: '@sublang/playbook/code/registry'
@@ -104,21 +119,26 @@ roles:
   coder: dev.coder
 ```
 
-Use a block to override only that role invocation's model or effort:
+Use a block to override only that role invocation's model, effort, or fast
+mode:
 
 ```yaml
 roles:
   coder:
     player: dev.coder
-    model: claude-opus-4-8[1m]
+    model: gpt-5.6-sol
     effort: false # explicitly reset to this provider's default
+    fastMode: false # literal disabled request, not a default sentinel
 ```
 
-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.
+Omitting any override inherits that player's top-level default. For `model`
+and `effort`, boolean `false` selects the provider default explicitly, so a
+resumed conversation cannot accidentally retain an earlier selection. For
+`fastMode`, `false` is a literal request to disable fast mode; omitting the
+top-level setting selects the provider default. A present fast-mode boolean is
+accepted only for adapters Cligent reports as supporting it. A role binding
+cannot override adapter, instruction, permissions, workspace, or tool posture;
+those define the stable player envelope.
 
 ## Sharing, isolation, and concurrency
 
@@ -136,9 +156,9 @@ second top-level player and change only its binding:
 ```yaml
 players:
   review.coder:
-    adapter: claude
-    model: claude-opus-4-8[1m]
-    effort: xhigh
+    adapter: codex
+    model: gpt-5.6-sol
+    effort: ultra
 
 playbooks:
   review:
@@ -183,8 +203,9 @@ playbook run --with fast-lineup.yaml "/code implement the approved change"
 # fast-lineup.yaml — retune the shared Coder; nothing is written back.
 players:
   dev.coder:
-    model: claude-opus-4-8
+    model: gpt-5.6-sol
     effort: medium
+    fastMode: false
 ```
 
 Fragments merge into the agent block rather than replacing it, so
@@ -207,9 +228,37 @@ The global file is never modified, and `--with` is not forwarded to
 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.
+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.
+
+## Session storage
+
+Both front ends select canonical session manifests and write replay streams in
+one directory, where external hosts may keep their own sidecars too. Set the
+optional top-level `sessions` key to move that shared store:
+
+```yaml
+sessions: ./state/playbook-sessions
+```
+
+The value must be a nonempty filesystem path. When the key is absent, the
+directory is
+`${XDG_STATE_HOME:-$HOME/.local/state}/playbook/sessions`. An absolute path is
+used as given; `~` and `~/...` expand from the home directory, while `~user`
+is rejected. Every other value, including a bare relative path such as the one
+above, resolves against the primary config file's directory rather than the
+invocation directory. A `sessions` value in a `--with` overlay replaces the
+primary value, with later overlays winning.
+
+Launch validates that the resolved path can serve as the mode-`0700`, real,
+non-symlink session store before selecting a record or starting agent work and
+fails closed when it cannot. The non-launching `playbook --list` command still
+validates the locator's syntax but does not inspect that directory's filesystem
+usability. The resolved locator is launch configuration only: it never enters
+a persisted structural or execution projection
+([[playbook-cli-78](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook-cli.md#playbook-cli-78)]).
 
 ## Durable shared configuration
 
@@ -223,9 +272,9 @@ 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.
+compatible model, effort, or fast-mode 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
 

package/docs/embedding.md

@@ -37,7 +37,9 @@ 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 createPlaybookRuntime, {
+  type ReviewPlaybookHostCapabilities,
+} from '@sublang/playbook/review/playbook';
 import type {
   CaptainCallOptions,
   CaptainResult,
@@ -144,9 +146,21 @@ const ports: PlaybookPorts = {
   },
 };
 
-const runtime = createPlaybookRuntime({});
-
 const playbookSessionId = randomUUID();
+
+// Schema-3 artifacts keep persisted configured options separate from live
+// current-host authority. Build these capabilities only after acquiring the
+// session lease and resolving the canonical Git worktree. Their authority
+// must name this playbook/session/working directory and their repository and
+// effect-ledger operations must stay live; never put them in configuration,
+// machine input, or a persisted snapshot.
+declare const hostCapabilities: ReviewPlaybookHostCapabilities;
+
+const runtime = createPlaybookRuntime({
+  configuredOptions: {},
+  hostCapabilities,
+});
+
 await runtime.init({
   sessionId: playbookSessionId,
   playbookId: 'review',
@@ -165,7 +179,7 @@ await runtime.dispose();
 
 ## Sessions and traces
 
-Every init-to-dispose lifecycle is one playbook session. Schema-3
+Every init-to-dispose lifecycle is one playbook session. Schema-4
 `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. A
@@ -184,15 +198,115 @@ 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
+Runtime and complete shell snapshots are schema 4. Their role-resume
+projection remains role-local, while the composing shell persists the stable
+player ledger, every frame's exact role bindings, and the host's authoritative
+effect-ledger mirror. The bundled CLI wraps that shell state in Captain
+session-record schema 6. Do not restore an earlier snapshot or session record
+by guessing identity or effect evidence. This includes both pre-release
+schema-5 record shapes; the earlier one predates required `unresolvedEffects`,
+and neither is a canonical schema-6 boundary. Explicit selection rejects them,
+while fresh discovery reports and skips them. A fully validated nonresumable
+record participates in settled same-directory ordering and declines adoption
+only when it is newest; an older or different-directory record does not block a
+newer resumable predecessor. An unvalidatable record leaves ordering unproved,
+so discovery publishes an empty target without falling through. 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.
+provider-default selection) and rebuild live host capabilities under the
+current lease, so neither invocation identity nor repository authority comes
+from stale machine state. Trace data, tokens, repository projections, and
+capability functions never enter Boss-visible status text or configured
+options. Because trace observers do receive opaque resume tokens, persisted
+traces should be protected as sensitive data.
+
+## Sharing the CLI session store
+
+An external host that needs the CLI's canonical session validation and
+token-free replay format can use the narrow, semver-stable
+`@sublang/playbook/session-store` facade. It shares the CLI's private store and
+validators by construction but exposes no canonical manifest, snapshot,
+provider credential, effect ledger, recovery operation, or turn-lifecycle
+operation:
+
+```ts
+import {
+  defaultSessionsDir,
+  openSessionStore,
+} from '@sublang/playbook/session-store';
+
+const store = openSessionStore(defaultSessionsDir());
+const { sessions, skipped } = await store.list();
+
+const sessionId = sessions[0]?.sessionId;
+if (sessionId !== undefined) {
+  const summary = await store.read(sessionId);
+  console.log(summary.sessionId, summary.state, summary.cwd);
+
+  const first = await store.readStream(sessionId);
+  const next = await store.readStream(sessionId, {
+    afterSeq: first.lastReadableSeq,
+  });
+  console.log(next.entries, skipped);
+}
+```
+
+`list()` reports valid summaries and separately reports skipped canonical
+manifests with their validation or cutover reason. A summary has exactly
+`schemaVersion`, `sessionId`, `state`, `cwd`, and `updatedAt`. A lease-free
+`readStream()` returns complete envelopes and `lastReadableSeq` only: it makes
+no claim that another process has durably checkpointed the observed bytes or
+that its live writer remains complete. An absent stream reads as empty, and
+acquiring its lease does not require a manifest; only `read()` requires a
+canonical session summary. Pass an absolute path to `openSessionStore()` when
+using a directory other than the environment-derived default.
+
+Writing requires the one exclusive session lease. The writer assigns envelope
+version and sequence, serializes overlapping appends in invocation order, and
+strips provider resume credentials from every accepted record:
+
+```ts
+const lease = await store.acquire(
+  '4f2c0000-0000-4000-8000-000000009ab1',
+);
+try {
+  await lease.append({ type: 'host_notice', message: 'attached' });
+  const status = lease.streamStatus();
+  console.log(status);
+  if (status.lastReadableSeq !== null) {
+    const replay = await lease.readStream();
+    console.log(replay.lastReadableSeq, replay.lastDurableSeq);
+  }
+} finally {
+  const finalStatus = await lease.release();
+  console.log(finalStatus);
+}
+```
+
+`streamStatus()` synchronously returns the current live status. If initialization
+could not establish a trustworthy whole-stream boundary, it returns
+`{ lastReadableSeq: null, lastDurableSeq: null, incomplete: true }`, and
+`lease.readStream()` rejects rather than return partial history.
+An `append()` suppressed before release by either unavailable initialization or
+a numeric incomplete latch resolves `undefined` without recording the supplied
+record, so fulfillment alone does not prove persistence.
+
+Always release a successfully acquired lease. `release()` closes append
+admission, drains earlier appends, attempts the final checkpoint, retires the
+lease, and returns the final `lastReadableSeq`, `lastDurableSeq`, and
+`incomplete` status. A replay initialization failure reports unavailable null
+boundaries; a later sanitization, repair, or persistence failure latches
+numeric `incomplete` status. Either state suppresses later replay work on that
+lease and remains isolated from canonical session lifecycle work. The facade
+writes no warning to stdout or stderr; the embedding host owns any presentation
+of that status.
+
+For control flow, a missing canonical manifest from `read()` uses
+`Error.code === 'PLAYBOOK_SESSION_NOT_FOUND'`, and a competing live or foreign
+lease uses `Error.code === 'PLAYBOOK_SESSION_LEASE_ACTIVE'`. Do not match error
+messages or assume those codes for malformed input, unsafe storage, an
+indeterminate owner probe, or another storage failure
+([[playbook-cli-73](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook-cli.md#playbook-cli-73)]).
 
 See
 [`code.playbook.test.ts`](https://github.com/sublang-ai/playbook/blob/main/reference/sdlc/code.playbook/code.playbook.test.ts)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sublang/playbook",
-  "version": "9.0.0",
+  "version": "11.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",
@@ -28,6 +28,9 @@
     "src/runtime.ts",
     "src/runtime.js",
     "src/runtime.d.ts",
+    "src/accepted-outcome.ts",
+    "src/accepted-outcome.js",
+    "src/accepted-outcome.d.ts",
     "src/xstate-runtime.ts",
     "src/xstate-runtime.js",
     "src/xstate-runtime.d.ts",
@@ -64,15 +67,19 @@
     "reference/sdlc/code.playbook/playbook-captain.ts",
     "reference/sdlc/code.playbook/playbook-captain.js",
     "reference/sdlc/code.playbook/playbook-captain.d.ts",
+    "reference/sdlc/code.playbook/session-store.js",
+    "reference/sdlc/code.playbook/session-store.d.ts",
     "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/interactive-session.js",
+    "reference/sdlc/code.playbook/bin/replay-observer.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/code.playbook/bin/repository-effects.js",
     "reference/sdlc/review.playbook/review.gears.md",
     "reference/sdlc/review.playbook/review.fsm.ts",
     "reference/sdlc/review.playbook/review.fsm.js",
@@ -123,6 +130,10 @@
       "types": "./reference/sdlc/code.playbook/playbook-captain.d.ts",
       "default": "./reference/sdlc/code.playbook/playbook-captain.js"
     },
+    "./session-store": {
+      "types": "./reference/sdlc/code.playbook/session-store.d.ts",
+      "default": "./reference/sdlc/code.playbook/session-store.js"
+    },
     "./slc/*": "./slc/*",
     "./review/playbook": {
       "types": "./reference/sdlc/review.playbook/review.playbook.d.ts",
@@ -154,8 +165,8 @@
     "provenance": true
   },
   "dependencies": {
-    "@sublang/cligent": "^0.22.0",
-    "@sublang/spex": "^2.1.1",
+    "@sublang/cligent": "^0.24.0",
+    "@sublang/spex": "^3.0.0",
     "p-queue": "^9.3.1",
     "xstate": "^5.19.4",
     "yaml": "^2.9.0"