@sublang/playbook 16.0.0 → 17.0.0

package/reference/sdlc/code.playbook/session-host.d.ts

@@ -48,7 +48,7 @@ export interface OpenSessionHostOptions {
   readonly store?: SharedSessionStore;
   readonly sessionsDir?: string;
   readonly sessionId?: string;
-  readonly mode?: 'new' | 'continue' | 'retry';
+  readonly mode?: 'new' | 'continue' | 'retry' | 'recover';
   readonly cwd?: string;
   readonly config?: SessionExecutionProjection;
   readonly plan?: any;
@@ -98,6 +98,9 @@ export interface SessionHostController {
    */
   submitShellAction(actionId: string): Promise<SessionRecovery>;
   retry(): Promise<SessionRecovery>;
+  /** Restore and report recorded uncertainty without running work; settled pauses require Boss input. Never discards work.
+   * After this live controller becomes uncertain, dispose and reopen with mode:'recover' first. */
+  recover(input?: string): Promise<SessionRecovery>;
   dispose(): Promise<void>;
 }
 export declare function openSessionHost(options: OpenSessionHostOptions): Promise<SessionHostController>;

package/reference/sdlc/code.playbook/session-store.d.ts

@@ -113,6 +113,18 @@ export interface SessionStructuralProjection {
   readonly players: readonly Readonly<Record<string, any>>[];
   readonly catalog: Readonly<Record<string, any>>;
 }
+export interface SessionStep {
+  readonly id: string;
+  readonly kind: 'player' | 'captain' | 'script' | 'preparation' | 'completion' | 'answer';
+  readonly stateId: string;
+  readonly runtimeSessionId: string;
+  readonly playbookId: string;
+  readonly result?: unknown;
+}
+export interface SessionProgressChange {
+  readonly snapshot?: SessionSnapshot | null;
+  readonly step?: SessionStep;
+}
 export interface SessionRecovery {
   readonly schemaVersion: 6;
   readonly kind: 'captain-session';
@@ -135,6 +147,7 @@ export interface SessionRecovery {
     readonly markedAt: string;
     readonly attemptedExecutionProjection: SessionExecutionProjection;
     readonly abandonment?: Readonly<Record<string, any>>;
+    readonly progress?: { readonly snapshot: SessionSnapshot | null; readonly steps: readonly SessionStep[]; readonly positionStepId?: string | null };
   };
 }
 export interface SessionReplayCheckpoint {
@@ -215,6 +228,7 @@ export interface PlaybookSessionLifecycle extends PlaybookSessionLease {
   abandonFreshSettled(options: { expected: SessionRecovery }): Promise<boolean>;
   beginTurn(options: { input: string; attemptId: string; attemptedExecutionProjection: SessionExecutionProjection }): Promise<SessionRecovery>;
   beginRetry(options: { expectedAttemptId: string; nextAttemptId: string }): Promise<SessionRecovery>;
+  recordProgress(change: SessionProgressChange): Promise<void>;
   settle(options: { attemptId: string; snapshot: SessionSnapshot; unresolvedEffects: readonly SessionUnresolvedEffect[]; retentionUpdates?: readonly SessionRetentionUpdate[] }): Promise<SessionRecovery>;
   discard(options: { attemptId: string }): Promise<SessionRecovery | undefined>;
   beginUnresolvedEffectAbandonment(options: any): Promise<any>;
@@ -255,3 +269,6 @@ export declare function validateCaptainSessionExecutionProjection(value: unknown
 export declare function validateCaptainSessionStructuralProjection(value: unknown): SessionStructuralProjection;
 export declare function assertCaptainSessionExecutionCompatible(structural: SessionStructuralProjection, execution: SessionExecutionProjection): SessionExecutionProjection;
 export declare function attachSessionHints(snapshot: SessionSnapshot, hints: SessionHints): SessionSnapshot;
+
+/** Whether discarding an uncertain turn restores its untouched baseline. */
+export declare function isUncertainTurnDiscardable(record: SessionRecovery): boolean;

package/reference/sdlc/code.playbook/session-store.js

@@ -117,6 +117,7 @@ function projectStatus(status) {
 
 export {
   createCaptainSessionStore as createSessionStore,
+  isUncertainTurnDiscardable,
   projectCaptainSessionStructure,
   validateCaptainSessionExecutionProjection,
   validateCaptainSessionStructuralProjection,

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

@@ -203,15 +203,15 @@ export type DecideOutput = {
  */
 export declare function authoredChildResult(error: unknown, expectedPlaybookId: string): PlaybookCallResult | undefined;
 export declare const decideMachine: import("xstate").StateMachine<DecideContext, import("xstate").AnyEventObject, {
-    [x: string]: import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<PlaybookOutput, PlaybookInput, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<PlayerOutput, PlayerInput, import("xstate").EventObject>> | undefined;
+    [x: string]: import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<PlayerOutput, PlayerInput, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<PlaybookOutput, PlaybookInput, import("xstate").EventObject>> | undefined;
 }, {
-    src: "playbook";
-    logic: import("xstate").PromiseActorLogic<PlaybookOutput, PlaybookInput, import("xstate").EventObject>;
-    id: string | undefined;
-} | {
     src: "player";
     logic: import("xstate").PromiseActorLogic<PlayerOutput, PlayerInput, import("xstate").EventObject>;
     id: string | undefined;
+} | {
+    src: "playbook";
+    logic: import("xstate").PromiseActorLogic<PlaybookOutput, PlaybookInput, import("xstate").EventObject>;
+    id: string | undefined;
 }, {
     type: "playbook.acceptedOutcome";
     params: {

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

@@ -152,15 +152,15 @@ export declare const devMachine: import("xstate").StateMachine<DevContext, {
     readonly answer: string;
     readonly questionId?: string;
 }, {
-    [x: string]: import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<PlaybookOutput, PlaybookInput, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<PlayerOutput, PlayerInput, import("xstate").EventObject>> | undefined;
+    [x: string]: import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<PlayerOutput, PlayerInput, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<PlaybookOutput, PlaybookInput, import("xstate").EventObject>> | undefined;
 }, {
-    src: "playbook";
-    logic: import("xstate").PromiseActorLogic<PlaybookOutput, PlaybookInput, import("xstate").EventObject>;
-    id: string | undefined;
-} | {
     src: "player";
     logic: import("xstate").PromiseActorLogic<PlayerOutput, PlayerInput, import("xstate").EventObject>;
     id: string | undefined;
+} | {
+    src: "playbook";
+    logic: import("xstate").PromiseActorLogic<PlaybookOutput, PlaybookInput, import("xstate").EventObject>;
+    id: string | undefined;
 }, {
     type: "playbook.acceptedOutcome";
     params: {

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

@@ -162,12 +162,8 @@ export declare const prMachine: import("xstate").StateMachine<PrContext, {
     readonly answer: string;
     readonly questionId?: "openPullRequest";
 }, {
-    [x: string]: import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<PlaybookOutput, PlaybookInput, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<PlayerOutput, PlayerInput, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<ScriptOutput, ScriptInput, import("xstate").EventObject>> | undefined;
+    [x: string]: import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<PlayerOutput, PlayerInput, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<ScriptOutput, ScriptInput, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<PlaybookOutput, PlaybookInput, import("xstate").EventObject>> | undefined;
 }, {
-    src: "playbook";
-    logic: import("xstate").PromiseActorLogic<PlaybookOutput, PlaybookInput, import("xstate").EventObject>;
-    id: string | undefined;
-} | {
     src: "player";
     logic: import("xstate").PromiseActorLogic<PlayerOutput, PlayerInput, import("xstate").EventObject>;
     id: string | undefined;
@@ -175,6 +171,10 @@ export declare const prMachine: import("xstate").StateMachine<PrContext, {
     src: "script";
     logic: import("xstate").PromiseActorLogic<ScriptOutput, ScriptInput, import("xstate").EventObject>;
     id: string | undefined;
+} | {
+    src: "playbook";
+    logic: import("xstate").PromiseActorLogic<PlaybookOutput, PlaybookInput, import("xstate").EventObject>;
+    id: string | undefined;
 }, {
     type: "playbook.acceptedOutcome";
     params: {

package/slc/gears2fsm.md

@@ -243,15 +243,16 @@ teardown event. The completion rule of
 output clause binds only where Source declares a terminal result, which a
 controller Source does not.
 The controller decision state's direct-Captain result contract discriminates
-the closed action set of DR-029 as extended by DR-038. Its guard discriminants
+the closed action set of DR-029 as extended by DR-038 and DR-069. Its guard discriminants
 are a stable compiler contract, not names the compiler may invent — `respond`, `resume`,
-`start`, `switch`, `dismiss`, `deliver`, and `runtime` — with each guard's
+`start`, `switch`, `dismiss`, `deliver`, and `runtime`, plus `recover` when Source declares recovery preparation — with each guard's
 required payload fields:
 
 - `respond` requires `text`;
 - `resume` requires `playbookId` and carries no `input`;
 - `start` and `switch` each require `playbookId` and `input`;
 - `runtime` requires `actionId`;
+- `recover`, when declared, requires no payload and selects host-owned preparation followed by runtime-validated continuation;
 - `dismiss` and `deliver` require none — a `deliver` result in particular
   carries no text payload: the host is authoritative for the delivered text,
   so the contract declares no field for it.
@@ -779,8 +780,7 @@ current event, not solely from the context that action will populate.
 For an omitted event value, use an existing context seed only where Source
 permits it; do not manufacture a required constructor value to satisfy a
 context-only entry guard. The linked runtime sends the entry event normally;
-its `entryEvent.contextField` declaration supports failure retry and does not
-copy fresh text into context before the guard.
+entry metadata does not copy fresh text into context before the guard.
 An entry event's copy action shall not clear per-run parameters the event omits: an absent optional field falls back to the existing (input-seeded) context value.
 The two surfaces shall not be collapsed. `BOSS_INTERRUPT` always carries its
 target id and may additionally carry typed Boss-supplied fields such as an
@@ -803,7 +803,7 @@ Boss-reply suspension, because its hub already receives every Boss turn and a
 clarifying question to Boss is a `respond` selection over the closed action
 set. The rule below is therefore universal over workflow states and silent
 about that class; in particular, adding `needsBossReply` to the controller
-decision state would add an eighth outcome to a closed seven-action contract
+decision state would add an unauthorized outcome to its closed controller contract
 whose guard discriminants [Setup](#setup) fixes, and is nonconformant.
 There is no source-level opt-in annotation and no `needsBossReply` result metadata in GEARS output.
 The FSM compiler shall preserve the GEARS blockquote as the state's domain `prompt` body and shall not inject any Boss-question instruction into `invoke.input.prompt`.

package/slc/link.md

@@ -65,7 +65,7 @@ node "<definition-directory>/materialize-link.mjs" --fsm "<source.fsm.ts>" --out
   "label": "EXAMPLE",
   "options": {},
   "inputMapping": {},
-  "entryEvent": { "type": "BOSS_TASK", "textField": "bossIntent", "contextField": "bossIntent" },
+  "entryEvent": { "type": "BOSS_TASK", "textField": "bossIntent" },
   "bossEvents": [],
   "outcomeAuthority": {
     "governedPlayerStates": {
@@ -196,6 +196,8 @@ interface PlaybookRuntime {
   handleBossInput(turn: {
     text: string;
     signal: AbortSignal;
+    /** Called synchronously just before accepting the event, at most once. */
+    onAccepted?: () => void;
   }): Promise<PlaybookRunResult>;
   resumePlaybookCall(input: {
     callId: string;
@@ -366,6 +368,7 @@ interface PlaybookEffectBoundary {
   readonly baseline: PlaybookRepositoryObservation;
   readonly after?: PlaybookRepositoryObservation;
   readonly physicalReceipt?: PlaybookRepositoryReceipt;
+  readonly restored?: PlaybookRepositoryObservation;
   readonly finalText?: string;
   readonly semanticCandidate?: JsonValue;
   readonly initialSemanticCandidate?: JsonValue;
@@ -405,6 +408,7 @@ type PlaybookEffectBoundaryStart = Omit<
   | 'finalText'
   | 'semanticCandidate'
   | 'initialSemanticCandidate'
+  | 'restored'
 >;
 
 type PlaybookEffectLogicalOperationStart = Omit<
@@ -466,6 +470,23 @@ interface PlaybookEffectLedgerCapability {
   ): Promise<PlaybookEffectLedger>;
 }
 
+interface PlaybookRecoveryCheckpoint {
+  readonly id?: string;
+  readonly stateId: string;
+  readonly prompt: string;
+  readonly machine: JsonValue;
+  readonly boundaryPrefix: number;
+  readonly result?: JsonValue;
+  readonly delivered?: true;
+}
+
+interface PlaybookStepRecord {
+  readonly id: string;
+  readonly kind: 'player' | 'captain' | 'script';
+  readonly stateId: string;
+  readonly result?: JsonValue;
+}
+
 interface PlaybookRuntimeSnapshot {
   schemaVersion: 4;
   playbookId: string;
@@ -496,6 +517,8 @@ interface PlaybookRuntimeSnapshot {
     readonly boundaryPrefix: number;
     readonly attemptId: string | null;
   };
+  /** Interrupted invocation, captured before its external call (DR-069). */
+  recoveryCheckpoint?: PlaybookRecoveryCheckpoint;
   suspendedCall?: PlaybookSuspendedCall;
 }
 
@@ -580,7 +603,7 @@ interface XStatePlaybookRuntimeConstruction<
 
 The shared type-only contract module shall export `PlaybookRepositoryDisposition`, `PlaybookRepositoryObservation`, `PlaybookRepositoryReceipt`, `PlaybookEffectBoundary`, `PlaybookEffectBoundaryStart`, `PlaybookEffectLogicalOperation`, `PlaybookEffectLedger`, `PlaybookEffectLedgerCommand`, `PlaybookEffectLedgerCommandBatch`, and `PlaybookEffectLedgerCapability`; the executable `@sublang/playbook/xstate-runtime` module shall export `assertPlaybookEffectLedger`, `emptyPlaybookEffectLedger`, and `isPlaybookEffectLedgerMonotonicExtension` over those types.
 That executable module shall also export the centralized schema-3 semantic surface: `PlaybookSemanticFieldAuthority`, `PlaybookSemanticOutcomeSpec`, `PlaybookSemanticEvidenceInput`, `PlaybookReconciledSemanticOutput`, `PlaybookRetainedSemanticEvidence`, `PlaybookSemanticReconciliationReason`, `PlaybookSemanticReconciliation`, `PlaybookSemanticCandidateStructureError`, and `reconcilePlaybookSemanticEvidence`.
-The pure reconciler shall accept the declared state-local outcomes, an unknown semantic candidate, and optional unknown `finalText`, repository receipt, and runtime-field evidence; shall return a detached frozen `resolved` or `deferred` decision with exact output and retained evidence, or an `unresolved` decision with retained evidence and one closed reason from `missing-presentation-evidence`, `missing-repository-receipt`, `invalid-repository-receipt`, `repository-disposition-mismatch`, `missing-effect-evidence`, `missing-runtime-evidence`, and `inconsistent-runtime-evidence`; and shall reserve `PlaybookSemanticCandidateStructureError` for candidate defects eligible for the bounded correction path rather than effect-evidence disagreement.
+The pure reconciler shall accept the declared state-local outcomes, an unknown semantic candidate, and optional unknown `finalText`, repository receipt, and runtime-field evidence; shall return a detached frozen `resolved` or `deferred` decision with exact output and retained evidence, or an `unresolved` decision with retained evidence and one closed reason from `no-matching-outcome`, `missing-presentation-evidence`, `missing-repository-receipt`, `invalid-repository-receipt`, `repository-disposition-mismatch`, `missing-effect-evidence`, `missing-runtime-evidence`, and `inconsistent-runtime-evidence`; and shall reserve `PlaybookSemanticCandidateStructureError` for candidate defects eligible for the bounded correction path rather than effect-evidence disagreement.
 The empty ledger shall be exactly `{ schemaVersion: 1, revision: 0, boundaries: [], logicalOperations: [] }`, and revision shall be zero if and only if both ordered ledgers are empty.
 The validator shall capture the complete supplied ledger once as detached frozen JSON and enforce every closed member, identity, ordering, receipt, cross-reference, correction-budget, and logical-operation invariant represented above.
 One optional host-owned UUID `cohortId` shall identify every member of exactly one contiguous, distinct-role, all-`unchanged` physical cohort in declared role order; every member shall share attempt, playbook, runtime-session, turn, canonical-worktree, and baseline identity and shall be uniformly started or uniformly complete, complete members shall carry the identical after observation and receipt, and the id shall never be reused by another group.
@@ -642,8 +665,8 @@ Boss text supplied by the entry event is not a required startup option unless So
 A generated entry guard that requires the text already in context is likewise
 not independent Source evidence; it is a producer defect when the entry action
 has yet to copy the event's text. Do not compensate with a required option or
-invented startup task. `entryEvent.contextField` supplies failure-retry text;
-it does not populate fresh entry context before FSM guards execute.
+invented startup task. Entry metadata does not populate fresh context before
+FSM guards execute. Interrupted-step checkpoints retain accepted input.
 A source-appropriate optional seed may remain, and genuine required bootstrap catalogs or other options shall not be erased or filled with invented defaults.
 
 Concrete player binding and prompt identity are host policy and shall not enter `PlaybookRuntimeOptions`, machine input, or the emitted artifact.
@@ -654,6 +677,7 @@ The host shall derive `promptIdentity` from the current effective model when pre
 
 ```typescript
 interface PlaybookPorts {
+  recordStep?(step: PlaybookStepRecord, position?: PlaybookRuntimeSnapshot): Promise<void>;
   callPlayer(
     roleId: string,
     prompt: string,
@@ -1283,6 +1307,13 @@ field.
 It shall reject an absent required field, an undeclared or extra field, a
 field supplied by the wrong authority, an invalid value, or any mutually
 inconsistent candidate before FSM delivery.
+When no outcome matches, a governed judge may instead return exactly
+`{ blocked: <nonempty explanation> }`.
+The shared reconciler retains this candidate and returns `no-matching-outcome`
+with its explanation as a `runtime-defect` cause; it authorizes neither a
+corrective judge nor an FSM outcome.
+Both shared and bespoke judge prompts shall state this alternative explicitly
+instead of forcing a match when the declared results are incomplete.
 
 For a non-deferred candidate, reconciliation shall require a complete durable
 physical receipt, or the complete cumulative logical receipt of a deferred
@@ -1356,7 +1387,8 @@ Two default adjudication strategies, in selection order:
   answer keyed to exactly one of the declared guards: a nongoverned player uses
   `{ guard, …structuralPayloadFields }`, while a governed schema-3 player uses
   `{ guard, …semanticOwnedPayloadFields }` and explicitly forbids every other
-  payload field. Both forms exclude the runtime-injected direct-Captain
+  payload field. The governed form also permits the blocked report above when no outcome matches.
+  Both forms exclude the runtime-injected direct-Captain
   `question` and `response` fields above. The prompt shall identify hidden control work,
   prohibit tool use, file inspection, and external evidence, direct the judge
   to decide only from the supplied actor output and declared outcomes, and
@@ -1887,7 +1919,8 @@ rehydrate it in a later process (DR-014). A runtime that implements either
 member shall implement both. When generated for a runtime whose host needs
 durability, the pair shall behave as follows.
 
-`exportSnapshot()` shall return `undefined` unless the runtime is at a safe
+A shared runtime may also receive the internal step-start snapshot for its current invocation or `exportSnapshot({child})` for a bridge-owned child during startup; these capture stopped positions without execution.
+Ordinary `exportSnapshot()` shall return `undefined` unless the runtime is at a safe
 capture point: initialized, not disposing or disposed, no active
 `handleBossInput`/`resumePlaybookCall` boundary, and the root actor at a
 quiescent state with actor status `active`.
@@ -2096,6 +2129,14 @@ interface PlaybookControlAction {
   reason?: PlaybookControlActionReason;   // why it is not `ready`
 }
 
+interface PlaybookRecoveryOffer {
+  prompt: string;
+  description?: string;
+  preparation?: string;
+  evidence?: JsonValue;
+  continuation: { kind: 'reply' } | { kind: 'runtime'; actionId: string };
+}
+
 interface PlaybookControlView {
   state: PlaybookState;
   stateDescription?: string;  // runtime-published meaning of the current state
@@ -2103,12 +2144,13 @@ interface PlaybookControlView {
   pendingQuestions: readonly PlaybookPendingBossQuestion[];
   lastError?: NormalizedError;
   actions: readonly PlaybookControlAction[];
+  recovery?: PlaybookRecoveryOffer;
 }
 
 type PlaybookControlReceipt =
   | { disposition: 'rejected'; reason: string }          // before any effect
   | { disposition: 'executed'; run: PlaybookRunResult }
-  | { disposition: 'failed'; error: NormalizedError };   // effects may exist
+  | { disposition: 'failed'; error: NormalizedError; run?: PlaybookRunResult };   // effects may exist
 
 // Optional PlaybookRuntime members — both or neither:
 describe?(): PlaybookControlView;
@@ -2129,6 +2171,7 @@ throw. The view carries the current normalized state descriptor, the state
 description defined below, the authored context projection defined below, the
 pending Boss questions with their stable ids, the last recorded error in
 normalized form, and the currently valid actions.
+The shared runtime owns the optional recovery context and invocation checkpoint; linked artifacts need no recovery-specific source, event, or actor.
 
 `stateDescription` is the runtime's own Boss-facing statement of what its
 current state means, taken from the same source state descriptions the action
@@ -2181,25 +2224,17 @@ parked-session snapshot uses (actor status `active`, quiescent, no pending
 nested call); anywhere else `actions` is empty while the rest of the view
 still describes the state.
 While effect-possible outcome evidence remains unresolved, the view shall omit its pending Boss questions and state description and shall replace every ordinary action with exactly `reconcile:unresolved-effect` labeled `Retry unresolved effect reconciliation` and `abandon:unresolved-effect` labeled `Abandon unresolved workflow attempt`.
-Otherwise two ordinary families exist, labeled from source state descriptions:
-
-- **Failure-state retry** — while the singular state id is the recoverable
-  failure state and the live snapshot accepts the retry event sourced below,
-  the runtime shall advertise `retry:<EVENT_TYPE>` replaying exactly that
-  event. Where the emitted module's entry-event declaration names the FSM
-  context member the machine's entry action copies the exact Boss text into
-  (DR-034), the retry event is that deterministic entry event built from the
-  live snapshot's member — excluded when the member is absent, not a string,
-  or blank, and never falling back to the record. Where it names no member,
-  the retry event is the recorded last classified event (the event a public
-  Boss boundary sent that drove the run into `failed`, kept with its recorded
-  payload), and there is none while the runtime holds none. The member is
-  declared, never inferred from a context member that happens to match the
-  entry event's text field.
+A valid invocation checkpoint is the only source of a retry: it retries only the stopped invocation after its effect checks, using `retry:<EVENT_TYPE>` for the same entry target or `retry:step` otherwise.
+Saved-result assessment (`retry:adjudication`) never repeats the player and is not offered for an output the machine has already received (checkpoint `delivered: true`), and verified read-only restoration (`retry:restored-step`) records an exact baseline check before replay.
+These retries have standing `ready`; an unsafe checkpoint grants no replay. Saved-result assessment withholds ordinary state jumps. Reconciliation and abandonment remain available whenever effects are unresolved, even alongside an eligible assessment or restoration.
+Ordinary retry and jump actions use source state descriptions and require assessment and unresolved-effect fences to be absent:
+
+- **Failure-state retry** — a valid invocation checkpoint retries that step only; a completed saved result is consumed without executing the operation again. No checkpoint means no retry. Legacy `entryEvent.contextField` metadata is ignored.
 - **Jump entries** — for each registered resumable state id whose
   explicit-state-jump event (`BOSS_INTERRUPT` with that `targetId`, optional
   textual fields omitted) the live snapshot accepts, guards included, the
-  runtime shall advertise `jump:<stateId>`.
+  runtime shall advertise `jump:<stateId>`, except that a jump out of a governed
+  failure must also pass the full failed-attempt effect check above.
 
 A candidate whose event requires a payload the runtime cannot source from
 recorded state shall be excluded from `actions` — `apply` never invents free
@@ -2209,9 +2244,8 @@ back to a target id or to the replayed event type, because a controller host
 names an executed or refused action by its label and never by its id, so an
 identifier used as a label defeats that substitution. A jump whose target
 publishes no description is therefore not advertised — borrowing another
-state's description would name the wrong state — and a retry falls back from
-its target's description to its own source state's, and is not advertised when
-neither exists.
+state's description would name the wrong state — and a retry requires the
+interrupted invocation's source description.
 
 `apply({ actionId, key, signal })` shall revalidate the action against the
 live state and settle `{ disposition: 'rejected', reason }` with no effect
@@ -2227,7 +2261,7 @@ pair, and may execute once the action is advertised — and a key whose call
 threw before reaching acceptance (lifecycle misuse, invalid input, a
 pre-acceptance abort, a rejected start-boundary sink) likewise records
 nothing, so a later call with that key may execute.
-Executing an ordinary retry or jump sends the validated event through the same actor drive as `handleBossInput` — state
+Executing a jump sends the validated event through the same actor drive as `handleBossInput` — state
 transitions, player/judge boundaries, statuses, and traces flow unchanged —
 and settles `executed` with the projected run result, or `failed` with the
 normalized error when the run settles in the failure state, aborts, or a
@@ -2260,12 +2294,18 @@ signal's own abort reason, in which case it evidences the cancellation and is
 dropped, not latched
 ([DR-036](../specs/decisions/036-coherent-abort-settlement.md)).
 
-The recorded receipts and the recorded last classified event are
-process-local: the durable runtime snapshot persists neither. A restored
-runtime therefore advertises the retry of a declared entry-event source
-immediately — that payload rides the persisted machine snapshot — while a
-module declaring no source advertises a retry again only after its next
-classified event.
+Recorded control receipts are process-local. Invocation checkpoints retain the original input and accepted output across restoration; a restored runtime offers only the currently valid step controls.
+
+The optional `PlaybookPorts.recordStep(step, position?)` lets a durable host save ordinary work without understanding machine internals.
+The shared runtime records player, direct-Captain and script starts before execution and their actor results before advancing.
+The runtime owns the complete stopped position, including accepted Boss input; the host joins nested frames and atomically stores starts and results; retention changes wait for settlement.
+An invocation inside a parallel region records its start and result without a single-invocation recovery position, including when only its last region is resuming.
+Sequential invocations after the join use ordinary checkpoints.
+A custom runtime that cannot provide a position remains runnable, but a crash without a supported position returns to Captain with recorded work preserved.
+Automatic recovery requires a failed or quiescent outcome produced by an operation in the same turn; resuming or adopting an older stop starts no preparation.
+The store identifies the step that owns a saved position, so a consumed result cannot be attached to a later stopped snapshot.
+Only internal step-start capture creates a synthetic failed position; public snapshot capture returns the actual stopped state.
+Opening or reporting an interrupted run executes no work; Boss chooses the next action after checking outside effects and stopping any surviving worker.
 
 ## Abort
 
@@ -2374,6 +2414,10 @@ The runtime shall emit, at minimum:
   semantics matter to Boss — e.g., `respondToReview`, `failed`). The
   default is to emit on every transition and let the host filter; hosts
   may bind a stricter rule.
+  Mark both a player-question status and its waiting marker with status data
+  `{ kind: "boss-question" }`; the session Captain replaces those statuses with
+  its own clear reply, using the complete pending question from the control view.
+  Keep the original question in state and telemetry, and deliver Boss input unchanged.
 - One `emitTelemetry` per state transition under a namespaced topic
   (recommended `playbook.fsm.state`), with structured `from`, `to`, `event`,
   `previousState`, and `state` fields. Descriptors carry the JSON-safe XState

package/src/runtime.d.ts

@@ -173,10 +173,13 @@ export type PlaybookRunResult = {
     pendingCall: PlaybookPendingCall;
 };
 export interface PlaybookPorts {
+    /** Acknowledge the durable start before work and its result before transition. */
+    recordStep?(step: PlaybookStepRecord, position?: PlaybookRuntimeSnapshot): Promise<void>;
     callPlayer(roleId: string, prompt: string, signal: AbortSignal, options: PlayerCallOptions): Promise<PlayerResult>;
     callCaptain(prompt: string, signal: AbortSignal, options: CaptainCallOptions): Promise<CaptainResult>;
     callJudge(prompt: string, signal: AbortSignal): Promise<string>;
     callPlaybook(request: PlaybookCallRequest, signal: AbortSignal): Promise<PlaybookCallStart>;
+    /** Mark question presentation with data.kind = "boss-question"; Captain relays it from pendingQuestions. */
     emitStatus(message: string, data?: unknown): Promise<void>;
     emitTelemetry(event: {
         topic: string;
@@ -275,6 +278,8 @@ export interface PlaybookEffectBoundary {
     readonly baseline: PlaybookRepositoryObservation;
     readonly after?: PlaybookRepositoryObservation;
     readonly physicalReceipt?: PlaybookRepositoryReceipt;
+    /** A later exact restoration permits replay of this standalone read-only call. */
+    readonly restored?: PlaybookRepositoryObservation;
     readonly finalText?: string;
     readonly semanticCandidate?: JsonValue;
     readonly initialSemanticCandidate?: JsonValue;
@@ -286,7 +291,7 @@ export interface PlaybookEffectBoundary {
     readonly logicalOperationId?: string;
 }
 /** One physical boundary before the host assigns attempt and sequence data. */
-export type PlaybookEffectBoundaryStart = Omit<PlaybookEffectBoundary, 'sequence' | 'attemptId' | 'attemptNumber' | 'after' | 'physicalReceipt' | 'finalText' | 'semanticCandidate' | 'initialSemanticCandidate'>;
+export type PlaybookEffectBoundaryStart = Omit<PlaybookEffectBoundary, 'sequence' | 'attemptId' | 'attemptNumber' | 'after' | 'physicalReceipt' | 'restored' | 'finalText' | 'semanticCandidate' | 'initialSemanticCandidate'>;
 /** One deferred logical operation spanning its ordered physical boundaries. */
 export interface PlaybookEffectLogicalOperation {
     readonly sequence: number;
@@ -388,8 +393,26 @@ export interface PlaybookRuntimeSnapshot {
         readonly boundaryPrefix: number;
         readonly attemptId: string | null;
     };
+    /** Interrupted invocation, captured before its external call (DR-069). */
+    recoveryCheckpoint?: PlaybookRecoveryCheckpoint;
     suspendedCall?: PlaybookSuspendedCall;
 }
+export interface PlaybookRecoveryCheckpoint {
+    readonly id?: string;
+    readonly stateId: string;
+    readonly prompt: string;
+    readonly machine: JsonValue;
+    readonly boundaryPrefix: number;
+    /** Completed actor output supplied by the execution journal on restore. */
+    readonly result?: JsonValue;
+    readonly delivered?: true;
+}
+export interface PlaybookStepRecord {
+    readonly id: string;
+    readonly kind: 'player' | 'captain' | 'script';
+    readonly stateId: string;
+    readonly result?: JsonValue;
+}
 export type PlaybookControlStanding = 'ready' | 'no-op' | 'blocked';
 export type PlaybookControlActionReason = 'receipt-complete';
 export interface PlaybookControlAction {
@@ -398,6 +421,20 @@ export interface PlaybookControlAction {
     standing?: PlaybookControlStanding;
     reason?: PlaybookControlActionReason;
 }
+export interface PlaybookRecoveryOffer {
+    prompt: string;
+    description?: string;
+    /** Runtime-owned conditions to satisfy; these never authorize task completion. */
+    preparation?: string;
+    /** Saved observations and result choices for diagnosing the stopped step. */
+    evidence?: JsonValue;
+    continuation: {
+        kind: 'reply';
+    } | {
+        kind: 'runtime';
+        actionId: string;
+    };
+}
 export interface PlaybookControlView {
     state: PlaybookState;
     stateDescription?: string;
@@ -405,6 +442,8 @@ export interface PlaybookControlView {
     pendingQuestions: readonly PlaybookPendingBossQuestion[];
     lastError?: NormalizedError;
     actions: readonly PlaybookControlAction[];
+    /** Context only for an explicitly authorized Captain preparation call. */
+    recovery?: PlaybookRecoveryOffer;
 }
 export type PlaybookControlReceipt = {
     disposition: 'rejected';
@@ -415,13 +454,16 @@ export type PlaybookControlReceipt = {
 } | {
     disposition: 'failed';
     error: NormalizedError;
+    run?: PlaybookRunResult;
 };
 export interface PlaybookRetainedGenerationMetadata {
     readonly unfinishedFinalStateIds: readonly string[];
 }
 export interface PlaybookRuntime {
     init(session: PlaybookSession): Promise<void>;
-    exportSnapshot?(): PlaybookRuntimeSnapshot | undefined;
+    exportSnapshot?(checkpoint?: {
+        child?: PlaybookPendingCall;
+    }): PlaybookRuntimeSnapshot | undefined;
     restore?(session: PlaybookSession, snapshot: PlaybookRuntimeSnapshot): Promise<void>;
     adopt?(session: PlaybookSession, snapshot: PlaybookRuntimeSnapshot, context: PlaybookAdoptionContext): Promise<void>;
     readonly retainedGenerationMetadata?: PlaybookRetainedGenerationMetadata;
@@ -447,6 +489,8 @@ export interface PlaybookRuntime {
     handleBossInput(turn: {
         text: string;
         signal: AbortSignal;
+        /** Called synchronously just before accepting the event, at most once. */
+        onAccepted?: () => void;
     }): Promise<PlaybookRunResult>;
     resumePlaybookCall(input: {
         callId: string;