@sublang/playbook 12.3.0 → 13.0.0

package/reference/sdlc/code.playbook/bin/portable-codec.js

@@ -0,0 +1,190 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+
+import { createHash } from 'node:crypto';
+import { posix, win32 } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import {
+  validateCaptainSessionRecord,
+  validateCaptainSessionExecutionProjection,
+  sanitizeReplayRecord,
+  SESSION_ID_PATTERN,
+} from './session-store.js';
+
+export const SESSION_MANIFEST_VERSION = 7;
+export const EMPTY_REPLAY_SHA256 = createHash('sha256').digest('hex');
+export const sha256 = (bytes) => createHash('sha256').update(bytes).digest('hex');
+const COMMON = ['schemaVersion', 'kind', 'sessionId', 'cwd', 'createdAt', 'updatedAt', 'state', 'replay', 'contextSeq'];
+const RECOVERY = ['structuralProjection', 'lastAppliedExecutionProjection', 'snapshot', 'effectLedger', 'unresolvedEffects'];
+const OPTIONAL = ['retainedGenerations', 'settledAbandonment'];
+const HEX = /^[0-9a-f]{64}$/;
+const clone = (value) => structuredClone(value);
+const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const nonempty = (value) => typeof value === 'string' && value.length > 0;
+function exact(value, required, optional = []) {
+  if (!object(value) || required.some((key) => !Object.hasOwn(value, key)) || Object.keys(value).some((key) => !required.includes(key) && !optional.includes(key))) throw new Error('invalid or unknown session format fields');
+}
+function iso(value) {
+  if (typeof value !== 'string' || !Number.isFinite(Date.parse(value)) || new Date(value).toISOString() !== value) throw new Error('session timestamp must be canonical ISO UTC');
+}
+export function isRecordedAbsolutePath(value) {
+  return typeof value === 'string' && !value.includes('\0') && (
+    (posix.isAbsolute(value) && posix.resolve(value) === value) ||
+    (/^(?:[A-Za-z]:\\|\\\\[^\\]+\\[^\\]+(?:\\|$))/.test(value) && win32.resolve(value) === value)
+  );
+}
+export function validateReplayCheckpoint(value) {
+  exact(value, ['seq', 'sha256', 'incomplete']);
+  if (!Number.isSafeInteger(value.seq) || value.seq < 0 || !HEX.test(value.sha256) || typeof value.incomplete !== 'boolean' || (value.seq === 0 && value.sha256 !== EMPTY_REPLAY_SHA256)) throw new Error('invalid replay checkpoint');
+  return clone(value);
+}
+
+// The schema-6 validator remains the legacy decoder and the shared in-memory
+// recovery validator. Portable metadata never enters the runtime's snapshots.
+export function validateSessionManifest(value) {
+  if (!object(value) || value.schemaVersion !== 7) throw new Error(`unsupported session manifest schema ${value?.schemaVersion}`);
+  const history = value.state === 'history-only';
+  exact(value, [...COMMON, ...(history ? ['reason'] : RECOVERY), ...(value.state === 'uncertain' ? ['uncertain'] : [])], history ? [] : OPTIONAL);
+  if (value.kind !== 'captain-session' || !SESSION_ID_PATTERN.test(value.sessionId) || !isRecordedAbsolutePath(value.cwd)) throw new Error('invalid session manifest identity');
+  iso(value.createdAt); iso(value.updatedAt);
+  if (Date.parse(value.updatedAt) < Date.parse(value.createdAt)) throw new Error('session update precedes creation');
+  validateReplayCheckpoint(value.replay);
+  if (!(history && value.contextSeq === null) && (!Number.isSafeInteger(value.contextSeq) || value.contextSeq <= 0 || value.contextSeq > value.replay.seq)) throw new Error('invalid session context reference');
+  if (history) {
+    if (!nonempty(value.reason)) throw new Error('history-only session needs a reason');
+  } else {
+    const recovery = recoveryFromManifestUnchecked(value);
+    validateCaptainSessionRecord(recovery);
+    if (!isDeepStrictEqual(projectRecovery(recovery), recovery)) throw new Error('portable recovery contains provider continuation fields');
+  }
+  return clone(value);
+}
+function recoveryFromManifestUnchecked(value) {
+  const { replay, contextSeq, ...recovery } = value;
+  return { ...recovery, schemaVersion: 6 };
+}
+export function recoveryFromManifest(value) {
+  const manifest = validateSessionManifest(value);
+  if (manifest.state === 'history-only') throw new Error(manifest.reason);
+  return validateCaptainSessionRecord(recoveryFromManifestUnchecked(manifest));
+}
+export function manifestFromRecovery(value, replay, contextSeq) {
+  const recovery = projectRecovery(validateCaptainSessionRecord(value));
+  return validateSessionManifest({ ...recovery, schemaVersion: 7, replay, contextSeq });
+}
+export function projectRecovery(value) {
+  const source = clone(value);
+  for (const key of ['snapshot', 'effectLedger', 'retainedGenerations']) {
+    if (source[key] !== undefined) source[key] = clone(sanitizeReplayRecord(source[key]));
+  }
+  const catalog = source.structuralProjection.catalog;
+  const continuation = (operation, ledger) => {
+    if (!Object.hasOwn(operation, 'playerContinuation')) return;
+    const binding = operation.playerContinuation;
+    const entry = catalog[operation.playbookId];
+    const roleId = operation.pendingQuestion?.asker?.kind === 'role'
+      ? operation.pendingQuestion.asker.roleId
+      : ledger.boundaries.find((item) => operation.boundaryIds.includes(item.boundaryId))?.roleId;
+    const playerId = entry?.roles?.[roleId]?.playerId;
+    if (!nonempty(playerId)) throw new Error('pending operation has ambiguous player identity');
+    if (object(binding) && (!isDeepStrictEqual(binding, { v: 1, playerId }))) throw new Error('unsupported deferred player continuation binding');
+    if (!object(binding) && binding !== false && !nonempty(binding)) throw new Error('unsupported deferred player continuation binding');
+    operation.playerContinuation = { v: 1, playerId };
+  };
+  const visit = (node) => {
+    if (!object(node)) return;
+    if (object(node.captain) && object(node.playerSessions) && Array.isArray(node.journal)) {
+      node.captain.conversation = { kind: node.journal.length === 0 ? 'unopened' : 'needsSeeding' };
+      for (const entry of Object.values(node.playerSessions)) delete entry.resumeToken;
+    }
+    if (object(node.roleResumeTokens)) node.roleResumeTokens = {};
+    if (node.schemaVersion === 1 && Array.isArray(node.boundaries) && Array.isArray(node.logicalOperations)) {
+      for (const operation of node.logicalOperations) continuation(operation, node);
+    }
+    for (const [key, child] of Object.entries(node)) {
+      if (key === 'journal' && Array.isArray(child)) {
+        node[key] = child.map((entry) => ({ ...entry, ...(object(entry.payload) ? { payload: sanitizeReplayRecord(entry.payload) } : {}) }));
+      } else if (key !== 'configuration' && key !== 'structuralProjection' && key !== 'lastAppliedExecutionProjection' && key !== 'attemptedExecutionProjection') {
+        if (Array.isArray(child)) child.forEach(visit); else visit(child);
+      }
+    }
+  };
+  visit(source);
+  return source;
+}
+export function validateSessionContext(value) {
+  exact(value, ['type', 'timestamp', 'contextVersion', 'captainId', 'configuration', 'graphs', 'initialVisible']);
+  if (value.type !== 'session_context' || value.contextVersion !== 1 || !Number.isFinite(value.timestamp) || !SESSION_ID_PATTERN.test(value.captainId)) throw new Error('unsupported session context');
+  const configuration = validateCaptainSessionExecutionProjection(value.configuration);
+  const players = new Set(configuration.players.map(({ id }) => id));
+  if (!Array.isArray(value.initialVisible) || value.initialVisible.some((id) => !players.has(id)) || new Set(value.initialVisible).size !== value.initialVisible.length) throw new Error('invalid initially visible players');
+  if (!Array.isArray(value.graphs) || value.graphs.length !== Object.keys(configuration.catalog).length) throw new Error('context graphs must cover the catalog');
+  const ids = new Set();
+  for (const item of value.graphs) {
+    exact(item, ['playbookId', 'graph']);
+    if (!Object.hasOwn(configuration.catalog, item.playbookId) || ids.has(item.playbookId)) throw new Error('invalid context graph identity');
+    ids.add(item.playbookId);
+    if (item.graph !== null) validateGraph(item.graph);
+  }
+  return clone(value);
+}
+function validateGraph(graph) {
+  exact(graph, ['initial', 'nodes', 'edges']);
+  if (!Array.isArray(graph.nodes) || !Array.isArray(graph.edges)) throw new Error('invalid graph arrays');
+  const nodes = new Map();
+  for (const node of graph.nodes) {
+    exact(node, ['id', 'kind', 'tags'], ['parent', 'role', 'description']);
+    if (!nonempty(node.id) || nodes.has(node.id) || !['state', 'final'].includes(node.kind) || !Array.isArray(node.tags) || node.tags.some((tag) => typeof tag !== 'string') || ['parent', 'role', 'description'].some((key) => Object.hasOwn(node, key) && typeof node[key] !== 'string')) throw new Error('invalid graph node');
+    nodes.set(node.id, node);
+  }
+  if (!nodes.has(graph.initial)) throw new Error('graph initial node is absent');
+  for (const node of nodes.values()) {
+    const visited = new Set([node.id]);
+    let parent = node.parent;
+    while (parent !== undefined) {
+      if (!nodes.has(parent) || visited.has(parent)) throw new Error('graph parent is absent or cyclic');
+      visited.add(parent); parent = nodes.get(parent).parent;
+    }
+  }
+  const edges = new Set();
+  for (const edge of graph.edges) {
+    exact(edge, ['id', 'from', 'to', 'event']);
+    if (!nonempty(edge.id) || edges.has(edge.id) || !nodes.has(edge.from) || !nodes.has(edge.to) || typeof edge.event !== 'string') throw new Error('invalid graph edge');
+    edges.add(edge.id);
+  }
+}
+export function contextFromRecovery(record, graphs = [], initialVisible = []) {
+  const configuration = record.state === 'uncertain' ? record.uncertain.attemptedExecutionProjection : record.lastAppliedExecutionProjection;
+  return validateSessionContext({ type: 'session_context', timestamp: Date.now(), contextVersion: 1, captainId: record.snapshot.captain.sessionId, configuration, graphs: Object.keys(configuration.catalog).map((playbookId) => ({ playbookId, graph: graphs.find((item) => item.playbookId === playbookId)?.graph ?? null })), initialVisible });
+}
+export function validateSessionHints(value, manifestBytes, manifest) {
+  exact(value, ['v', 'sessionId', 'checkpointSha256', 'players'], ['captain']);
+  if (value.v !== 1 || value.sessionId !== manifest.sessionId || value.checkpointSha256 !== sha256(manifestBytes) || !object(value.players)) throw new Error('provider hints do not match the checkpoint');
+  const players = new Set(manifest.structuralProjection?.players.map(({ id }) => id) ?? []);
+  for (const [id, token] of Object.entries(value.players)) if (!players.has(id) || !nonempty(token)) throw new Error('invalid player hint');
+  if (value.captain !== undefined) {
+    const captain = value.captain;
+    if (captain.kind === 'pinned') { exact(captain, ['kind', 'token']); if (!nonempty(captain.token)) throw new Error('invalid Captain hint'); }
+    else if (captain.kind === 'needsCatchUp') { exact(captain, ['kind', 'resume', 'afterJournalSeq']); if (!(captain.resume === false || nonempty(captain.resume)) || !Number.isSafeInteger(captain.afterJournalSeq) || captain.afterJournalSeq < 0 || captain.afterJournalSeq > manifest.snapshot.sequences.journal) throw new Error('invalid Captain catch-up hint'); }
+    else throw new Error('invalid Captain conversation hint');
+  }
+  return clone(value);
+}
+export function attachSessionHints(snapshot, hints) {
+  const result = clone(snapshot);
+  if (hints?.captain) result.captain.conversation = clone(hints.captain);
+  for (const [id, token] of Object.entries(hints?.players ?? {})) if (result.playerSessions[id]) result.playerSessions[id].resumeToken = token;
+  const visit = (node, inheritedBindings = {}) => {
+    if (!object(node)) return;
+    const bindings = node.roleBindings ?? inheritedBindings;
+    if (object(node.roleResumeTokens)) {
+      node.roleResumeTokens = Object.fromEntries(Object.entries(bindings).flatMap(([role, binding]) => {
+        const token = hints?.players?.[typeof binding === 'string' ? binding : binding.playerId];
+        return token === undefined ? [] : [[role, token]];
+      }));
+    }
+    for (const child of Object.values(node)) if (Array.isArray(child)) child.forEach((item) => visit(item, bindings)); else visit(child, bindings);
+  };
+  visit(result);
+  return result;
+}

package/reference/sdlc/code.playbook/bin/replay-observer.js

@@ -7,10 +7,25 @@ const PLAYER_RECORD_TYPES = new Set([
   'player_finished',
 ]);
 
-export function createReplayRecordObserver({ lease, onIncomplete }) {
+export function createReplayRecordObserver({ lease, onIncomplete, onStored }) {
   const activeFrames = new Map();
   let incompleteReported = false;
   let lastIncomplete = readIncomplete(lease);
+  let lastDeliveredSeq = 0;
+  try { lastDeliveredSeq = lease.streamStatus().lastReadableSeq ?? 0; } catch { /* Unavailable replay has no delivery cursor. */ }
+  let deliveryQueue = Promise.resolve();
+  const flushStoredRecords = () => {
+    if (!onStored) return Promise.resolve();
+    const operation = deliveryQueue.then(async () => {
+      const result = await lease.readStream({ afterSeq: lastDeliveredSeq });
+      for (const entry of result.entries) {
+        await onStored(entry, lease.streamStatus());
+        lastDeliveredSeq = entry.seq;
+      }
+    });
+    deliveryQueue = operation.catch(() => reportIfIncomplete());
+    return deliveryQueue;
+  };
 
   const reportIfIncomplete = async (knownStatus) => {
     if (incompleteReported) return;
@@ -36,6 +51,7 @@ export function createReplayRecordObserver({ lease, onIncomplete }) {
       }
       try {
         await lease.append(record, ...(role === undefined ? [] : [role]));
+        await flushStoredRecords();
       } catch {
         // The replay writer records failure in its live latch. The observer
         // remains installed so later host records and lifecycle work continue.
@@ -48,7 +64,7 @@ export function createReplayRecordObserver({ lease, onIncomplete }) {
     },
   });
 
-  return Object.freeze({ observer, reportIfIncomplete });
+  return Object.freeze({ observer, reportIfIncomplete, flushStoredRecords });
 }
 
 function readIncomplete(lease, knownStatus) {

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

@@ -7,6 +7,7 @@
 // presenter; it does not construct a registry runtime or PlaybookPorts itself.
 
 import { randomUUID } from "node:crypto";
+import { attachSessionHints, validateSessionContext } from "./portable-codec.js";
 import { homedir } from "node:os";
 import { resolve } from "node:path";
 import { isDeepStrictEqual } from "node:util";
@@ -30,6 +31,7 @@ import {
   checkReadiness,
   invalidRegistryEntryReason,
   loadLaunchPlan,
+  loadSelectedLaunchPlanDataOnly,
   projectHostAgent,
   resolveLaunchSessionsDir,
   relocateLegacyUserConfig,
@@ -50,7 +52,6 @@ import {
 import {
   assertCaptainSessionExecutionCompatible,
   assertCaptainSessionsDirectoryUsable,
-  captainSessionSelectedMembers,
   createCaptainSessionStore,
   projectCaptainSessionStructure,
   SESSION_ID_PATTERN,
@@ -142,6 +143,7 @@ export async function runPlaybookRun(options = {}) {
   }
   const bootstrapConfigNotices = [];
   let resolvedSessionsDir;
+  let migrateDefaultStore = false;
   if (options.sessionStore === undefined) {
     try {
       resolvedSessionsDir = resolveLaunchSessionsDir({
@@ -153,6 +155,7 @@ export async function runPlaybookRun(options = {}) {
           ? { sessionsDir: options.sessionsDir }
           : {}),
         preparePrimary: !continuing,
+        onDefault: () => { migrateDefaultStore = !(typeof env.SPEX_HOME === 'string' && env.SPEX_HOME.trim() !== ''); },
         onNotice: (line) => bootstrapConfigNotices.push(line),
       });
       await assertCaptainSessionsDirectoryUsable(resolvedSessionsDir);
@@ -178,6 +181,11 @@ export async function runPlaybookRun(options = {}) {
           ? { createTempId: options.createSessionTempId }
           : {}),
       });
+    if (migrateDefaultStore) {
+      const migrated = await store.migrateLegacyDefault();
+      if (migrated.migrated.length > 0) await writeStream(stderr, `playbook run: migrated ${migrated.migrated.length} sessions from ${migrated.sourceDir}\n`);
+      for (const skipped of migrated.skipped) await writeStream(stderr, `playbook run: preserved legacy session ${skipped.sessionId} in ${migrated.sourceDir}: ${skipped.reason}\n`);
+    }
   } catch (error) {
     await writeStream(stderr, `playbook run: ${message(error)}\n`);
     return { code: EXIT.argument };
@@ -226,6 +234,8 @@ export async function runPlaybookRun(options = {}) {
       }
       throwIfAborted(options.signal);
       lease = await store.acquire(sessionId);
+      if (!args.discardUncertain) await lease.assertContinuable();
+      else if ((await lease.readManifest()).schemaVersion !== 7) throw new Error(`session requires explicit migration; run playbook migrate-session ${sessionId}`);
       replayChannel = createHeadlessReplayChannel({
         lease,
         sessionId,
@@ -343,20 +353,20 @@ export async function runPlaybookRun(options = {}) {
     const configNotices = [...bootstrapConfigNotices];
     try {
       throwIfAborted(options.signal);
-      plan = await loadLaunchPlan({
-        userConfigPath,
-        overlayPaths: args.withPaths,
-        loadModule,
-        prepareRegistryModule,
-        onNotice: (line) => configNotices.push(line),
-        ...(continuing
-          ? {
-              selectedMembers: captainSessionSelectedMembers(
-                priorRecord.structuralProjection,
-              ),
-            }
-          : {}),
-      });
+      plan = continuing
+        ? await loadSelectedLaunchPlanDataOnly({
+            userConfigPath,
+            overlayPaths: args.withPaths,
+            structuralProjection: priorRecord.structuralProjection,
+            onNotice: (line) => configNotices.push(line),
+          })
+        : await loadLaunchPlan({
+            userConfigPath,
+            overlayPaths: args.withPaths,
+            loadModule,
+            prepareRegistryModule,
+            onNotice: (line) => configNotices.push(line),
+          });
       throwIfAborted(options.signal);
     } catch (error) {
       for (const line of configNotices) await writeStream(stderr, line);
@@ -376,9 +386,10 @@ export async function runPlaybookRun(options = {}) {
     try {
       const current = executionConfigFromPlan(plan);
       if (continuing) {
-        config = assertCaptainSessionExecutionCompatible(
+        config = await validateFrozenExecutionConfig(
           priorRecord.structuralProjection,
           current,
+          { loadModule, prepareRegistryModule },
         );
       } else {
         sessionId = (options.createLogicalSessionId ?? randomUUID)();
@@ -1007,7 +1018,10 @@ export async function createCaptainSessionHost({
   restoreSnapshot,
   reconcileUncertainTurnReplay = false,
   signal,
+  graphs = [],
+  initialVisible = [],
 }) {
+  if (restoreSnapshot !== undefined) await sessionLease.assertContinuable({ cwd, executionProjection: config });
   const hostCapabilities = await createRepositoryEffectCapabilities({
     cwd,
     catalog: config.catalog,
@@ -1065,9 +1079,30 @@ export async function createCaptainSessionHost({
       "Captain session effect ledger requires reconciliation before source-state restoration",
     );
   }
+  if (sourceSnapshot !== undefined && typeof sessionLease.consumeHints === "function") {
+    sourceSnapshot = attachSessionHints(sourceSnapshot, await sessionLease.consumeHints());
+  }
+  const bufferedRecords = [];
+  let presentationReady = false;
+  const presentationTurnOffset = restoreSnapshot?.sequences.turn ?? 0;
+  const forwardRecord = async (record) => {
+    const projected = presentationTurnOffset > 0 && typeof record.turnId === "number"
+      ? { ...record, turnId: record.turnId + presentationTurnOffset, ...(record.type === "turn_started" ? { turn: { ...record.turn, id: record.turn.id + presentationTurnOffset } } : {}) }
+      : record;
+    for (const observer of observers ?? []) await observer.onRecord?.(projected);
+  };
+  const bufferedObservers = [{ async onRecord(record) {
+    if (!presentationReady) bufferedRecords.push(record);
+    else await forwardRecord(record);
+  } }];
   const shell = createPlaybookCaptainShell(captainOptionsFromConfig(config), {
     loadModule,
     hostCapabilities,
+    continuity: {
+      async beforeCall(participantId) { sessionLease.clearHint?.(participantId); await sessionLease.assertOwner(); },
+      acknowledged(participantId, token) { sessionLease.acknowledgeHint?.(participantId, token); },
+      async reset(participantId, reason) { await sessionLease.append({ type: "continuity_reset", timestamp: Date.now(), participantId, reason }); },
+    },
     unresolvedEffectSettlement: {
       begin: (input) => sessionLease.beginUnresolvedEffectAbandonment(input),
       complete: (input) =>
@@ -1092,7 +1127,7 @@ export async function createCaptainSessionHost({
         ...projectHostAgent(agent, `Captain execution config.players.${id}`),
       })),
       cwd,
-      observers,
+      observers: bufferedObservers,
       ...(signal ? { signal } : {}),
       ...(adapterImports ? { adapterImports } : {}),
     });
@@ -1111,6 +1146,15 @@ export async function createCaptainSessionHost({
     if (sessionId !== undefined) {
       assertLogicalSessionIdDistinct({ sessionId, snapshot });
     }
+    if (typeof sessionLease.recordContext === "function") {
+      await sessionLease.recordContext(validateSessionContext({
+        type: "session_context", timestamp: Date.now(), contextVersion: 1,
+        captainId: snapshot.captain.sessionId, configuration: config,
+        graphs: Object.keys(config.catalog).map((playbookId) => ({ playbookId, graph: graphs.find((item) => item.playbookId === playbookId)?.graph ?? null })), initialVisible,
+      }));
+    }
+    presentationReady = true;
+    for (const record of bufferedRecords) await forwardRecord(record);
     return { shell, host, snapshot, reconcileRepositoryEffects };
   } catch (error) {
     let cleanupError;
@@ -1699,7 +1743,7 @@ export async function reportSkippedCaptainSession(
   { sessionId, path, schemaVersion, reason },
 ) {
   const explanation =
-    kind === "legacy" ? legacyCaptainSessionReason(schemaVersion) : reason;
+    kind === "legacy" ? reason ?? legacyCaptainSessionReason(schemaVersion) : reason;
   await writeStream(
     stderr,
     `${commandName}: skipping ${kind} Captain session ${JSON.stringify(sessionId)} at ${JSON.stringify(path)} because ${explanation}; move it outside the sessions directory or remove it to silence this warning\n`,

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

@@ -0,0 +1,104 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+
+import { randomUUID } from 'node:crypto';
+import { createCaptainSessionStore, projectCaptainSessionStructure } from './session-store.js';
+import { createCaptainSessionHost, executionConfigFromPlan, installRetainedGenerationsForLaunch, validateFrozenExecutionConfig } from './run.js';
+import { createReplayRecordObserver } from './replay-observer.js';
+
+/** Own one session lease and the same durable turn transaction as the CLIs. */
+export async function openSessionHost(options) {
+  const store = options.store ?? createCaptainSessionStore({ sessionsDir: options.sessionsDir });
+  const sessionId = options.sessionId ?? randomUUID();
+  const loadModule = options.loadModule ?? ((specifier) => import(specifier));
+  const lease = await store.acquire(sessionId);
+  let active, closed = false, closing;
+  let created;
+  let retryPending = options.mode === 'retry';
+  try {
+    let record = await lease.read();
+    if (record !== undefined) await lease.assertContinuable({ cwd: options.cwd });
+    record = await lease.recoverUnresolvedEffectAbandonment();
+    if (options.mode === 'new' && record !== undefined) throw new Error('session already exists');
+    if (options.mode !== 'new' && options.sessionId && record === undefined) throw new Error('session does not exist');
+    if (record?.state === 'uncertain' && !retryPending) throw new Error('session has an uncertain turn; select Retry or Discard');
+    if (retryPending && record?.state !== 'uncertain') throw new Error('session has no uncertain turn to retry');
+    const cwd = options.cwd ?? record?.cwd ?? process.cwd();
+    const selected = retryPending ? record.uncertain.attemptedExecutionProjection : options.config ?? (options.plan ? executionConfigFromPlan(options.plan) : record?.lastAppliedExecutionProjection);
+    if (!selected) throw new Error('a new session requires a validated execution configuration');
+    const structure = record?.structuralProjection ?? projectCaptainSessionStructure(selected);
+    if (record !== undefined) await lease.assertContinuable({ cwd, executionProjection: selected });
+    const config = await validateFrozenExecutionConfig(structure, selected, { loadModule, prepareRegistryModule: options.prepareRegistryModule });
+    const replay = createReplayRecordObserver({ lease, onIncomplete: options.onIncomplete ?? (() => {}), onStored: options.onStoredRecord });
+    let terminal, replies = [];
+    const observe = {
+      async onRecord(value) {
+        if (value.type === "turn_finished" || value.type === "turn_aborted") terminal = value;
+        if (value.type === "captain_reply") replies.push(value);
+        await replay.observer.onRecord(value);
+        for (const observer of options.observers ?? []) await observer.onRecord?.(value);
+      },
+    };
+    created = await createCaptainSessionHost({ ...options, config, sessionId, cwd, sessionLease: lease, loadModule, observers: [observe], restoreSnapshot: record?.snapshot, reconcileUncertainTurnReplay: retryPending });
+    await installRetainedGenerationsForLaunch({ lease, shell: created.shell, ...(record === undefined ? { freshBoundary: { cwd, structuralProjection: structure, executionProjection: config, snapshot: created.snapshot } } : {}), retainedGenerations: record?.retainedGenerations ?? {}, reconcileRepositoryEffects: created.reconcileRepositoryEffects });
+    record = await lease.read();
+    await replay.flushStoredRecords();
+    const execute = async (input, retry) => {
+      if (closed || closing) throw new Error('session host is closing');
+      if (active) throw new Error('session turn is already active');
+      const operation = (async () => {
+        let prior = await lease.read();
+        if (retry) {
+          if (prior?.state !== 'uncertain') throw new Error('session has no uncertain turn to retry');
+          input = prior.uncertain.input;
+          if (!retryPending) throw new Error('retry requires reopening the uncertain checkpoint');
+        } else if (prior?.state !== 'settled') throw new Error('session has an uncertain turn; select Retry or Discard');
+        if (typeof input !== 'string' || input.trim().length === 0) throw new Error('session input must be nonempty');
+        await created.reconcileRepositoryEffects();
+        terminal = undefined; replies = [];
+        const attemptId = options.createAttemptId?.() ?? randomUUID();
+        const marked = retry ? await lease.beginRetry({ expectedAttemptId: prior.uncertain.attemptId, nextAttemptId: attemptId }) : await lease.beginTurn({ input, attemptId, attemptedExecutionProjection: config });
+        retryPending = false;
+        await replay.flushStoredRecords();
+        await options.onCheckpoint?.(marked);
+        await lease.assertOwner();
+        await created.host.runBossTurn(input);
+        if (terminal?.type !== "turn_finished" || replies.length !== 1 || typeof replies[0].text !== "string" || replies[0].text.trim().length === 0) throw new Error("Captain turn did not finish with one reply; session remains uncertain");
+        const settlement = created.shell.exportSettlement();
+        if (settlement === undefined) throw new Error('Captain turn ended without durable settlement; session remains uncertain');
+        record = await lease.settle({ attemptId, snapshot: settlement.snapshot, unresolvedEffects: settlement.unresolvedEffects, retentionUpdates: settlement.retentionUpdates });
+        await replay.flushStoredRecords();
+        await options.onCheckpoint?.(record);
+        return record;
+      })();
+      active = operation;
+      try { return await operation; } finally { active = undefined; }
+    };
+    const dispose = () => {
+      if (closed) return Promise.resolve();
+      if (closing) return closing;
+      closing = (async () => {
+        try { await active; } catch { /* Preserve the durable uncertain marker. */ }
+        await created.host.dispose();
+        await lease.release(); closed = true;
+      })();
+      return closing;
+    };
+    return Object.freeze({ sessionId, host: created.host, shell: created.shell, lease, read: () => lease.read(), handleBossTurn: (input) => execute(input, false), retry: () => execute(undefined, true), dispose });
+  } catch (cause) {
+    const failures = [cause];
+    let disposed = true;
+    try { await created?.host.dispose(); } catch (error) { disposed = false; failures.push(error); }
+    if (disposed) try { await lease.release(); } catch (error) { failures.push(error); }
+    throw failures.length === 1 ? cause : new AggregateError(failures, 'session host setup and cleanup failed');
+  }
+}
+
+export async function discardSessionUncertain(store, sessionId) {
+  const lease = await store.acquire(sessionId);
+  try {
+    const record = await lease.recoverUnresolvedEffectAbandonment();
+    if (record?.state !== 'uncertain') throw new Error('session has no uncertain turn to discard');
+    return await lease.discard({ attemptId: record.uncertain.attemptId });
+  } finally { await lease.release(); }
+}