@sublang/playbook 12.2.2 → 13.0.0

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

@@ -103,6 +103,11 @@ type SnapshotAgentEnvelope = DeepReadonly<
 type PlayerLedgerSnapshotEntry = DeepReadonly<PlayerLedgerEntry>;
 
 export interface PlaybookCaptainDeps {
+  continuity?: {
+    beforeCall(participantId: string): Promise<void>;
+    acknowledged(participantId: string, token: string): void;
+    reset(participantId: string, reason: 'missing_hint' | 'rejected_hint'): Promise<void>;
+  };
   loadModule?: (specifier: string) => Promise<unknown>;
   createSessionId?: () => string;
   hostCapabilities?: Readonly<
@@ -549,8 +554,24 @@ const INTERNAL_CAPTAIN_ID = 'captain';
 const UUID_PATTERN =
   /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 const PLAYER_ID_PATTERN = /^[a-z][a-z0-9_-]*(?:\.[a-z][a-z0-9_-]*)*$/;
-const ROLE_ID_PATTERN = /^[a-z][a-z0-9_-]*$/;
+const ROLE_ID_WHITESPACE_OR_CONTROL = /[\s\p{Cc}]/u;
 const HOST_CAPABILITIES_OPTION_KEY = 'hostCapabilities';
+
+// PBCLI-4: a local role id is its source role name lowercased by Unicode case
+// mapping — nonempty, free of whitespace and control characters, and equal to
+// its own lowercase form. The rule restricts neither script nor alphabet, so
+// `coder`, `编码者`, and `作者` are canonical while `Coder` is not. Callers
+// enforce the reserved `captain` name separately. The CLI host owns the same
+// predicate in `bin/session-store.js`; that private module already imports
+// this one, so the text is repeated here rather than cycled back.
+function isCanonicalLocalRoleId(value: unknown): value is string {
+  return (
+    typeof value === 'string' &&
+    value.length > 0 &&
+    value === value.toLowerCase() &&
+    !ROLE_ID_WHITESPACE_OR_CONTROL.test(value)
+  );
+}
 const UNRESOLVED_EFFECT_RECONCILIATION_ACTION_ID =
   'reconcile:unresolved-effect';
 const UNRESOLVED_EFFECT_ABANDONMENT_ACTION_ID = 'abandon:unresolved-effect';
@@ -1452,9 +1473,7 @@ function isValidRegistryEntry(
     !Array.isArray(e.requiredRoleIds) ||
     e.requiredRoleIds.some(
       (role) =>
-        typeof role !== 'string' ||
-        !ROLE_ID_PATTERN.test(role) ||
-        role === INTERNAL_CAPTAIN_ID,
+        !isCanonicalLocalRoleId(role) || role === INTERNAL_CAPTAIN_ID,
     ) ||
     new Set(e.requiredRoleIds).size !== e.requiredRoleIds.length ||
     !Array.isArray(e.concurrentRoleSets)
@@ -1773,7 +1792,7 @@ function snapshotFrameRoleBindings(
   const bindings = snapshotRecord(value, path);
   return Object.fromEntries(
     Object.entries(bindings).map(([roleId, raw]) => {
-      if (!ROLE_ID_PATTERN.test(roleId) || roleId === INTERNAL_CAPTAIN_ID) {
+      if (!isCanonicalLocalRoleId(roleId) || roleId === INTERNAL_CAPTAIN_ID) {
         throw new TypeError(`${path} has invalid role id ${JSON.stringify(roleId)}`);
       }
       const playerId = snapshotString(raw, `${path}.${roleId}`);
@@ -1805,6 +1824,7 @@ function normalizeHostPlayerResult(
     'resumeToken',
     'finalText',
     'error',
+    'errorCode',
   ]);
   const normalized: Record<string, unknown> = {};
   for (const key of Reflect.ownKeys(descriptors)) {
@@ -1827,13 +1847,18 @@ function normalizeHostPlayerResult(
   const record = snapshotRecord(snapshotJsonValue(normalized, path), path);
   rejectSnapshotKeys(
     record,
-    ['status', 'playerId', 'turnId', 'resumeToken', 'finalText', 'error'],
+    ['status', 'playerId', 'turnId', 'resumeToken', 'finalText', 'error', 'errorCode'],
     path,
   );
   if (record.playerId !== expectedPlayerId) {
     throw new TypeError(`${path}.playerId does not match the requested player`);
   }
   snapshotInteger(record.turnId, `${path}.turnId`, 1);
+  if (record.errorCode !== undefined &&
+      (record.errorCode !== 'SESSION_RESUME_REJECTED' ||
+       record.status !== 'error' || record.resumeToken !== undefined)) {
+    throw new TypeError(`${path}.errorCode is not a definite resume rejection`);
+  }
   return validatePlayerResult(
     {
       status: record.status,
@@ -2974,6 +2999,7 @@ export function createPlaybookCaptainShell(
     PlaybookCaptainDeps['createCaptainRuntime']
   > = deps.createCaptainRuntime ?? createDefaultCaptainRuntime;
   const unresolvedEffectSettlement = deps.unresolvedEffectSettlement;
+  const continuity = deps.continuity;
   let pendingHostCapabilities = deps.hostCapabilities;
   let currentEffectLedger = () => emptyPlaybookEffectLedger();
   // The returned shell must not retain the caller's aggregate dependency
@@ -4362,16 +4388,37 @@ export function createPlaybookCaptainShell(
       try {
         let rawResult: unknown;
         try {
-          rawResult = await trackHostCall(
-            frame,
-            classifySettingsCall(() =>
-              context.callPlayer(binding.playerId, prompt, {
-                resume: options.resume,
-                settings,
-              }),
-            ),
-          );
-          hostResolved = true;
+          const call = async (resume: string | false): Promise<unknown> => {
+            await continuity?.beforeCall(binding.playerId);
+            signal.throwIfAborted();
+            const raw = await trackHostCall(
+              frame,
+              classifySettingsCall(() =>
+                context.callPlayer(binding.playerId, prompt, { resume, settings }),
+              ),
+            );
+            hostResolved = true;
+            return raw;
+          };
+          if (options.resume === false) {
+            await continuity?.reset(binding.playerId, 'missing_hint');
+          }
+          rawResult = await call(options.resume);
+          normalizeHostPlayerResult(rawResult, binding.playerId);
+          if (typeof options.resume === 'string' && options.resume.length > 0 &&
+              Object.getOwnPropertyDescriptor(rawResult as object, 'errorCode')?.value ===
+                'SESSION_RESUME_REJECTED') {
+            if (playerTransactions.get(binding.playerId) !== calling ||
+                calling.abandoned || signal.aborted || activeTurn !== admittedTurn ||
+                frame.playerCallScope !== scope || !frames.includes(frame)) {
+              signal.throwIfAborted();
+              throw new Error(`${frameLabel(frame)} player rejection arrived after its runtime operation ended`);
+            }
+            delete ledger.resumeToken;
+            await continuity?.reset(binding.playerId, 'rejected_hint');
+            hostResolved = false;
+            rawResult = await call(false);
+          }
         } catch (error) {
           if (error instanceof AgentSettingsPreflightError) {
             if (
@@ -4725,6 +4772,9 @@ export function createPlaybookCaptainShell(
       try {
         if (resumeToken === undefined) delete ledger.resumeToken;
         else ledger.resumeToken = resumeToken;
+        if (pending.status === 'ok' && resumeToken !== undefined) {
+          continuity?.acknowledged(binding.playerId, resumeToken);
+        }
       } finally {
         playerTransactions.delete(binding.playerId);
       }
@@ -5177,6 +5227,12 @@ export function createPlaybookCaptainShell(
         childSessionId: frame.sessionId,
         state: result.state,
         ...(result.output !== undefined ? { output: result.output } : {}),
+        // DR-048: the child runtime read this record from its own artifact;
+        // the host relays it unchanged so the caller's bridge can route a
+        // failure terminal without knowing the callee's output fields.
+        ...(result.terminal !== undefined
+          ? { terminal: result.terminal }
+          : {}),
       };
     }
     if (result.outcome === 'aborted') {
@@ -6141,7 +6197,7 @@ export function createPlaybookCaptainShell(
   class CaptainContinuityError extends Error {
     constructor(cause: unknown) {
       super(
-        'the session Captain conversation could not be resynchronized after one reseeded re-issue',
+        'the session Captain conversation lost continuity',
         { cause },
       );
       this.name = 'CaptainContinuityError';
@@ -6165,8 +6221,11 @@ export function createPlaybookCaptainShell(
     finalText?: string;
     resumeToken?: string;
     error?: string;
+    errorCode?: 'SESSION_RESUME_REJECTED';
   }> => {
     const queued = captainQueue.add(async () => {
+      context.signal.throwIfAborted();
+      await continuity?.beforeCall('captain');
       context.signal.throwIfAborted();
       attempt.providerBoundaryEntered = true;
       const result = await classifySettingsCall(() =>
@@ -6185,14 +6244,12 @@ export function createPlaybookCaptainShell(
       finalText?: string;
       resumeToken?: string;
       error?: string;
+      errorCode?: 'SESSION_RESUME_REJECTED';
     }>;
   };
 
-  // CAPTAIN-35: unsynchronized when the call throws, returns non-`ok`, or
-  // returns `ok` without a token. Exactly one re-issue on a fresh conversation
-  // seeded with the reseed digest plus the current ControlView digest. A
-  // conversation that is owed a reseed carries the digest on its very next
-  // call, so the turn after a failed reseed starts seeded rather than blank.
+  // Only proven pre-execution rejection permits an immediate fresh call.
+  // Other continuity loss leaves the journal reseed for the next Boss turn.
   const durableCall = async (
     context: CaptainContext,
     compose: (options: { reseedDigest?: string }) => string,
@@ -6209,10 +6266,11 @@ export function createPlaybookCaptainShell(
     const representedJournalSeq = journalSeq;
     const firstAttempt = { providerBoundaryEntered: false };
     let result:
-      | { status: string; finalText?: string; resumeToken?: string; error?: string }
+      | { status: string; finalText?: string; resumeToken?: string; error?: string; errorCode?: 'SESSION_RESUME_REJECTED' }
       | undefined;
     let failure: unknown;
     try {
+      if (resume === false) await continuity?.reset('captain', 'missing_hint');
       result = await rawDurableCall(
         context,
         compose(
@@ -6259,9 +6317,10 @@ export function createPlaybookCaptainShell(
       failure !== undefined ||
       result === undefined ||
       result.status !== 'ok' ||
-      result.resumeToken === undefined;
+      typeof result.resumeToken !== 'string' || result.resumeToken.trim().length === 0;
     if (!unsynchronized) {
       conversation = { kind: 'pinned', token: result!.resumeToken! };
+      continuity?.acknowledged('captain', result!.resumeToken!);
       if (activeTurn) {
         activeTurn.captainSyncedJournalSeq = representedJournalSeq;
       }
@@ -6277,9 +6336,16 @@ export function createPlaybookCaptainShell(
     // stays `needsSeeding` until a call comes back with a token, so a reseed
     // that itself fails leaves the obligation standing for the next turn.
     conversation = { kind: 'needsSeeding' };
+    if (typeof resume !== 'string' || resume.length === 0 ||
+        result?.status !== 'error' || result.errorCode !== 'SESSION_RESUME_REJECTED') {
+      throw markControlFailure(new CaptainContinuityError(
+        failure ?? result?.error ?? 'callCaptain did not establish continuation',
+      ));
+    }
+    await continuity?.reset('captain', 'rejected_hint');
     const recap = reseedDigest();
     let reissued:
-      | { status: string; finalText?: string; resumeToken?: string; error?: string }
+      | { status: string; finalText?: string; resumeToken?: string; error?: string; errorCode?: 'SESSION_RESUME_REJECTED' }
       | undefined;
     const reissueAttempt = { providerBoundaryEntered: false };
     try {
@@ -6299,7 +6365,7 @@ export function createPlaybookCaptainShell(
       }
       throw markControlFailure(new CaptainContinuityError(error));
     }
-    if (reissued.status !== 'ok' || reissued.resumeToken === undefined) {
+    if (reissued.status !== 'ok' || typeof reissued.resumeToken !== 'string' || reissued.resumeToken.trim().length === 0) {
       throw markControlFailure(
         new CaptainContinuityError(
           reissued.error ??
@@ -6308,6 +6374,7 @@ export function createPlaybookCaptainShell(
       );
     }
     conversation = { kind: 'pinned', token: reissued.resumeToken };
+    continuity?.acknowledged('captain', reissued.resumeToken);
     if (activeTurn) activeTurn.captainSyncedJournalSeq = journalSeq;
     return {
       ...(reissued.finalText !== undefined

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

@@ -0,0 +1,75 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+
+import type { PlaybookCaptainShell, PlaybookCaptainShellSnapshot } from './playbook-captain.js';
+import type { PlaybookEffectLedger } from './host-capabilities.js';
+import type { PlaybookSessionLifecycle, SessionExecutionProjection, SessionStructuralProjection, SessionFreshBoundary, SessionRecovery } from './session-store.js';
+
+export interface SessionHost {
+  readonly shell: PlaybookCaptainShell;
+  readonly host: { runBossTurn(input: string): Promise<void>; abortActiveTurn(): void; dispose(): Promise<void>; [key: string]: any };
+  readonly snapshot: PlaybookCaptainShellSnapshot;
+  reconcileRepositoryEffects(): Promise<PlaybookEffectLedger>;
+}
+export interface SessionHostOptions {
+  readonly config: SessionExecutionProjection;
+  readonly sessionId?: string;
+  readonly cwd: string;
+  readonly sessionLease: PlaybookSessionLifecycle;
+  readonly loadModule: (specifier: string) => Promise<any>;
+  readonly restoreSnapshot?: PlaybookCaptainShellSnapshot;
+  readonly reconcileUncertainTurnReplay?: boolean;
+  readonly signal?: AbortSignal;
+  readonly [key: string]: any;
+}
+export declare function createCaptainSessionHost(options: SessionHostOptions): Promise<SessionHost>;
+export declare function installRetainedGenerationsForLaunch(options: {
+  lease: PlaybookSessionLifecycle;
+  shell: PlaybookCaptainShell;
+  freshBoundary?: SessionFreshBoundary;
+  onFreshRecord?: (record: SessionRecovery | undefined) => void;
+  onLegacyRecord?: (record: any) => void | Promise<void>;
+  onInvalidRecord?: (record: any) => void | Promise<void>;
+  retainedGenerations?: Readonly<Record<string, any>>;
+  reconcileRepositoryEffects?: () => Promise<PlaybookEffectLedger>;
+}): Promise<Readonly<Record<string, any>>>;
+export declare function executionConfigFromPlan(plan: any): SessionExecutionProjection;
+export declare function validateFrozenExecutionConfig(structural: SessionStructuralProjection, execution: SessionExecutionProjection, dependencies: { loadModule: (specifier: string) => Promise<any>; prepareRegistryModule?: (request: {id: string; from: string; authoredFrom: string}) => Promise<string | void> }): Promise<SessionExecutionProjection>;
+export declare function driveHeadlessCaptainTurn(options: any): Promise<any>;
+export declare function normalizeLaunchPlan(top: any, options?: any): Promise<any>;
+export declare function loadLaunchPlan(options: any): Promise<any>;
+export declare function composeGenericConfig(top: any, loadModule: (specifier: string) => Promise<any>, configPath?: string): Promise<any>;
+export declare function projectTmuxConfig(plan: any): any;
+export declare function resolveLaunchSessionsDir(options: any): string;
+
+import type { SharedSessionStore, ReplayStreamStatus, ReplayStreamEntry, SessionGraph } from './session-store.js';
+export interface OpenSessionHostOptions {
+  readonly store?: SharedSessionStore;
+  readonly sessionsDir?: string;
+  readonly sessionId?: string;
+  readonly mode?: 'new' | 'continue' | 'retry';
+  readonly cwd?: string;
+  readonly config?: SessionExecutionProjection;
+  readonly plan?: any;
+  readonly loadModule?: (specifier: string) => Promise<any>;
+  readonly prepareRegistryModule?: (request: {id: string; from: string; authoredFrom: string}) => Promise<string | void>;
+  readonly observers?: readonly { onRecord?(record: any): void | Promise<void> }[];
+  readonly onStoredRecord?: (record: ReplayStreamEntry, status: ReplayStreamStatus) => void | Promise<void>;
+  readonly onCheckpoint?: (record: SessionRecovery) => void | Promise<void>;
+  readonly onIncomplete?: () => void | Promise<void>;
+  readonly graphs?: readonly { playbookId: string; graph: SessionGraph | null }[];
+  readonly initialVisible?: readonly string[];
+  readonly [key: string]: any;
+}
+export interface SessionHostController {
+  readonly sessionId: string;
+  readonly host: SessionHost['host'];
+  readonly shell: PlaybookCaptainShell;
+  readonly lease: PlaybookSessionLifecycle;
+  read(): Promise<SessionRecovery | undefined>;
+  handleBossTurn(input: string): Promise<SessionRecovery>;
+  retry(): Promise<SessionRecovery>;
+  dispose(): Promise<void>;
+}
+export declare function openSessionHost(options: OpenSessionHostOptions): Promise<SessionHostController>;
+export declare function discardSessionUncertain(store: SharedSessionStore, sessionId: string): Promise<SessionRecovery | undefined>;

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

@@ -0,0 +1,18 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+
+export {
+  createCaptainSessionHost,
+  installRetainedGenerationsForLaunch,
+  executionConfigFromPlan,
+  validateFrozenExecutionConfig,
+  driveHeadlessCaptainTurn,
+} from './bin/run.js';
+export {
+  normalizeLaunchPlan,
+  loadLaunchPlan,
+  composeGenericConfig,
+  projectTmuxConfig,
+  resolveLaunchSessionsDir,
+} from './bin/launch-config.js';
+export { openSessionHost, discardSessionUncertain } from './bin/session-host.js';

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

@@ -48,7 +48,7 @@ export type ReplayStreamStatus =
 export interface PlaybookSessionSummary {
   readonly schemaVersion: number;
   readonly sessionId: string;
-  readonly state: 'settled' | 'uncertain';
+  readonly state: 'settled' | 'uncertain' | 'history-only';
   readonly cwd: string;
   readonly updatedAt: string;
 }
@@ -80,3 +80,178 @@ export interface PlaybookSessionLease {
   streamStatus(): ReplayStreamStatus;
   release(): Promise<ReplayStreamStatus>;
 }
+
+/** Recovery data is interpreted by the version-aware codec, not by live runtimes. */
+export type SessionSnapshot = Readonly<Record<string, any>>;
+export interface SessionEffectLedger {
+  readonly schemaVersion: 1;
+  readonly revision: number;
+  readonly boundaries: readonly Readonly<Record<string, any>>[];
+  readonly logicalOperations: readonly Readonly<Record<string, any>>[];
+}
+export interface SessionUnresolvedEffect {
+  readonly classification: 'one-descendant-commit' | 'multiple-commits' |
+    'rewritten-or-non-descendant' | 'worktree-only-change' |
+    'concurrent-or-foreign-change' | 'observation-ambiguous' | 'incomplete';
+  readonly baselineHead: string;
+  readonly afterHead?: string;
+  readonly commitOid?: string;
+}
+export type SessionRetentionUpdate =
+  | { readonly kind: 'retain'; readonly rootPlaybookId: string; readonly generation: Readonly<Record<string, any>> }
+  | { readonly kind: 'clear'; readonly rootPlaybookId: string };
+
+export interface SessionExecutionProjection {
+  readonly schemaVersion: 2;
+  readonly captain: Readonly<Record<string, any>>;
+  readonly players: readonly Readonly<Record<string, any>>[];
+  readonly catalog: Readonly<Record<string, any>>;
+}
+export interface SessionStructuralProjection {
+  readonly schemaVersion: 1;
+  readonly captain: Readonly<Record<string, any>>;
+  readonly players: readonly Readonly<Record<string, any>>[];
+  readonly catalog: Readonly<Record<string, any>>;
+}
+export interface SessionRecovery {
+  readonly schemaVersion: 6;
+  readonly kind: 'captain-session';
+  readonly sessionId: string;
+  readonly cwd: string;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+  readonly state: 'settled' | 'uncertain';
+  readonly structuralProjection: SessionStructuralProjection;
+  readonly lastAppliedExecutionProjection: SessionExecutionProjection;
+  readonly snapshot: SessionSnapshot;
+  readonly effectLedger: SessionEffectLedger;
+  readonly unresolvedEffects: readonly SessionUnresolvedEffect[];
+  readonly retainedGenerations?: Readonly<Record<string, any>>;
+  readonly uncertain?: {
+    readonly input: string;
+    readonly attemptId: string;
+    readonly attemptNumber: number;
+    readonly baseUpdatedAt: string | null;
+    readonly markedAt: string;
+    readonly attemptedExecutionProjection: SessionExecutionProjection;
+    readonly abandonment?: Readonly<Record<string, any>>;
+  };
+}
+export interface SessionReplayCheckpoint {
+  readonly seq: number;
+  readonly sha256: string;
+  readonly incomplete: boolean;
+}
+export type SessionManifest = Omit<SessionRecovery, 'schemaVersion'> & {
+  readonly schemaVersion: 7;
+  readonly replay: SessionReplayCheckpoint;
+  readonly contextSeq: number;
+} | {
+  readonly schemaVersion: 7;
+  readonly kind: 'captain-session';
+  readonly state: 'history-only';
+  readonly sessionId: string;
+  readonly cwd: string;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+  readonly replay: SessionReplayCheckpoint;
+  readonly contextSeq: number | null;
+  readonly reason: string;
+};
+export type StoredSessionManifest = SessionManifest | {
+  readonly schemaVersion: number;
+  readonly sessionId: string;
+  readonly cwd?: unknown;
+  readonly [key: string]: unknown;
+};
+export interface SessionGraph {
+  readonly initial: string;
+  readonly nodes: readonly { readonly id: string; readonly kind: 'state' | 'final'; readonly tags: readonly string[]; readonly parent?: string; readonly role?: string; readonly description?: string }[];
+  readonly edges: readonly { readonly id: string; readonly from: string; readonly to: string; readonly event: string }[];
+}
+export interface SessionContext {
+  readonly type: 'session_context';
+  readonly timestamp: number;
+  readonly contextVersion: 1;
+  readonly captainId: string;
+  readonly configuration: SessionExecutionProjection;
+  readonly graphs: readonly { readonly playbookId: string; readonly graph: SessionGraph | null }[];
+  readonly initialVisible: readonly string[];
+}
+export interface SessionHistory extends ReplayStreamReadResult {
+  readonly synthetic?: true;
+  readonly missing: boolean;
+  readonly incomplete: boolean;
+  readonly pendingTail: boolean;
+  readonly damage?: { readonly seq: number; readonly offset: number; readonly reason: string };
+  readonly digests: readonly string[];
+  readonly completeBytes: number;
+}
+export interface SessionValidation {
+  readonly integrityValid: boolean;
+  readonly sessionId: string;
+  readonly resumable: boolean;
+  readonly reasons: readonly string[];
+  readonly manifest: StoredSessionManifest;
+  readonly history: SessionHistory;
+}
+export interface SessionHints {
+  readonly players: Readonly<Record<string, string>>;
+  readonly captain?: { readonly kind: 'pinned'; readonly token: string } | { readonly kind: 'needsCatchUp'; readonly resume: string | false; readonly afterJournalSeq: number };
+}
+export interface SessionFreshBoundary {
+  readonly cwd: string;
+  readonly structuralProjection: SessionStructuralProjection;
+  readonly executionProjection: SessionExecutionProjection;
+  readonly snapshot: SessionSnapshot;
+  readonly context?: SessionContext;
+  readonly onLegacyRecord?: (record: any) => void | Promise<void>;
+  readonly onInvalidRecord?: (record: any) => void | Promise<void>;
+}
+export interface PlaybookSessionLifecycle extends PlaybookSessionLease {
+  read(): Promise<SessionRecovery | undefined>;
+  readManifest(): Promise<StoredSessionManifest>;
+  initializeSettledWithPredecessor(options: SessionFreshBoundary): Promise<SessionRecovery>;
+  abandonFreshSettled(options: { expected: SessionRecovery }): Promise<boolean>;
+  beginTurn(options: { input: string; attemptId: string; attemptedExecutionProjection: SessionExecutionProjection }): Promise<SessionRecovery>;
+  beginRetry(options: { expectedAttemptId: string; nextAttemptId: string }): Promise<SessionRecovery>;
+  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>;
+  completeUnresolvedEffectAbandonment(options: any): Promise<any>;
+  recoverUnresolvedEffectAbandonment(): Promise<SessionRecovery | undefined>;
+  writeEffectLedger(authority: any, commands: readonly Readonly<Record<string, any>>[]): Promise<SessionEffectLedger>;
+  assertOwner(): Promise<any>;
+  assertContinuable(context?: { cwd?: string; executionProjection?: SessionExecutionProjection }): Promise<SessionValidation>;
+  recordContext(context: SessionContext): Promise<number>;
+  consumeHints(): Promise<SessionHints>;
+  acknowledgeHint(participantId: string, token: string): void;
+  clearHint(participantId: string): void;
+}
+export interface SharedSessionStore {
+  readonly sessionsDir: string;
+  prepare(): Promise<void>;
+  read(sessionId: string): Promise<SessionRecovery>;
+  readManifest(sessionId: string): Promise<StoredSessionManifest>;
+  /** Observation only; mutations still require acquiring the lease. */
+  readLeaseState(sessionId: string): Promise<'active' | 'idle' | 'unknown'>;
+  readHistory(sessionId: string, options?: ReplayStreamReadOptions): Promise<SessionHistory>;
+  readStream(sessionId: string, options?: ReplayStreamReadOptions): Promise<ReplayStreamReadResult>;
+  readSummary(sessionId: string): Promise<PlaybookSessionSummary>;
+  listSummaries(): Promise<PlaybookSessionListResult>;
+  latest(options?: { preferredCwd?: string; onLegacyRecord?: (record: any) => void | Promise<void> }): Promise<SessionRecovery>;
+  acquire(sessionId: string): Promise<PlaybookSessionLifecycle>;
+  acquireManagement(sessionId: string): Promise<{ readonly sessionId: string; readonly ownerToken: string; assertOwner(): Promise<unknown>; release(): Promise<void> }>;
+  validate(sessionId: string, context?: { cwd?: string; executionProjection?: SessionExecutionProjection }): Promise<SessionValidation>;
+  delete(sessionId: string): Promise<void>;
+  migrateLegacyDefault(options?: { env?: Readonly<Record<string, string | undefined>>; homeDir?: string }): Promise<{ sourceDir: string; migrated: readonly string[]; skipped: readonly { sessionId: string; reason: string }[] }>;
+  migrate(sessionId: string, options?: { sourcePath?: string; cwd?: string; backupDir?: string }): Promise<{ manifest: SessionManifest; migrated: boolean; reasons: readonly string[] }>;
+}
+export declare function createSessionStore(options?: { sessionsDir?: string; env?: Readonly<Record<string, string | undefined>>; homeDir?: string; [key: string]: any }): SharedSessionStore;
+export declare function validateSessionManifest(value: unknown): SessionManifest;
+export declare function validateSessionContext(value: unknown): SessionContext;
+export declare function projectCaptainSessionStructure(value: SessionExecutionProjection): SessionStructuralProjection;
+export declare function validateCaptainSessionExecutionProjection(value: unknown): SessionExecutionProjection;
+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;

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

@@ -21,14 +21,17 @@ export function openSessionStore(sessionsDir) {
 }
 
 function wrapStore(store) {
+  let preparation;
+  const prepared = async (operation) => {
+    await (preparation ??= store.prepare());
+    return operation();
+  };
   return Object.freeze({
     sessionsDir: store.sessionsDir,
-    list: async () => projectListResult(await store.listSummaries()),
-    read: async (sessionId) =>
-      projectSummary(await store.readSummary(sessionId)),
-    readStream: async (sessionId, options) =>
-      projectReadResult(await store.readStream(sessionId, options)),
-    acquire: async (sessionId) => wrapLease(await store.acquire(sessionId)),
+    list: () => prepared(async () => projectListResult(await store.listSummaries())),
+    read: (sessionId) => prepared(async () => projectSummary(await store.readSummary(sessionId))),
+    readStream: (sessionId, options) => prepared(async () => projectReadResult(await store.readStream(sessionId, options))),
+    acquire: (sessionId) => prepared(async () => wrapLease(await store.acquire(sessionId))),
   });
 }
 
@@ -111,3 +114,16 @@ function projectStatus(status) {
     incomplete: status.incomplete,
   });
 }
+
+export {
+  createCaptainSessionStore as createSessionStore,
+  projectCaptainSessionStructure,
+  validateCaptainSessionExecutionProjection,
+  validateCaptainSessionStructuralProjection,
+  assertCaptainSessionExecutionCompatible,
+} from './bin/session-store.js';
+export {
+  validateSessionManifest,
+  validateSessionContext,
+  attachSessionHints,
+} from './bin/portable-codec.js';

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

@@ -960,6 +960,9 @@ export const decideMachine = setup({
                 playbook: {
                     stateId: 'reportedReviewFailure',
                     description: 'DECIDE reports REVIEW’s failure and its last commit.',
+                    // DR-048: this final state means the workflow failed, so a caller
+                    // learns that from the machine rather than from DECIDE's output.
+                    terminal: 'failure',
                 },
             },
         },
@@ -971,6 +974,7 @@ export const decideMachine = setup({
                 playbook: {
                     stateId: 'done',
                     description: 'DECIDE completed with an approved commit.',
+                    terminal: 'success',
                 },
             },
         },

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

@@ -1233,6 +1233,9 @@ export const decideMachine = setup({
         playbook: {
           stateId: 'reportedReviewFailure',
           description: 'DECIDE reports REVIEW’s failure and its last commit.',
+          // DR-048: this final state means the workflow failed, so a caller
+          // learns that from the machine rather than from DECIDE's output.
+          terminal: 'failure',
         },
       },
     },
@@ -1244,6 +1247,7 @@ export const decideMachine = setup({
         playbook: {
           stateId: 'done',
           description: 'DECIDE completed with an approved commit.',
+          terminal: 'success',
         },
       },
     },