@sublang/playbook 8.0.0 → 9.0.0

package/README.md

@@ -81,7 +81,7 @@ playbook run --session 4f2c0000-0000-4000-8000-000000009ab1 "continue"
 
 `playbook run` prints the one Boss-visible Captain reply to stdout and operational status to stderr; CODE and DECIDE can complete their nested REVIEW calls there too.
 
-See [Using the CLI](docs/cli.md) for flags and durable continuation, [Configuring agents](docs/configuration.md) for the shared lineup, [Embedding](docs/embedding.md) for custom hosts, and the [changelog](CHANGELOG.md) for releases.
+See [Using the CLI](docs/cli.md) for flags and durable continuation, [Configuring agents](docs/configuration.md) for the shared lineup, [Embedding](docs/embedding.md) for custom hosts, and the [changelog](https://github.com/sublang-ai/playbook/blob/main/CHANGELOG.md) for releases.
 
 ## Create your own playbook
 
@@ -129,8 +129,8 @@ pnpm playbook   # drive a Boss turn against the source tree
 ```
 
 Playbook is itself spec-driven: the compiler phases are specs in [`slc/`](slc), and the reference playbooks are regenerated from their prose sources.
-Edit a source, regenerate its GEARS, FSM, and runtime artifacts, sync the tests and downstream specs until `pnpm test` passes, and commit with co-author trailers per [`specs/packages/git.md`](specs/packages/git.md).
-The gears↔FSM contract ([the playbook package](specs/packages/playbook.md)) and runtime contract ([the playbook-runtime package](specs/packages/playbook-runtime.md)) are pinned in [`specs/packages/`](specs/packages) and verified by the test suite.
+Edit a source, regenerate its GEARS, FSM, and runtime artifacts, sync the tests and downstream specs until `pnpm test` passes, and commit with co-author trailers per [`specs/packages/git.md`](https://github.com/sublang-ai/playbook/blob/main/specs/packages/git.md).
+The gears↔FSM contract ([the playbook package](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook.md)) and runtime contract ([the playbook-runtime package](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook-runtime.md)) are pinned in [`specs/packages/`](https://github.com/sublang-ai/playbook/tree/main/specs/packages) and verified by the test suite.
 
 ## License
 

package/docs/cli.md

@@ -18,7 +18,7 @@ Each adapter is backed by a vendor runtime that installing
 agent stack you did not ask for. Which versions each adapter supports
 is [cligent](https://github.com/sublang-ai/cligent)'s knowledge and
 ships with it
-([DR-027](../specs/decisions/027-runtime-compatibility-from-cligent.md));
+([DR-027](https://github.com/sublang-ai/playbook/blob/main/specs/decisions/027-runtime-compatibility-from-cligent.md));
 the commands below install the latest, which cligent accepts from its
 supported floor up. Install the SDKs your config names, each as its
 own top-level install root:
@@ -45,7 +45,7 @@ finds a bare specifier by walking *up* from there — which reaches the
 install prefix's own `node_modules`, but never into a sibling package's
 subtree. An SDK that landed inside some other package is invisible to
 the adapter even though it is on disk
-([DR-026](../specs/decisions/026-optional-adapter-sdks.md)).
+([DR-026](https://github.com/sublang-ai/playbook/blob/main/specs/decisions/026-optional-adapter-sdks.md)).
 
 Both surfaces check this before doing any work: a declared adapter
 whose runtime is not loadable — or is installed below the version
@@ -54,7 +54,7 @@ runtime is reported as not installed; a stale one with its installed
 and required versions, never as absent. Either way the remedy printed
 is cligent's pinned install, `npm install -g <package>@<version>`, so
 following it cannot install a version the gate refuses again
-([[playbook-cli-40](../specs/packages/playbook-cli.md#playbook-cli-40)]).
+([[playbook-cli-40](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook-cli.md#playbook-cli-40)]).
 
 ## Interactive
 
@@ -98,8 +98,8 @@ later signals use native client detach or termination semantics and do not
 retire the pane child's session. Only `--config` and composed
 `--theme-diagnostics` use the stock subprocess boundary: those forms mirror
 its exit status or signal and exit `127` when it cannot be spawned
-([[playbook-cli-1](../specs/packages/playbook-cli.md#playbook-cli-1)],
-[[playbook-cli-2](../specs/packages/playbook-cli.md#playbook-cli-2)]).
+([[playbook-cli-1](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook-cli.md#playbook-cli-1)],
+[[playbook-cli-2](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook-cli.md#playbook-cli-2)]).
 
 ### Running a Boss turn
 
@@ -118,8 +118,8 @@ currently offers. It never does the specialized work itself, and a
 conversational turn — including a progress or status question — leaves
 the engagement, its parked state, and any pending player question
 untouched
-([[playbook-captain-1](../specs/packages/playbook-captain.md#playbook-captain-1)],
-[[playbook-captain-2](../specs/packages/playbook-captain.md#playbook-captain-2)]).
+([[playbook-captain-1](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook-captain.md#playbook-captain-1)],
+[[playbook-captain-2](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook-captain.md#playbook-captain-2)]).
 
 The current CODE, REVIEW, and DECIDE workflows take their deterministic
 initial event from the selecting Boss turn. CODE and DECIDE then call REVIEW
@@ -131,16 +131,16 @@ identical. When a player surfaces a
 clarifying question the FSM parks, the pane shows the question, and a
 judge classifies your next turn as its reply or a fresh directive that
 abandons it
-([[playbook-runtime-2](../specs/packages/playbook-runtime.md#playbook-runtime-2)]).
+([[playbook-runtime-2](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook-runtime.md#playbook-runtime-2)]).
 
 The Captain pane shows start/stop/finished status with `◇` lines and
 streams progress with captain-speech classification and questions
-([[playbook-runtime-3](../specs/packages/playbook-runtime.md#playbook-runtime-3)]), while player
+([[playbook-runtime-3](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook-runtime.md#playbook-runtime-3)]), while player
 prompts ride their own panes. A turn that actually did something ends
 with one Captain reply summarizing what changed, composed only from that
 turn's reported outcome; a turn that changed nothing ends with an
 ordinary reply and no saved-counts line
-([[playbook-captain-19](../specs/packages/playbook-captain.md#playbook-captain-19)]).
+([[playbook-captain-19](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook-captain.md#playbook-captain-19)]).
 
 ## Headless
 
@@ -182,7 +182,7 @@ Captain reply. Argument, config, catalog, readiness, or pre-turn setup errors
 exit `1`; a started-turn, persistence, lease-release, or presentation failure
 exits `2` with stdout empty. SIGINT, SIGTERM, and SIGHUP preserve the
 uncertain boundary, withhold stdout, and are re-raised after lease retirement
-([[playbook-cli-18](../specs/packages/playbook-cli.md#playbook-cli-18)]).
+([[playbook-cli-18](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook-cli.md#playbook-cli-18)]).
 
 The former positional `<from>`, `resume`, `--player`, `--captain`,
 `--option`, `--cwd`, `--last`, run-only `--config`, and top-level `run:`
@@ -221,8 +221,8 @@ the primary config file. Before either front end imports a configured
 filesystem registry, the shared launcher checks whether that module can
 resolve `xstate` and `@sublang/playbook/xstate-runtime`. When needed, it
 creates engine symlinks beside the module and prints one provisioning line
-([[playbook-cli-36](../specs/packages/playbook-cli.md#playbook-cli-36)],
-[DR-024](../specs/decisions/024-runtime-engine-provisioning.md)).
+([[playbook-cli-36](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook-cli.md#playbook-cli-36)],
+[DR-024](https://github.com/sublang-ai/playbook/blob/main/specs/decisions/024-runtime-engine-provisioning.md)).
 
 A directory where both imports already resolve is untouched, and
 `--no-provision` disables new links for either fresh front end. If the
@@ -261,8 +261,8 @@ current `model` and `effort` selections apply to the next call, including an
 explicit boolean `false` provider-default reset. The retained provider token
 is never silently replaced by a fresh conversation if that selection is not
 supported
-([[playbook-cli-22](../specs/packages/playbook-cli.md#playbook-cli-22)],
-[DR-032](../specs/decisions/032-explicit-roles-session-players.md)).
+([[playbook-cli-22](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook-cli.md#playbook-cli-22)],
+[DR-032](https://github.com/sublang-ai/playbook/blob/main/specs/decisions/032-explicit-roles-session-players.md)).
 
 ### Recovering an uncertain turn
 

package/docs/configuration.md

@@ -30,7 +30,7 @@ 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](../specs/decisions/021-inline-agent-settings.md)). Dots in a
+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.
@@ -91,7 +91,7 @@ playbooks:
 The current bundled workflows accept no workflow-specific options.
 Each role's per-call prompt names its current `model`, else its player's
 `adapter`
-([[playbook-runtime-4](../specs/packages/playbook-runtime.md#playbook-runtime-4)]),
+([[playbook-runtime-4](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook-runtime.md#playbook-runtime-4)]),
 so commit trailers credit the concrete model rather than the adapter
 family.
 
@@ -160,7 +160,7 @@ instead of doing the work itself. Claude and Gemini enforce that 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](../specs/decisions/013-routing-only-captain-control.md) A1).
+([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.
 
 Adapter readiness is intentionally light: `claude` is ready with local
@@ -203,7 +203,7 @@ playbooks:
 ```
 
 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)]).
+`tmux-play` ([[playbook-cli-25](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook-cli.md#playbook-cli-25)]).
 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
@@ -250,6 +250,11 @@ playbooks:
 playbook run "/my-workflow perform the task"
 ```
 
+Importing a `.ts` registry uses Node's native type stripping, available
+unflagged on Node 22.18+ and 23.6+; on the older Node versions this
+package supports (>= 20.6), compile the registry and point `from` at the
+emitted `.js` module instead.
+
 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.
@@ -318,9 +323,9 @@ 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)]).
+cannot be continued by the new host ([[playbook-cli-19](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook-cli.md#playbook-cli-19)],
+[[playbook-cli-22](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook-cli.md#playbook-cli-22)],
+[[playbook-cli-28](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook-cli.md#playbook-cli-28)]).
 
 ## Migrating from `profiles`
 
@@ -334,7 +339,7 @@ do by hand.
 
 For a one-off, pass a raw `tmux-play` config explicitly. This bypasses
 the seed, composition, and readiness gate, forwarding arguments to
-`tmux-play` verbatim ([[playbook-cli-1](../specs/packages/playbook-cli.md#playbook-cli-1)]):
+`tmux-play` verbatim ([[playbook-cli-1](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook-cli.md#playbook-cli-1)]):
 
 ```sh
 playbook --config ./tmux-play.config.yaml

package/docs/embedding.md

@@ -9,7 +9,7 @@ app) is another. This guide shows how to wire a playbook runtime into
 your own host.
 
 > **Release note:** this guide targets the current semver-stable six-port
-> contract; see the [CHANGELOG](../CHANGELOG.md) for migration details.
+> contract; see the [CHANGELOG](https://github.com/sublang-ai/playbook/blob/main/CHANGELOG.md) for migration details.
 
 ## The runtime contract
 
@@ -31,6 +31,11 @@ nested-playbook bridge.
 
 ## Constructing a runtime against your own ports
 
+`p-queue` is your host's own dependency here — declare it in your
+application's `dependencies` (the same library `@sublang/playbook` itself
+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 type {
@@ -190,7 +195,7 @@ Boss-visible status text. Because trace observers do receive opaque resume
 tokens, persisted traces should be protected as sensitive data.
 
 See
-[`code.playbook.test.ts`](../reference/sdlc/code.playbook/code.playbook.test.ts)
+[`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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sublang/playbook",
-  "version": "8.0.0",
+  "version": "9.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",

package/reference/sdlc/captain.playbook/captain.playbook.js

@@ -33,7 +33,7 @@
 //                controller-port submission, and status formatting.
 // Compat:        spec.compat = { artifactSchema: 2, runtimeAbi: 1 }
 //                (DR-022; checked at construction by the loading engine).
-import { createXStatePlaybookRuntime, defaultComposeCaptainPrompt, normalizeError, normalizeErrorCompact, parseJudgeJson, snapshotJsonValue, RUNTIME_ABI, } from '../../../src/xstate-runtime.js';
+import { createXStatePlaybookRuntime, defaultComposeCaptainPrompt, normalizeError, normalizeErrorCompact, parseJudgeJson, snapshotJsonValue, } from '../../../src/xstate-runtime.js';
 import { captainMachine, } from './captain.fsm.js';
 function assertNonEmptyString(value, label) {
     if (typeof value !== 'string' || value.trim().length === 0) {
@@ -516,7 +516,11 @@ export const _internal = {
 // describe/apply control surface — lives in @sublang/playbook/xstate-runtime.
 const runtimeSpec = {
     label: 'CAPTAIN',
-    compat: { artifactSchema: 2, runtimeAbi: RUNTIME_ABI },
+    // DR-022 / slc/link.md: the declaration carries the value current at link
+    // time — a literal, never the loading engine's RUNTIME_ABI self-report,
+    // which would follow whatever engine loads the module and make the
+    // factory's skew check compare that engine with itself.
+    compat: { artifactSchema: 2, runtimeAbi: 1 },
     snapshotOptions: snapshotCaptainOptions,
     machineInput: (options) => ({ enabledPlaybooks: options.enabledPlaybooks }),
     classifyBossText: (text, ports, signal, snapshotOrState, boundary, options) => classifyControllerTurn(text, ports, signal, snapshotOrState, boundary, options),
@@ -543,8 +547,15 @@ const runtimeSpec = {
     ],
     statusesForState,
 };
-const createCaptainPlaybookRuntime = createXStatePlaybookRuntime(captainMachine, runtimeSpec);
+// DR-022's compat check fails fast at factory construction. The Captain is
+// statically imported by the shell and both CLI front ends, so constructing
+// here at module evaluation would turn a future compat mismatch into an
+// uncaught ESM-load error that takes even `--help` down; constructing on
+// the first runtime request keeps the failure inside the caught
+// host-construction boundary that owes the Boss a setup diagnostic.
+let createCaptainPlaybookRuntime;
 export function createPlaybookRuntime(options) {
+    createCaptainPlaybookRuntime ??= createXStatePlaybookRuntime(captainMachine, runtimeSpec);
     return createCaptainPlaybookRuntime(options);
 }
 const factory = createPlaybookRuntime;

package/reference/sdlc/captain.playbook/captain.playbook.ts

@@ -41,7 +41,6 @@ import {
   normalizeErrorCompact,
   parseJudgeJson,
   snapshotJsonValue,
-  RUNTIME_ABI,
   type PlaybookActorOutput,
   type PlaybookCaptainInput,
   type ScheduledStatus,
@@ -798,7 +797,11 @@ export const _internal = {
 // describe/apply control surface — lives in @sublang/playbook/xstate-runtime.
 const runtimeSpec: XStatePlaybookRuntimeSpec<ValidatedCaptainOptions> = {
   label: 'CAPTAIN',
-  compat: { artifactSchema: 2, runtimeAbi: RUNTIME_ABI },
+  // DR-022 / slc/link.md: the declaration carries the value current at link
+  // time — a literal, never the loading engine's RUNTIME_ABI self-report,
+  // which would follow whatever engine loads the module and make the
+  // factory's skew check compare that engine with itself.
+  compat: { artifactSchema: 2, runtimeAbi: 1 },
   snapshotOptions: snapshotCaptainOptions,
   machineInput: (options) => ({ enabledPlaybooks: options.enabledPlaybooks }),
   classifyBossText: (text, ports, signal, snapshotOrState, boundary, options) =>
@@ -834,12 +837,23 @@ const runtimeSpec: XStatePlaybookRuntimeSpec<ValidatedCaptainOptions> = {
   statusesForState,
 };
 
-const createCaptainPlaybookRuntime: PlaybookRuntimeFactory<ValidatedCaptainOptions> =
-  createXStatePlaybookRuntime(captainMachine, runtimeSpec);
+// DR-022's compat check fails fast at factory construction. The Captain is
+// statically imported by the shell and both CLI front ends, so constructing
+// here at module evaluation would turn a future compat mismatch into an
+// uncaught ESM-load error that takes even `--help` down; constructing on
+// the first runtime request keeps the failure inside the caught
+// host-construction boundary that owes the Boss a setup diagnostic.
+let createCaptainPlaybookRuntime:
+  | PlaybookRuntimeFactory<ValidatedCaptainOptions>
+  | undefined;
 
 export function createPlaybookRuntime(
   options: PlaybookRuntimeOptions,
 ): PlaybookRuntime {
+  createCaptainPlaybookRuntime ??= createXStatePlaybookRuntime(
+    captainMachine,
+    runtimeSpec,
+  );
   return createCaptainPlaybookRuntime(options);
 }
 

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

@@ -202,7 +202,7 @@ export declare const codingMachine: import("xstate").StateMachine<CodingContext,
 } | {
     type: "resumesIrTask";
     params: unknown;
-}, never, "done" | "failed" | "awaitBossReply" | "ready" | "runFirstPhase" | "reviewFirstCommit" | "runIrTask" | "reviewIrTask", string, CodingInput, {
+}, never, "done" | "failed" | "awaitBossReply" | "ready" | "runFirstPhase" | "reviewFirstCommit" | "runIrTask" | "reviewIrTask" | "reportedReviewFailure", string, CodingInput, {
     readonly status: "complete";
     /** Exact identity of the latest CODE-owned commit. */
     readonly lastCodeCommit: string;
@@ -239,6 +239,9 @@ export declare const codingMachine: import("xstate").StateMachine<CodingContext,
         readonly failed: {
             id: "failed";
         };
+        readonly reportedReviewFailure: {
+            id: "reportedReviewFailure";
+        };
         readonly done: {
             id: "done";
         };

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

@@ -53,6 +53,7 @@ const STATE_DESCRIPTIONS = {
     reviewIrTask: 'The REVIEW playbook is checking the latest task commit.',
     awaitBossReply: 'Waiting for Boss to answer Coder.',
     failed: 'The coding workflow failed and is waiting for a new coding intent.',
+    reportedReviewFailure: 'The coding workflow reported a REVIEW failure and the last code-owned commit.',
     done: 'The coding workflow completed after REVIEW found no unsettled findings.',
 };
 function playbookMeta(stateId, role) {
@@ -530,14 +531,14 @@ export const codingMachine = machineSetup.createMachine({
                         target: 'runIrTask',
                     },
                     {
-                        target: 'done',
+                        target: 'reportedReviewFailure',
                         actions: 'completeWithInvalidReviewOutput',
                     },
                 ],
                 onError: [
                     {
                         guard: 'authoredReviewFailure',
-                        target: 'done',
+                        target: 'reportedReviewFailure',
                         actions: 'completeWithReviewFailure',
                     },
                     { target: 'failed', actions: 'rememberActorError' },
@@ -619,14 +620,14 @@ export const codingMachine = machineSetup.createMachine({
                         actions: 'completeSuccessfully',
                     },
                     {
-                        target: 'done',
+                        target: 'reportedReviewFailure',
                         actions: 'completeWithInvalidReviewOutput',
                     },
                 ],
                 onError: [
                     {
                         guard: 'authoredReviewFailure',
-                        target: 'done',
+                        target: 'reportedReviewFailure',
                         actions: 'completeWithReviewFailure',
                     },
                     { target: 'failed', actions: 'rememberActorError' },
@@ -670,6 +671,12 @@ export const codingMachine = machineSetup.createMachine({
                 START_CODE: { target: 'runFirstPhase', actions: 'startCoding' },
             },
         },
+        reportedReviewFailure: {
+            id: 'reportedReviewFailure',
+            description: STATE_DESCRIPTIONS.reportedReviewFailure,
+            meta: playbookMeta('reportedReviewFailure'),
+            type: 'final',
+        },
         done: {
             id: 'done',
             description: STATE_DESCRIPTIONS.done,

package/reference/sdlc/code.playbook/code.fsm.ts

@@ -202,6 +202,8 @@ const STATE_DESCRIPTIONS = {
   reviewIrTask: 'The REVIEW playbook is checking the latest task commit.',
   awaitBossReply: 'Waiting for Boss to answer Coder.',
   failed: 'The coding workflow failed and is waiting for a new coding intent.',
+  reportedReviewFailure:
+    'The coding workflow reported a REVIEW failure and the last code-owned commit.',
   done: 'The coding workflow completed after REVIEW found no unsettled findings.',
 } as const;
 
@@ -768,14 +770,14 @@ export const codingMachine = machineSetup.createMachine({
             target: 'runIrTask',
           },
           {
-            target: 'done',
+            target: 'reportedReviewFailure',
             actions: 'completeWithInvalidReviewOutput',
           },
         ],
         onError: [
           {
             guard: 'authoredReviewFailure',
-            target: 'done',
+            target: 'reportedReviewFailure',
             actions: 'completeWithReviewFailure',
           },
           { target: 'failed', actions: 'rememberActorError' },
@@ -857,14 +859,14 @@ export const codingMachine = machineSetup.createMachine({
             actions: 'completeSuccessfully',
           },
           {
-            target: 'done',
+            target: 'reportedReviewFailure',
             actions: 'completeWithInvalidReviewOutput',
           },
         ],
         onError: [
           {
             guard: 'authoredReviewFailure',
-            target: 'done',
+            target: 'reportedReviewFailure',
             actions: 'completeWithReviewFailure',
           },
           { target: 'failed', actions: 'rememberActorError' },
@@ -908,6 +910,12 @@ export const codingMachine = machineSetup.createMachine({
         START_CODE: { target: 'runFirstPhase', actions: 'startCoding' },
       },
     },
+    reportedReviewFailure: {
+      id: 'reportedReviewFailure',
+      description: STATE_DESCRIPTIONS.reportedReviewFailure,
+      meta: playbookMeta('reportedReviewFailure'),
+      type: 'final',
+    },
     done: {
       id: 'done',
       description: STATE_DESCRIPTIONS.done,

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

@@ -9,7 +9,7 @@
 // Adjudication:  LLM judge per player state; coderOutput is carried verbatim
 // Nested call:   literal review target through the shared bridge
 // Compat:        artifact schema 2 / runtime ABI 1
-import { RUNTIME_ABI, createXStatePlaybookRuntime, snapshotJsonValue, } from '@sublang/playbook/xstate-runtime';
+import { createXStatePlaybookRuntime, snapshotJsonValue, } from '@sublang/playbook/xstate-runtime';
 import { codingMachine, } from './code.fsm.js';
 const OPTION_KEYS = new Set(['runResults']);
 const PLACEHOLDER = /<(#|[A-Za-z_$][A-Za-z0-9_$-]*)>/g;
@@ -81,9 +81,20 @@ export const _internal = {
 };
 const runtimeSpec = {
     label: 'CODE',
-    compat: { artifactSchema: 2, runtimeAbi: RUNTIME_ABI },
+    // DR-022 / slc/link.md: the declaration carries the value current at link
+    // time — a literal, never the loading engine's RUNTIME_ABI self-report,
+    // which would follow whatever engine loads the module and make the
+    // factory's skew check compare that engine with itself.
+    compat: { artifactSchema: 2, runtimeAbi: 1 },
     snapshotOptions: snapshotCodeOptions,
-    entryEvent: { type: 'START_CODE', textField: 'callerInput' },
+    entryEvent: {
+        type: 'START_CODE',
+        textField: 'callerInput',
+        // `startCoding` copies the entry text here, so the failure-state retry
+        // reads it back from the persisted machine snapshot and survives a
+        // continued session (DR-034).
+        contextField: 'callerInput',
+    },
     roleStates: {
         runFirstPhase: {
             role: 'coder',

package/reference/sdlc/code.playbook/code.playbook.ts

@@ -11,7 +11,6 @@
 // Compat:        artifact schema 2 / runtime ABI 1
 
 import {
-  RUNTIME_ABI,
   createXStatePlaybookRuntime,
   snapshotJsonValue,
   type PlaybookPlayerInput,
@@ -168,9 +167,20 @@ export const _internal = {
 
 const runtimeSpec = {
   label: 'CODE',
-  compat: { artifactSchema: 2, runtimeAbi: RUNTIME_ABI },
+  // DR-022 / slc/link.md: the declaration carries the value current at link
+  // time — a literal, never the loading engine's RUNTIME_ABI self-report,
+  // which would follow whatever engine loads the module and make the
+  // factory's skew check compare that engine with itself.
+  compat: { artifactSchema: 2, runtimeAbi: 1 },
   snapshotOptions: snapshotCodeOptions,
-  entryEvent: { type: 'START_CODE', textField: 'callerInput' },
+  entryEvent: {
+    type: 'START_CODE',
+    textField: 'callerInput',
+    // `startCoding` copies the entry text here, so the failure-state retry
+    // reads it back from the persisted machine snapshot and survives a
+    // continued session (DR-034).
+    contextField: 'callerInput',
+  },
   roleStates: {
     runFirstPhase: {
       role: 'coder',

package/reference/sdlc/code.playbook/playbook-captain.js

@@ -126,6 +126,34 @@ function stateDigestLine(state, description) {
         digestLine `status ${state.status}`,
     ].join('; ');
 }
+// CAPTAIN-5's mirrored ledger member holds the runtime snapshot's
+// pending-question projection — entries of `{ questionId, asker, question,
+// sourceItem }` — never a raw telemetry payload: the linked runtime's state
+// telemetry carries the singular full-context question, whose extra
+// runtime-internal fields (`resumeStateId`) fail the durable snapshot's
+// leaf-projection equality (CAPTAIN-41) and with it headless settlement.
+function mirroredBossQuestions(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    const entries = Array.isArray(value) ? value : [value];
+    return entries.map((entry) => {
+        if (typeof entry !== 'object' || entry === null)
+            return entry;
+        const record = entry;
+        const projected = {};
+        if (record.questionId !== undefined) {
+            projected.questionId = record.questionId;
+        }
+        if (record.asker !== undefined)
+            projected.asker = record.asker;
+        if (record.question !== undefined)
+            projected.question = record.question;
+        if (record.sourceItem !== undefined) {
+            projected.sourceItem = record.sourceItem;
+        }
+        return projected;
+    });
+}
 function pendingQuestionLines(pending) {
     const list = Array.isArray(pending)
         ? pending
@@ -1491,8 +1519,7 @@ export function createPlaybookCaptainShell(options, deps = {}) {
             }
         }
         if (leafFrame() === frame) {
-            pendingBossQuestions =
-                record.pendingBossQuestions ?? record.pendingBossQuestion;
+            pendingBossQuestions = mirroredBossQuestions(record.pendingBossQuestions ?? record.pendingBossQuestion);
             lastError = normalizeErrorCompact(record.lastError);
             if (state.quiescent && state.tags.includes('playbook.parked')) {
                 await setMode('engaged.parked', `sub-runtime:${state.stateId ?? 'structured'}`);
@@ -2308,7 +2335,7 @@ export function createPlaybookCaptainShell(options, deps = {}) {
                 // runtime publishes before disposal removes the frame. The opaque run
                 // output remains runtime-to-runtime data and never becomes Captain
                 // evidence (CAPPLAY-10).
-                activeTurn?.settlementFacts.push(rootCompletionFact(frame));
+                activeTurn?.settlementFacts.push(rootCompletionFact(frame, result));
                 await runEffect(() => disposeStack('final'));
             }
             return;
@@ -3200,10 +3227,10 @@ export function createPlaybookCaptainShell(options, deps = {}) {
     // -------------------------------------------------------------------------
     // The controller port (DR-029): host validation is the sole effector.
     // -------------------------------------------------------------------------
-    // The leaf's published state description, read from its control view the
-    // same way the digest reads it. A leaf without the pair — or one whose view
-    // cannot be read at this moment — publishes none, and the summary then says
-    // so instead of falling back to the state id.
+    // The legacy state-description channel, read from the live control view the
+    // same way the digest reads it. DR-037 makes the terminal result authoritative
+    // for completion; this remains only for an older runtime that omits the new
+    // optional member.
     const leafStateDescription = (frame) => {
         if (typeof frame.runtime.describe !== 'function')
             return undefined;
@@ -3214,9 +3241,16 @@ export function createPlaybookCaptainShell(options, deps = {}) {
             return undefined;
         }
     };
-    const rootCompletionFact = (frame) => {
-        const published = leafStateDescription(frame);
-        const description = published === undefined ? '' : compactEvidence(published);
+    const rootCompletionFact = (frame, result) => {
+        const returned = result.stateDescription === undefined
+            ? ''
+            : compactEvidence(result.stateDescription);
+        const legacy = returned === '' ? leafStateDescription(frame) : undefined;
+        const description = returned !== ''
+            ? returned
+            : legacy === undefined
+                ? ''
+                : compactEvidence(legacy);
         return description === ''
             ? `${frameLabel(frame)} completed; its runtime published no result description.`
             : `${frameLabel(frame)} completed; its runtime-published result meaning was ${quoteEvidence(description)}.`;