@sublang/playbook 12.3.0 → 13.0.0

package/docs/cli.md

@@ -235,7 +235,7 @@ module's directory is a git repository, add `node_modules/` to its
 
 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
+default is `${SPEX_HOME:-$HOME/.spex}/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
@@ -259,7 +259,7 @@ 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,
+Captain recovery journal, engagement stack, nested child boundary,
 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
@@ -272,8 +272,9 @@ 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
+Provider conversations are local hints. Missing hints start fresh from stored
+context; a definite pre-execution rejection permits one fresh attempt.
+Unsupported settings and ambiguous failures do not trigger that fallback
 ([[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)).
 
@@ -287,36 +288,44 @@ 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
+Manifests use schema 7 and contain token-free recovery. The matching replay
+stream carries immutable configuration and graph records, so history does not
+require installed modules. Provider continuation hints live separately in
+`<session-id>.hints.json` and stay local. A hint is consumed before use and
+accepted only for the exact checkpoint that created it.
+
+The manifest hashes its exact durable replay prefix. Missing or changed bytes,
+saved incompleteness, or unsupported required context block continuation while
+preserving readable history. A partial final line waits for completion; valid
+unknown record kinds are skipped for presentation. New session creation fails
+if its required context cannot be saved before work.
+
+After work begins, replay failure stops recording and reports an incomplete
+history warning without authorizing a repeated action. Recovery and uncertainty
+remain durable; the incomplete marker persists across process restarts.
+Release retains the lease if that marker cannot be saved.
+
+Copy the manifest and matching replay together. Do not copy hints or leases.
+Continuation also requires matching working-directory/module paths and
+compatible runtimes; changed paths allow history only. Prompts, replies and
+tool content remain sensitive even after structured continuation fields have
+been removed. See the [shared storage contract](https://github.com/sublang-ai/playbook/blob/main/specs/packages/session-storage.md).
+
+### Migrating older sessions
+
+Stop old writers and snapshot Spex home and `${XDG_STATE_HOME:-$HOME/.local/state}/playbook` before upgrading.
+The ordinary default migrates known legacy formats into `~/.spex/sessions`, retaining history even when recovery is unavailable; explicit store overrides remain isolated.
+Migration retains original files under `local/migrations/` beside the destination sessions directory, validates the new bundle, then removes the former replay and manifest.
+Unknown or unsafe inputs stay in place with a diagnostic.
+
+For an explicitly configured store, migrate each selected legacy session before continuing it:
+
+```sh
+playbook migrate-session <id> [--with <path>]...
 ```
 
-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)]).
+Schema 6 may retain execution; older CLI records and desktop sidecars lacking complete recovery remain readable history.
+Discovery skips these histories and unmigrated records with a reason; they do not block other sessions.
 
 ### Reconciling possible repository effects
 
@@ -359,23 +368,18 @@ 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. 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.
+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.
+
+Stop old writers before upgrading. When using the ordinary `~/.spex/sessions`
+default, the CLI imports sessions from
+`${XDG_STATE_HOME:-$HOME/.local/state}/playbook/sessions`. Explicit `SPEX_HOME`
+or `sessions` selections bypass this discovery. Other locations can be migrated
+through the [shared API](embedding.md#sharing-the-cli-session-store).
+
+Migration preserves the complete replay and retains original bytes before
+removing old active files. Valid schema-6 recovery becomes token-free; schemas
+2–5 and incomplete desktop sidecars become history only. Unsupported inputs
+stay in place with a diagnostic; active writers and destination conflicts stop
+the cutover. Ordinary continuation never guesses missing identity or effects.

package/docs/configuration.md

@@ -250,7 +250,7 @@ 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
+one directory, shared with embedding hosts. Set the
 optional top-level `sessions` key to move that shared store:
 
 ```yaml
@@ -259,7 +259,7 @@ 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
+`${SPEX_HOME:-$HOME/.spex}/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

package/docs/embedding.md

@@ -200,19 +200,11 @@ 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 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
+Runtime and complete shell snapshots are schema 4. The shared store projects
+provider continuations out of nested snapshots and writes schema-7 manifests.
+Local hints may rehydrate the current checkpoint; retained generations never
+restore provider tokens. Use the shared migrator for older records instead of
+guessing identity or effect evidence. On a compatible
 restore, rebuild
 `promptIdentity` from the current model selection (or adapter for an explicit
 provider-default selection) and rebuild live host capabilities under the
@@ -304,12 +296,9 @@ lease, session record, resume credential, catalog, or recovery member
 
 ## 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:
+`@sublang/playbook/session-store` provides the shared lifecycle and management
+API. Its existing `openSessionStore()` facade remains available for narrow
+summary/replay consumers:
 
 ```ts
 import {
@@ -373,15 +362,10 @@ 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.
+Always release a successfully acquired lease. Release drains admitted work,
+saves newly detected incompleteness and retires ownership. A failed save or
+unproved ownership leaves the lease held. The facade owns no presentation;
+embedding hosts decide how to display recording failures.
 
 For control flow, a missing canonical manifest from `read()` uses
 `Error.code === 'PLAYBOOK_SESSION_NOT_FOUND'`, and a competing live or foreign
@@ -390,10 +374,62 @@ 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)
-for the full range of port shapes (classifier, judge, abort, interrupt,
-status/telemetry) the runtime is contract-tested against.
+For complete sessions, use `createSessionStore()` and `openSessionHost()`:
+
+```ts
+import { createSessionStore } from '@sublang/playbook/session-store';
+import { openSessionHost } from '@sublang/playbook/session-host';
+
+const shared = createSessionStore();
+await shared.prepare();
+const controller = await openSessionHost({
+  store: shared,
+  sessionId,
+  mode: 'continue',
+});
+try {
+  await controller.handleBossTurn('Continue the recorded work.');
+} finally {
+  await controller.dispose();
+}
+```
+
+A new host supplies a validated `SessionExecutionProjection` as `config`, or a
+plan from `loadLaunchPlan()`, and the working directory. Resolve a configured
+`sessions` path with `resolveLaunchSessionsDir()` and pass that store explicitly.
+The controller owns uncertainty, reconciliation, settlement and lease release;
+observers receive presentation events or exact appended envelopes through
+`onStoredRecord`. Keep the controller open for successive turns.
+
+`shared.readLeaseState(sessionId)` reports `active`, `idle` or `unknown` without
+changing files. Use it for presentation; mutations still require a lease.
+
+`shared.migrate(id, { sourcePath })` imports a legacy manifest and its adjacent
+replay while holding both stores' leases. `shared.migrateLegacyDefault()` imports
+the former XDG default and reports migrated and preserved unsupported IDs.
+Embedding applications select and migrate stores during startup;
+`openSessionHost()` does not discover old profiles. Stop old writers first.
+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.
+
+`readHistory()` returns readable history and a damaged boundary, including a
+clearly marked synthetic projection when a validated legacy journal has no
+stream. `validate()` separates byte integrity from resumability.
+`readManifest()` may return an older or unknown object; use
+`validateSessionManifest()` before interpreting schema-7 recovery.
+`migrate()` preserves original inputs before conversion. `delete()` removes the
+bundle under the shared lease, with the manifest last. Management needs no
+playbook module. A coordination-only `acquireManagement()` lease reserves even
+an absent ID and never checkpoints or rewrites selected bytes on release.
+
+The [storage contract](https://github.com/sublang-ai/playbook/blob/main/specs/packages/session-storage.md)
+defines the files, versions and compatibility rules.
 
 ## Reading the published spec contracts
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sublang/playbook",
-  "version": "12.3.0",
+  "version": "13.0.0",
   "type": "module",
   "description": "Composable XState v5 playbook runtime with compiled Captain, CODE, REVIEW, DECIDE, and DEV workflows driven by GEARS specs.",
   "license": "Apache-2.0",
@@ -113,7 +113,11 @@
     "reference/sdlc/dev.playbook/dev.registry.ts",
     "reference/sdlc/dev.playbook/dev.registry.js",
     "reference/sdlc/dev.playbook/dev.registry.d.ts",
-    "docs"
+    "docs",
+    "reference/sdlc/code.playbook/session-host.js",
+    "reference/sdlc/code.playbook/session-host.d.ts",
+    "reference/sdlc/code.playbook/bin/portable-codec.js",
+    "reference/sdlc/code.playbook/bin/session-host.js"
   ],
   "bin": {
     "playbook": "reference/sdlc/code.playbook/bin/playbook.js"
@@ -175,6 +179,10 @@
     "./dev/registry": {
       "types": "./reference/sdlc/dev.playbook/dev.registry.d.ts",
       "default": "./reference/sdlc/dev.playbook/dev.registry.js"
+    },
+    "./session-host": {
+      "types": "./reference/sdlc/code.playbook/session-host.d.ts",
+      "default": "./reference/sdlc/code.playbook/session-host.js"
     }
   },
   "scripts": {
@@ -190,7 +198,7 @@
     "provenance": true
   },
   "dependencies": {
-    "@sublang/cligent": "^0.24.0",
+    "@sublang/cligent": "^0.25.0",
     "@sublang/spex": "^3.0.0",
     "p-queue": "^9.3.1",
     "xstate": "^5.19.4",

package/reference/sdlc/code.playbook/bin/interactive-session.js

@@ -378,6 +378,7 @@ export function createManagedInteractiveLifecycle(payloadValue, options = {}) {
       let host;
       try {
         lease = await store.acquire(payload.sessionId);
+        if (payload.mode === 'selected') await lease.assertContinuable({ cwd: payload.cwd, executionProjection: payload.executionProjection });
         replayChannel = createManagedReplayChannel({
           lease,
           sessionId: payload.sessionId,

package/reference/sdlc/code.playbook/bin/launch-config.js

@@ -173,6 +173,7 @@ export function resolveLaunchSessionsDir({
   preparePrimary = false,
   templatePath = DEFAULT_TEMPLATE_PATH,
   onNotice = () => {},
+  onDefault = () => {},
 }) {
   // The private injection used by tests and managed launch plumbing remains
   // authoritative over configuration, just like an injected store.
@@ -199,6 +200,7 @@ export function resolveLaunchSessionsDir({
   }
 
   if (locator === undefined) {
+    onDefault();
     return defaultCaptainSessionsDir(env, homeDir);
   }
   if (typeof locator !== "string" || locator.length === 0) {

package/reference/sdlc/code.playbook/bin/playbook.js

@@ -82,6 +82,31 @@ export async function runPlaybookCli(options = {}) {
   const userConfigPath =
     options.userConfigPath ?? resolveUserConfigPath(env, home);
 
+  if (argv[0] === "migrate-session") {
+    try {
+      const { withPaths, rest } = extractWithFlags(argv.slice(1));
+      if (rest.length === 1 && ["--help", "-h"].includes(rest[0])) {
+        stdout.write("Usage: playbook migrate-session <id> [--with <path>]...\n");
+        return { code: 0 };
+      }
+      if (rest.length !== 1 || !SESSION_ID_PATTERN.test(rest[0])) throw new Error("expected one canonical session UUID: playbook migrate-session <id> [--with <path>]...");
+      const sessionsDir = options.sessionStore === undefined ? resolveLaunchSessionsDir({
+        userConfigPath, overlayPaths: withPaths, env, homeDir: home,
+        ...(options.sessionsDir !== undefined ? { sessionsDir: options.sessionsDir } : {}),
+        preparePrimary: false,
+      }) : options.sessionStore.sessionsDir;
+      const store = options.sessionStore ?? createCaptainSessionStore({ sessionsDir, env, homeDir: home });
+      const result = await store.migrate(rest[0]);
+      stdout.write(`playbook: ${result.migrated ? 'migrated' : 'already portable'} session ${rest[0]} in ${sessionsDir} (${result.manifest.state})\n`);
+      if (result.manifest.state === 'history-only') stderr.write(`playbook: ${result.manifest.reason}\n`);
+      for (const reason of result.reasons) stderr.write(`playbook: ${reason}\n`);
+      return { code: 0 };
+    } catch (error) {
+      stderr.write(`playbook migrate-session: ${errorMessage(error)}\n`);
+      return { code: COMPOSITION_FAILURE_EXIT_CODE };
+    }
+  }
+
   // PBCLI-18: `playbook run ...` is the non-interactive presentation of the
   // same generic-config Captain session. It never resolves or launches the
   // tmux presenter, but it receives the launch inputs shared with this host.
@@ -229,6 +254,7 @@ export async function runPlaybookCli(options = {}) {
     interactiveArgs.cwd ?? ".",
   );
   let resolvedSessionsDir;
+  let migrateDefaultStore = false;
   if (options.sessionStore === undefined) {
     try {
       resolvedSessionsDir = resolveLaunchSessionsDir({
@@ -240,6 +266,7 @@ export async function runPlaybookCli(options = {}) {
           ? { sessionsDir: options.sessionsDir }
           : {}),
         preparePrimary: interactiveArgs.sessionId === undefined,
+        onDefault: () => { migrateDefaultStore = !(typeof env.SPEX_HOME === 'string' && env.SPEX_HOME.trim() !== ''); },
         onNotice: (line) => stderr.write(line),
       });
       // PBCLI-78: listing validates the locator but never consumes the store.
@@ -258,7 +285,10 @@ export async function runPlaybookCli(options = {}) {
   let selectedRecord;
   if (interactiveArgs.sessionId !== undefined) {
     try {
-      store = createInteractiveStore(options, env, home, resolvedSessionsDir);
+      store = await createInteractiveStore(options, env, home, resolvedSessionsDir, migrateDefaultStore, stderr);
+      await store.prepare();
+      const validation = await store.validate(interactiveArgs.sessionId);
+      if (!validation.resumable) throw new Error(validation.reasons.join('; '));
       selectedRecord = validateCaptainSessionRecord(
         await store.read(interactiveArgs.sessionId),
       );
@@ -276,6 +306,7 @@ export async function runPlaybookCli(options = {}) {
         const recoveryLease = await store.acquire(interactiveArgs.sessionId);
         let recoveryError;
         try {
+          await recoveryLease.assertContinuable();
           selectedRecord = validateCaptainSessionRecord(
             await recoveryLease.recoverUnresolvedEffectAbandonment(),
           );
@@ -405,7 +436,7 @@ export async function runPlaybookCli(options = {}) {
   }
 
   try {
-    store ??= createInteractiveStore(options, env, home, resolvedSessionsDir);
+    store ??= await createInteractiveStore(options, env, home, resolvedSessionsDir, migrateDefaultStore, stderr);
   } catch (error) {
     stderr.write(`playbook: ${errorMessage(error)}\n`);
     return { code: COMPOSITION_FAILURE_EXIT_CODE };
@@ -743,8 +774,8 @@ function optionValue(argv, index, name) {
   return value;
 }
 
-function createInteractiveStore(options, env, home, sessionsDir) {
-  return (
+async function createInteractiveStore(options, env, home, sessionsDir, migrateDefault, stderr) {
+  const store = (
     options.sessionStore ??
     createCaptainSessionStore({
       env,
@@ -756,6 +787,12 @@ function createInteractiveStore(options, env, home, sessionsDir) {
         : {}),
     })
   );
+  if (migrateDefault && options.sessionStore === undefined) {
+    const migrated = await store.migrateLegacyDefault();
+    if (migrated.migrated.length > 0) stderr.write(`playbook: migrated ${migrated.migrated.length} sessions from ${migrated.sourceDir}\n`);
+    for (const skipped of migrated.skipped) stderr.write(`playbook: preserved legacy session ${skipped.sessionId} in ${migrated.sourceDir}: ${skipped.reason}\n`);
+  }
+  return store;
 }
 
 async function writeStream(stream, text, signal) {
@@ -887,6 +924,7 @@ function helpText({
     "  playbook run (--continue | --session <id>) [reply]",
     "  playbook run --session <id> --retry-uncertain",
     "  playbook run --session <id> --discard-uncertain",
+    "  playbook migrate-session <id> [--with <path>]...",
     "  playbook --help",
     "",
     `Default config: ${userConfigPath}`,