@sublang/playbook 12.3.0 → 13.0.0

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

@@ -35,6 +35,11 @@ interface PlaybookCaptainUnresolvedEffectSettlementInput {
 type SnapshotAgentEnvelope = DeepReadonly<Omit<SessionAgent, 'model' | 'effort' | 'fastMode'>>;
 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<Record<string, PlaybookHostConstructionCapabilities>>;

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

@@ -949,6 +949,7 @@ function normalizeHostPlayerResult(value, expectedPlayerId) {
         'resumeToken',
         'finalText',
         'error',
+        'errorCode',
     ]);
     const normalized = {};
     for (const key of Reflect.ownKeys(descriptors)) {
@@ -970,11 +971,16 @@ function normalizeHostPlayerResult(value, expectedPlayerId) {
             normalized[key] = descriptor.value;
     }
     const record = snapshotRecord(snapshotJsonValue(normalized, path), path);
-    rejectSnapshotKeys(record, ['status', 'playerId', 'turnId', 'resumeToken', 'finalText', 'error'], path);
+    rejectSnapshotKeys(record, ['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,
         ...(record.resumeToken === undefined
@@ -1629,6 +1635,7 @@ export function createPlaybookCaptainShell(options, deps = {}) {
     const createSessionId = deps.createSessionId ?? randomUUID;
     const 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
@@ -2615,11 +2622,32 @@ export function createPlaybookCaptainShell(options, deps = {}) {
             try {
                 let rawResult;
                 try {
-                    rawResult = await trackHostCall(frame, classifySettingsCall(() => context.callPlayer(binding.playerId, prompt, {
-                        resume: options.resume,
-                        settings,
-                    })));
-                    hostResolved = true;
+                    const call = async (resume) => {
+                        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, '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) {
@@ -2914,6 +2942,9 @@ export function createPlaybookCaptainShell(options, deps = {}) {
                     delete ledger.resumeToken;
                 else
                     ledger.resumeToken = resumeToken;
+                if (pending.status === 'ok' && resumeToken !== undefined) {
+                    continuity?.acknowledged(binding.playerId, resumeToken);
+                }
             }
             finally {
                 playerTransactions.delete(binding.playerId);
@@ -4109,7 +4140,7 @@ export function createPlaybookCaptainShell(options, deps = {}) {
     };
     class CaptainContinuityError extends Error {
         constructor(cause) {
-            super('the session Captain conversation could not be resynchronized after one reseeded re-issue', { cause });
+            super('the session Captain conversation lost continuity', { cause });
             this.name = 'CaptainContinuityError';
         }
     }
@@ -4121,6 +4152,8 @@ export function createPlaybookCaptainShell(options, deps = {}) {
     }
     const rawDurableCall = async (context, prompt, resume, attempt) => {
         const queued = captainQueue.add(async () => {
+            context.signal.throwIfAborted();
+            await continuity?.beforeCall('captain');
             context.signal.throwIfAborted();
             attempt.providerBoundaryEntered = true;
             const result = await classifySettingsCall(() => context.callCaptain(prompt, {
@@ -4134,11 +4167,8 @@ export function createPlaybookCaptainShell(options, deps = {}) {
         });
         return trackTurnCall(queued);
     };
-    // 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, compose) => {
         const startingConversation = conversation;
         const resume = startingConversation.kind === 'pinned'
@@ -4153,6 +4183,8 @@ export function createPlaybookCaptainShell(options, deps = {}) {
         let result;
         let failure;
         try {
+            if (resume === false)
+                await continuity?.reset('captain', 'missing_hint');
             result = await rawDurableCall(context, compose(seedFirstCall
                 ? { reseedDigest: reseedDigest() }
                 : startingConversation.kind === 'needsCatchUp'
@@ -4187,9 +4219,10 @@ export function createPlaybookCaptainShell(options, deps = {}) {
         const unsynchronized = 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;
             }
@@ -4205,6 +4238,11 @@ export function createPlaybookCaptainShell(options, deps = {}) {
         // 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;
         const reissueAttempt = { providerBoundaryEntered: false };
@@ -4221,11 +4259,12 @@ export function createPlaybookCaptainShell(options, deps = {}) {
             }
             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 ??
                 `callCaptain status "${reissued.status}" without a resume token`));
         }
         conversation = { kind: 'pinned', token: reissued.resumeToken };
+        continuity?.acknowledged('captain', reissued.resumeToken);
         if (activeTurn)
             activeTurn.captainSyncedJournalSeq = journalSeq;
         return {

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<
@@ -1819,6 +1824,7 @@ function normalizeHostPlayerResult(
     'resumeToken',
     'finalText',
     'error',
+    'errorCode',
   ]);
   const normalized: Record<string, unknown> = {};
   for (const key of Reflect.ownKeys(descriptors)) {
@@ -1841,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,
@@ -2988,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
@@ -4376,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 (
@@ -4739,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);
       }
@@ -6161,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';
@@ -6185,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(() =>
@@ -6205,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,
@@ -6229,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(
@@ -6279,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;
       }
@@ -6297,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 {
@@ -6319,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 ??
@@ -6328,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;