@sublang/playbook 3.1.0 → 5.0.0

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

@@ -1,103 +1,193 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
 //
-// slc link artifact
-// FSM path: ./captain.fsm.ts
-// Player binding: none (no delegated-player states)
-// Adjudication strategy: LLM-judge per Captain state
-// Boss-event mapping: deterministic ready entry; LLM-judge classification otherwise
-
-import PQueue from 'p-queue';
-import { createActor, fromPromise, type ActorRefFrom } from 'xstate';
+// Generated by slc/link.md (FSM-to-Runtime linker).
+// Source FSM:    ./captain.fsm.ts
+// Player bind:   none (the session Captain declares no player behavior)
+// Boss event:    deterministic controller entry (slc/link.md §Boss-event
+//                mapping): every turn maps from the exact Boss text and the
+//                host's command-parse resolution supplied through the linked
+//                options' controller port — BOSS_TURN / PARSED_RESPOND /
+//                PARSED_ACTION / SHUTDOWN — with no classifier judge call.
+// Captain calls: hidden controller form (slc/link.md §Captain adjudication,
+//                DR-029): decision and closing-reply calls run
+//                `{ visibility: 'hidden' }`; the host's session-Captain
+//                wrapper owns the durable-conversation resume selection and
+//                pins the returned token (the runtime requests
+//                `resume: false` as the typed placeholder and its traces
+//                carry no resume member). The decision reply is `{ action,
+//                … }` control JSON validated here against the declared
+//                decision-state contract — never adjudicated through a
+//                judge call and never Boss presentation; controller prose
+//                reaches Boss only as host-validated captain speech through
+//                the host's presentation seam (cligent
+//                `CaptainContext.emitReply`).
+// Contract:      types imported and re-exported from
+//                @sublang/playbook/runtime (slc/link.md §Output); the
+//                shared createXStatePlaybookRuntime factory from
+//                @sublang/playbook/xstate-runtime interprets the FSM
+//                (DR-019). This module carries only the Captain-specific
+//                spec: options validation (catalog + controller port),
+//                deterministic entry mapping, the controller captain-call
+//                strategy with its single corrective re-ask (CAPPLAY-18),
+//                controller-port submission, and status formatting.
+// Compat:        spec.compat = { artifactSchema: 1, runtimeAbi: 1 }
+//                (DR-022; checked at construction by the loading engine).
 
+import {
+  createXStatePlaybookRuntime,
+  defaultComposeCaptainPrompt,
+  normalizeError,
+  normalizeErrorCompact,
+  parseJudgeJson,
+  snapshotJsonValue,
+  RUNTIME_ABI,
+  type PlaybookActorOutput,
+  type PlaybookCaptainInput,
+  type ScheduledStatus,
+  type XStateCaptainStrategyRun,
+  type XStatePlaybookRuntimeSpec,
+} from '../../../src/xstate-runtime.js';
 import {
   captainMachine,
   type CaptainInput,
   type CaptainOutput,
+  type DecisionAction,
   type EnabledPlaybook,
-  type PlaybookInput,
+  type ParsedActingDecision,
+  type SettlementEvidence,
+  type SettlementReceiptEvidence,
 } from './captain.fsm.js';
-
 import type {
   CaptainCallOptions,
   CaptainResult,
   JsonValue,
+  NormalizedError,
+  PlayerCallOptions,
+  PlaybookCallRequest,
   PlaybookCallResult,
-  PlaybookPorts,
-  PlaybookRuntime,
-  PlaybookRuntimeFactory,
+  PlaybookCallStart,
+  PlaybookControlReceipt,
+  PlaybookControlView,
+  PlaybookPendingCall,
   PlaybookRunResult,
+  PlaybookRuntimeSnapshot,
   PlaybookSession,
   PlaybookState,
+  PlaybookStateValue,
   PlaybookTraceEvent,
-} from '../../../src/runtime.js';
-
-import {
-  assertJsonSafe,
-  combineAbortSignals,
-  createNestedPlaybookBridge,
-  normalizeError,
-  normalizePlaybookSnapshot,
-  snapshotJsonValue,
-  snapshotPlaybookSession,
-  validateCaptainResult,
-  waitForPlaybookQuiescence,
-} from '../../../src/xstate-runtime.js';
+  PlaybookTraceType,
+  PlaybookPorts,
+  PlaybookRuntime,
+  PlaybookRuntimeFactory,
+  PlayerResult,
+} from '@sublang/playbook/runtime';
 
+// Public contract re-exports (slc/link.md §Output): every linked playbook
+// shares the one contract definition from @sublang/playbook/runtime.
 export type {
   CaptainCallOptions,
   CaptainResult,
   JsonValue,
   NormalizedError,
+  PlayerCallOptions,
   PlaybookCallRequest,
   PlaybookCallResult,
   PlaybookCallStart,
-  PlaybookPorts,
+  PlaybookControlReceipt,
+  PlaybookControlView,
+  PlaybookPendingCall,
   PlaybookRunResult,
+  PlayerResult,
+  PlaybookPorts,
   PlaybookRuntime,
   PlaybookRuntimeFactory,
+  PlaybookRuntimeSnapshot,
   PlaybookSession,
   PlaybookState,
   PlaybookStateValue,
   PlaybookTraceEvent,
-  PlayerCallOptions,
-  PlayerResult,
-} from '../../../src/runtime.js';
+  PlaybookTraceType,
+};
 
-export interface PlaybookRuntimeOptions {
-  readonly enabledPlaybooks: readonly EnabledPlaybook[];
-}
+// Artifact-declared controller types (slc/link.md §PlaybookRuntime contract:
+// host-supplied port-shaped callbacks are linker-exposed option members whose
+// types the artifact itself declares, so `PlaybookPorts` stays six members).
+export type {
+  DecisionAction,
+  EnabledPlaybook,
+  ParsedActingDecision,
+  SettlementEvidence,
+  SettlementReceiptEvidence,
+};
 
-type RootActor = ActorRefFrom<typeof captainMachine>;
+/** One nonempty complete standalone request selected for `start` or `switch`. */
+export type CaptainControllerInput = string;
 
-type BossEvent =
-  | { readonly type: 'BOSS_INTENT'; readonly bossIntent: string }
-  | {
-      readonly type: 'BOSS_INTERRUPT';
-      readonly targetId: 'routing';
-      readonly bossIntent: string;
-    }
+/** One validated controller selection submitted through the port (DR-029). */
+export type CaptainControllerSelection =
+  | { readonly action: 'respond'; readonly text: string }
   | {
-      readonly type: 'BOSS_REPLY';
-      readonly answer: string;
-      readonly questionId?: string;
-    };
-
-type BossMapping = BossEvent | { readonly type: 'NO_ACTION' } | undefined;
+      readonly action: 'start' | 'switch';
+      readonly playbookId: string;
+      /** Complete standalone request synthesized from the remembered Boss conversation. */
+      readonly input: CaptainControllerInput;
+    }
+  | { readonly action: 'dismiss' }
+  | { readonly action: 'deliver' }
+  | { readonly action: 'runtime'; readonly actionId: string };
+
+/**
+ * The host's deterministic per-turn resolution (CAPTAIN-7 parse table):
+ * `undefined` sends the turn to the hidden decision call; `respond` routes
+ * the dedicated prose item; `action` injects the parse-resolved decision
+ * object; `shutdown` is the host teardown entry to the machine's one final
+ * state.
+ */
+export type CaptainParsedResolution =
+  | { readonly kind: 'respond' }
+  | { readonly kind: 'action'; readonly decision: ParsedActingDecision }
+  | { readonly kind: 'shutdown' };
+
+/**
+ * The host-supplied controller port (CAPPLAY-9, DR-029): one validated
+ * selection per Boss turn in, its settlement back as the only evidence of
+ * effects. The optional `resolveParsedTurn` member supplies the host's
+ * deterministic command-parse resolution for the entry mapping.
+ */
+export interface CaptainControllerPort {
+  submit(
+    selection: CaptainControllerSelection,
+    signal: AbortSignal,
+  ): Promise<SettlementEvidence>;
+  resolveParsedTurn?(text: string): CaptainParsedResolution | undefined;
+}
 
-type RuntimeSession = Omit<PlaybookSession, 'ports'> & {
-  readonly ports: PlaybookPorts;
-};
+export interface PlaybookRuntimeOptions {
+  readonly enabledPlaybooks: readonly EnabledPlaybook[];
+  /**
+   * The host-supplied controller port. Every Boss turn settles through it
+   * (CAPPLAY-9), so it is declared required. It was optional here only until
+   * the IR-036 task-4 shell rework landed; that rework has landed and the
+   * shell now supplies the port on every construction, so a declaration that
+   * still admitted its absence typechecked a runtime that cannot settle a
+   * single turn.
+   */
+  readonly controller: CaptainControllerPort;
+}
 
-const CAPTAIN_OPTIONS: CaptainCallOptions = {
-  visibility: 'visible',
-  resume: false,
-  allowedTools: [],
+/**
+ * The validated option record the engine carries. It differs from the public
+ * declaration in exactly one place: `controller` is optional here, because a
+ * construction from untyped JavaScript can still omit it and the shape has to
+ * describe what validation actually accepts. Where that ends is
+ * `requireControllerPort` — the first Boss turn, with a named error rather
+ * than a silent one.
+ */
+type ValidatedCaptainOptions = Omit<PlaybookRuntimeOptions, 'controller'> & {
+  readonly controller?: CaptainControllerPort;
 };
 
-const CONTINUATION_PREAMBLE =
-  'You previously paused this task to ask Boss a question; Boss has now replied. Continue the same task using the reply below.';
-
 function assertNonEmptyString(value: unknown, label: string): string {
   if (typeof value !== 'string' || value.trim().length === 0) {
     throw new TypeError(`${label} must be a non-empty string`);
@@ -113,95 +203,33 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return prototype === Object.prototype || prototype === null;
 }
 
-function omitUndefined<T extends Record<string, unknown>>(value: T): JsonValue {
-  const copy: Record<string, JsonValue> = {};
-  for (const [key, entry] of Object.entries(value)) {
-    if (entry !== undefined) {
-      assertJsonSafe(entry, key);
-      copy[key] = snapshotJsonValue(entry, key);
-    }
-  }
-  return snapshotJsonValue(copy);
-}
-
-function stableJson(value: unknown): string {
-  const json = snapshotJsonValue(value);
-  return JSON.stringify(sortJson(json));
-}
-
-function sortJson(value: JsonValue): JsonValue {
-  if (Array.isArray(value)) return Object.freeze(value.map((entry) => sortJson(entry)));
-  if (value && typeof value === 'object') {
-    const record = value as { readonly [key: string]: JsonValue };
-    const sorted: Record<string, JsonValue> = {};
-    for (const key of Object.keys(value).sort()) {
-      sorted[key] = sortJson(record[key]);
-    }
-    return Object.freeze(sorted);
-  }
-  return value;
-}
-
-function replacePlaceholders(template: string, replacements: ReadonlyMap<string, string>): string {
-  return template.replace(/<[^>\n]+>/g, (placeholder) => replacements.get(placeholder) ?? placeholder);
-}
-
-function continuationPrefix(input: {
-  readonly pendingBossQuestion?: { readonly question: string };
-  readonly bossReply?: string;
-}): string {
-  if (!input.pendingBossQuestion || !input.bossReply) return '';
-  return [
-    CONTINUATION_PREAMBLE,
-    '',
-    'Boss question:',
-    input.pendingBossQuestion.question,
-    '',
-    'Boss reply:',
-    input.bossReply,
-    '',
-    '',
-  ].join('\n');
-}
-
-export function composeCaptainPrompt(input: CaptainInput): string {
-  const replacements = new Map<string, string>();
-  replacements.set('<boss-intent>', input.bossIntent);
-  replacements.set('<enabled-playbooks>', stableJson(input.enabledPlaybooks));
-  if (input.remainingPlan !== undefined) {
-    replacements.set('<remaining-plan>', stableJson(input.remainingPlan));
-  }
-  if (input.completedCallResults !== undefined) {
-    replacements.set('<completed-call-results>', stableJson(input.completedCallResults));
-  }
-  return `${continuationPrefix(input)}${replacePlaceholders(input.prompt, replacements)}`;
-}
-
-export function composePlayerPrompt(input: {
-  readonly prompt: string;
-  readonly pendingBossQuestion?: { readonly question: string };
-  readonly bossReply?: string;
-}): string {
-  return `${continuationPrefix(input)}${input.prompt}`;
-}
-
-function validateEnabledPlaybooks(value: readonly EnabledPlaybook[]): readonly EnabledPlaybook[] {
+function validateEnabledPlaybooks(
+  value: unknown,
+): readonly EnabledPlaybook[] {
   if (!Array.isArray(value)) {
     throw new TypeError('enabledPlaybooks must be an array');
   }
   const ids = new Set<string>();
   return Object.freeze(
-    value.map((entry, index) => {
+    value.map((entry: unknown, index) => {
       if (!isRecord(entry)) {
         throw new TypeError(`enabledPlaybooks[${index}] must be an object`);
       }
       const keys = Object.keys(entry).sort();
       if (keys.join('\0') !== ['command', 'id', 'intent'].join('\0')) {
-        throw new TypeError(`enabledPlaybooks[${index}] must contain exactly id, command, and intent`);
+        throw new TypeError(
+          `enabledPlaybooks[${index}] must contain exactly id, command, and intent`,
+        );
       }
       const id = assertNonEmptyString(entry.id, `enabledPlaybooks[${index}].id`);
-      const command = assertNonEmptyString(entry.command, `enabledPlaybooks[${index}].command`);
-      const intent = assertNonEmptyString(entry.intent, `enabledPlaybooks[${index}].intent`);
+      const command = assertNonEmptyString(
+        entry.command,
+        `enabledPlaybooks[${index}].command`,
+      );
+      const intent = assertNonEmptyString(
+        entry.intent,
+        `enabledPlaybooks[${index}].intent`,
+      );
       if (ids.has(id)) {
         throw new TypeError(`enabledPlaybooks id ${id} is duplicated`);
       }
@@ -211,934 +239,609 @@ function validateEnabledPlaybooks(value: readonly EnabledPlaybook[]): readonly E
   );
 }
 
-function parseJsonObjectLoose(text: string): Record<string, unknown> | undefined {
-  const source = text;
-  for (let start = 0; start < source.length; start += 1) {
-    if (source[start] !== '{') continue;
-    const bounded = boundedJsonCandidate(source, start);
-    const candidates = bounded ? [bounded, bounded.replace(/,\s*([}\]])/g, '$1')] : [repairJsonSuffix(source.slice(start))];
-    for (const candidate of candidates) {
-      try {
-        const parsed: unknown = JSON.parse(candidate);
-        if (isRecord(parsed)) return parsed;
-      } catch {
-        // Try the next candidate at the same object boundary.
-      }
-    }
+function validateControllerPort(value: unknown): CaptainControllerPort {
+  if (value === null || typeof value !== 'object') {
+    throw new TypeError('options.controller must be an object');
   }
-  return undefined;
-}
-
-function boundedJsonCandidate(source: string, start: number): string | undefined {
-  let depth = 0;
-  let inString = false;
-  let escaped = false;
-  for (let index = start; index < source.length; index += 1) {
-    const char = source[index];
-    if (inString) {
-      if (escaped) escaped = false;
-      else if (char === '\\') escaped = true;
-      else if (char === '"') inString = false;
-      continue;
-    }
-    if (char === '"') inString = true;
-    else if (char === '{' || char === '[') depth += 1;
-    else if (char === '}' || char === ']') {
-      depth -= 1;
-      if (depth === 0) return source.slice(start, index + 1);
-    }
+  const record = value as Record<string, unknown>;
+  if (typeof record.submit !== 'function') {
+    throw new TypeError('options.controller.submit must be a function');
   }
-  return undefined;
-}
-
-function repairJsonSuffix(source: string): string {
-  let repaired = source.replace(/,\s*$/g, '');
-  let inString = false;
-  let escaped = false;
-  const stack: string[] = [];
-  for (const char of repaired) {
-    if (inString) {
-      if (escaped) escaped = false;
-      else if (char === '\\') escaped = true;
-      else if (char === '"') inString = false;
-      continue;
-    }
-    if (char === '"') inString = true;
-    else if (char === '{') stack.push('}');
-    else if (char === '[') stack.push(']');
-    else if (char === '}' || char === ']') stack.pop();
+  if (
+    record.resolveParsedTurn !== undefined &&
+    typeof record.resolveParsedTurn !== 'function'
+  ) {
+    throw new TypeError(
+      'options.controller.resolveParsedTurn must be a function when present',
+    );
   }
-  if (inString) repaired += '"';
-  while (stack.length > 0) repaired += stack.pop();
-  return repaired.replace(/,\s*([}\]])/g, '$1');
+  return value as CaptainControllerPort;
 }
 
-function requiredOutputFields(description: string): readonly string[] {
-  const marker = description.match(/Output shall include\s+(.+)$/);
-  if (!marker) return [];
-  const fields: string[] = [];
-  const seen = new Set<string>();
-  const regex = /`([^`]+)`/g;
-  let match: RegExpExecArray | null;
-  while ((match = regex.exec(marker[1])) !== null) {
-    const name = match[1].split(':', 1)[0]?.trim();
-    if (name && /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) && !seen.has(name)) {
-      seen.add(name);
-      fields.push(name);
-    }
-  }
-  return fields;
+function snapshotCaptainOptions(value: unknown): ValidatedCaptainOptions {
+  if (!isRecord(value)) {
+    throw new TypeError('Captain runtime options must be an object');
+  }
+  const allowed = new Set(['enabledPlaybooks', 'controller']);
+  for (const key of Object.keys(value)) {
+    if (!allowed.has(key)) {
+      throw new TypeError(`Captain runtime options.${key} is not declared`);
+    }
+  }
+  const enabledPlaybooks = validateEnabledPlaybooks(value.enabledPlaybooks);
+  const controller =
+    value.controller === undefined
+      ? undefined
+      : validateControllerPort(value.controller);
+  return Object.freeze({
+    enabledPlaybooks,
+    ...(controller === undefined ? {} : { controller }),
+  });
 }
 
-function makeJudgePrompt(input: CaptainInput, visibleText: string): string {
-  return [
-    'Adjudicate the direct Captain output for this FSM state.',
-    `State id: ${input.stateId}`,
-    `Source item: ${input.sourceItem}`,
-    '',
-    'Visible Captain output:',
-    visibleText,
-    '',
-    'Result keys and descriptions:',
-    ...Object.entries(input.result).map(([key, description]) => `- ${key}: ${description}`),
-    '',
-    'Return one JSON object with exactly one declared guard.',
-    'For direct Captain question or response guards, do not include question or response; the runtime injects the visible text.',
-  ].join('\n');
-}
+// ---------------------------------------------------------------------------
+// Deterministic controller entry mapping (slc/link.md §Boss-event mapping):
+// the exact Boss text rides the runtime-owned `bossText` field; the host's
+// parse resolution selects the hub entry arm; no classifier judge call runs.
+// ---------------------------------------------------------------------------
 
-function adjudicateCaptainOutput(input: CaptainInput, visibleText: string, judgeText: string): CaptainOutput {
-  const parsed = parseJsonObjectLoose(judgeText);
-  if (!parsed) throw new Error('adjudicator reply did not contain a JSON object');
-  const guard = parsed.guard;
-  if (typeof guard !== 'string' || !(guard in input.result)) {
-    throw new Error(`adjudicator selected undeclared guard ${String(guard)}`);
-  }
-  const allowed = new Set(['guard']);
-  for (const field of requiredOutputFields(input.result[guard] ?? '')) {
-    if (field !== 'question' && field !== 'response') allowed.add(field);
+function validateParsedActingDecision(value: unknown): ParsedActingDecision {
+  if (!isRecord(value)) {
+    throw new TypeError('parse-resolved decision must be an object');
   }
-  for (const key of Object.keys(parsed)) {
-    if (!allowed.has(key)) throw new Error(`adjudicator supplied undeclared field ${key}`);
-  }
-  if (guard === 'question' || guard === 'followUpQuestion' || guard === 'needsBossReply') {
-    return { guard, question: visibleText } as CaptainOutput;
+  if (value.action === 'deliver') {
+    if (Object.keys(value).length !== 1) {
+      throw new TypeError('a parse-resolved deliver decision carries no payload');
+    }
+    return { action: 'deliver' };
   }
-  if (guard === 'final') {
-    return { guard, response: visibleText };
+  if (value.action !== 'start' && value.action !== 'switch') {
+    throw new TypeError(
+      `parse-resolved decision names unknown action ${String(value.action)}`,
+    );
   }
-  if (guard === 'delegation' || guard === 'continuing') {
-    const missing = ['remainingPlan', 'nextPlaybookId', 'nextPlaybookInput'].filter((field) => !(field in parsed));
-    if (missing.length > 0) {
-      throw new Error(`adjudicator omitted required field ${missing.join(', ')}`);
+  const allowed = new Set(['action', 'playbookId', 'input']);
+  for (const key of Object.keys(value)) {
+    if (!allowed.has(key)) {
+      throw new TypeError(`parse-resolved decision carries undeclared ${key}`);
     }
-    const remainingPlan = snapshotJsonValue(parsed.remainingPlan, 'remainingPlan');
-    if (!Array.isArray(remainingPlan)) throw new Error('adjudicator remainingPlan must be a JSON array');
-    return {
-      guard,
-      remainingPlan,
-      nextPlaybookId: assertNonEmptyString(parsed.nextPlaybookId, 'nextPlaybookId'),
-      nextPlaybookInput: assertNonEmptyString(parsed.nextPlaybookInput, 'nextPlaybookInput'),
-    } as CaptainOutput;
   }
-  throw new Error(`adjudicator selected unsupported guard ${guard}`);
+  return {
+    action: value.action,
+    playbookId: assertNonEmptyString(
+      value.playbookId,
+      'parse-resolved decision playbookId',
+    ),
+    input: assertNonEmptyString(value.input, 'parse-resolved decision input'),
+  };
 }
 
-function validateClassifier(text: string, bossText: string, pendingQuestionId: string | undefined): BossMapping {
-  const parsed = parseJsonObjectLoose(text);
-  if (!parsed) return undefined;
-  const type = parsed.type;
-  if (type === 'NO_ACTION') {
-    if (Object.keys(parsed).length !== 1) return undefined;
-    return { type: 'NO_ACTION' };
-  }
-  if (type === 'BOSS_INTENT') {
-    if (Object.keys(parsed).length !== 1) return undefined;
-    return { type: 'BOSS_INTENT', bossIntent: bossText };
-  }
-  if (type === 'BOSS_INTERRUPT') {
-    if (Object.keys(parsed).sort().join('\0') !== ['targetId', 'type'].join('\0')) return undefined;
-    if (parsed.targetId !== 'routing') return undefined;
-    return { type: 'BOSS_INTERRUPT', targetId: 'routing', bossIntent: bossText };
-  }
-  if (type === 'BOSS_REPLY') {
-    const keys = Object.keys(parsed).sort();
-    if (keys.join('\0') !== ['questionId', 'type'].join('\0') && keys.join('\0') !== 'type') return undefined;
-    const questionId = parsed.questionId === undefined ? pendingQuestionId : parsed.questionId;
-    if (questionId !== pendingQuestionId || typeof questionId !== 'string') return undefined;
-    return { type: 'BOSS_REPLY', answer: bossText, questionId };
+function classifyControllerTurn(
+  text: string,
+  _ports: PlaybookPorts,
+  _signal: AbortSignal,
+  _snapshotOrState: unknown,
+  _boundary?: unknown,
+  options?: ValidatedCaptainOptions,
+): Promise<Record<string, unknown> | undefined> {
+  const resolution = options?.controller?.resolveParsedTurn?.(text);
+  if (resolution === undefined) {
+    return Promise.resolve({ type: 'BOSS_TURN', bossText: text });
+  }
+  if (!isRecord(resolution)) {
+    throw new TypeError('controller parse resolution must be an object');
+  }
+  const widened = resolution as {
+    readonly kind?: unknown;
+    readonly decision?: unknown;
+  };
+  switch (widened.kind) {
+    case 'respond':
+      return Promise.resolve({ type: 'PARSED_RESPOND', bossText: text });
+    case 'action':
+      return Promise.resolve({
+        type: 'PARSED_ACTION',
+        bossText: text,
+        decision: validateParsedActingDecision(widened.decision),
+      });
+    case 'shutdown':
+      return Promise.resolve({ type: 'SHUTDOWN' });
+    default:
+      throw new TypeError(
+        `controller parse resolution names unknown kind ${String(widened.kind)}`,
+      );
   }
-  return undefined;
 }
 
-function classifierPrompt(text: string, state: PlaybookState, pending: unknown): string {
+// ---------------------------------------------------------------------------
+// Decision-reply validation (CAPPLAY-18): the hidden decision call's reply is
+// `{ action, … }` control JSON over the closed set, validated against the
+// declared decision-state contract — known action, required payload fields,
+// catalog membership, never this Captain playbook itself as a target. A
+// malformed reply earns exactly one corrective call appending the rejection
+// reason and the restated reply contract; a second malformed reply settles
+// the turn as a recoverable hub return with no action executed.
+// ---------------------------------------------------------------------------
+
+const RESTATED_REPLY_CONTRACT = [
+  'Reply again with exactly one JSON object `{ "action": …, … }` and no other text, selecting exactly one action from the closed set `respond` | `start` | `switch` | `dismiss` | `deliver` | `runtime`:',
+  '`{ "action": "respond", "text": … }`, `{ "action": "start", "playbookId": …, "input": … }`, `{ "action": "switch", "playbookId": …, "input": … }`, `{ "action": "dismiss" }`, `{ "action": "deliver" }`, or `{ "action": "runtime", "actionId": … }`; every `input` is one nonempty complete standalone request.',
+].join('\n');
+
+function correctiveDecisionPrompt(prompt: string, reason: string): string {
   return [
-    'Classify this Boss message for the Captain playbook FSM.',
-    '',
-    'Boss message:',
-    text,
-    '',
-    'Current state:',
-    stableJson(state),
-    '',
-    'Pending Boss question:',
-    stableJson(pending ?? null),
+    prompt,
     '',
-    'Return JSON only. Allowed objects are {"type":"BOSS_REPLY","questionId":"routing-or-reassessing"}, {"type":"BOSS_INTERRUPT","targetId":"routing"}, {"type":"BOSS_INTENT"}, or {"type":"NO_ACTION"}.',
+    `Your previous control reply was rejected: ${reason}.`,
+    RESTATED_REPLY_CONTRACT,
   ].join('\n');
 }
 
-function stateFromSnapshot(actor: RootActor, pendingCall?: { readonly callId: string; readonly playbookId: string; readonly childSessionId: string }): PlaybookState {
-  return normalizePlaybookSnapshot(actor.getSnapshot(), { pendingCall });
-}
-
-function resultFromState(
-  state: PlaybookState,
-  output: JsonValue | undefined,
-  pendingCall?: { readonly callId: string; readonly playbookId: string; readonly childSessionId: string },
-  error?: unknown,
-): PlaybookRunResult {
-  if (pendingCall) return { outcome: 'suspended', state, pendingCall };
-  if (state.status === 'done') {
-    return output === undefined ? { outcome: 'terminal', state } : { outcome: 'terminal', state, output };
-  }
-  if (state.stateId === 'failed') {
-    return error === undefined ? { outcome: 'failed', state } : { outcome: 'failed', state, error: normalizeError(error) };
-  }
-  return { outcome: 'quiescent', state };
-}
-
-function isAbortLikeError(error: unknown): boolean {
-  return normalizeError(error).name === 'AbortError';
-}
-
-function isSignalAbort(error: unknown, signal: AbortSignal): boolean {
-  return signal.aborted && error === signal.reason;
-}
-
-class CaptainPlaybookRuntime implements PlaybookRuntime {
-  private readonly enabledPlaybooks: readonly EnabledPlaybook[];
-  private readonly emissionQueue = new PQueue({ concurrency: 1 });
-  private readonly captainLane = new PQueue({ concurrency: 1 });
-  private session: RuntimeSession | undefined;
-  private actor: RootActor | undefined;
-  private nestedBridge: ReturnType<typeof createNestedPlaybookBridge<PlaybookInput>> | undefined;
-  private sequence = 0;
-  private turnId = 0;
-  private callId = 0;
-  private boundaryTurnId: number | undefined;
-  private readonly playbookCallTurnIds = new Map<string, number>();
-  private activeBoundarySignal: AbortSignal | undefined;
-  private activeTurn: Promise<PlaybookRunResult> | undefined;
-  private disposing: Promise<void> | undefined;
-  private disposed = false;
-  private terminallyDisposedBeforeInit = false;
-  private disposalTraceEmitted = false;
-  private initializing = false;
-  private initializationDone: Promise<void> | undefined;
-  private resolveInitializationDone: (() => void) | undefined;
-  private latchedControlError: unknown;
-  private suppressInspection = false;
-  private previousState: PlaybookState | undefined;
-
-  constructor(options: PlaybookRuntimeOptions) {
-    this.enabledPlaybooks = validateEnabledPlaybooks(options.enabledPlaybooks);
-  }
-
-  async init(session: PlaybookSession): Promise<void> {
-    if (this.session || this.actor) throw new Error('playbook runtime is already initialized');
-    if (this.disposed || this.terminallyDisposedBeforeInit || this.disposing) throw new Error('playbook runtime is disposed');
-    this.initializing = true;
-    this.initializationDone = new Promise((resolve) => {
-      this.resolveInitializationDone = resolve;
-    });
-    this.disposalTraceEmitted = false;
-    let actor: RootActor | undefined;
-    let initialState: PlaybookState | undefined;
-    try {
-      const captured = snapshotPlaybookSession(session);
-      this.session = captured;
-      this.nestedBridge = this.createBridge(captured);
-      actor = this.createActor(captured, this.nestedBridge);
-      this.actor = actor;
-      initialState = stateFromSnapshot(actor);
-      this.previousState = initialState;
-      await this.trace('session.started', omitUndefined({ state: initialState, stateId: initialState.stateId }));
-      await this.drain();
-      actor.start();
-      await this.drain();
-    } catch (error) {
-      this.suppressInspection = true;
-      actor?.stop();
-      if (initialState && !this.disposalTraceEmitted) await this.bestEffortDisposeTrace(initialState);
-      this.session = undefined;
-      this.actor = undefined;
-      this.nestedBridge = undefined;
-      this.sequence = 0;
-      this.turnId = 0;
-      this.callId = 0;
-      this.latchedControlError = undefined;
-      this.previousState = undefined;
-      this.suppressInspection = false;
-      throw error;
-    } finally {
-      this.initializing = false;
-      this.resolveInitializationDone?.();
-      this.resolveInitializationDone = undefined;
-    }
+type DecisionReplyReading =
+  | { readonly selection: CaptainControllerSelection; readonly reason?: undefined }
+  | { readonly selection?: undefined; readonly reason: string };
+
+function readDecisionReply(
+  reply: string,
+  options: ValidatedCaptainOptions,
+  selfPlaybookId: string,
+  declaredActions: ReadonlySet<string>,
+): DecisionReplyReading {
+  let parsed: unknown;
+  try {
+    parsed = parseJudgeJson(reply);
+  } catch {
+    return { reason: 'the reply contains no recoverable JSON object' };
+  }
+  if (!isRecord(parsed)) {
+    return { reason: 'the reply is not a JSON object' };
+  }
+  const action = parsed.action;
+  if (typeof action !== 'string' || !declaredActions.has(action)) {
+    return {
+      reason: `the reply names no known action (got ${JSON.stringify(action ?? null)})`,
+    };
   }
-
-  async handleBossInput(turn: { text: string; signal: AbortSignal }): Promise<PlaybookRunResult> {
-    if (this.activeTurn) throw new Error('playbook runtime already has an active boundary');
-    if (this.disposing || this.disposed) throw new Error('playbook runtime is disposing');
-    const run = this.handleBossInputInner(turn);
-    this.activeTurn = run;
-    try {
-      return await run;
-    } catch (error) {
-      if (isSignalAbort(error, turn.signal)) {
-        const actor = this.actor;
-        const bridge = this.nestedBridge;
-        const snapshot = actor
-          ? await waitForPlaybookQuiescence(actor, { pendingCalls: bridge })
-          : undefined;
-        const state = snapshot
-          ? normalizePlaybookSnapshot(snapshot, { pendingCall: bridge?.getPendingCall() })
-          : { value: 'failed', activeStateIds: ['failed'], tags: ['playbook.parked'], status: 'active', quiescent: true, stateId: 'failed' } satisfies PlaybookState;
-        try {
-          await this.drain();
-        } catch {
-          // The signal-driven abort remains the public outcome.
-        }
-        return { outcome: 'aborted', state, error: normalizeError(error) };
+  const requireKeys = (
+    required: readonly string[],
+    tolerated: readonly string[] = [],
+  ): string | undefined => {
+    for (const key of required) {
+      if (!(key in parsed)) {
+        return `the ${action} selection omits required field \`${key}\``;
       }
-      throw error;
-    } finally {
-      this.activeTurn = undefined;
-      const error = this.latchedControlError;
-      this.latchedControlError = undefined;
-      const aborted = this.activeBoundarySignal?.aborted === true;
-      this.activeBoundarySignal = undefined;
-      this.boundaryTurnId = undefined;
-      if (error && (!aborted || !isAbortLikeError(error))) throw error;
     }
-  }
-
-  async resumePlaybookCall(input: { callId: string; result: PlaybookCallResult; signal: AbortSignal }): Promise<PlaybookRunResult> {
-    if (this.activeTurn) throw new Error('playbook runtime already has an active boundary');
-    if (this.disposing || this.disposed) throw new Error('playbook runtime is disposing');
-    const run = this.resumePlaybookCallInner(input);
-    this.activeTurn = run;
-    try {
-      return await run;
-    } finally {
-      this.activeTurn = undefined;
-      const error = this.latchedControlError;
-      this.latchedControlError = undefined;
-      const aborted = this.activeBoundarySignal?.aborted === true;
-      this.activeBoundarySignal = undefined;
-      this.boundaryTurnId = undefined;
-      if (error && (!aborted || !isAbortLikeError(error))) throw error;
-    }
-  }
-
-  dispose(): Promise<void> {
-    if (this.activeTurn) return Promise.reject(new Error('cannot dispose during an active boundary'));
-    if (this.disposing) return this.disposing;
-    if (!this.initializing && !this.session && !this.actor && !this.disposed) {
-      this.terminallyDisposedBeforeInit = true;
-      this.disposed = true;
-      this.disposing = Promise.resolve();
-      return this.disposing;
-    }
-    this.disposing = this.disposeInner();
-    return this.disposing;
-  }
-
-  private async handleBossInputInner(turn: { text: string; signal: AbortSignal }): Promise<PlaybookRunResult> {
-    const actor = this.requireActor();
-    const nestedBridge = this.requireBridge();
-    const currentTurnId = this.nextTurnId();
-    this.boundaryTurnId = currentTurnId;
-    this.activeBoundarySignal = turn.signal;
-    await this.trace('boss.input.received', { text: turn.text }, currentTurnId);
-    const state = stateFromSnapshot(actor, nestedBridge.getPendingCall());
-    let event: BossMapping;
-    if (turn.text.trim().length === 0) {
-      const result: PlaybookRunResult = { outcome: 'no-action', state };
-      await this.traceSettled(result, currentTurnId);
-      await this.drain();
-      return result;
+    for (const key of Object.keys(parsed)) {
+      if (
+        key !== 'action' &&
+        !required.includes(key) &&
+        !tolerated.includes(key)
+      ) {
+        return `the ${action} selection carries undeclared field \`${key}\``;
+      }
     }
-    if (state.stateId === 'ready' || state.stateId === 'failed') {
-      event = { type: 'BOSS_INTENT', bossIntent: turn.text };
-    } else {
-      try {
-        event = await this.classifyBossInput(turn.text, state, turn.signal);
-      } catch (error) {
-        if (isSignalAbort(error, turn.signal)) {
-          const result: PlaybookRunResult = { outcome: 'aborted', state, error: normalizeError(error) };
-          await this.traceSettled(result, currentTurnId);
-          await this.drain();
-          return result;
-        }
-        await this.trace(
-          'boss.input.settled',
-          omitUndefined({
-            outcome: 'no-action',
-            state,
-            stateId: state.stateId,
-            error: normalizeError(error),
-          }),
-          currentTurnId,
-        );
-        await this.drain();
-        throw error;
+    return undefined;
+  };
+  const nonEmpty = (key: string): string | undefined =>
+    typeof parsed[key] === 'string' && parsed[key].trim().length > 0
+      ? undefined
+      : `the ${action} selection's \`${key}\` must be a non-empty string`;
+  switch (action) {
+    case 'respond': {
+      const shape = requireKeys(['text']) ?? nonEmpty('text');
+      if (shape !== undefined) return { reason: shape };
+      return { selection: { action, text: parsed.text as string } };
+    }
+    case 'start':
+    case 'switch': {
+      const shape =
+        requireKeys(['playbookId', 'input']) ??
+        nonEmpty('playbookId') ??
+        nonEmpty('input');
+      if (shape !== undefined) return { reason: shape };
+      const playbookId = parsed.playbookId as string;
+      if (playbookId === selfPlaybookId) {
+        return {
+          reason: `the ${action} target may never be this Captain playbook itself`,
+        };
       }
-      if (!event) {
-        await this.emitStatus('classification was invalid; Boss input was not actionable.', { state });
-        const result: PlaybookRunResult = { outcome: 'no-action', state };
-        await this.traceSettled(result, currentTurnId);
-        await this.drain();
-        return result;
+      if (
+        !options.enabledPlaybooks.some((entry) => entry.id === playbookId)
+      ) {
+        return {
+          reason: `the ${action} target ${JSON.stringify(playbookId)} is not an enabled catalog id`,
+        };
       }
+      return {
+        selection: {
+          action,
+          playbookId,
+          input: parsed.input as string,
+        },
+      };
     }
-    if (event?.type === 'NO_ACTION') {
-      const result: PlaybookRunResult = { outcome: 'no-action', state };
-      await this.traceSettled(result, currentTurnId);
-      await this.drain();
-      return result;
-    }
-    if (turn.signal.aborted) {
-      const result: PlaybookRunResult = { outcome: 'aborted', state, error: normalizeError(turn.signal.reason) };
-      await this.traceSettled(result, currentTurnId);
-      await this.drain();
-      return result;
+    case 'dismiss': {
+      const shape = requireKeys([]);
+      if (shape !== undefined) return { reason: shape };
+      return { selection: { action } };
     }
-    if (actor.getSnapshot().status === 'done') {
-      this.reconstructActor();
+    case 'deliver': {
+      // A deliver selection carries no text payload: the host is
+      // authoritative for the delivered text, so a carried `text` is
+      // ignored and never delivered (CAPPLAY-9).
+      const shape = requireKeys([], ['text']);
+      if (shape !== undefined) return { reason: shape };
+      return { selection: { action } };
     }
-    this.requireActor().send(event);
-    const snapshot = await waitForPlaybookQuiescence(this.requireActor(), { pendingCalls: nestedBridge });
-    const settledState = normalizePlaybookSnapshot(snapshot, { pendingCall: nestedBridge.getPendingCall() });
-    const result = turn.signal.aborted
-      ? { outcome: 'aborted', state: settledState, error: normalizeError(turn.signal.reason) } satisfies PlaybookRunResult
-      : resultFromState(
-        settledState,
-        this.machineOutput(),
-        nestedBridge.getPendingCall(),
-        this.latchedControlError,
-      );
-    await this.traceSettled(result, currentTurnId);
-    await this.drain();
-    return result;
-  }
-
-  private async resumePlaybookCallInner(input: { callId: string; result: PlaybookCallResult; signal: AbortSignal }): Promise<PlaybookRunResult> {
-    const nestedBridge = this.requireBridge();
-    this.activeBoundarySignal = input.signal;
-    this.boundaryTurnId = this.playbookCallTurnIds.get(input.callId);
-    let resumeError: unknown;
-    try {
-      await nestedBridge.resume(input);
-    } catch (error) {
-      resumeError = error;
+    case 'runtime': {
+      const shape = requireKeys(['actionId']) ?? nonEmpty('actionId');
+      if (shape !== undefined) return { reason: shape };
+      return { selection: { action, actionId: parsed.actionId as string } };
     }
-    const snapshot = await waitForPlaybookQuiescence(this.requireActor(), { pendingCalls: nestedBridge });
-    const pendingCall = nestedBridge.getPendingCall();
-    const state = normalizePlaybookSnapshot(snapshot, { pendingCall });
-    const result = resultFromState(state, this.machineOutput(), pendingCall);
-    await this.drain();
-    if (resumeError !== undefined) throw resumeError;
-    return input.signal.aborted ? { outcome: 'aborted', state, error: normalizeError(input.signal.reason) } : result;
+    default:
+      return { reason: `the reply names no known action (${action})` };
   }
+}
 
-  private async disposeInner(): Promise<void> {
-    if (this.disposed) return;
-    if (this.initializing) {
-      await this.initializationDone;
-    }
-    const actor = this.actor;
-    const bridge = this.nestedBridge;
-    const finalState = actor ? stateFromSnapshot(actor, bridge?.getPendingCall()) : undefined;
-    let cleanupError: unknown;
-    this.suppressInspection = true;
-    actor?.stop();
-    try {
-      await bridge?.dispose();
-    } catch (error) {
-      cleanupError = error;
-    }
-    if (this.initializing) {
-      try {
-        await this.drain();
-      } catch (error) {
-        if (cleanupError === undefined) cleanupError = error;
-      }
-    } else {
-      try {
-        await this.drain();
-      } catch (error) {
-        if (cleanupError === undefined) cleanupError = error;
-      }
-    }
-    this.latchedControlError = undefined;
-    if (finalState && !this.disposalTraceEmitted) {
-      this.disposalTraceEmitted = true;
-      try {
-        await this.trace('session.disposed', omitUndefined({ state: finalState, stateId: finalState.stateId }));
-      } catch (error) {
-        if (cleanupError === undefined) cleanupError = error;
-      }
-    }
-    try {
-      await this.drain();
-    } catch (error) {
-      if (cleanupError === undefined) cleanupError = error;
-    }
-    this.session = undefined;
-    this.actor = undefined;
-    this.nestedBridge = undefined;
-    this.disposed = true;
-    if (cleanupError !== undefined) throw cleanupError;
-  }
+function selectionFromParsedDecision(
+  decision: ParsedActingDecision,
+): CaptainControllerSelection {
+  if (decision.action === 'deliver') {
+    return { action: 'deliver' };
+  }
+  // A parse-resolved `start` / `switch` is always the exact command remainder
+  // supplied by the host (CAPTAIN-7 command table).
+  return {
+    action: decision.action,
+    playbookId: decision.playbookId,
+    input: decision.input,
+  };
+}
 
-  private createActor(session: RuntimeSession, bridge: ReturnType<typeof createNestedPlaybookBridge<PlaybookInput>>): RootActor {
-    const provided = captainMachine.provide({
-      actors: {
-        captain: fromPromise<CaptainOutput, CaptainInput>(async ({ input, signal }) => {
-          await this.drain();
-          const combined = combineAbortSignals(signal, this.activeBoundarySignal);
-          return await this.runCaptainActor(input, combined);
-        }),
-        playbook: bridge.actorLogic,
-      },
-    });
-    let rootActor: RootActor;
-    rootActor = createActor(provided, {
-      input: {
-        enabledPlaybooks: this.enabledPlaybooks,
-        selfPlaybookId: session.playbookId,
-      },
-      inspect: (inspectionEvent) => {
-        if (this.suppressInspection) return;
-        if (inspectionEvent.type !== '@xstate.snapshot') return;
-        if (inspectionEvent.actorRef !== rootActor) return;
-        try {
-          this.enqueueTransition(inspectionEvent.event, rootActor);
-        } catch (error) {
-          this.latchControlError(error);
-        }
-      },
-    });
-    return rootActor;
+/** The machine retains the selected standalone input and settlement evidence. */
+function decisionOutputOf(
+  selection: CaptainControllerSelection,
+): Record<string, unknown> {
+  if (selection.action === 'start' || selection.action === 'switch') {
+    return {
+      guard: selection.action,
+      playbookId: selection.playbookId,
+      input: selection.input,
+    };
   }
+  return { ...selection, guard: selection.action };
+}
 
-  private createBridge(session: RuntimeSession): ReturnType<typeof createNestedPlaybookBridge<PlaybookInput>> {
-    return createNestedPlaybookBridge<PlaybookInput>({
-      nextCallId: () => `call-${this.nextCallId()}`,
-      getBoundarySignal: () => this.activeBoundarySignal,
-      callPlaybook: (request, signal) => session.ports.callPlaybook(request, signal),
-      emitStarted: async (event) => {
-        const turnId = this.currentTraceTurnId();
-        if (turnId !== undefined) this.playbookCallTurnIds.set(event.callId, turnId);
-        await this.trace('playbook.call.started', {
-          stateId: event.stateId,
-          playbookId: event.playbookId,
-          text: event.text,
-        }, turnId, event.callId);
-      },
-      emitFinished: async (event) => {
-        const turnId = this.playbookCallTurnIds.get(event.callId) ?? this.currentTraceTurnId();
-        await this.trace('playbook.call.finished', {
-          stateId: event.stateId,
-          playbookId: event.playbookId,
-          text: event.text,
-          result: event.result,
-        }, turnId, event.callId);
-        this.playbookCallTurnIds.delete(event.callId);
-      },
-      drain: () => this.drain(),
-      bindResumeSignal: (signal) => {
-        this.activeBoundarySignal = signal;
-      },
-      onControlPlaneError: (error) => this.latchControlError(error),
-      onBackgroundError: (error) => this.latchControlError(error),
-    });
+// ---------------------------------------------------------------------------
+// Settlement validation: the returned settlement is the only evidence of
+// effects, and the machine retains only its status, facts, receipt
+// disposition, and leaf-state summary (CAPPLAY-10). A malformed settlement
+// is a host control-plane failure.
+// ---------------------------------------------------------------------------
+
+function validateSettlement(value: unknown): SettlementEvidence {
+  if (!isRecord(value)) {
+    throw new TypeError('controller settlement must be an object');
+  }
+  const allowed = new Set([
+    'status',
+    'facts',
+    'reason',
+    'receipt',
+    'leafStateSummary',
+  ]);
+  for (const key of Object.keys(value)) {
+    if (!allowed.has(key)) {
+      throw new TypeError(`controller settlement carries undeclared ${key}`);
+    }
+  }
+  if (
+    value.status !== 'ok' &&
+    value.status !== 'rejected' &&
+    value.status !== 'failed'
+  ) {
+    throw new TypeError(
+      `controller settlement status must be ok | rejected | failed (got ${String(value.status)})`,
+    );
   }
-
-  private async runCaptainActor(input: CaptainInput, signal: AbortSignal): Promise<CaptainOutput> {
-    try {
-      const prompt = composeCaptainPrompt(input);
-      const result = await this.callCaptain(input, prompt, signal);
-      if (signal.aborted) throw signal.reason;
-      if (result.status !== 'ok') {
-        throw new Error(result.error ?? `Captain returned ${result.status}`);
-      }
-      if (!result.finalText) {
-        throw new Error('Captain returned ok without finalText');
-      }
-      const judgePrompt = makeJudgePrompt(input, result.finalText);
-      const judgeText = await this.callJudge('captain-output-adjudication', judgePrompt, signal, input.stateId);
-      return adjudicateCaptainOutput(input, result.finalText, judgeText);
-    } catch (error) {
-      if (!signal.aborted) this.latchControlError(error);
-      throw error;
-    }
+  if (
+    !Array.isArray(value.facts) ||
+    value.facts.some((fact: unknown) => typeof fact !== 'string')
+  ) {
+    throw new TypeError('controller settlement facts must be a string array');
+  }
+  if ('reason' in value && typeof value.reason !== 'string') {
+    throw new TypeError('controller settlement reason must be a string');
+  }
+  if (
+    'leafStateSummary' in value &&
+    typeof value.leafStateSummary !== 'string'
+  ) {
+    throw new TypeError(
+      'controller settlement leafStateSummary must be a string',
+    );
   }
-
-  private async callCaptain(input: CaptainInput, prompt: string, signal: AbortSignal): Promise<CaptainResult> {
-    const callId = `captain-${this.nextCallId()}`;
-    const startPayload = {
-      stateId: input.stateId,
-      sourceItem: input.sourceItem,
-      prompt,
-      visibility: 'visible',
-      resume: false,
-      allowedTools: [],
-    };
-    try {
-      await this.trace('captain.call.started', startPayload, this.currentTraceTurnId(), callId);
-    } catch (error) {
-      await this.tracePreservingError(
-        'captain.call.finished',
-        {
-          ...startPayload,
-          status: 'error',
-          error: normalizeError(error),
-        },
-        error,
-        this.currentTraceTurnId(),
-        callId,
-      );
-      throw error;
-    }
-    let result: CaptainResult | undefined;
-    let failure: unknown;
-    try {
-      result = await this.captainLane.add(async () => {
-        if (signal.aborted) throw signal.reason;
-        const raw = await this.requireSession().ports.callCaptain(prompt, signal, CAPTAIN_OPTIONS);
-        if (signal.aborted) throw signal.reason;
-        return validateCaptainResult(raw);
-      });
-      if (result.status !== 'ok') {
-        failure = new Error(result.error ?? `Captain returned ${result.status}`);
-      } else if (!result.finalText) {
-        failure = new Error('Captain returned ok without finalText');
-      }
-    } catch (error) {
-      failure = error;
+  let receipt: SettlementReceiptEvidence | undefined;
+  if ('receipt' in value) {
+    if (!isRecord(value.receipt)) {
+      throw new TypeError('controller settlement receipt must be an object');
     }
-    const normalized = failure === undefined ? undefined : normalizeError(failure);
-    const abortedFailure = failure !== undefined && isSignalAbort(failure, signal);
-    const finishPayload = {
-      stateId: input.stateId,
-      sourceItem: input.sourceItem,
-      prompt,
-      visibility: 'visible',
-      resume: false,
-      allowedTools: [],
-      status: result?.status ?? (abortedFailure ? 'aborted' : 'error'),
-      ...(result?.finalText === undefined ? {} : { finalText: result.finalText }),
-      ...(result?.error === undefined ? {} : { error: result.error }),
-      ...(normalized === undefined ? {} : { error: normalized }),
-    };
-    if (failure !== undefined) {
-      if (isSignalAbort(failure, signal)) {
-        await this.trace('captain.call.finished', finishPayload, this.currentTraceTurnId(), callId);
-        throw failure;
+    const receiptAllowed = new Set(['disposition', 'reason', 'error']);
+    for (const key of Object.keys(value.receipt)) {
+      if (!receiptAllowed.has(key)) {
+        throw new TypeError(
+          `controller settlement receipt carries undeclared ${key}`,
+        );
       }
-      await this.tracePreservingError('captain.call.finished', finishPayload, failure, this.currentTraceTurnId(), callId);
-      throw failure;
     }
-    await this.trace('captain.call.finished', finishPayload, this.currentTraceTurnId(), callId);
-    if (failure !== undefined) throw failure;
-    if (!result) throw new Error('Captain returned no result');
-    return result;
-  }
-
-  private async callJudge(purpose: string, prompt: string, signal: AbortSignal, stateId?: string): Promise<string> {
-    const callId = `judge-${this.nextCallId()}`;
-    const startPayload = omitUndefined({ purpose, prompt, stateId });
-    try {
-      await this.trace('judge.call.started', startPayload, this.currentTraceTurnId(), callId);
-    } catch (error) {
-      await this.tracePreservingError(
-        'judge.call.finished',
-        omitUndefined({ purpose, prompt, stateId, status: 'error', error: normalizeError(error) }),
-        error,
-        this.currentTraceTurnId(),
-        callId,
+    const disposition = value.receipt.disposition;
+    if (
+      disposition !== 'executed' &&
+      disposition !== 'rejected' &&
+      disposition !== 'failed'
+    ) {
+      throw new TypeError(
+        'controller settlement receipt disposition must be executed | rejected | failed',
       );
-      throw error;
     }
-    let reply: string | undefined;
-    let failure: unknown;
-    try {
-      reply = await this.captainLane.add(async () => {
-        if (signal.aborted) throw signal.reason;
-        const text = await this.requireSession().ports.callJudge(prompt, signal);
-        if (signal.aborted) throw signal.reason;
-        if (typeof text !== 'string') throw new TypeError('judge reply must be a string');
-        return text;
-      });
-    } catch (error) {
-      failure = error;
+    if ('reason' in value.receipt && typeof value.receipt.reason !== 'string') {
+      throw new TypeError(
+        'controller settlement receipt reason must be a string',
+      );
     }
-    if (failure !== undefined) {
-      const aborted = isSignalAbort(failure, signal);
-      const finishPayload = omitUndefined({
-        purpose,
-        prompt,
-        stateId,
-        status: aborted ? 'aborted' : 'error',
-        error: normalizeError(failure),
-      });
-      if (aborted) {
-        await this.trace('judge.call.finished', finishPayload, this.currentTraceTurnId(), callId);
-      } else {
-        await this.tracePreservingError(
-          'judge.call.finished',
-          finishPayload,
-          failure,
-          this.currentTraceTurnId(),
-          callId,
+    let error: { name: string; message: string } | undefined;
+    if ('error' in value.receipt) {
+      const compact = normalizeErrorCompact(value.receipt.error);
+      if (compact === undefined) {
+        throw new TypeError(
+          'controller settlement receipt error must be a normalized error',
         );
       }
-      throw failure;
-    }
-    await this.trace(
-      'judge.call.finished',
-      omitUndefined({ purpose, prompt, stateId, status: 'ok', reply }),
-      this.currentTraceTurnId(),
-      callId,
-    );
-    if (reply === undefined) throw new Error('judge returned no reply');
-    return reply;
-  }
-
-  private async classifyBossInput(text: string, state: PlaybookState, signal: AbortSignal): Promise<BossMapping> {
-    const pending = this.pendingQuestion();
-    const prompt = classifierPrompt(text, state, pending ? { questionId: pending.questionId, player: pending.player, question: pending.question } : undefined);
-    const reply = await this.callJudge('boss-input-classification', prompt, signal, state.stateId);
-    const event = validateClassifier(reply, text, pending?.questionId);
-    if (!event) return undefined;
-    return event;
-  }
-
-  private pendingQuestion(): { readonly questionId: string; readonly player: string; readonly question: string } | undefined {
-    const snapshot = this.actor?.getSnapshot();
-    const context = snapshot?.context as unknown;
-    if (!isRecord(context) || !isRecord(context.pendingBossQuestion)) return undefined;
-    return {
-      questionId: assertNonEmptyString(context.pendingBossQuestion.questionId, 'pending question id'),
-      player: assertNonEmptyString(context.pendingBossQuestion.player, 'pending question player'),
-      question: assertNonEmptyString(context.pendingBossQuestion.question, 'pending question text'),
-    };
-  }
-
-  private enqueueTransition(event: unknown, actor: RootActor): void {
-    const state = stateFromSnapshot(actor, this.nestedBridge?.getPendingCall());
-    const previousState = this.previousState ?? state;
-    this.previousState = state;
-    const transition = omitUndefined({
-      event: this.describeEvent(event),
-      from: previousState,
-      to: state,
-      previousState,
-      state,
-      stateId: state.stateId,
-      pendingBossQuestion: this.pendingQuestion(),
-      lastError: this.lastError(),
-    });
-    this.enqueue(async () => {
-      await this.traceNow('fsm.transition', transition, this.currentTraceTurnId());
-      await this.requireSession().ports.emitTelemetry({ topic: 'playbook.fsm.state', payload: transition });
-      if (state.stateId !== 'ready' && state.stateId !== 'done') {
-        await this.traceNow('status.emitted', omitUndefined({ message: `Entered ${state.stateId ?? 'state'}`, state, stateId: state.stateId }), this.currentTraceTurnId());
-        await this.requireSession().ports.emitStatus(`Entered ${state.stateId ?? 'state'}`, transition);
-      }
+      error = compact;
+    }
+    receipt = Object.freeze({
+      disposition,
+      ...(typeof value.receipt.reason === 'string'
+        ? { reason: value.receipt.reason }
+        : {}),
+      ...(error === undefined ? {} : { error: Object.freeze(error) }),
     });
   }
+  return Object.freeze({
+    status: value.status,
+    facts: Object.freeze([...(value.facts as readonly string[])]),
+    ...(typeof value.reason === 'string' ? { reason: value.reason } : {}),
+    ...(receipt === undefined ? {} : { receipt }),
+    ...(typeof value.leafStateSummary === 'string'
+      ? { leafStateSummary: value.leafStateSummary }
+      : {}),
+  });
+}
 
-  private describeEvent(event: unknown): JsonValue {
-    if (!isRecord(event)) return { type: 'unknown' };
-    const type = typeof event.type === 'string' ? event.type : 'unknown';
-    const copy: Record<string, JsonValue> = { type };
-    for (const key of ['bossIntent', 'targetId', 'answer', 'questionId', 'output']) {
-      if (key in event && event[key] === undefined) continue;
-      if (key in event) copy[key] = snapshotJsonValue(event[key], `event.${key}`);
-    }
-    if ('error' in event) copy.error = snapshotJsonValue(normalizeError(event.error));
-    return snapshotJsonValue(copy);
-  }
-
-  private lastError(): JsonValue | undefined {
-    const context = this.actor?.getSnapshot().context as unknown;
-    if (!isRecord(context) || !('lastError' in context)) return undefined;
-    if (context.lastError === undefined) return undefined;
-    return snapshotJsonValue(context.lastError, 'lastError');
-  }
-
-  private machineOutput(): JsonValue | undefined {
-    const snapshot = this.actor?.getSnapshot();
-    if (!snapshot || snapshot.status !== 'done') return undefined;
-    const output = snapshot.output as unknown;
-    return output === undefined ? undefined : snapshotJsonValue(output, 'machine output');
-  }
-
-  private async emitStatus(message: string, data?: unknown): Promise<void> {
-    const state = stateFromSnapshot(this.requireActor(), this.nestedBridge?.getPendingCall());
-    const payload = omitUndefined({ message, data, state, stateId: state.stateId });
-    await this.trace('status.emitted', payload, this.currentTraceTurnId());
-    await this.requireSession().ports.emitStatus(message, data);
-  }
-
-  private async traceSettled(result: PlaybookRunResult, turnId: number): Promise<void> {
-    await this.trace('boss.input.settled', this.runResultPayload(result), turnId);
-  }
-
-  private runResultPayload(result: PlaybookRunResult): JsonValue {
-    return omitUndefined({
-      outcome: result.outcome,
-      state: result.state,
-      stateId: result.state.stateId,
-      pendingCall: 'pendingCall' in result ? result.pendingCall : undefined,
-      output: 'output' in result ? result.output : undefined,
-      error: 'error' in result ? result.error : undefined,
-    });
-  }
-
-  private async trace(type: PlaybookTraceEvent['type'], payload: unknown, turnId?: number, callId?: string): Promise<void> {
-    this.enqueue(async () => {
-      await this.traceNow(type, payload, turnId, callId);
-    });
-    await this.drain();
+// ---------------------------------------------------------------------------
+// The controller captain-call strategy (slc/link.md §Captain adjudication,
+// controller form). The engine composes the prompt, traces every call as its
+// own captain.call pair on the shared serialized lane, and owns
+// control-plane latching; this strategy owns the hidden calls, the decision
+// validation with its one corrective re-ask, and the controller-port
+// submission.
+// ---------------------------------------------------------------------------
+
+const HIDDEN = { visibility: 'hidden' } as const;
+
+async function callHidden(
+  run: XStateCaptainStrategyRun<ValidatedCaptainOptions>,
+  prompt: string,
+): Promise<CaptainResult> {
+  try {
+    return await run.callCaptain(prompt, HIDDEN);
+  } catch (error) {
+    // DR-028: exactly one corrective re-ask of the same composed call on an
+    // empty `ok` result; a second such result follows the failure path from
+    // the boundary itself.
+    if (!run.isEmptyOkRetry(error)) throw error;
+    return await run.callCaptain(prompt, HIDDEN);
   }
+}
 
-  private async tracePreservingError(
-    type: PlaybookTraceEvent['type'],
-    payload: unknown,
-    preservedError: unknown,
-    turnId?: number,
-    callId?: string,
-  ): Promise<void> {
-    const previous = this.latchedControlError;
-    this.latchedControlError = undefined;
-    try {
-      await this.trace(type, payload, turnId, callId);
-    } catch (error) {
-      // Preserve the earlier boundary/control failure.
-    } finally {
-      this.latchedControlError = previous ?? preservedError;
-    }
+function requireControllerPort(
+  options: ValidatedCaptainOptions,
+): CaptainControllerPort {
+  if (options.controller === undefined) {
+    throw new Error(
+      'captain.playbook: the host-supplied controller port is required to settle a Boss turn (CAPPLAY-9); construct the runtime with options.controller',
+    );
   }
+  return options.controller;
+}
 
-  private async traceNow(type: PlaybookTraceEvent['type'], payload: unknown, turnId?: number, callId?: string): Promise<void> {
-    const session = this.requireSession();
-    const event: PlaybookTraceEvent = {
-      schemaVersion: 2,
-      sessionId: session.sessionId,
-      playbookId: session.playbookId,
-      rootSessionId: session.rootSessionId,
-      ...(session.parentSessionId === undefined ? {} : { parentSessionId: session.parentSessionId }),
-      ...(session.parentCallId === undefined ? {} : { parentCallId: session.parentCallId }),
-      depth: session.depth,
-      sequence: this.nextSequence(),
-      timestamp: Date.now(),
-      type,
-      ...(turnId === undefined ? {} : { turnId }),
-      ...(callId === undefined ? {} : { callId }),
-      payload: snapshotJsonValue(payload, `trace ${type}`),
-    };
-    await session.ports.emitTelemetry({ topic: 'playbook.trace', payload: event });
-  }
+async function submitSelection(
+  run: XStateCaptainStrategyRun<ValidatedCaptainOptions>,
+  selection: CaptainControllerSelection,
+): Promise<SettlementEvidence> {
+  const port = requireControllerPort(run.options);
+  const settlement = validateSettlement(
+    await port.submit(selection, run.signal),
+  );
+  run.signal.throwIfAborted();
+  return settlement;
+}
 
-  private enqueue(task: () => Promise<void>): void {
-    void this.emissionQueue.add(async () => {
-      try {
-        await task();
-      } catch (error) {
-        this.latchControlError(error);
-        throw error;
+async function runDecisionState(
+  run: XStateCaptainStrategyRun<ValidatedCaptainOptions>,
+): Promise<CaptainOutput> {
+  const input = run.input as unknown as CaptainInput;
+  const declaredActions = new Set(Object.keys(run.input.result));
+  let selection: CaptainControllerSelection;
+  if (input.parsedDecision !== undefined) {
+    // A parse-resolved turn enters with its decision already made: the
+    // injected decision object is the turn's decision and no decision call
+    // occurs (CAPTAIN-7, CAPPLAY-6). A malformed injection is a host bug —
+    // control-plane, not a corrective re-ask.
+    selection = selectionFromParsedDecision(
+      validateParsedActingDecision(input.parsedDecision),
+    );
+  } else {
+    const first = await callHidden(run, run.prompt);
+    const firstReading = readDecisionReply(
+      first.finalText ?? '',
+      run.options,
+      run.session.playbookId,
+      declaredActions,
+    );
+    if (firstReading.selection !== undefined) {
+      selection = firstReading.selection;
+    } else {
+      // CAPPLAY-18: exactly one corrective call appending the rejection
+      // reason and the restated reply contract to the same prompt.
+      const second = await callHidden(
+        run,
+        correctiveDecisionPrompt(run.prompt, firstReading.reason),
+      );
+      const secondReading = readDecisionReply(
+        second.finalText ?? '',
+        run.options,
+        run.session.playbookId,
+        declaredActions,
+      );
+      if (secondReading.selection === undefined) {
+        // A second malformed reply settles the turn as a Boss-appropriate
+        // failure reply with no action executed and the engagement stack
+        // untouched; the machine returns to its hub (CAPPLAY-18/19). The
+        // marker property routes the FSM's authored hub-recovery arm.
+        const failure = new Error(
+          `the decision reply stayed malformed after one corrective re-ask: ${secondReading.reason}`,
+        ) as Error & { controllerDecisionFailure?: boolean };
+        failure.name = 'ControllerDecisionError';
+        failure.controllerDecisionFailure = true;
+        throw run.recoverableFailure(failure);
       }
-    }).catch(() => undefined);
-  }
-
-  private drain(): Promise<void> {
-    return this.emissionQueue.onIdle().then(() => {
-      if (this.latchedControlError) throw this.latchedControlError;
-    });
-  }
-
-  private async bestEffortDisposeTrace(state: PlaybookState): Promise<void> {
-    try {
-      this.disposalTraceEmitted = true;
-      await this.trace('session.disposed', omitUndefined({ state, stateId: state.stateId }));
-      await this.drain();
-    } catch {
-      // Preserve the original initialization error.
+      selection = secondReading.selection;
     }
   }
+  const settlement = await submitSelection(run, selection);
+  return {
+    ...decisionOutputOf(selection),
+    settlement,
+  } as unknown as CaptainOutput;
+}
 
-  private reconstructActor(): void {
-    this.actor?.stop();
-    const session = this.requireSession();
-    const bridge = this.requireBridge();
-    this.actor = this.createActor(session, bridge);
-    this.actor.start();
-  }
-
-  private requireSession(): RuntimeSession {
-    if (!this.session) throw new Error('playbook runtime is not initialized');
-    return this.session;
-  }
-
-  private requireActor(): RootActor {
-    if (!this.actor) throw new Error('playbook runtime actor is not initialized');
-    return this.actor;
-  }
-
-  private requireBridge(): ReturnType<typeof createNestedPlaybookBridge<PlaybookInput>> {
-    if (!this.nestedBridge) throw new Error('nested bridge is not initialized');
-    return this.nestedBridge;
-  }
-
-  private nextSequence(): number {
-    this.sequence += 1;
-    return this.sequence;
-  }
-
-  private nextTurnId(): number {
-    this.turnId += 1;
-    return this.turnId;
-  }
-
-  private currentTraceTurnId(): number | undefined {
-    return this.boundaryTurnId;
-  }
+async function controllerCaptainStrategy(
+  run: XStateCaptainStrategyRun<ValidatedCaptainOptions>,
+): Promise<PlaybookActorOutput> {
+  if (run.input.stateId === 'deciding') {
+    return (await runDecisionState(run)) as unknown as PlaybookActorOutput;
+  }
+  // The prose states (answeringCommand, reporting): one hidden durable call
+  // whose validated text the host surfaces as captain speech through its
+  // presentation seam; the machine retains no reply prose (CAPPLAY-10) and
+  // the state settles with the default single-outcome `done` contract.
+  await callHidden(run, run.prompt);
+  return { guard: 'done' };
+}
 
-  private nextCallId(): number {
-    this.callId += 1;
-    return this.callId;
-  }
+// ---------------------------------------------------------------------------
+// Captain-pane status lines. The shell suppresses this runtime's human
+// status stream while forwarding structured telemetry (CAPPLAY-9); the
+// lines stay Boss-appropriate regardless. The parked hub and the shutdown
+// state emit no human status (slc/link.md §Session lifecycle).
+// ---------------------------------------------------------------------------
 
-  private latchControlError(error: unknown): void {
-    if (!this.latchedControlError) this.latchedControlError = error;
+function statusesForState(
+  state: PlaybookState,
+  context: Record<string, unknown>,
+): ScheduledStatus[] {
+  switch (state.stateId) {
+    case 'deciding':
+      return [{ message: '⤷ Captain: decide the Boss turn' }];
+    case 'answeringCommand':
+      return [{ message: '⤷ Captain: answer the command turn' }];
+    case 'reporting':
+      return [{ message: '⤷ Captain: compose the closing reply' }];
+    case 'failed': {
+      const lastError = normalizeErrorCompact(context.lastError);
+      return [
+        {
+          message: '◆ failed',
+          ...(lastError === undefined
+            ? {}
+            : { data: snapshotJsonValue({ lastError }, 'failed status data') }),
+        },
+      ];
+    }
+    default:
+      return [];
   }
 }
 
+// Internal export surface for verification and tests. Not part of the
+// stable public API; the leading underscore signals "subject to change."
 export const _internal = {
-  composeCaptainPrompt,
-  composePlayerPrompt,
-  parseJsonObjectLoose,
+  // No placeholder exists in any compiled Captain prompt: the labeled
+  // Boss-message, ControlView digest, and catalog digest blocks are
+  // shell-composed inside the hidden-control envelope (CAPTAIN-9), so the
+  // shared default composer emits the verbatim GEARS domain body.
+  composeCaptainPrompt: (input: CaptainInput): string =>
+    defaultComposeCaptainPrompt(input as unknown as PlaybookCaptainInput),
+  classifyControllerTurn,
+  readDecisionReply,
+  correctiveDecisionPrompt,
+  validateSettlement,
+  validateParsedActingDecision,
+  statusesForState,
+  normalizeError,
 };
 
-export function createPlaybookRuntime(options: PlaybookRuntimeOptions): PlaybookRuntime {
-  return new CaptainPlaybookRuntime(options);
+// The Captain-specific spec handed to the shared runtime factory
+// (slc/link.md §Output, DR-019). Generic machinery — actor wiring, boundary
+// tracing, lifecycle, abort, the parked-session snapshot, and the DR-029
+// describe/apply control surface — lives in @sublang/playbook/xstate-runtime.
+const runtimeSpec: XStatePlaybookRuntimeSpec<ValidatedCaptainOptions> = {
+  label: 'CAPTAIN',
+  compat: { artifactSchema: 1, runtimeAbi: RUNTIME_ABI },
+  snapshotOptions: snapshotCaptainOptions,
+  machineInput: (options) => ({ enabledPlaybooks: options.enabledPlaybooks }),
+  classifyBossText: (text, ports, signal, snapshotOrState, boundary, options) =>
+    classifyControllerTurn(
+      text,
+      ports,
+      signal,
+      snapshotOrState,
+      boundary,
+      options,
+    ) as Promise<import('xstate').EventObject | undefined>,
+  captainStrategy: controllerCaptainStrategy,
+  // CAPPLAY-10 / PBRT-52: the Captain's own ControlView context projection —
+  // the settlement evidence the machine retains for its decision and reply
+  // phases, and nothing else. `enabledPlaybooks` is the host-supplied
+  // catalog (an option value), and `parsedDecision` and `lastError` are
+  // control-plane scratch; none of the three is settlement evidence, so none
+  // is exported. Declaring the list here is what makes "Captain-visible
+  // context" an enumerated set rather than whatever the FSM happens to hold.
+  controlContextFields: [
+    'bossText',
+    'selectedAction',
+    'settlementStatus',
+    'settlementFacts',
+    'settlementReason',
+    'receiptDisposition',
+    'receiptReason',
+    'receiptError',
+    'leafStateSummary',
+  ],
+  statusesForState,
+};
+
+const createCaptainPlaybookRuntime: PlaybookRuntimeFactory<ValidatedCaptainOptions> =
+  createXStatePlaybookRuntime(captainMachine, runtimeSpec);
+
+export function createPlaybookRuntime(
+  options: PlaybookRuntimeOptions,
+): PlaybookRuntime {
+  return createCaptainPlaybookRuntime(options);
 }
 
-const factory: PlaybookRuntimeFactory<PlaybookRuntimeOptions> = createPlaybookRuntime;
+const factory: PlaybookRuntimeFactory<PlaybookRuntimeOptions> =
+  createPlaybookRuntime;
 
 export default factory;