mixdog 0.9.87 → 0.9.89

package/src/runtime/agent/orchestrator/session/store/listing.mjs

@@ -2,13 +2,15 @@
 // from store.mjs, which keeps the persistence half (save/load/close/delete).
 // The two halves share the in-flight save map so an unpersisted session still
 // shows up in listings; the cycle is import-only (calls happen at runtime).
-import { existsSync, readFileSync, readdirSync, statSync, unlinkSync } from 'fs';
+import { readFileSync, readdirSync, statSync, unlinkSync } from 'fs';
 import { join } from 'path';
-import { loadConfig } from '../../config.mjs';
+import { Worker } from 'worker_threads';
+import { getPluginData, loadConfig } from '../../config.mjs';
 import { isAgentOwner } from '../../agent-owner.mjs';
-import { scanTopLevelLifecycle } from '../lifecycle-scan.mjs';
+import { readTopLevelLifecycleRecord, isLifecycleUnreadable } from '../lifecycle-scan.mjs';
 import { resolveAgentTerminalReapMs } from '../../../../../session-runtime/config-helpers.mjs';
 import { getStoreDir, sessionPath } from './paths-heartbeat.mjs';
+import { probePath, PROBE_PRESENT, PROBE_ABSENT } from './fs-probe.mjs';
 import { isCancelledWrite as _isCancelledWrite } from './write-guards.mjs';
 import {
     SESSION_SUMMARY_INDEX_VERSION,
@@ -30,12 +32,14 @@ import {
     _summaryRowsCache,
 } from './summary-cache.mjs';
 import { _saveAsyncQueued, _saveWorkerPending } from './save-worker.mjs';
-import { _ensureLifecycleFields, _storedSessionFromFile } from './serialize.mjs';
+import { STORED_SESSION_UNREADABLE, _ensureLifecycleFields, _storedSessionFromFile } from './serialize.mjs';
 import { _savePending, deleteSession, markSessionClosed } from '../store.mjs';
 
 // Disk mtime of the summary index when the in-memory cache was last refreshed
 // from it — the cross-process staleness detector.
 let _summaryIndexMtimeSeen = 0;
+let _summaryRebuildWorker = null;
+let _summaryRebuildDataDir = '';
 
 const DEFAULT_SESSION_TTL_MS = 5 * 60 * 1000; // 5 minutes idle — aligned with Anthropic 5m messages tier and OpenAI in-memory cache window
 const AGENT_TERMINAL_STATUSES = new Set(['idle', 'done', 'error']);
@@ -63,8 +67,10 @@ const BLANK_SCRATCH_MAX_AGE_MS = 60 * 60 * 1000; // 1h
 
 export function listStoredSessions(options = {}) {
     const dir = getStoreDir();
-    if (!existsSync(dir))
-        return [];
+    // Only ENOENT/ENOTDIR is absence. An unreadable directory (EACCES/EIO) is
+    // NOT "no sessions": listing yields nothing, but nothing may be treated as
+    // deleted/absent on that basis either.
+    if (probePath(dir).state !== PROBE_PRESENT) return [];
     const files = readdirSync(dir).filter(f => f.endsWith('.json'));
     const sessionsById = new Map();
     const invalidStorageIds = options._invalidStorageIds instanceof Set
@@ -72,10 +78,12 @@ export function listStoredSessions(options = {}) {
         : new Set();
     for (const f of files) {
         const session = _storedSessionFromFile(dir, f);
-        if (session) {
+        if (session && session !== STORED_SESSION_UNREADABLE) {
             sessionsById.set(session.id, session);
             continue;
         }
+        // Present-but-unreadable owns its identity too: it may never be
+        // replaced by a live/pending overlay, so it is marked invalid.
         const storageId = f.slice(0, -5);
         if (/^[A-Za-z0-9_-]+$/.test(storageId)) invalidStorageIds.add(storageId);
     }
@@ -128,20 +136,40 @@ function _overlayUnpersistedSummaryRows(rows, invalidStorageIds = new Set()) {
     return [...byId.values()].sort((a, b) => (b.updatedAt || 0) - (a.updatedAt || 0));
 }
 
-function rebuildSessionSummaryIndex() {
-    _ensureSummaryCacheDataDir();
-    const { rows } = _scanStoredSessionSummaryRows();
-    const indexedRows = _writeSummaryIndex(rows);
-    // This process just authored the new cache base. Remember its mtime so the
-    // next local save cannot mistake the rebuild for a cross-process update
-    // and replace a newer in-memory row with the just-obsoleted sidecar.
-    try { _summaryIndexMtimeSeen = statSync(summaryIndexPath()).mtimeMs || 0; } catch { /* stat only */ }
-    return _setSummaryRowsCache(indexedRows);
+function scheduleSessionSummaryIndexRebuild() {
+    const dataDir = getPluginData();
+    if (_summaryRebuildWorker && _summaryRebuildDataDir === dataDir) return;
+    if (_summaryRebuildWorker) {
+        try { void _summaryRebuildWorker.terminate(); } catch { /* stale worker exits independently */ }
+    }
+    let worker;
+    try {
+        worker = new Worker(new URL('./summary-rebuild-worker.mjs', import.meta.url), {
+            execArgv: [],
+            workerData: { dataDir },
+        });
+    } catch {
+        return;
+    }
+    _summaryRebuildWorker = worker;
+    _summaryRebuildDataDir = dataDir;
+    const clear = () => {
+        if (_summaryRebuildWorker !== worker) return;
+        _summaryRebuildWorker = null;
+        _summaryRebuildDataDir = '';
+    };
+    worker.on('message', (message) => {
+        if (message?.ok !== true || message.dataDir !== getPluginData() || !Array.isArray(message.rows)) return;
+        try { _summaryIndexMtimeSeen = statSync(summaryIndexPath()).mtimeMs || 0; } catch { /* stat only */ }
+        _setSummaryRowsCache(message.rows);
+    });
+    worker.on('error', clear);
+    worker.on('exit', clear);
+    worker.unref();
 }
 
 export function listStoredSessionSummaries(options = {}) {
     _ensureSummaryCacheDataDir();
-    const rebuildIfMissing = options.rebuildIfMissing !== false;
     // This is intentionally the only path that rescans every session JSON:
     // callers use it as an on-demand authoritative refresh (including resume
     // authorization), so it must not trust either the cache or sidecar.
@@ -195,11 +223,26 @@ export function listStoredSessionSummaries(options = {}) {
     let indexedRows = [];
     let p;
     let hasIndex = false;
+    let indexUnreadable = false;
     try {
         p = summaryIndexPath();
-        hasIndex = existsSync(p);
+        const probe = probePath(p);
+        hasIndex = probe.state === PROBE_PRESENT;
+        if (probe.state !== PROBE_PRESENT && probe.state !== PROBE_ABSENT) indexUnreadable = true;
         if (hasIndex) {
-            const raw = JSON.parse(readFileSync(p, 'utf-8'));
+            let text;
+            try {
+                text = readFileSync(p, 'utf-8');
+            } catch (err) {
+                // Stat said PRESENT and the read failed: the sidecar is there
+                // and we cannot have it. FAIL CLOSED — keep serving the cache,
+                // never emit empty rows and never schedule a rebuild that
+                // would overwrite a sidecar we could not read.
+                const code = err?.code || 'EUNKNOWN';
+                if (code !== 'ENOENT' && code !== 'ENOTDIR') indexUnreadable = true;
+                throw err;
+            }
+            const raw = JSON.parse(text);
             hasIndex = Number(raw?.version) === SESSION_SUMMARY_INDEX_VERSION;
             if (hasIndex) indexedRows = _normalizeSummaryIndex(raw).rows;
             if (hasIndex) {
@@ -208,18 +251,27 @@ export function listStoredSessionSummaries(options = {}) {
         }
     } catch { /* unreadable/malformed sidecar falls through to rebuild */ }
 
+    if (indexUnreadable) {
+        // Present-but-unreadable sidecar: retain authority. A COLD cache has
+        // no rows yet (null) — return an empty result rather than crashing on
+        // `.slice()`, and never rebuild/replace the sidecar we could not read.
+        const cached = _cachedSummaryRows();
+        return Array.isArray(cached) ? cached.slice() : [];
+    }
     if (!p || !hasIndex) {
-        try { return rebuildIfMissing ? rebuildSessionSummaryIndex() : _setSummaryRowsCache([]); }
-        catch { return _setSummaryRowsCache(indexedRows); }
+        scheduleSessionSummaryIndexRebuild();
+        return _setSummaryRowsCache(indexedRows);
     }
     try {
         if (indexedRows.length > 0) return _setSummaryRowsCache(indexedRows);
         const dir = getStoreDir();
-        const hasSessionFiles = existsSync(dir) && readdirSync(dir).some((f) => f.endsWith('.json'));
-        return hasSessionFiles && rebuildIfMissing ? rebuildSessionSummaryIndex() : _setSummaryRowsCache(indexedRows);
+        const hasSessionFiles = probePath(dir).state === PROBE_PRESENT
+            && readdirSync(dir).some((f) => f.endsWith('.json'));
+        if (hasSessionFiles) scheduleSessionSummaryIndexRebuild();
+        return _setSummaryRowsCache(indexedRows);
     } catch {
-        try { return rebuildIfMissing ? rebuildSessionSummaryIndex() : _setSummaryRowsCache(indexedRows); }
-        catch { return _setSummaryRowsCache(indexedRows); }
+        scheduleSessionSummaryIndexRebuild();
+        return _setSummaryRowsCache(indexedRows);
     }
 }
 
@@ -230,12 +282,12 @@ export function listStoredSessionSummaries(options = {}) {
  */
 export function getStoredSessionsRaw() {
     const dir = getStoreDir();
-    if (!existsSync(dir)) return [];
+    if (probePath(dir).state !== PROBE_PRESENT) return [];
     const files = readdirSync(dir).filter(f => f.endsWith('.json'));
     const sessions = [];
     for (const f of files) {
         const session = _storedSessionFromFile(dir, f, false);
-        if (session) sessions.push(session);
+        if (session && session !== STORED_SESSION_UNREADABLE) sessions.push(session);
     }
     return sessions;
 }
@@ -265,7 +317,9 @@ function* sweepStaleSessionSteps(ttlMs, options = {}) {
     const openMaxAgeMs = Number.isFinite(_optAge) && _optAge > 0 ? _optAge : RESUMABLE_OPEN_MAX_AGE_MS;
     const openMaxCount = Number.isFinite(_optCount) && _optCount >= 0 ? _optCount : RESUMABLE_OPEN_MAX_COUNT;
     const dir = getStoreDir();
-    if (!existsSync(dir))
+    // An unreadable store dir is not an empty one: sweeping (deleting,
+    // closing, pruning) on a probe we could not make is never allowed.
+    if (probePath(dir).state !== PROBE_PRESENT)
         return { cleaned: 0, remaining: 0, details: [], tombstonesCleaned: 0, tombstoneDetails: [], tombstoneErrors: [] };
     // Reconcile the index-derived candidate set with a direct directory scan:
     // the summary index is a best-effort sidecar that can lag far behind disk
@@ -308,17 +362,28 @@ function* sweepStaleSessionSteps(ttlMs, options = {}) {
         try {
             if (!row?.id) continue;
             const jsonPath = sessionPath(row.id);
-            if (!existsSync(jsonPath)) {
+            const jsonProbe = probePath(jsonPath);
+            // ONLY a proven-absent record may retire its summary row. An
+            // EACCES/EIO probe means the file is very likely still there:
+            // queueing a removal would delete the row of a live session.
+            if (jsonProbe.state === PROBE_ABSENT) {
                 _queueSessionSummaryRemoval(row.id);
                 continue;
             }
-            let jsonMtime = 0;
+            if (jsonProbe.state !== PROBE_PRESENT) {
+                remaining++;
+                continue;
+            }
+            let jsonMtime = jsonProbe.mtimeMs || 0;
             let heartbeatMtime = 0;
-            try { jsonMtime = statSync(jsonPath).mtimeMs || 0; } catch {}
-            try {
-                const hbPath = join(dir, `${row.id}.hb`);
-                if (existsSync(hbPath)) heartbeatMtime = statSync(hbPath).mtimeMs || 0;
-            } catch { /* .hb unavailable — fall back to JSON fields */ }
+            const hbProbe = probePath(join(dir, `${row.id}.hb`));
+            if (hbProbe.state === PROBE_PRESENT) heartbeatMtime = hbProbe.mtimeMs || 0;
+            else if (hbProbe.state !== PROBE_ABSENT) {
+                // Liveness sidecar unreadable: this record's freshness cannot
+                // be judged, so it is not a sweep candidate at all.
+                remaining++;
+                continue;
+            }
             // Truth source: the summary index is a deferred/best-effort sidecar,
             // so a row can still claim status='idle'/open while the session JSON
             // was already tombstoned. Read the real session JSON BEFORE the
@@ -329,25 +394,35 @@ function* sweepStaleSessionSteps(ttlMs, options = {}) {
             let raw = null;
             try { raw = readFileSync(jsonPath, 'utf-8'); }
             catch { /* racing unlink / transient read failure */ }
-            let actual = null;
-            let diskClosed;
+            // NOTHING ambiguous is ever swept. This loop deletes files, plants
+            // tombstones and rewrites summary rows, so a record it cannot read
+            // authoritatively (read fault, malformed JSON, duplicate top-level
+            // id/closed/generation) is left EXACTLY as it is — not deleted, not
+            // closed, not repaired, and never resolved by a last-wins
+            // JSON.parse fallback or by the best-effort summary row (which may
+            // describe a completely different generation of this id).
             if (raw == null) {
-                diskClosed = (row.closed === true || row.status === 'closed');
-            } else {
-                // Cheap top-level scan avoids allocating the whole messages array
-                // just to read the closed flag for the (common) fresh open
-                // session the gate will skip; full-parse only when the scan can't
-                // resolve the top-level flag.
-                const scan = scanTopLevelLifecycle(raw);
-                if (scan && typeof scan.closed === 'boolean') {
-                    diskClosed = scan.closed;
-                } else {
-                    try { actual = JSON.parse(raw); } catch { actual = null; }
-                    diskClosed = actual
-                        ? (actual.closed === true || actual.status === 'closed')
-                        : (row.closed === true || row.status === 'closed');
-                }
+                remaining++;
+                continue;
+            }
+            const record = readTopLevelLifecycleRecord(raw);
+            if (isLifecycleUnreadable(record)) {
+                remaining++;
+                continue;
             }
+            // OWNERSHIP: the record must name the id this row/file claims.
+            // A foreign record (including a foreign TOMBSTONE that would look
+            // perfectly mature) is preserved untouched — never deleted, never
+            // closed, never upserted into the summary index under the wrong id.
+            if (record.id !== row.id) {
+                remaining++;
+                continue;
+            }
+            // One strict parse for the whole record: every decision below reads
+            // the SAME authoritative document (owner/status/timestamps/
+            // messages), so there is no second, divergent parse of this file.
+            const actual = record.doc;
+            const diskClosed = record.closed === true || actual.status === 'closed';
             if (diskClosed) {
                 // A shared store can be tombstoned by another process while
                 // this process still owns an in-flight controller for the same
@@ -363,7 +438,6 @@ function* sweepStaleSessionSteps(ttlMs, options = {}) {
                 // perpetually "fresh" and never mature. Maturity is governed ONLY
                 // by the ORIGINAL close time (disk updatedAt, not row.updatedAt
                 // which a stale row may carry from before the close).
-                if (!actual && raw != null) { try { actual = JSON.parse(raw); } catch { actual = null; } }
                 const closedAt = Number(actual?.updatedAt ?? row.updatedAt);
                 const age = now - closedAt;
                 if (sweepTombstones && Number.isFinite(closedAt) && age >= tombstoneMaxAgeMs) {
@@ -382,7 +456,7 @@ function* sweepStaleSessionSteps(ttlMs, options = {}) {
                 // Repair a stale summary row that still claimed the session was
                 // open: reflect the real closed state so the next sweep sees the
                 // correct closed=true/updatedAt and never re-closes it.
-                if (actual && !(row.closed === true || row.status === 'closed')) {
+                if (!(row.closed === true || row.status === 'closed')) {
                     try { _queueSessionSummaryUpsert(actual); } catch { /* best-effort */ }
                 }
                 remaining++;
@@ -392,7 +466,6 @@ function* sweepStaleSessionSteps(ttlMs, options = {}) {
             // use their provider's Advanced terminal duration rather than the
             // general sweep cadence. A short provider override must therefore
             // not be hidden behind the default 5-minute gate.
-            if (!actual && raw != null) { try { actual = JSON.parse(raw); } catch { actual = null; } }
             const gateOwner = (actual && typeof actual.owner === 'string' && actual.owner.length > 0)
                 ? actual.owner : row.owner;
             const gateStatus = (actual && typeof actual.status === 'string') ? actual.status : row.status;
@@ -433,8 +506,7 @@ function* sweepStaleSessionSteps(ttlMs, options = {}) {
             // Prefer the AUTHORITATIVE on-disk JSON over the best-effort (and
             // possibly stale) summary row for every open/idle liveness and
             // ownership decision below — a stale row must not close or prune the
-            // wrong session. Full-parse here if the cheap scan skipped it.
-            if (!actual && raw != null) { try { actual = JSON.parse(raw); } catch { actual = null; } }
+            // wrong session.
             const effOwner = (actual && typeof actual.owner === 'string' && actual.owner.length > 0)
                 ? actual.owner : row.owner;
             const ownerRef = { owner: effOwner };
@@ -518,10 +590,13 @@ function* sweepStaleSessionSteps(ttlMs, options = {}) {
                     continue;
                 }
                 let preCloseHeartbeatMtime = 0;
-                try {
-                    const hbPath = join(dir, `${row.id}.hb`);
-                    if (existsSync(hbPath)) preCloseHeartbeatMtime = statSync(hbPath).mtimeMs || 0;
-                } catch { /* sidecar unavailable — retain scan-time gates */ }
+                const preCloseProbe = probePath(join(dir, `${row.id}.hb`));
+                if (preCloseProbe.state === PROBE_PRESENT) preCloseHeartbeatMtime = preCloseProbe.mtimeMs || 0;
+                else if (preCloseProbe.state !== PROBE_ABSENT) {
+                    // Unknown liveness at the destructive edge: do not close.
+                    remaining++;
+                    continue;
+                }
                 if (preCloseHeartbeatMtime > 0 && now - preCloseHeartbeatMtime <= sessionMaxAge) {
                     remaining++;
                     continue;
@@ -597,9 +672,11 @@ function* sweepStaleSessionSteps(ttlMs, options = {}) {
     try {
         for (const h of readdirSync(dir).filter(f => f.endsWith('.hb') || f.endsWith('.own'))) {
             yield undefined;
-            if (existsSync(join(dir, h.replace(/\.(hb|own)$/, '.json')))) continue;
-            let hbMtime = 0;
-            try { hbMtime = statSync(join(dir, h)).mtimeMs; } catch { continue; }
+            // Only a PROVEN-absent session file makes its sidecar an orphan.
+            if (!(probePath(join(dir, h.replace(/\.(hb|own)$/, '.json'))).state === PROBE_ABSENT)) continue;
+            const sidecarProbe = probePath(join(dir, h));
+            if (sidecarProbe.state !== PROBE_PRESENT) continue;
+            const hbMtime = sidecarProbe.mtimeMs;
             if (now - hbMtime > maxAge) {
                 try { unlinkSync(join(dir, h)); cleaned++; } catch { /* ignore */ }
             }

package/src/runtime/agent/orchestrator/session/store/live-state.mjs

@@ -12,6 +12,138 @@ export const _liveSessions = new Map();
 // it must not be evicted (data loss) nor shadowed by the stale disk copy.
 export const _droppedSaveIds = new Set();
 
+// ── Save identity (epoch) ───────────────────────────────────────────────────
+// Every save ATTEMPT takes a monotonically increasing epoch when it is issued.
+// A failure/drop records the epoch of the state that never landed, so only a
+// save at least that new may clear the id-wide error/drop markers. Without it
+// an OLDER worker write landing after a NEWER sync/async failure cleared the
+// markers, un-pinning (and then evicting) the only copy of the newest turn.
+let _saveEpochSeq = 0;
+const _failureEpochs = new Map(); // id -> epoch of the newest failed/dropped save
+// The EXACT snapshot whose own save failed in this process, per id. This is
+// the only evidence that may let an in-memory object stand in for an
+// unreadable canonical file (see loadSession's read-after-failure contract):
+// "some live/pending object exists for this id" proves nothing about disk,
+// while "THIS object's write to disk failed" proves the bytes never landed
+// and that this copy is strictly newer than whatever the file holds. Lives
+// exactly as long as _lastSaveError (cleared by the next landed save).
+// Stored as an IMMUTABLE point-in-time clone (see _failedSaveClone), never the
+// live reference.
+const _failedSaveSnapshots = new Map(); // id -> frozen-in-time session copy
+
+export function _nextSaveEpoch() {
+    return ++_saveEpochSeq;
+}
+
+// ── Save outcomes ───────────────────────────────────────────────────────────
+// A refused write is NOT one thing: an ownership/cancellation drop means this
+// process holds state disk does not (pin it, flag the split-brain), while a
+// stale-epoch refusal means a strictly NEWER write already landed — nothing
+// was lost, so no marker may move and the snapshot stays immediately
+// evictable. Every save path reports which one happened.
+export const SAVE_OUTCOME_SAVED = 'saved';
+export const SAVE_OUTCOME_DROPPED = 'dropped';
+export const SAVE_OUTCOME_STALE = 'stale';
+
+// ── Session incarnations ────────────────────────────────────────────────────
+// Work (worker write, queued payload, parked snapshot, in-process save) is
+// stamped with the OBJECT identifying the id's current incarnation. A
+// successful hard delete retires that object; a re-created id mints a brand
+// new one. Identity comparison — not a counter — is what makes this exact:
+// no wrap, no reset, no reuse, so pre-delete work can never look current
+// again, however many deletes happen and however often an id is reused.
+//
+// Entries are pinned while work references them; the (generous) cap only ever
+// evicts UNREFERENCED entries, and an evicted entry can at worst make some
+// later settlement inert — never make stale work current.
+let _incarnationSeq = 0;
+const _sessionIncarnations = new Map(); // id -> { id, token, refs }
+const SESSION_INCARNATION_MAX = 4096;
+
+function _evictSessionIncarnations() {
+    if (_sessionIncarnations.size <= SESSION_INCARNATION_MAX) return;
+    for (const [key, incarnation] of _sessionIncarnations) {
+        if (_sessionIncarnations.size <= SESSION_INCARNATION_MAX) break;
+        if (incarnation.refs > 0) continue; // still referenced by outstanding work
+        _sessionIncarnations.delete(key);
+    }
+}
+
+// Strict diagnostics: a release without a matching acquire is a BUG, not a
+// clamp. Tests assert this stays zero instead of relying on the clamp.
+let _incarnationReleaseUnderflows = 0;
+
+export function _sessionIncarnationStats() {
+    return {
+        size: _sessionIncarnations.size,
+        max: SESSION_INCARNATION_MAX,
+        releaseUnderflows: _incarnationReleaseUnderflows,
+    };
+}
+
+/** Stamp for a new unit of work; keeps the incarnation alive until released. */
+export function _acquireSessionIncarnation(id) {
+    if (!id) return null;
+    let incarnation = _sessionIncarnations.get(id);
+    if (incarnation) _sessionIncarnations.delete(id);
+    else incarnation = { id, token: ++_incarnationSeq, refs: 0 };
+    incarnation.refs += 1;
+    _sessionIncarnations.set(id, incarnation); // LRU touch
+    _evictSessionIncarnations();
+    return incarnation;
+}
+
+export function _releaseSessionIncarnation(incarnation) {
+    if (!incarnation) return;
+    if (incarnation.refs > 0) incarnation.refs -= 1;
+    else _incarnationReleaseUnderflows += 1; // double release — surfaced, not hidden
+    // The cap is enforced on RELEASE too: a token that just became
+    // unreferenced is exactly the one eviction is allowed to reclaim.
+    if (incarnation.refs === 0) _evictSessionIncarnations();
+}
+
+/** Diagnostics/tests: outstanding references to an id's incarnation. */
+export function _sessionIncarnationRefs(id) {
+    const incarnation = id && _sessionIncarnations.get(id);
+    return incarnation ? incarnation.refs : 0;
+}
+
+/** False once the id was hard-deleted (or re-created) after this stamp. */
+export function _isCurrentSessionIncarnation(id, incarnation) {
+    if (!incarnation) return true; // unstamped work keeps its legacy behavior
+    return _sessionIncarnations.get(id) === incarnation;
+}
+
+/**
+ * Retire an id's incarnation on a SUCCESSFUL hard delete. The object is
+ * dropped from the registry and never handed out again: outstanding work that
+ * still holds it is permanently non-current, and a re-created id gets a fresh
+ * object of its own.
+ */
+export function _retireSessionIncarnation(id) {
+    if (id) _sessionIncarnations.delete(id);
+}
+
+/** Clear every save marker for an id (successful hard delete). */
+export function _clearSessionSaveState(id) {
+    if (!id) return;
+    _lastSaveError.delete(id);
+    _failureEpochs.delete(id);
+    // The recovery evidence dies with the file it was evidence ABOUT: a
+    // re-created id must never inherit the deleted incarnation's snapshot
+    // (that would resurrect a deleted transcript as the "only good copy").
+    _failedSaveSnapshots.delete(id);
+    _droppedSaveIds.delete(id);
+}
+
+function _markFailureEpoch(id, epoch) {
+    // An unknown epoch is treated as "newest": callers without an identity
+    // must never weaken the marker.
+    const value = Number.isFinite(epoch) ? epoch : _nextSaveEpoch();
+    const previous = _failureEpochs.get(id);
+    if (previous === undefined || value > previous) _failureEpochs.set(id, value);
+}
+
 export function setLiveSession(session) {
     if (!session?.id) return;
     _liveSessions.set(session.id, session);
@@ -46,4 +178,125 @@ export function getSessionSaveError(id) {
 
 export function clearSessionSaveError(id) {
     _lastSaveError.delete(id);
+    _failureEpochs.delete(id);
+    _failedSaveSnapshots.delete(id);
+}
+
+/**
+ * Record a failed atomic save. The disk copy is now BEHIND this process's live
+ * snapshot, so the id is flagged on BOTH channels:
+ *  - _lastSaveError: surfaced to callers (getSessionSaveError) and used by the
+ *    idle sweep / loadSession to keep the only-good in-memory state readable.
+ *  - _droppedSaveIds: the existing "disk is behind the snapshot" marker, so a
+ *    stale/lower-generation disk record cannot shadow the live transcript.
+ * Both are cleared by the next successful save (clearSessionSaveError +
+ * _droppedSaveIds.delete in the store's commit path).
+ */
+/**
+ * Point-in-time COPY of the exact payload whose save failed.
+ *
+ * Never the live reference: the caller keeps mutating that object (the next
+ * turn appends messages, status flips, the turn hook is re-attached), and a
+ * fallback read must reproduce what the failed write actually attempted —
+ * not a later state that was never offered to disk and is not backed by any
+ * failure evidence. The JSON round-trip detaches every nested container and
+ * drops functions/symbols (turn hooks), so no later mutation can reach it.
+ * An unclonable payload (circular ref) records NO evidence: readers then
+ * report the unreadable file instead of masking it.
+ */
+function _failedSaveClone(session) {
+    try {
+        const clone = JSON.parse(JSON.stringify(session));
+        return clone && typeof clone === 'object' && !Array.isArray(clone) ? clone : null;
+    } catch {
+        return null;
+    }
+}
+
+export function _recordSaveFailure(id, err, epoch = null, session = null) {
+    if (!id) return;
+    _lastSaveError.set(id, { message: err?.message ?? String(err), at: Date.now() });
+    _droppedSaveIds.add(id);
+    _markFailureEpoch(id, epoch);
+    // Only a snapshot that IS this id's failed payload is retained; a caller
+    // without one records no recovery evidence at all (readers then report the
+    // unreadable file instead of masking it).
+    if (session && session.id === id) {
+        const clone = _failedSaveClone(session);
+        if (clone && clone.id === id) _failedSaveSnapshots.set(id, clone);
+    }
+}
+
+/**
+ * The in-memory snapshot whose own save failed for `id`, or null.
+ * Deliberately NOT "the live session for id": it is the narrow proof that a
+ * same-process copy is newer than the canonical file.
+ */
+export function getFailedSaveSnapshot(id) {
+    if (!id) return null;
+    const snapshot = _failedSaveSnapshots.get(id);
+    if (!snapshot) return null;
+    // Hand out a COPY as well: a reader that mutates what it got back (every
+    // session consumer does) must not be able to edit the stored evidence.
+    return _failedSaveClone(snapshot);
+}
+
+/**
+ * Record an ownership-DROPPED save (nothing was written, disk moved past this
+ * snapshot). Same identity rule as a failure: an older landed write may not
+ * clear it.
+ */
+export function _recordSaveDrop(id, epoch = null) {
+    if (!id) return;
+    _droppedSaveIds.add(id);
+    _markFailureEpoch(id, epoch);
+}
+
+/**
+ * Clear the id's failure/drop markers on behalf of a LANDED save — but only
+ * when that save is at least as new as the newest recorded failure/drop.
+ * Returns whether the markers were cleared.
+ */
+export function _clearSaveStateIfCurrent(id, epoch = null) {
+    if (!id) return false;
+    const marked = _failureEpochs.get(id);
+    if (marked !== undefined && Number.isFinite(epoch) && epoch < marked) return false;
+    _failureEpochs.delete(id);
+    _lastSaveError.delete(id);
+    _failedSaveSnapshots.delete(id);
+    _droppedSaveIds.delete(id);
+    return true;
+}
+
+/** True while this process's last save attempt for `id` failed. */
+export function hasSessionSaveFailure(id) {
+    return !!id && _lastSaveError.has(id);
+}
+
+// ── Lifecycle (tombstone/detach) commit failures ────────────────────────────
+// markSessionClosed/bumpSessionGeneration return null for BOTH a legitimate
+// veto (session gone, liveness veto, contended commit lock) and a genuine
+// durable-write failure. closeSession must react very differently to the two:
+// a failed lifecycle barrier means NOTHING was fenced on disk, so tearing the
+// runtime down would strand a live turn behind an un-planted tombstone. This
+// map is the disambiguator — set only on a real commit failure, cleared when
+// the barrier lands.
+const _lifecycleCommitErrors = new Map(); // id -> { message, at, code, reason }
+
+export function _recordLifecycleCommitFailure(id, err, reason = null) {
+    if (!id) return;
+    _lifecycleCommitErrors.set(id, {
+        message: err?.message ?? String(err),
+        code: err?.code ?? null,
+        reason,
+        at: Date.now(),
+    });
+}
+
+export function getSessionLifecycleCommitError(id) {
+    return _lifecycleCommitErrors.get(id) ?? null;
+}
+
+export function clearSessionLifecycleCommitError(id) {
+    _lifecycleCommitErrors.delete(id);
 }