@sublang/playbook 12.2.2 → 13.0.0

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

@@ -7,6 +7,12 @@
 // complete retained-generation map under guarded source-first publication.
 
 import { createHash, randomUUID } from 'node:crypto';
+import {
+  SESSION_MANIFEST_VERSION, EMPTY_REPLAY_SHA256, sha256,
+  validateSessionManifest, recoveryFromManifest, manifestFromRecovery,
+  contextFromRecovery, validateSessionContext, validateSessionHints,
+  projectRecovery, isRecordedAbsolutePath,
+} from './portable-codec.js';
 import { constants } from 'node:fs';
 import {
   access,
@@ -57,8 +63,22 @@ export const CAPTAIN_SESSION_STRUCTURAL_PROJECTION_SCHEMA_VERSION = 1;
 export const CAPTAIN_SESSION_EXECUTION_PROJECTION_SCHEMA_VERSION = 2;
 
 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 RESERVED_ID = 'captain';
+
+// 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.
+export function isCanonicalLocalRoleId(value) {
+  return (
+    typeof value === 'string' &&
+    value.length > 0 &&
+    value === value.toLowerCase() &&
+    !ROLE_ID_WHITESPACE_OR_CONTROL.test(value)
+  );
+}
 const HOST_CAPABILITIES_OPTION_KEY = 'hostCapabilities';
 const KNOWN_ADAPTERS = new Set(KNOWN_PLAYER_ADAPTERS);
 
@@ -205,8 +225,7 @@ export function defaultCaptainSessionsDir(
   env = process.env,
   home = env.HOME ?? homedir(),
 ) {
-  const stateHome = env.XDG_STATE_HOME || join(home, '.local', 'state');
-  return join(stateHome, 'playbook', 'sessions');
+  return join(typeof env.SPEX_HOME === 'string' && env.SPEX_HOME.trim() !== '' ? env.SPEX_HOME : join(home, '.spex'), 'sessions');
 }
 
 // PBCLI-78: front-end bootstrap checks the same private filesystem boundary
@@ -221,6 +240,7 @@ export async function assertCaptainSessionsDirectoryUsable(
   }
   const fs = { ...DEFAULT_FS_OPERATIONS, ...(options.fsOps ?? {}) };
   try {
+    await prepareSessionPermissions(sessionsDir, fs);
     await assertPrivateDirectory(sessionsDir, fs);
     await fs.access(
       sessionsDir,
@@ -616,6 +636,7 @@ export function createCaptainSessionStore(options = {}) {
   const fs = { ...DEFAULT_FS_OPERATIONS, ...(options.fsOps ?? {}) };
   const replayReadCursors = new Map();
   const replayReadQueues = new Map();
+  const portableWriters = new Map();
 
   if (!isAbsolute(sessionsDir)) {
     throw new Error('Captain session store path must be absolute');
@@ -651,7 +672,7 @@ export function createCaptainSessionStore(options = {}) {
     return join(sessionsDir, `.${sessionId}.lock.retired.${ownerToken}`);
   };
 
-  const readRecord = async (sessionId, { missing = 'error' } = {}) => {
+  const readRecord = async (sessionId, { missing = 'error', requirePortable = false } = {}) => {
     const path = recordPathFor(sessionId);
     let text;
     try {
@@ -676,7 +697,16 @@ export function createCaptainSessionStore(options = {}) {
     }
     let record;
     try {
-      record = validateCaptainSessionRecord(value);
+      if (value.schemaVersion === SESSION_MANIFEST_VERSION && value.state === 'history-only') {
+        const manifest = validateSessionManifest(value);
+        throw new CaptainSessionRecordNonresumableError(7, manifest.reason, captainSessionOrderingBoundary(manifest));
+      }
+      record = value.schemaVersion === SESSION_MANIFEST_VERSION
+        ? recoveryFromManifest(value)
+        : validateCaptainSessionRecord(value);
+      if (requirePortable && value.schemaVersion !== SESSION_MANIFEST_VERSION) {
+        throw new CaptainSessionRecordNonresumableError(value.schemaVersion, `schema ${value.schemaVersion} requires explicit migration; run playbook migrate-session ${sessionId}`, captainSessionOrderingBoundary(record));
+      }
     } catch (cause) {
       const context =
         `Captain session ${JSON.stringify(sessionId)} at ` +
@@ -720,6 +750,70 @@ export function createCaptainSessionStore(options = {}) {
     return record;
   };
 
+  const readManifest = async (sessionId) => {
+    let bytes;
+    try { await assertPrivateDirectory(sessionsDir, fs); bytes = await readPrivateRegularFile(recordPathFor(sessionId), 0o600, fs, 'record'); }
+    catch (cause) { if (cause?.code === 'ENOENT') throw new CaptainSessionNotFoundError(sessionId, recordPathFor(sessionId)); throw cause; }
+    const value = JSON.parse(bytes);
+    if (value.sessionId !== sessionId) throw new Error('session manifest identity does not match its filename');
+    return value.schemaVersion === 7 ? validateSessionManifest(value) : value;
+  };
+  const prepare = () => prepareSessionPermissions(sessionsDir, fs);
+  const readHistory = async (sessionId, options = {}) => {
+    assertSessionId(sessionId);
+    const history = await readSessionHistory({ sessionsDir, path: recordsPathFor(sessionId), fs, afterSeq: options.afterSeq ?? 0 });
+    if (!history.missing) return history;
+    let legacy;
+    try {
+      legacy = JSON.parse(await readPrivateRegularFile(recordPathFor(sessionId), 0o600, fs, 'legacy record'));
+      if (![2, 3, 4, 5, 6].includes(legacy.schemaVersion)) return history;
+      if (legacy.kind !== CAPTAIN_SESSION_RECORD_KIND || legacy.sessionId !== sessionId || !Array.isArray(legacy.snapshot?.journal) || !Number.isFinite(Date.parse(legacy.updatedAt))) return history;
+    } catch { return history; }
+    return legacyJournalHistory(legacy, options.afterSeq ?? 0, history);
+  };
+  const validate = async (sessionId, context = {}) => {
+    const manifest = await readManifest(sessionId);
+    const history = await readHistory(sessionId);
+    const reasons = [];
+    let integrityValid = !history.missing && !history.incomplete;
+    if (history.missing) reasons.push('session replay file is missing');
+    if (history.pendingTail) reasons.push('session replay has an unfinished final record');
+    if (manifest.schemaVersion !== 7) {
+      if ([2, 3, 4, 5, 6].includes(manifest.schemaVersion)) {
+        try { validateCaptainSessionRecord(manifest); }
+        catch (cause) { if (!(cause instanceof CaptainSessionRecordNonresumableError)) throw cause; reasons.push(cause.message); }
+        reasons.push(`schema ${manifest.schemaVersion} requires explicit migration; run playbook migrate-session ${sessionId}`);
+      } else reasons.push(`unsupported session schema ${manifest.schemaVersion}`);
+    }
+    else {
+      if (history.entries.some(({ record }) => !isDeepStrictEqual(record, sanitizeReplayRecord(record)))) {
+        integrityValid = false;
+        reasons.push('session replay contains provider continuation fields');
+      }
+      if (manifest.state === 'history-only') reasons.push(manifest.reason);
+      if (manifest.replay.incomplete || history.incomplete) reasons.push('session replay is incomplete');
+      if (history.digests[manifest.replay.seq] !== manifest.replay.sha256) { integrityValid = false; reasons.push('session replay checkpoint digest does not match'); }
+      if (manifest.contextSeq !== null) {
+        const contextRecord = history.entries.find((entry) => entry.seq === manifest.contextSeq)?.record;
+        try {
+          const supported = validateSessionContext(contextRecord);
+          if (manifest.state !== 'history-only') {
+            const execution = manifest.state === 'uncertain'
+              ? manifest.uncertain.attemptedExecutionProjection : manifest.lastAppliedExecutionProjection;
+            if (!isDeepStrictEqual(supported.configuration, execution) || supported.captainId !== manifest.snapshot.captain.sessionId) { integrityValid = false; reasons.push('required session context differs from checkpoint recovery'); }
+          }
+        } catch { reasons.push('required session context is absent or unsupported'); }
+      }
+      if (!isAbsolute(manifest.cwd) || resolve(manifest.cwd) !== manifest.cwd) reasons.push('recorded working directory is not native; checkpoint relocation is unsupported');
+      if (context.cwd !== undefined && context.cwd !== manifest.cwd) reasons.push('recorded working directory differs; checkpoint relocation is unsupported');
+      if (context.executionProjection !== undefined && manifest.state !== 'history-only') {
+        try { assertCaptainSessionExecutionCompatible(manifest.structuralProjection, context.executionProjection); }
+        catch (cause) { reasons.push(errorMessage(cause)); }
+      }
+    }
+    return Object.freeze({ sessionId, integrityValid, resumable: integrityValid && reasons.length === 0, reasons: Object.freeze(reasons), manifest, history });
+  };
+
   const read = (sessionId) => readRecord(sessionId);
 
   const readStream = async (sessionId, options) => {
@@ -809,15 +903,16 @@ export function createCaptainSessionStore(options = {}) {
       // Canonically named records are store-owned. Corruption must not make
       // --continue silently select an older logical session.
       try {
-        candidates.push(await readRecord(sessionId));
+        candidates.push(await readRecord(sessionId, { requirePortable: true }));
       } catch (error) {
         if (error instanceof CaptainSessionRecordNonresumableError) {
-          await onLegacyOrderingBoundary?.(error.orderingBoundary);
+          if (error.orderingBoundary) await onLegacyOrderingBoundary?.(error.orderingBoundary);
           await onLegacyRecord?.(
             Object.freeze({
               sessionId,
               path: recordPathFor(sessionId),
               schemaVersion: error.schemaVersion,
+              ...(error.schemaVersion >= 6 ? { reason: error.cause?.message ?? error.message } : {}),
             }),
           );
           continue;
@@ -851,37 +946,24 @@ export function createCaptainSessionStore(options = {}) {
     );
   };
 
-  const readSummary = async (sessionId) =>
-    projectPlaybookSessionSummary(await readRecord(sessionId));
+  const readSummary = async (sessionId) => {
+    const manifest = await readManifest(sessionId);
+    if (manifest.schemaVersion !== 7) validateCaptainSessionRecord(manifest);
+    return projectPlaybookSessionSummary(manifest);
+  };
 
   const listSummaries = async () => {
-    const skipped = [];
-    const records = await listRecords({
-      onLegacyRecord: ({ sessionId, schemaVersion }) => {
-        skipped.push(
-          Object.freeze({
-            sessionId,
-            reason:
-              `Captain session schema ${schemaVersion} is below current ` +
-              `schema ${CAPTAIN_SESSION_RECORD_SCHEMA_VERSION}`,
-          }),
-        );
-      },
-      onInvalidRecord: ({ sessionId, reason }) => {
-        skipped.push(Object.freeze({ sessionId, reason }));
-      },
-      skipInvalidRecords: true,
-    });
-    return Object.freeze({
-      sessions: Object.freeze(
-        sortCaptainSessionRecords(records).map(projectPlaybookSessionSummary),
-      ),
-      skipped: Object.freeze(
-        skipped.sort((left, right) =>
-          left.sessionId.localeCompare(right.sessionId),
-        ),
-      ),
-    });
+    const sessions = [], skipped = [];
+    let names;
+    try { await assertPrivateDirectory(sessionsDir, fs); names = await fs.readdir(sessionsDir); }
+    catch (cause) { if (cause?.code === 'ENOENT') return { sessions, skipped }; throw cause; }
+    for (const name of names.sort()) {
+      const sessionId = name.slice(0, -5);
+      if (!name.endsWith('.json') || !SESSION_ID_PATTERN.test(sessionId)) continue;
+      try { sessions.push(await readSummary(sessionId)); }
+      catch (cause) { skipped.push({ sessionId, reason: errorMessage(cause) }); }
+    }
+    return Object.freeze({ sessions: Object.freeze(sortCaptainSessionRecords(sessions)), skipped: Object.freeze(skipped) });
   };
 
   const scanAdoptionPredecessor = async (
@@ -916,7 +998,7 @@ export function createCaptainSessionStore(options = {}) {
       ...legacyOrderingBoundaries.filter(
         (candidate) =>
           candidate.sessionId !== target.sessionId &&
-          candidate.state === 'settled' &&
+          candidate.state !== 'uncertain' &&
           candidate.cwd === target.cwd,
       ),
     ]);
@@ -940,9 +1022,12 @@ export function createCaptainSessionStore(options = {}) {
 
   const writeRecord = async (
     recordValue,
-    { noReplace, onPublished },
+    { noReplace, onPublished, portable = false },
   ) => {
-    const record = validateCaptainSessionRecord(recordValue);
+    const record = portable
+      ? validateSessionManifest(recordValue)
+      : await portableWriters.get(recordValue.sessionId)?.checkpoint(recordValue);
+    if (record === undefined) throw new Error('session persistence requires its owning lifecycle');
     const destination = recordPathFor(record.sessionId);
     await ensurePrivateDirectory(sessionsDir, fs);
 
@@ -1006,6 +1091,7 @@ export function createCaptainSessionStore(options = {}) {
         onPublished?.();
       }
       await syncDirectory(sessionsDir, fs);
+      portableWriters.get(record.sessionId)?.published(record);
       return record;
     } catch (cause) {
       try {
@@ -1025,10 +1111,11 @@ export function createCaptainSessionStore(options = {}) {
   };
 
   const deleteRecord = async (sessionId) => {
-    const path = recordPathFor(sessionId);
-    await assertPrivateRegularPath(path, 0o600, fs, 'record');
-    await fs.unlink(path);
-    await syncDirectory(sessionsDir, fs);
+    for (const suffix of ['.records.jsonl', '.hints.json', '.spex.json', '.json']) {
+      const path = join(sessionsDir, `${sessionId}${suffix}`);
+      try { await assertPrivateRegularPath(path, 0o600, fs, 'session file'); await fs.unlink(path); await syncDirectory(sessionsDir, fs); }
+      catch (cause) { if (cause?.code !== 'ENOENT') throw cause; }
+    }
   };
 
   const readLeaseDirectory = async (
@@ -1083,6 +1170,26 @@ export function createCaptainSessionStore(options = {}) {
   const readLeaseOwner = (sessionId, path = leasePathFor(sessionId)) =>
     readLeaseDirectory(sessionId, path, [LEASE_OWNER_FILE]);
 
+  const readLeaseState = async (sessionId) => {
+    assertSessionId(sessionId);
+    try {
+      await assertPrivateDirectory(sessionsDir, fs);
+      await fs.lstat(leasePathFor(sessionId));
+    } catch (cause) { return cause?.code === 'ENOENT' ? 'idle' : 'unknown'; }
+    try {
+      const owner = await readLeaseOwner(sessionId);
+      if (owner.hostname !== localHostname) return 'unknown';
+      let state = 'active';
+      try { await probeProcess(owner.pid); }
+      catch (cause) {
+        if (cause?.code !== 'ESRCH') return 'unknown';
+        state = 'idle';
+      }
+      const current = await readLeaseOwner(sessionId);
+      return current.ownerToken === owner.ownerToken ? state : 'unknown';
+    } catch { return 'unknown'; }
+  };
+
   const activeLeaseErrorFor = async (sessionId, owner) => {
     if (owner.hostname !== localHostname) {
       return foreignCaptainSessionLeaseActiveError(
@@ -1286,8 +1393,9 @@ export function createCaptainSessionStore(options = {}) {
     return publishedOwner;
   };
 
-  const acquire = async (sessionId) => {
+  const acquire = async (sessionId, management = false) => {
     assertSessionId(sessionId);
+    await prepareSessionPermissions(sessionsDir, fs, sessionId);
     let stage;
     let stagePublished = false;
     try {
@@ -1316,6 +1424,21 @@ export function createCaptainSessionStore(options = {}) {
       await publishLeaseStage(sessionId, stage, () => {
         stagePublished = true;
       });
+      if (management) {
+        let released = false;
+        const assertOwner = async () => {
+          if (released) throw new Error('session management lease was released');
+          const current = await readLeaseOwner(sessionId);
+          if (current.ownerToken !== stage.owner.ownerToken) throw new Error('session management ownership changed');
+          return current;
+        };
+        return Object.freeze({ sessionId, ownerToken: stage.owner.ownerToken, assertOwner, async release() {
+          if (released) return;
+          const current = await assertOwner();
+          await retireObservedLease(sessionId, current);
+          released = true;
+        } });
+      }
       return await createLease({
         sessionId,
         owner: stage.owner,
@@ -1324,6 +1447,10 @@ export function createCaptainSessionStore(options = {}) {
         replayFs: fs,
         readReplayStream: (options) => readStream(sessionId, options),
         readRecord,
+        readManifest,
+        readHistory,
+        validateSession: validate,
+        portableWriters,
         writeRecord,
         syncRecordDirectory: () => syncDirectory(sessionsDir, fs),
         deleteRecord,
@@ -1361,14 +1488,219 @@ export function createCaptainSessionStore(options = {}) {
     }
   };
 
+  const migrate = async (sessionId, migration = {}) => {
+    assertSessionId(sessionId);
+    await prepareSessionPermissions(sessionsDir, fs, sessionId, true);
+    const sourcePath = migration.sourcePath ?? recordPathFor(sessionId);
+    const sidecar = sourcePath.endsWith('.spex.json');
+    const sourceDir = dirname(sourcePath);
+    const sourceReplayPath = join(sourceDir, `${sessionId}.records.jsonl`);
+    const external = sourceDir !== sessionsDir;
+    if (!isAbsolute(sourcePath) || sourcePath !== join(sourceDir, `${sessionId}${sidecar ? '.spex' : ''}.json`)) throw new Error('migration source must be the canonical session file');
+    const backupDir = migration.backupDir ?? join(dirname(sessionsDir), 'local', 'migrations', sessionId);
+    const inputsDir = join(backupDir, 'inputs');
+    const receiptPath = join(backupDir, 'receipt.json');
+    const decodeSource = (sourceBytes) => {
+      const source = JSON.parse(sourceBytes);
+      if (!sidecar && source.schemaVersion === 7) {
+        if (external) throw new Error('source is already portable; select its complete bundle instead of legacy migration');
+        return { source };
+      }
+      let recovery, metadata;
+      if (sidecar) {
+        const value = source.session ?? source;
+        if (source.v !== 1 || value.id !== sessionId || !Number.isFinite(value.createdAt) || typeof migration.cwd !== 'string' || !isAbsolute(migration.cwd) || resolve(migration.cwd) !== migration.cwd) throw new Error('invalid legacy desktop sidecar or missing normalized cwd');
+        metadata = { cwd: migration.cwd, createdAt: new Date(value.createdAt).toISOString(), updatedAt: new Date(value.endedAt ?? value.createdAt).toISOString(), reason: 'legacy desktop history lacks complete durable recovery', journal: value.snapshot?.shell?.journal ?? [] };
+      } else {
+        if (source.sessionId !== sessionId) throw new Error('migration session identity mismatch');
+        try { recovery = validateCaptainSessionRecord(source); }
+        catch (cause) {
+          if (!(cause instanceof CaptainSessionRecordNonresumableError)) throw cause;
+          metadata = { cwd: source.cwd, createdAt: source.createdAt, updatedAt: source.updatedAt, reason: `legacy schema ${source.schemaVersion} has no supported recovery`, journal: source.snapshot?.journal ?? [] };
+        }
+        if (recovery && source.schemaVersion !== 6) throw new Error('only schema 6 supports executable migration');
+      }
+      return { source, recovery, metadata };
+    };
+    if (external) await prepareSessionPermissions(sourceDir, fs, sessionId, true);
+    // Refusal needs no ownership or persistent memo. Reread after acquiring
+    // the lease below; a preflight read never authorizes migration writes.
+    try { decodeSource(await readPrivateRegularFile(sourcePath, 0o600, fs, 'migration source')); }
+    catch (cause) { if (cause?.code !== 'ENOENT' || !sidecar && !external) throw cause; }
+    let sourceLease, lease;
+    try {
+      if (external) {
+        const sourceStore = createCaptainSessionStore({ sessionsDir: sourceDir, env, homeDir: home, fsOps: fs, hostname: localHostname, pid: localPid, probeProcess });
+        sourceLease = await sourceStore.acquireManagement(sessionId);
+      }
+      lease = await acquire(sessionId, true);
+      await lease.assertOwner();
+      let sourceBytes;
+      try { sourceBytes = await readPrivateRegularFile(sourcePath, 0o600, fs, 'migration source'); }
+      catch (cause) {
+        if ((!sidecar && !external) || cause?.code !== 'ENOENT') throw cause;
+        let receipt;
+        if (external) {
+          receipt = JSON.parse(await readPrivateRegularFile(receiptPath, 0o600, fs, 'migration receipt'));
+          if (receipt.v !== 1 || receipt.id !== sessionId || !Array.isArray(receipt.inputs) || receipt.inputs[0]?.path !== sourcePath || ![1, 2].includes(receipt.inputs.length)) throw new Error('missing migration source has no matching receipt');
+          for (const [index, input] of receipt.inputs.entries()) {
+            const bytes = await readPrivateRegularFile(join(inputsDir, String(index)), 0o600, fs, 'retained migration input', true);
+            if (sha256(bytes) !== input.sha256) throw new Error('retained migration input differs');
+          }
+        }
+        const current = await validate(sessionId);
+        if (!current.integrityValid) throw new Error('completed migration destination failed validation');
+        if (receipt?.complete === false) await writePrivateJson(receiptPath, { ...receipt, complete: true }, fs);
+        return { manifest: current.manifest, migrated: false, reasons: current.reasons };
+      }
+      let { source, recovery, metadata } = decodeSource(sourceBytes);
+      if (!sidecar && source.schemaVersion === 7) {
+        const current = await validate(sessionId);
+        return { manifest: current.manifest, migrated: false, reasons: current.reasons };
+      }
+      const sourceSnapshot = await readReplaySnapshot({ sessionsDir: sourceDir, path: sourceReplayPath, fs, afterSeq: 0, forceFullRead: true });
+      const snapshot = external ? await readReplaySnapshot({ sessionsDir, path: recordsPathFor(sessionId), fs, afterSeq: 0, forceFullRead: true }) : sourceSnapshot;
+      const currentReplay = snapshot.absent ? undefined : snapshot.bytes;
+      let originalReplay = sourceSnapshot.absent ? undefined : sourceSnapshot.bytes;
+      let priorReceipt;
+      try { priorReceipt = JSON.parse(await readPrivateRegularFile(receiptPath, 0o600, fs, 'migration receipt')); }
+      catch (cause) { if (cause?.code !== 'ENOENT') throw cause; }
+      if (priorReceipt !== undefined) {
+        if (priorReceipt.v !== 1 || priorReceipt.id !== sessionId || !Array.isArray(priorReceipt.inputs) || priorReceipt.inputs[0]?.path !== sourcePath || priorReceipt.inputs[0]?.sha256 !== sha256(Buffer.from(sourceBytes))) throw new Error('migration source differs from retained input');
+        const retainedSource = await readPrivateRegularFile(join(inputsDir, '0'), 0o600, fs, 'retained migration source');
+        if (retainedSource !== sourceBytes) throw new Error('migration retained source differs');
+        if (priorReceipt.inputs.length === 2) {
+          originalReplay = await readPrivateRegularFile(join(inputsDir, '1'), 0o600, fs, 'retained migration replay', true);
+          if (priorReceipt.inputs[1].path !== sourceReplayPath || sha256(originalReplay) !== priorReceipt.inputs[1].sha256) throw new Error('retained migration replay differs');
+        } else if (priorReceipt.inputs.length === 1) originalReplay = undefined;
+        else throw new Error('invalid migration inputs');
+      }
+      if (external && priorReceipt && !sourceSnapshot.absent && !sourceSnapshot.bytes.equals(originalReplay ?? Buffer.alloc(0))) throw new Error('migration source replay differs from retained input');
+      let replayBytes = originalReplay ?? Buffer.alloc(0);
+      if (originalReplay === undefined) {
+        const journal = metadata?.journal ?? recovery?.snapshot?.journal ?? [];
+        const updatedAt = source.updatedAt ?? metadata.updatedAt;
+        const projected = legacyJournalHistory({ updatedAt, snapshot: { journal } }, 0, {}).entries;
+        const records = [...projected.map(({ record }) => record), ...journal.map((entry) => ({ type: 'legacy_journal', timestamp: Date.parse(updatedAt), entry }))];
+        replayBytes = Buffer.from(records.map((record, index) => `${JSON.stringify({ v: 1, seq: index + 1, record: sanitizeReplayRecord(record) })}\n`).join(''));
+      }
+      let history = parseSessionHistory(replayBytes);
+      if (history.pendingTail) {
+        try {
+          parseReplayEnvelope(replayBytes.subarray(history.completeBytes), history.lastReadableSeq + 1);
+          replayBytes = Buffer.concat([replayBytes, Buffer.from('\n')]);
+          history = parseSessionHistory(replayBytes);
+        } catch { /* Preserve a torn or invalid tail in the retained input only. */ }
+      }
+      const completeReplay = replayBytes.subarray(0, history.completeBytes);
+      let offset = 0;
+      replayBytes = Buffer.concat(history.entries.map((entry) => {
+        const end = completeReplay.indexOf(0x0a, offset) + 1;
+        const line = completeReplay.subarray(offset, end);
+        offset = end;
+        const record = sanitizeReplayRecord(entry.record);
+        return isDeepStrictEqual(record, entry.record)
+          ? line : Buffer.from(`${JSON.stringify({ ...entry, record })}\n`);
+      }));
+      let manifest;
+      if (recovery && !history.incomplete && !history.pendingTail) {
+        const context = contextFromRecovery(recovery);
+        context.timestamp = Date.parse(recovery.updatedAt);
+        const contextSeq = history.lastReadableSeq + 1;
+        replayBytes = Buffer.concat([replayBytes, Buffer.from(`${JSON.stringify({v:1,seq:contextSeq,record:context})}\n`)]);
+        manifest = manifestFromRecovery(recovery, { seq: contextSeq, sha256: sha256(replayBytes), incomplete: false }, contextSeq);
+      } else {
+        if (recovery) metadata = { cwd: recovery.cwd, createdAt: recovery.createdAt, updatedAt: recovery.updatedAt, reason: 'legacy replay is incomplete' };
+        manifest = validateSessionManifest({ schemaVersion: 7, kind: 'captain-session', sessionId, state: 'history-only', cwd: metadata.cwd, createdAt: metadata.createdAt, updatedAt: metadata.updatedAt, reason: metadata.reason, replay: { seq: history.lastReadableSeq, sha256: sha256(replayBytes), incomplete: history.incomplete || history.pendingTail }, contextSeq: null });
+      }
+      if (priorReceipt && currentReplay !== undefined && !currentReplay.equals(originalReplay ?? Buffer.alloc(0)) && !currentReplay.equals(replayBytes)) throw new Error('migration destination replay diverged');
+      if (external && currentReplay !== undefined && !currentReplay.equals(replayBytes)) throw new Error('migration destination replay diverged');
+      if (sidecar || external) {
+        try {
+          const existing = await readPrivateRegularFile(recordPathFor(sessionId), 0o600, fs, 'migration destination');
+          if (existing !== `${JSON.stringify(manifest)}\n`) throw new Error('migration destination manifest diverged');
+        } catch (cause) { if (cause?.code !== 'ENOENT') throw cause; }
+      }
+      await ensurePrivateDirectory(inputsDir, fs);
+      const inputs = [{ path: sourcePath, bytes: Buffer.from(sourceBytes, 'utf8') }, ...(originalReplay === undefined ? [] : [{ path: sourceReplayPath, bytes: originalReplay }])];
+      for (const [index, input] of inputs.entries()) {
+        const path = join(inputsDir, String(index));
+        try {
+          const retained = await readPrivateRegularFile(path, 0o600, fs, 'retained migration source', true);
+          if (!retained.equals(input.bytes)) throw new Error('migration retained source differs');
+        } catch (cause) { if (cause?.code !== 'ENOENT') throw cause; await writePrivateBytes(path, input.bytes, fs); }
+      }
+      const receipt = { v: 1, id: sessionId, inputs: inputs.map(({ path, bytes }) => ({ path, sha256: sha256(bytes) })), complete: false };
+      await writePrivateJson(receiptPath, receipt, fs);
+      await lease.assertOwner();
+      await writePrivateBytes(recordsPathFor(sessionId), replayBytes, fs);
+      await writePrivateBytes(recordPathFor(sessionId), Buffer.from(`${JSON.stringify(manifest)}\n`), fs);
+      const published = await validate(sessionId);
+      if (!published.integrityValid) throw new Error('published migration bundle failed validation');
+      if (external) {
+        await sourceLease.assertOwner();
+        try { await assertPrivateRegularPath(sourceReplayPath, 0o600, fs, 'migration source replay'); await fs.unlink(sourceReplayPath); await syncDirectory(sourceDir, fs); }
+        catch (cause) { if (cause?.code !== 'ENOENT') throw cause; }
+      }
+      if (sidecar || external) { await fs.unlink(sourcePath); await syncDirectory(sourceDir, fs); }
+      await writePrivateJson(receiptPath, { ...receipt, complete: true }, fs);
+      return { manifest, migrated: true, reasons: [] };
+    } finally {
+      try { await lease?.release(); } finally { await sourceLease?.release(); }
+    }
+  };
+
+  const migrateLegacyDefault = async (migration = {}) => {
+    const sourceEnv = migration.env ?? env;
+    const sourceHome = migration.homeDir ?? home;
+    const sourceDir = join(sourceEnv.XDG_STATE_HOME || join(sourceHome, '.local', 'state'), 'playbook', 'sessions');
+    const result = { sourceDir, migrated: [], skipped: [] };
+    if (sourceDir === sessionsDir) return result;
+    const sourceStore = createCaptainSessionStore({ sessionsDir: sourceDir, env: sourceEnv, homeDir: sourceHome, fsOps: fs, hostname: localHostname, pid: localPid, probeProcess });
+    await sourceStore.prepare();
+    try { await assertPrivateDirectory(sourceDir, fs); }
+    catch (cause) { if (cause?.code === 'ENOENT') return result; throw cause; }
+    const names = await fs.readdir(sourceDir);
+    const ids = [...new Set(names.map((name) => name.endsWith('.records.jsonl') ? name.slice(0, -14) : name.endsWith('.json') ? name.slice(0, -5) : '').filter((id) => SESSION_ID_PATTERN.test(id)))].sort();
+    for (const sessionId of ids) {
+      const state = await sourceStore.readLeaseState(sessionId);
+      if (state !== 'idle') throw new Error(`legacy session ${sessionId} ownership is ${state}; stop all old writers before migration`);
+      const sourcePath = join(sourceDir, `${sessionId}.json`);
+      try {
+        const source = JSON.parse(await readPrivateRegularFile(sourcePath, 0o600, fs, 'legacy default manifest'));
+        if (![2, 3, 4, 5, 6].includes(source.schemaVersion)) throw new Error(`unsupported legacy schema ${source.schemaVersion}`);
+        try { validateCaptainSessionRecord(source); }
+        catch (cause) { if (!(cause instanceof CaptainSessionRecordNonresumableError)) throw cause; }
+      } catch (cause) { result.skipped.push({ sessionId, reason: errorMessage(cause) }); continue; }
+      await migrate(sessionId, { sourcePath });
+      result.migrated.push(sessionId);
+    }
+    return result;
+  };
+
+  const remove = async (sessionId) => {
+    const lease = await acquire(sessionId, true);
+    try { await lease.assertOwner(); await deleteRecord(sessionId); }
+    finally { await lease.release(); }
+  };
+
   return Object.freeze({
     sessionsDir,
+    prepare,
+    migrate,
+    migrateLegacyDefault,
+    readManifest,
+    readHistory,
+    readLeaseState,
+    validate,
+    delete: remove,
     listSummaries,
     readSummary,
     read,
     readStream,
     latest,
     acquire,
+    acquireManagement: (sessionId) => acquire(sessionId, true),
   });
 }
 
@@ -2063,7 +2395,7 @@ function canonicalReplayJson(value) {
   return JSON.stringify(value);
 }
 
-function sanitizeReplayValue(value, path, ancestors) {
+function sanitizeReplayValue(value, path, ancestors, scope = 'record') {
   if (
     value === null ||
     typeof value === 'string' ||
@@ -2118,6 +2450,7 @@ function sanitizeReplayValue(value, path, ancestors) {
           descriptor.value,
           `${path}[${index}]`,
           nextAncestors,
+          scope,
         ),
       );
     }
@@ -2151,10 +2484,19 @@ function sanitizeReplayValue(value, path, ancestors) {
     throw new TypeError(`${path} must not contain symbol-keyed properties`);
   }
   const nextAncestors = new Set(ancestors).add(value);
+  // Cligent session IDs are provider continuations. Playbook trace and
+  // checkpoint session IDs are logical identities and must survive.
+  const type = descriptors.type?.value;
+  const adapterEvent = scope !== 'content' &&
+    typeof type === 'string' && typeof descriptors.agent?.value === 'string' &&
+    Number.isFinite(descriptors.timestamp?.value) && Object.hasOwn(descriptors, 'payload');
+  const provider = scope === 'provider' || scope === 'identity' || adapterEvent;
+  const observed = type === 'captain_event' || type === 'player_event';
   const copy = {};
   for (const key of keys) {
     if (typeof key !== 'string') continue;
     if (key === 'resumeToken') continue;
+    if (provider && (['sessionid', 'nativesessionid', 'threadid', 'conversationid'].includes(key.replaceAll('_', '').toLowerCase()) || (scope === 'identity' && key === 'id'))) continue;
     const descriptor = descriptors[key];
     if (
       descriptor === undefined ||
@@ -2172,6 +2514,11 @@ function sanitizeReplayValue(value, path, ancestors) {
         descriptor.value,
         `${path}.${key}`,
         nextAncestors,
+        scope === 'content' || (provider && (key === 'input' || key === 'output'))
+          ? 'content'
+          : provider
+            ? ['session', 'thread', 'conversation'].includes(key) ? 'identity' : 'provider'
+            : observed && key === 'event' ? 'provider' : 'record',
       ),
       enumerable: true,
       configurable: true,
@@ -2189,6 +2536,10 @@ async function createLease({
   replayFs,
   readReplayStream,
   readRecord,
+  readManifest,
+  readHistory,
+  validateSession,
+  portableWriters,
   writeRecord,
   syncRecordDirectory,
   deleteRecord,
@@ -2239,9 +2590,102 @@ async function createLease({
     readStream: readReplayStream,
   });
 
+  let contextSeq;
+  let previousManifest;
+  let acknowledgedHints = { players: {} };
+  try { previousManifest = await readManifest(sessionId); contextSeq = previousManifest.contextSeq; }
+  catch { /* Unsupported recovery still permits leased migration/deletion. */ }
+
+  const recordContext = async (value) => {
+    const context = validateSessionContext(value);
+    if (contextSeq !== undefined && contextSeq !== null) {
+      const previous = (await readHistory(sessionId)).entries.find((entry) => entry.seq === contextSeq)?.record;
+      if (previous) {
+        const { timestamp: _previousTimestamp, ...oldContext } = previous;
+        const { timestamp: _newTimestamp, ...newContext } = context;
+        if (isDeepStrictEqual(oldContext, newContext)) return contextSeq;
+      }
+    }
+    await replayWriter.append(context);
+    await replayWriter.checkpoint();
+    const status = replayWriter.status();
+    if (status.incomplete || status.lastDurableSeq === null) throw new Error('cannot persist session execution context');
+    contextSeq = status.lastDurableSeq;
+    return contextSeq;
+  };
+  const checkpoint = async (value) => {
+    const recovery = validateCaptainSessionRecord(value);
+    const required = contextFromRecovery(recovery);
+    let contextHistory;
+    try { contextHistory = await readHistory(sessionId); } catch { /* Preserve the last proven context on replay failure. */ }
+    const applicable = contextHistory?.entries.findLast(({ record }) =>
+      record.type === 'session_context' && record.contextVersion === 1 &&
+      record.captainId === required.captainId && isDeepStrictEqual(record.configuration, required.configuration));
+    if (applicable) contextSeq = applicable.seq;
+    else if (contextSeq === undefined || contextSeq === null || !replayWriter.status().incomplete) await recordContext(required);
+    await replayWriter.checkpoint();
+    const status = replayWriter.status();
+    let history;
+    try { history = await readHistory(sessionId); }
+    catch { history = { digests: [], incomplete: true }; }
+    const durableSeq = status.lastDurableSeq ?? previousManifest?.replay?.seq ?? 0;
+    const seq = history.digests[durableSeq] === undefined ? previousManifest?.replay?.seq ?? 0 : durableSeq;
+    const digest = history.digests[seq] ?? previousManifest?.replay?.sha256 ?? EMPTY_REPLAY_SHA256;
+    const replay = { seq, sha256: digest, incomplete: previousManifest?.replay?.incomplete === true || status.incomplete || history.incomplete || history.digests[seq] === undefined };
+    const manifest = manifestFromRecovery(recovery, replay, contextSeq);
+    return manifest;
+  };
+  portableWriters.set(sessionId, { checkpoint, sync: replayWriter.checkpoint, published: (manifest) => { previousManifest = manifest; } });
+
+  const hintsPath = join(sessionsDir, `${sessionId}.hints.json`);
+  const readHints = async () => {
+    try {
+      const bytes = await readPrivateRegularFile(join(sessionsDir, `${sessionId}.json`), 0o600, replayFs, 'record');
+      const manifest = validateSessionManifest(JSON.parse(bytes));
+      const hints = JSON.parse(await readPrivateRegularFile(hintsPath, 0o600, replayFs, 'hints'));
+      return validateSessionHints(hints, bytes, manifest);
+    } catch { return { players: {} }; }
+  };
+  const writeHints = async (hints) => {
+    const bytes = await readPrivateRegularFile(join(sessionsDir, `${sessionId}.json`), 0o600, replayFs, 'record');
+    const manifest = validateSessionManifest(JSON.parse(bytes));
+    const value = { v: 1, sessionId, checkpointSha256: sha256(bytes), players: hints.players, ...(hints.captain ? { captain: hints.captain } : {}) };
+    validateSessionHints(value, bytes, manifest);
+    await writePrivateJson(hintsPath, value, replayFs);
+  };
+  const consumeHints = () => runExclusive(async () => {
+    await assertOwnerUnchecked();
+    const hints = await readHints();
+    await writeHints({ players: {} });
+    // Unused conversations cannot advance. Retain that proof until the
+    // participant's before-call hook clears it; crashes still lose the hints.
+    acknowledgedHints = structuredClone(hints);
+    return hints;
+  });
+  const acknowledgeHint = (participantId, token) => {
+    if (typeof token !== 'string' || token.length === 0) return;
+    if (participantId === 'captain') acknowledgedHints.captain = { kind: 'pinned', token };
+    else acknowledgedHints.players[participantId] = token;
+  };
+  const clearHint = (participantId) => {
+    if (participantId === 'captain') delete acknowledgedHints.captain;
+    else delete acknowledgedHints.players[participantId];
+  };
+  const assertContinuable = async (context = {}) => {
+    const result = await validateSession(sessionId, context);
+    if (!result.resumable) throw new Error(result.reasons.join('; '));
+    return result;
+  };
+  const append = (record, role) => replayWriter.append(
+    contextSeq !== undefined && record?.type !== 'session_context' && typeof record?.type === 'string' && Number.isFinite(record?.timestamp)
+      ? { ...record, contextSeq } : record,
+    role,
+  );
+
   const finishSettlement = async (record) => {
     await replayWriter.checkpoint();
-    return record;
+    try { await writeHints(acknowledgedHints); } catch { /* Hints are optional; missing hints start fresh. */ }
+    return validateCaptainSessionRecord(projectRecovery(record));
   };
 
   const read = () =>
@@ -2353,6 +2797,7 @@ async function createLease({
   const initializeSettledWithPredecessor = (options = {}) =>
     runExclusive(async () => {
       const target = freshSettledRecord(options);
+      if (options.context !== undefined) await recordContext(options.context);
       await assertOwnerUnchecked();
       if (
         (await readRecord(sessionId, { missing: 'undefined' })) !== undefined
@@ -2588,6 +3033,7 @@ async function createLease({
         'Captain session attempted execution projection',
       );
       await assertOwnerUnchecked();
+      await assertContinuable();
       const prior = await readRecord(sessionId, { missing: 'undefined' });
       if (prior === undefined) {
         throw new Error('Captain session does not exist for continuation');
@@ -2635,6 +3081,7 @@ async function createLease({
         throw new Error('Captain session retry requires a fresh attempt id');
       }
       await assertOwnerUnchecked();
+      await assertContinuable();
       const prior = await requireUncertainRecord(
         await readRecord(sessionId, { missing: 'undefined' }),
         expectedAttemptId,
@@ -2923,7 +3370,7 @@ async function createLease({
   } = {}) =>
     runExclusive(async () => {
       assertUuid(attemptId, 'Captain session attempt id');
-      const updates = validateRetainedGenerationUpdates(retentionUpdates);
+      const rawUpdates = validateRetainedGenerationUpdates(retentionUpdates);
       const settledUnresolvedEffects = assertPlaybookCaptainUnresolvedEffects(
         unresolvedEffects,
       );
@@ -2946,7 +3393,19 @@ async function createLease({
           'Captain session abandonment settlement attempt differs from its durable marker',
         );
       }
-      const settledSnapshot = assertPlaybookCaptainShellSnapshot(snapshot);
+      // Compare durable recovery forms, not provider-local continuation hints.
+      // Validate before projection so removing a token cannot legalize bad input.
+      const rawSnapshot = assertPlaybookCaptainShellSnapshot(snapshot);
+      const rawRetained = applyRetainedGenerationUpdates(
+        current.retainedGenerations ?? {}, rawUpdates, current.structuralProjection);
+      validateRetainedGenerations(rawRetained, current.structuralProjection, current.effectLedger);
+      const projected = projectRecovery({ ...current, snapshot: rawSnapshot,
+        retainedGenerations: rawRetained,
+      });
+      const settledSnapshot = assertPlaybookCaptainShellSnapshot(projected.snapshot);
+      const updates = rawUpdates.map((update) => update.kind === 'retain'
+        ? { ...update, generation: projected.retainedGenerations[update.rootPlaybookId] }
+        : update);
       if (settledAbandonment !== undefined) {
         requireAbandonmentSettlement(
           settledAbandonment,
@@ -3172,8 +3631,7 @@ async function createLease({
         await assertOwnerUnchecked();
         return undefined;
       }
-      // writeRecord's stable key order reconstructs the exact prior settled
-      // bytes from the baseline carried by the uncertain record.
+      // Restore the prior recovery baseline while retaining attempt history.
       const record = validateCaptainSessionRecord({
         schemaVersion: prior.schemaVersion,
         kind: CAPTAIN_SESSION_RECORD_KIND,
@@ -3200,9 +3658,14 @@ async function createLease({
     replayWriter.closeAppendAdmission();
     return runExclusive(async () => {
       await replayWriter.prepareRelease();
+      if (replayWriter.status().incomplete && previousManifest?.replay?.incomplete !== true) {
+        const record = await readRecord(sessionId, { missing: 'undefined' });
+        if (record !== undefined) await writeRecord(record, { noReplace: false });
+      }
       const current = await assertOwnerUnchecked();
       await retireObservedLease(sessionId, current);
       released = true;
+      portableWriters.delete(sessionId);
       return replayWriter.status();
     });
   };
@@ -3210,7 +3673,13 @@ async function createLease({
   return Object.freeze({
     sessionId,
     ownerToken: owner.ownerToken,
-    append: replayWriter.append,
+    append,
+    recordContext,
+    consumeHints,
+    acknowledgeHint,
+    clearHint,
+    assertContinuable,
+    readManifest: () => readManifest(sessionId),
     readStream: replayWriter.read,
     streamStatus: replayWriter.status,
     read,
@@ -3387,6 +3856,7 @@ export function captainSessionSelectedMembers(value) {
 }
 
 export function validateCaptainSessionRecord(value) {
+  if (value?.schemaVersion === 7) return recoveryFromManifest(value);
   const record = requireRecord(
     snapshotJsonValue(value, 'Captain session record'),
     'Captain session record',
@@ -3500,12 +3970,7 @@ function validateCanonicalCaptainSessionRecord(
       'settled Captain session updatedAt must follow its creation marker',
     );
   }
-  if (typeof record.cwd !== 'string' || !isAbsolute(record.cwd)) {
-    throw new Error('Captain session record cwd must be an absolute path');
-  }
-  if (resolve(record.cwd) !== record.cwd) {
-    throw new Error('Captain session record cwd must be normalized');
-  }
+  if (!isRecordedAbsolutePath(record.cwd)) throw new Error('Captain session record cwd must be a normalized absolute path');
   const structural = validateCaptainSessionStructuralProjectionWithSchemas(
     record.structuralProjection,
     'Captain session record structuralProjection',
@@ -4699,12 +5164,7 @@ function assertReleasedSchema2CaptainSessionRecord(record) {
       'settled Captain session updatedAt must follow its creation marker',
     );
   }
-  if (typeof record.cwd !== 'string' || !isAbsolute(record.cwd)) {
-    throw new Error('Captain session record cwd must be an absolute path');
-  }
-  if (resolve(record.cwd) !== record.cwd) {
-    throw new Error('Captain session record cwd must be normalized');
-  }
+  if (!isRecordedAbsolutePath(record.cwd)) throw new Error('Captain session record cwd must be a normalized absolute path');
   requireRecord(record.config, 'Captain session record config');
   requireRecord(record.snapshot, 'Captain session record snapshot');
 
@@ -5080,10 +5540,7 @@ function validateRoleIds(value, path) {
   if (
     !Array.isArray(value) ||
     value.some(
-      (roleId) =>
-        typeof roleId !== 'string' ||
-        !ROLE_ID_PATTERN.test(roleId) ||
-        roleId === RESERVED_ID,
+      (roleId) => !isCanonicalLocalRoleId(roleId) || roleId === RESERVED_ID,
     ) ||
     new Set(value).size !== value.length
   ) {
@@ -5889,8 +6346,8 @@ function nextTimestamp(value, previous) {
   return new Date(Date.parse(previous) + 1).toISOString();
 }
 
-async function readPrivateRegularFile(path, mode, fs, label) {
-  await assertPrivateRegularPath(path, mode, fs, label);
+async function readPrivateRegularFile(path, mode, fs, label, raw = false) {
+  const before = await assertPrivateRegularPath(path, mode, fs, label);
   const handle = await fs.open(
     path,
     constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0),
@@ -5903,7 +6360,12 @@ async function readPrivateRegularFile(path, mode, fs, label) {
     if ((stat.mode & 0o7777) !== mode) {
       throw new Error(`${label} permissions must be ${octal(mode)}`);
     }
-    return await handle.readFile('utf8');
+    if (!sameFileIdentity(before, stat)) throw new Error(`${label} changed during open`);
+    const bytes = await handle.readFile();
+    const after = await handle.stat();
+    const current = await assertPrivateRegularPath(path, mode, fs, label);
+    if (!sameFileIdentity(after, current) || after.size !== stat.size) throw new Error(`${label} changed during read`);
+    return raw ? bytes : new TextDecoder('utf-8', { fatal: true }).decode(bytes);
   } finally {
     await handle.close();
   }
@@ -6006,3 +6468,109 @@ async function assertDirectoryNotLink(path, fs) {
 function errorMessage(error) {
   return error instanceof Error ? error.message : String(error);
 }
+
+// Opening is the only permission preparation boundary. Strict readers never
+// change modes, and verified handles ensure tightening cannot follow links.
+async function prepareSessionPermissions(sessionsDir, fs, selectedSessionId, includeSidecars = false) {
+  let initial;
+  try { initial = await fs.lstat(sessionsDir); }
+  catch (cause) { if (cause?.code === 'ENOENT') return; throw cause; }
+  const uid = process.getuid?.();
+  const verify = (stat, directory) => {
+    const required = directory ? 0o700 : 0o600;
+    if (stat.isSymbolicLink() || (directory ? !stat.isDirectory() : !stat.isFile() || stat.nlink !== 1) || (uid !== undefined && stat.uid !== uid) || (stat.mode & required) !== required) throw new Error('session permission preparation refuses unsafe ownership, links, type, or owner access');
+  };
+  const tighten = async (path, before, directory) => {
+    verify(before, directory);
+    const handle = await fs.open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0) | (directory ? constants.O_DIRECTORY ?? 0 : 0));
+    try {
+      const opened = await handle.stat(); verify(opened, directory);
+      if (!sameFileIdentity(before, opened)) throw new Error('session entry changed during permission preparation');
+      const mode = directory ? 0o700 : 0o600;
+      if ((opened.mode & 0o7777) !== mode) await handle.chmod(mode);
+      const after = await handle.stat(); verify(after, directory);
+      const current = await fs.lstat(path); verify(current, directory);
+      if (!sameFileIdentity(after, current) || (after.mode & 0o7777) !== mode || (current.mode & 0o7777) !== mode) throw new Error('session permission tightening could not be verified');
+    } finally { await handle.close(); }
+  };
+  await tighten(sessionsDir, initial, true);
+  for (const name of await fs.readdir(sessionsDir)) {
+    const eligible = /^[0-9a-f-]{36}\.(?:json|records\.jsonl|hints\.json)$/.test(name)
+      || (includeSidecars && /^[0-9a-f-]{36}\.spex\.json$/.test(name));
+    if (!eligible || (selectedSessionId !== undefined && !name.startsWith(`${selectedSessionId}.`))) continue;
+    const path = join(sessionsDir, name);
+    await tighten(path, await fs.lstat(path), false);
+  }
+}
+
+async function readSessionHistory({ sessionsDir, path, fs, afterSeq = 0 }) {
+  if (!Number.isSafeInteger(afterSeq) || afterSeq < 0) throw new Error('history afterSeq must be a nonnegative safe integer');
+  const snapshot = await readReplaySnapshot({ sessionsDir, path, fs, afterSeq: 0, forceFullRead: true });
+  const bytes = snapshot.absent ? Buffer.alloc(0) : snapshot.bytes;
+  return Object.freeze({ ...parseSessionHistory(bytes, afterSeq), missing: snapshot.absent === true });
+}
+
+
+function legacyJournalHistory(record, afterSeq, absentHistory) {
+  const entries = [];
+  const timestamp = Date.parse(record.updatedAt);
+  let activeTurn;
+  const emit = (event) => entries.push(Object.freeze({ v: 1, seq: entries.length + 1, record: Object.freeze(event) }));
+  const finish = () => {
+    if (activeTurn !== undefined) emit({ type: 'turn_finished', timestamp, turnId: activeTurn });
+    activeTurn = undefined;
+  };
+  for (const entry of record.snapshot?.journal ?? []) {
+    if (!Number.isSafeInteger(entry.turnId) || entry.turnId <= 0 || typeof entry.payload !== 'string') continue;
+    if (entry.kind === 'boss') {
+      finish(); activeTurn = entry.turnId;
+      emit({ type: 'turn_started', timestamp, turnId: entry.turnId, turn: { id: entry.turnId, prompt: entry.payload } });
+    } else if (entry.kind === 'reply' && entry.turnId === activeTurn) {
+      emit({ type: 'captain_reply', timestamp, turnId: entry.turnId, text: entry.payload });
+    }
+  }
+  finish();
+  return Object.freeze({ ...absentHistory, synthetic: true, lastReadableSeq: entries.length, entries: Object.freeze(entries.filter(({ seq }) => seq > afterSeq)) });
+}
+
+function parseSessionHistory(bytes, afterSeq = 0) {
+  const entries = [], digests = [EMPTY_REPLAY_SHA256];
+  const hash = createHash('sha256');
+  let offset = 0, seq = 0, damage;
+  while (offset < bytes.length) {
+    const newline = bytes.indexOf(10, offset);
+    if (newline < 0) break;
+    let entry;
+    try { entry = parseReplayEnvelope(bytes.subarray(offset, newline), seq + 1); }
+    catch (cause) { damage = { seq: seq + 1, offset, reason: errorMessage(cause) }; break; }
+    hash.update(bytes.subarray(offset, newline + 1));
+    seq += 1; digests.push(hash.copy().digest('hex'));
+    if (seq > afterSeq) entries.push(entry);
+    offset = newline + 1;
+  }
+  return Object.freeze({ entries: Object.freeze(entries), lastReadableSeq: seq, incomplete: damage !== undefined, ...(damage ? { damage } : {}), pendingTail: damage === undefined && offset < bytes.length, digests: Object.freeze(digests), completeBytes: offset });
+}
+
+async function writePrivateJson(path, value, fs) {
+  return writePrivateBytes(path, Buffer.from(`${JSON.stringify(value)}\n`, 'utf8'), fs);
+}
+
+async function writePrivateBytes(path, bytes, fs) {
+  const directory = dirname(path);
+  await assertPrivateDirectory(directory, fs);
+  try { await assertPrivateRegularPath(path, 0o600, fs, 'session data'); }
+  catch (cause) { if (cause?.code !== 'ENOENT') throw cause; }
+  const temporary = join(directory, `.${randomUUID()}.tmp`);
+  let handle;
+  try {
+    handle = await fs.open(temporary, 'wx', 0o600);
+    await handle.chmod(0o600);
+    await handle.writeFile(bytes);
+    await handle.sync(); await handle.close(); handle = undefined;
+    await fs.rename(temporary, path);
+    await syncDirectory(directory, fs);
+  } finally {
+    await handle?.close();
+    try { await fs.unlink(temporary); } catch (cause) { if (cause?.code !== 'ENOENT') throw cause; }
+  }
+}