botmux 3.15.0 → 3.16.0

package/dist/services/session-store.js

@@ -10,6 +10,20 @@ import { removePromptContextDir } from './prompt-context-store.js';
 let sessions = new Map();
 let loaded = false;
 let currentAppId;
+let loadFailure;
+/**
+ * The compatibility reader deliberately exposes an empty projection after a
+ * read/parse failure. Destructive callers must use the strict API below so an
+ * unreadable store cannot be mistaken for "there are no durable sessions".
+ */
+export class SessionStoreUnavailableError extends Error {
+    loadError;
+    name = 'SessionStoreUnavailableError';
+    constructor(loadError) {
+        super(`session store is unavailable: ${loadError.message}`);
+        this.loadError = loadError;
+    }
+}
 // Legacy fields from the removed「处理中」placeholder-card PATCH delivery. They
 // no longer exist on Session and nothing reads them, but sessions persisted
 // before the removal still carry them on disk. Strip on write so the file
@@ -20,34 +34,34 @@ export function stripLegacyPendingCardFields(session) {
         delete session[f];
 }
 /** The active row no longer has the lineage/ownership sampled by the caller. */
-export class RiffLineageOwnershipError extends Error {
-    name = 'RiffLineageOwnershipError';
+export class RemoteLineageOwnershipError extends Error {
+    name = 'RemoteLineageOwnershipError';
 }
-export class RiffLineageBatchError extends Error {
+export class RemoteLineageBatchError extends Error {
     stage;
     sessionIds;
-    name = 'RiffLineageBatchError';
+    name = 'RemoteLineageBatchError';
     constructor(stage, sessionIds, message) {
         super(message);
         this.stage = stage;
         this.sessionIds = sessionIds;
     }
 }
-function riffDurableOwner(session) {
+function remoteDurableOwner(session) {
     return {
         pid: session.pid ?? null,
         larkAppId: session.larkAppId ?? null,
         backendType: session.backendType ?? null,
     };
 }
-function riffOwnersEqual(left, right) {
+function remoteOwnersEqual(left, right) {
     return left.pid === right.pid
         && left.larkAppId === right.larkAppId
         && left.backendType === right.backendType;
 }
-let testOnlyAfterRiffBatchRename;
-export function __testOnly_setAfterRiffBatchRename(hook) {
-    testOnlyAfterRiffBatchRename = hook;
+let testOnlyAfterRemoteBatchRename;
+export function __testOnly_setAfterRemoteBatchRename(hook) {
+    testOnlyAfterRemoteBatchRename = hook;
 }
 /**
  * Initialise session store for a specific bot (multi-daemon mode).
@@ -58,6 +72,7 @@ export function init(appId) {
     currentAppId = appId;
     loaded = false;
     sessions = new Map();
+    loadFailure = undefined;
 }
 function getFilePath() {
     const fileName = currentAppId ? `sessions-${currentAppId}.json` : 'sessions.json';
@@ -97,6 +112,13 @@ function repairMissingChatScopes() {
     }
     return repaired;
 }
+function parseSessionsProjectionStrict(raw, fp) {
+    const value = JSON.parse(raw);
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error(`invalid sessions projection at ${fp}`);
+    }
+    return value;
+}
 // Sessions persisted before 2026-04-29 lack `cliId`; consumers must fall back to 'unknown' at the render boundary.
 function load() {
     if (loaded)
@@ -106,7 +128,7 @@ function load() {
     withFileLockSync(fp, () => {
         if (existsSync(fp)) {
             try {
-                const data = JSON.parse(readFileSync(fp, 'utf-8'));
+                const data = parseSessionsProjectionStrict(readFileSync(fp, 'utf-8'), fp);
                 sessions = new Map(Object.entries(data));
                 const repaired = repairMissingChatScopes();
                 if (repaired > 0) {
@@ -126,6 +148,7 @@ function load() {
             }
             catch (err) {
                 logger.error(`Failed to load sessions: ${err}`);
+                loadFailure = err instanceof Error ? err : new Error(String(err));
                 sessions = new Map();
             }
         }
@@ -135,7 +158,7 @@ function load() {
             const legacyFp = join(config.session.dataDir, 'sessions.json');
             if (existsSync(legacyFp)) {
                 try {
-                    const data = JSON.parse(readFileSync(legacyFp, 'utf-8'));
+                    const data = parseSessionsProjectionStrict(readFileSync(legacyFp, 'utf-8'), legacyFp);
                     sessions = new Map();
                     for (const [k, v] of Object.entries(data)) {
                         if (v.larkAppId === currentAppId)
@@ -155,6 +178,7 @@ function load() {
                 }
                 catch (err) {
                     logger.error(`Failed to migrate sessions from legacy file: ${err}`);
+                    loadFailure = err instanceof Error ? err : new Error(String(err));
                     sessions = new Map();
                 }
             }
@@ -162,6 +186,18 @@ function load() {
     });
     loaded = true;
 }
+/**
+ * Mutations must never proceed from the compatibility reader's empty
+ * projection after a load failure. In particular, serialising that empty
+ * cache would replace the unreadable durable file and destroy the only copy
+ * of its rows. Keep the failure sticky until init() explicitly reloads the
+ * selected store, matching listSessionsStrict().
+ */
+function loadForWrite() {
+    load();
+    if (loadFailure)
+        throw new SessionStoreUnavailableError(loadFailure);
+}
 function readExistingSessionsFromDisk(fp) {
     if (!existsSync(fp))
         return { raw: '', parsed: {} };
@@ -177,11 +213,7 @@ function readSessionsProjectionStrict(fp) {
     if (!existsSync(fp))
         return { raw: '', parsed: {} };
     const raw = readFileSync(fp, 'utf-8');
-    const value = JSON.parse(raw);
-    if (!value || typeof value !== 'object' || Array.isArray(value)) {
-        throw new Error(`invalid sessions projection at ${fp}`);
-    }
-    return { raw, parsed: value };
+    return { raw, parsed: parseSessionsProjectionStrict(raw, fp) };
 }
 function duplicateIds(ids) {
     const seen = new Set();
@@ -195,15 +227,15 @@ function duplicateIds(ids) {
     return [...duplicates];
 }
 /**
- * Sample every active Riff participant from one fresh sessions projection.
+ * Sample every active remote participant from one fresh sessions projection.
  * Fleet shutdown takes this snapshot before fencing any worker.
  */
-export function getActiveRiffShutdownSnapshotsBatch(sessionIds, options = {}) {
+export function getActiveRemoteShutdownSnapshotsBatch(sessionIds, options = {}) {
     if (sessionIds.length === 0)
         return [];
     const duplicates = duplicateIds(sessionIds);
     if (duplicates.length > 0) {
-        throw new RiffLineageBatchError('prewrite_ownership', duplicates, `duplicate Riff shutdown session ids: ${duplicates.join(', ')}`);
+        throw new RemoteLineageBatchError('prewrite_ownership', duplicates, `duplicate remote shutdown session ids: ${duplicates.join(', ')}`);
     }
     ensureDir();
     const fp = getFilePath();
@@ -215,37 +247,38 @@ export function getActiveRiffShutdownSnapshotsBatch(sessionIds, options = {}) {
                 return !session || session.status !== 'active';
             });
             if (invalid.length > 0) {
-                throw new RiffLineageBatchError('prewrite_ownership', invalid, `cannot snapshot non-active Riff sessions: ${invalid.join(', ')}`);
+                throw new RemoteLineageBatchError('prewrite_ownership', invalid, `cannot snapshot non-active remote sessions: ${invalid.join(', ')}`);
             }
             return sessionIds.map((sessionId) => {
                 const session = parsed[sessionId];
                 return {
                     sessionId,
                     taskId: session.riffParentTaskId ?? null,
-                    owner: riffDurableOwner(session),
+                    owner: remoteDurableOwner(session),
                 };
             });
         }, { maxWaitMs: options.maxWaitMs });
     }
     catch (error) {
-        if (error instanceof RiffLineageBatchError)
+        if (error instanceof RemoteLineageBatchError)
             throw error;
-        throw new RiffLineageBatchError('prewrite_io', [...sessionIds], `failed to snapshot active Riff sessions: ${String(error)}`);
+        throw new RemoteLineageBatchError('prewrite_io', [...sessionIds], `failed to snapshot active remote sessions: ${String(error)}`);
     }
 }
 /**
- * Commit every prepared Riff lineage as one compare-and-set transaction.
+ * Commit every prepared remote lineage as one compare-and-set transaction.
  * The published projection is read back under the same lock before workers
  * are allowed to exit.
  */
-export function persistActiveRiffLineagesExactBatch(updates, options = {}) {
+export function persistActiveRemoteLineagesExactBatch(updates, options = {}) {
     if (updates.length === 0)
         return [];
     const sessionIds = updates.map(update => update.sessionId);
     const duplicates = duplicateIds(sessionIds);
     if (duplicates.length > 0) {
-        throw new RiffLineageBatchError('prewrite_ownership', duplicates, `duplicate Riff lineage batch session ids: ${duplicates.join(', ')}`);
+        throw new RemoteLineageBatchError('prewrite_ownership', duplicates, `duplicate remote lineage batch session ids: ${duplicates.join(', ')}`);
     }
+    loadForWrite();
     ensureDir();
     const fp = getFilePath();
     let published = false;
@@ -260,12 +293,12 @@ export function persistActiveRiffLineagesExactBatch(updates, options = {}) {
                 if (!durable
                     || durable.status !== 'active'
                     || !update.expectedCurrentTaskIds.some(candidate => candidate === durableTaskId)
-                    || !riffOwnersEqual(riffDurableOwner(durable), update.owner)) {
+                    || !remoteOwnersEqual(remoteDurableOwner(durable), update.owner)) {
                     conflicts.push(update.sessionId);
                 }
             }
             if (conflicts.length > 0) {
-                throw new RiffLineageBatchError('prewrite_ownership', conflicts, `Riff lineage batch compare-and-set failed for: ${conflicts.join(', ')}`);
+                throw new RemoteLineageBatchError('prewrite_ownership', conflicts, `Remote lineage batch compare-and-set failed for: ${conflicts.join(', ')}`);
             }
             for (const update of updates) {
                 const durable = parsed[update.sessionId];
@@ -283,29 +316,29 @@ export function persistActiveRiffLineagesExactBatch(updates, options = {}) {
                 renameSync(tmpFp, fp);
                 tmpFp = undefined;
                 published = true;
-                testOnlyAfterRiffBatchRename?.();
+                testOnlyAfterRemoteBatchRename?.();
             }
             let verifiedProjection;
             try {
                 verifiedProjection = readSessionsProjectionStrict(fp).parsed;
             }
             catch (error) {
-                throw new RiffLineageBatchError(published ? 'postrename_ambiguity' : 'prewrite_io', [...sessionIds], `failed to read back Riff lineage batch: ${String(error)}`);
+                throw new RemoteLineageBatchError(published ? 'postrename_ambiguity' : 'prewrite_io', [...sessionIds], `failed to read back Remote lineage batch: ${String(error)}`);
             }
             const ambiguous = updates.filter((update) => {
                 const durable = verifiedProjection[update.sessionId];
                 return !durable
                     || durable.status !== 'active'
                     || (durable.riffParentTaskId ?? null) !== update.targetTaskId
-                    || !riffOwnersEqual(riffDurableOwner(durable), update.owner);
+                    || !remoteOwnersEqual(remoteDurableOwner(durable), update.owner);
             }).map(update => update.sessionId);
             if (ambiguous.length > 0) {
-                throw new RiffLineageBatchError(published ? 'postrename_ambiguity' : 'prewrite_ownership', ambiguous, `Riff lineage batch readback mismatch for: ${ambiguous.join(', ')}`);
+                throw new RemoteLineageBatchError(published ? 'postrename_ambiguity' : 'prewrite_ownership', ambiguous, `Remote lineage batch readback mismatch for: ${ambiguous.join(', ')}`);
             }
             const verified = updates.map((update) => ({
                 sessionId: update.sessionId,
                 taskId: update.targetTaskId,
-                owner: riffDurableOwner(verifiedProjection[update.sessionId]),
+                owner: remoteDurableOwner(verifiedProjection[update.sessionId]),
             }));
             if (loaded) {
                 for (const update of updates) {
@@ -318,9 +351,9 @@ export function persistActiveRiffLineagesExactBatch(updates, options = {}) {
         }, { maxWaitMs: options.maxWaitMs });
     }
     catch (error) {
-        if (error instanceof RiffLineageBatchError)
+        if (error instanceof RemoteLineageBatchError)
             throw error;
-        throw new RiffLineageBatchError(published ? 'postrename_ambiguity' : 'prewrite_io', [...sessionIds], `failed to persist Riff lineage batch: ${String(error)}`);
+        throw new RemoteLineageBatchError(published ? 'postrename_ambiguity' : 'prewrite_io', [...sessionIds], `failed to persist Remote lineage batch: ${String(error)}`);
     }
     finally {
         if (tmpFp) {
@@ -332,6 +365,8 @@ export function persistActiveRiffLineagesExactBatch(updates, options = {}) {
     }
 }
 function save() {
+    if (loadFailure)
+        throw new SessionStoreUnavailableError(loadFailure);
     ensureDir();
     const fp = getFilePath();
     withFileLockSync(fp, () => {
@@ -354,7 +389,7 @@ function save() {
     });
 }
 export function createSession(chatId, rootMessageId, title, chatType, scope) {
-    load();
+    loadForWrite();
     const session = {
         sessionId: randomUUID(),
         chatId,
@@ -457,8 +492,270 @@ export function cleanupSessionBridgeSendMarkers(sessionId) {
     }
     cleanupSessionBridgeSendMarkersNow(sessionId);
 }
+export function isValidMojoCloseJournal(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const journal = value;
+    if (journal.phase !== 'preparing'
+        && journal.phase !== 'prepared'
+        && journal.phase !== 'uncertain')
+        return false;
+    if (typeof journal.requestId !== 'string' || !journal.requestId.trim())
+        return false;
+    if (typeof journal.updatedAt !== 'string' || !journal.updatedAt.trim())
+        return false;
+    if (journal.recovery !== undefined
+        && journal.recovery !== 'retryable'
+        && journal.recovery !== 'uncertain'
+        && journal.recovery !== 'irreversible')
+        return false;
+    if (journal.admission !== undefined
+        && journal.admission !== 'restorable'
+        && journal.admission !== 'fenced')
+        return false;
+    if (journal.commitOnly !== undefined && typeof journal.commitOnly !== 'boolean')
+        return false;
+    if (journal.localResidual !== undefined
+        && journal.localResidual !== 'local_subtree_unprovable_on_platform'
+        && journal.localResidual !== 'local_subtree_boundary_unproven')
+        return false;
+    // A retryable verdict never proves an irreversible teardown, so it must not
+    // arrive wearing the marker that suppresses further cancellation.
+    if (journal.recovery === 'retryable' && journal.commitOnly === true)
+        return false;
+    // An irreversible verdict is only ever legal as a commit-only `prepared` row:
+    // the remote side is gone, so nothing may cancel or abort it again.
+    if (journal.recovery === 'irreversible'
+        && (journal.phase !== 'prepared' || journal.commitOnly !== true))
+        return false;
+    if (journal.commitOnly === true && journal.phase !== 'prepared')
+        return false;
+    return journal.taskId === undefined
+        || (typeof journal.taskId === 'string' && !!journal.taskId.trim());
+}
+function mutateMojoCloseJournal(sessionId, mutate) {
+    loadForWrite();
+    const session = sessions.get(sessionId);
+    if (!session || session.status !== 'active') {
+        throw new Error(`cannot mutate Mojo close journal for non-active session ${sessionId}`);
+    }
+    if (session.backendType !== 'mojo') {
+        throw new Error(`cannot mutate Mojo close journal for non-Mojo session ${sessionId}`);
+    }
+    const priorJournal = session.mojoCloseJournal
+        ? { ...session.mojoCloseJournal }
+        : undefined;
+    const priorTaskId = session.riffParentTaskId;
+    if (session.mojoCloseJournal && !isValidMojoCloseJournal(session.mojoCloseJournal)) {
+        throw new Error(`cannot mutate malformed Mojo close journal for ${sessionId}`);
+    }
+    mutate(session);
+    try {
+        save();
+    }
+    catch (error) {
+        session.mojoCloseJournal = priorJournal;
+        session.riffParentTaskId = priorTaskId;
+        throw error;
+    }
+    return session;
+}
+/** Persist the admission fence before any authoritative Mojo cancel begins. */
+export function beginMojoCloseJournal(sessionId, requestId, expectedTaskId) {
+    return mutateMojoCloseJournal(sessionId, (session) => {
+        if (session.riffParentTaskId !== expectedTaskId) {
+            throw new Error(`Mojo close lineage changed before prepare for ${sessionId}`);
+        }
+        const existing = session.mojoCloseJournal;
+        if (existing) {
+            if (existing.commitOnly) {
+                // The remote teardown already completed irreversibly; only the local
+                // commit may be retried. Starting a second cancel here is exactly the
+                // double teardown this journal exists to prevent.
+                throw new Error(`cannot re-cancel commit-only Mojo close journal for ${sessionId}`);
+            }
+            if (existing.phase !== 'preparing' && existing.phase !== 'uncertain') {
+                throw new Error(`cannot restart ${existing.phase} Mojo close journal for ${sessionId}`);
+            }
+            if (existing.taskId !== expectedTaskId) {
+                throw new Error(`Mojo close journal lineage changed before retry for ${sessionId}`);
+            }
+            if (existing.requestId !== requestId) {
+                if (existing.phase !== 'uncertain' && existing.recovery !== 'retryable') {
+                    throw new Error(`another Mojo close journal already owns ${sessionId}`);
+                }
+                // Two journal shapes accept a fresh attempt under a NEW requestId:
+                //   * `retryable` — the failed prepare durably recorded that retrying
+                //     the cancel is legitimate. Refusing every fresh requestId here is
+                //     what made `retryable` dead-code and the row a permanent brick
+                //     (P1-1/P1-2).
+                //   * `uncertain` — an explicit close IS the manual reconciliation the
+                //     fence demanded. Only a live worker's prepare/commit reaches this
+                //     takeover (ownerless uncertain rows DRAIN instead — see
+                //     prepareMojoExplicitClose), and re-running the cancel is the
+                //     fail-safe direction: the frozen identity pins the tenant, and an
+                //     already-terminal remote session is classified as gone, not as a
+                //     second teardown. Without the takeover the live-worker case had no
+                //     exit at all (P0-new).
+                // commitOnly / `prepared` journals were rejected above and stay
+                // non-restartable: those record an IRREVERSIBLE teardown. The row is
+                // rebuilt from scratch so the stale recovery/admission verdict cannot
+                // survive into the new attempt; lineage equality was asserted above, so
+                // the retry still addresses the same remote session.
+                session.mojoCloseJournal = {
+                    phase: 'preparing',
+                    requestId,
+                    ...(expectedTaskId ? { taskId: expectedTaskId } : {}),
+                    updatedAt: new Date().toISOString(),
+                };
+            }
+            return;
+        }
+        session.mojoCloseJournal = {
+            phase: 'preparing',
+            requestId,
+            ...(expectedTaskId ? { taskId: expectedTaskId } : {}),
+            updatedAt: new Date().toISOString(),
+        };
+    });
+}
+/** Publish irreversible remote-cancel proof before the local close commit. */
+export function markMojoClosePrepared(sessionId, requestId, taskId, localResidual) {
+    return mutateMojoCloseJournal(sessionId, (session) => {
+        const existing = session.mojoCloseJournal;
+        if (existing && existing.requestId !== requestId) {
+            throw new Error(`stale Mojo close prepare for ${sessionId}`);
+        }
+        if (existing?.phase === 'uncertain') {
+            throw new Error(`cannot promote uncertain Mojo close journal for ${sessionId}`);
+        }
+        if (existing?.taskId && taskId && existing.taskId !== taskId) {
+            throw new Error(`Mojo close proof changed journal lineage for ${sessionId}`);
+        }
+        const provenTaskId = taskId ?? existing?.taskId;
+        if (provenTaskId && session.riffParentTaskId
+            && session.riffParentTaskId !== provenTaskId) {
+            throw new Error(`Mojo close result lineage changed for ${sessionId}`);
+        }
+        if (provenTaskId)
+            session.riffParentTaskId = provenTaskId;
+        // The residual is part of the PROOF being published: a replay of this
+        // prepared journal (runtime commit retry, or a daemon restart) must publish
+        // the same residual close it describes. A repeat prepare without one keeps
+        // the recorded residual — the evidence grade of the original close does not
+        // improve by being replayed.
+        const provenResidual = localResidual ?? existing?.localResidual;
+        session.mojoCloseJournal = {
+            phase: 'prepared',
+            requestId,
+            ...(provenTaskId ? { taskId: provenTaskId } : {}),
+            ...(provenResidual ? { localResidual: provenResidual } : {}),
+            updatedAt: new Date().toISOString(),
+        };
+    });
+}
+/**
+ * Finish a failed prepare after worker admission restore. If restore was not
+ * proven, keep a durable uncertain fence; either way retain a newly discovered
+ * pre-init lineage for later reconciliation.
+ */
+export function finishMojoCloseAbort(sessionId, requestId, options) {
+    return mutateMojoCloseJournal(sessionId, (session) => {
+        const existing = session.mojoCloseJournal;
+        if (!existing || existing.requestId !== requestId) {
+            throw new Error(`stale Mojo close abort for ${sessionId}`);
+        }
+        if (existing.commitOnly || existing.recovery === 'irreversible') {
+            // Checked BEFORE the generic prepared guard so the refusal names the reason:
+            // rolling this back would re-open write admission on a lineage whose remote
+            // side is already gone, leaving a session that looks writable and can never
+            // continue.
+            throw new Error(`cannot abort irreversible Mojo close journal for ${sessionId}`);
+        }
+        if (existing.phase === 'prepared') {
+            throw new Error(`cannot abort prepared Mojo close proof for ${sessionId}`);
+        }
+        if (existing.taskId && options.taskId && existing.taskId !== options.taskId) {
+            throw new Error(`Mojo close abort changed journal lineage for ${sessionId}`);
+        }
+        const retainedTaskId = options.taskId ?? existing.taskId;
+        if (retainedTaskId && session.riffParentTaskId
+            && session.riffParentTaskId !== retainedTaskId) {
+            throw new Error(`Mojo close abort lineage changed for ${sessionId}`);
+        }
+        if (retainedTaskId)
+            session.riffParentTaskId = retainedTaskId;
+        if (options.admissionRestored) {
+            session.mojoCloseJournal = undefined;
+            return;
+        }
+        session.mojoCloseJournal = {
+            phase: 'uncertain',
+            requestId,
+            ...(retainedTaskId ? { taskId: retainedTaskId } : {}),
+            recovery: 'uncertain',
+            admission: 'fenced',
+            updatedAt: new Date().toISOString(),
+        };
+    });
+}
+/**
+ * Persist a FAILED prepare that must NOT be rolled back, with its exact verdict.
+ *
+ * Such a prepare previously left the journal at `preparing` carrying the
+ * PRE-prepare task id: a restart could not tell "reconcile me" apart from "only
+ * the local commit is left", the lineage the worker actually reported was
+ * dropped, and nothing recorded that write admission was never re-opened.
+ *
+ * `irreversible` is stored as a commit-only `prepared` row on purpose - every
+ * existing recovery path (restore, retry, abort) then treats it as
+ * un-cancellable and finishes only the local close.
+ */
+export function markMojoCloseUnresolved(sessionId, requestId, options) {
+    return mutateMojoCloseJournal(sessionId, (session) => {
+        const existing = session.mojoCloseJournal;
+        if (existing && existing.requestId !== requestId) {
+            throw new Error(`stale Mojo close verdict for ${sessionId}`);
+        }
+        if (existing?.commitOnly && options.recovery !== 'irreversible') {
+            // Never downgrade a recorded irreversible teardown into something a later
+            // caller may cancel or abort again.
+            throw new Error(`cannot downgrade commit-only Mojo close journal for ${sessionId}`);
+        }
+        if (existing?.taskId && options.taskId && existing.taskId !== options.taskId) {
+            throw new Error(`Mojo close verdict changed journal lineage for ${sessionId}`);
+        }
+        const exactTaskId = options.taskId ?? existing?.taskId;
+        if (exactTaskId && session.riffParentTaskId
+            && session.riffParentTaskId !== exactTaskId) {
+            throw new Error(`Mojo close verdict lineage changed for ${sessionId}`);
+        }
+        // The worker may have learned the lineage only DURING the prepare (the
+        // pre-init window), so persist that exact id: a retry or a manual
+        // reconciliation must address the real remote session, not the stale guess.
+        if (exactTaskId)
+            session.riffParentTaskId = exactTaskId;
+        const irreversible = options.recovery === 'irreversible';
+        // A still-retryable close keeps its `preparing` intent: a retry SHOULD re-run
+        // the cancel. Promoting it to `uncertain` would demand manual reconciliation
+        // for a failure the retry can clear on its own -- while `admission: 'fenced'`
+        // independently keeps writes out.
+        const phase = irreversible
+            ? 'prepared'
+            : options.recovery === 'retryable' ? 'preparing' : 'uncertain';
+        session.mojoCloseJournal = {
+            phase,
+            requestId,
+            ...(exactTaskId ? { taskId: exactTaskId } : {}),
+            recovery: options.recovery,
+            admission: options.admission,
+            ...(irreversible ? { commitOnly: true } : {}),
+            updatedAt: new Date().toISOString(),
+        };
+    });
+}
 export function closeSession(sessionId, opts = {}) {
-    load();
+    loadForWrite();
     const session = sessions.get(sessionId);
     if (session) {
         const priorStatus = session.status;
@@ -466,10 +763,42 @@ export function closeSession(sessionId, opts = {}) {
         const priorRiffParentTaskId = session.riffParentTaskId;
         const priorDashboardAttachments = session.dashboardAttachments;
         const priorQueuedAttachments = session.queuedAttachments;
+        const priorPreviewTarget = session.previewTarget;
+        const priorQuarantinedLineage = session.mojoQuarantinedLineage;
+        const priorQuarantineNoticePending = session.mojoQuarantineNoticePending;
+        const priorLocalResidual = session.mojoLocalResidual;
+        const priorMojoCloseJournal = session.mojoCloseJournal
+            ? { ...session.mojoCloseJournal }
+            : undefined;
         session.status = 'closed';
         session.closedAt = new Date().toISOString();
         session.dashboardAttachments = undefined;
         session.queuedAttachments = undefined;
+        // `previewTarget` is a live loopback (host, port) the session's agent
+        // registered with `botmux preview <port>` for its CURRENT worker
+        // generation — routing state, not a durable property of the conversation.
+        // A closed session owns no port any more, and the OS is free to hand that
+        // number to an unrelated local server; the preview proxy dials a target by
+        // host/port alone, so a retained value would let a later reader (resume,
+        // an offline row copy, a dashboard snapshot) proxy the user into someone
+        // else's service. Drop it in the same atomic save as status='closed'.
+        // Cleanup only: registration and proxying are untouched, and a resumed
+        // session simply re-runs `botmux preview <port>`.
+        session.previewTarget = undefined;
+        session.mojoCloseJournal = undefined;
+        // Survives close on purpose — the containment handle is still in the durable
+        // store, so the row must keep reporting the residual until the handle clears.
+        if (opts.parkLocalResidual)
+            session.mojoLocalResidual = opts.parkLocalResidual;
+        if (opts.parkMojoLineage) {
+            // Keep both ids when a different one was already parked: each is the only
+            // handle left for manual cleanup of its remote session.
+            const already = session.mojoQuarantinedLineage;
+            session.mojoQuarantinedLineage = already && already !== opts.parkMojoLineage
+                ? `${already},${opts.parkMojoLineage}`
+                : opts.parkMojoLineage;
+            session.mojoQuarantineNoticePending = true;
+        }
         // Riff cancellation has already completed before this durable transition.
         // Clear its retry handle in the same atomic save as status='closed'.
         if (opts.clearRiffParentTaskId)
@@ -483,6 +812,14 @@ export function closeSession(sessionId, opts = {}) {
             session.riffParentTaskId = priorRiffParentTaskId;
             session.dashboardAttachments = priorDashboardAttachments;
             session.queuedAttachments = priorQueuedAttachments;
+            session.previewTarget = priorPreviewTarget;
+            // Without these two the row keeps a parked lineage after a FAILED close, so
+            // the next turn treats a still-live remote session as quarantined and starts
+            // a new one — i.e. the "close failed, retry unchanged" guarantee is broken.
+            session.mojoQuarantinedLineage = priorQuarantinedLineage;
+            session.mojoQuarantineNoticePending = priorQuarantineNoticePending;
+            session.mojoLocalResidual = priorLocalResidual;
+            session.mojoCloseJournal = priorMojoCloseJournal;
             throw err;
         }
         if (session.larkAppId && priorDashboardAttachments?.length) {
@@ -512,9 +849,13 @@ export function closeSession(sessionId, opts = {}) {
  * since 2026-07, but older closed rows can still contain prepared input.  A
  * generic resume is an explicit new lifecycle and must never revive that
  * abandoned FIFO.
+ *
+ * `previewTarget` is cleared here for the same reason: closeSession() now drops
+ * it, but rows closed by an older build still carry one on disk, and resume
+ * starts a new worker generation that has not registered any port.
  */
 export function reactivateClosedSession(sessionId) {
-    load();
+    loadForWrite();
     const session = sessions.get(sessionId);
     if (!session)
         return { ok: false, error: 'not_found' };
@@ -539,6 +880,8 @@ export function reactivateClosedSession(sessionId) {
         queuedActivationTail: session.queuedActivationTail,
         queuedActivationTailNextOrder: session.queuedActivationTailNextOrder,
         pendingRepoSetup: session.pendingRepoSetup,
+        previewTarget: session.previewTarget,
+        mojoCloseJournal: session.mojoCloseJournal,
     };
     session.status = 'active';
     session.closedAt = undefined;
@@ -558,6 +901,8 @@ export function reactivateClosedSession(sessionId) {
     session.queuedActivationTail = undefined;
     session.queuedActivationTailNextOrder = undefined;
     session.pendingRepoSetup = undefined;
+    session.previewTarget = undefined;
+    session.mojoCloseJournal = undefined;
     try {
         save();
     }
@@ -568,7 +913,7 @@ export function reactivateClosedSession(sessionId) {
     return { ok: true, session };
 }
 export function updateSessionPid(sessionId, pid) {
-    load();
+    loadForWrite();
     const session = sessions.get(sessionId);
     if (session) {
         session.pid = pid ?? undefined;
@@ -576,33 +921,33 @@ export function updateSessionPid(sessionId, pid) {
     }
 }
 export function updateSession(session) {
-    load();
+    loadForWrite();
     sessions.set(session.sessionId, session);
     save();
 }
 /**
- * Persist one exact Riff follow-up lineage for an active durable owner.
+ * Persist one exact remote follow-up lineage for an active durable owner.
  * The process cache changes only after the atomic file replacement succeeds.
  */
-export function persistActiveRiffLineageExact(sessionId, taskId, options = {}) {
-    load();
+export function persistActiveRemoteLineageExact(sessionId, taskId, options = {}) {
+    loadForWrite();
     ensureDir();
     const fp = getFilePath();
     return withFileLockSync(fp, () => {
         const { raw, parsed } = readExistingSessionsFromDisk(fp);
         const durable = parsed[sessionId];
         if (!durable || durable.status !== 'active') {
-            throw new RiffLineageOwnershipError(`cannot persist Riff lineage for non-active session ${sessionId}`);
+            throw new RemoteLineageOwnershipError(`cannot persist remote lineage for non-active session ${sessionId}`);
         }
         const durableTaskId = durable.riffParentTaskId ?? null;
         const expected = options.expectedCurrentTaskIds;
         if (expected && !expected.some(candidate => candidate === durableTaskId)) {
-            throw new RiffLineageOwnershipError(`Riff lineage compare-and-set failed for ${sessionId} `
+            throw new RemoteLineageOwnershipError(`Remote lineage compare-and-set failed for ${sessionId} `
                 + `(current=${durableTaskId ?? 'none'}, expected=${expected.map(id => id ?? 'none').join('|')})`);
         }
-        if (options.expectedOwner && !riffOwnersEqual(riffDurableOwner(durable), options.expectedOwner)) {
-            throw new RiffLineageOwnershipError(`Riff owner compare-and-set failed for ${sessionId} `
-                + `(current=${JSON.stringify(riffDurableOwner(durable))}, `
+        if (options.expectedOwner && !remoteOwnersEqual(remoteDurableOwner(durable), options.expectedOwner)) {
+            throw new RemoteLineageOwnershipError(`Remote owner compare-and-set failed for ${sessionId} `
+                + `(current=${JSON.stringify(remoteDurableOwner(durable))}, `
                 + `expected=${JSON.stringify(options.expectedOwner)})`);
         }
         const next = {
@@ -630,6 +975,19 @@ export function listSessions() {
     load();
     return [...sessions.values()];
 }
+/**
+ * Return the current projection only when its backing file was loaded safely.
+ * Use this for decisions that delete, retire, or reconfigure resources: the
+ * legacy empty-on-error behaviour of listSessions() is unsafe at those gates.
+ * A failed load remains unhealthy until init() explicitly selects/reloads a
+ * store, avoiding a silent mid-transaction recovery against a different view.
+ */
+export function listSessionsStrict() {
+    load();
+    if (loadFailure)
+        throw new SessionStoreUnavailableError(loadFailure);
+    return [...sessions.values()];
+}
 /**
  * Cross-file lookup: find every active session attached to a thread, across
  * all bots. Used when a not-yet-initialized bot is mentioned in a thread that