mixdog 0.7.1

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

@@ -0,0 +1,624 @@
+/**
+ * File-based session store.
+ * Sessions are saved to disk so CLI and MCP server can share state,
+ * and sessions survive server restarts (resume).
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, unlinkSync, statSync, appendFileSync } from 'fs';
+import * as fsp from 'fs/promises';
+import { randomBytes } from 'crypto';
+import { join } from 'path';
+import { Worker } from 'worker_threads';
+import { getPluginData } from '../config.mjs';
+import { renameWithRetrySync } from '../../../shared/atomic-file.mjs';
+
+const _lastSaveError = new Map(); // id -> { message, at }
+
+function _renameWithRetrySync(tmp, target) {
+    return renameWithRetrySync(tmp, target);
+}
+
+function getStoreDir() {
+    const dir = join(getPluginData(), 'sessions');
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    return dir;
+}
+function sessionPath(id) {
+    // Enforce minted session-id shape before using it in a path to prevent
+    // `../` traversal. session IDs are generated by createSession as
+    // `sess_<timestamp>_<hex>` — reject anything that doesn't match.
+    if (!id || typeof id !== 'string' || !/^[A-Za-z0-9_-]+$/.test(id)) {
+        throw new Error(`[session-store] invalid session id: ${JSON.stringify(id)}`);
+    }
+    return join(getStoreDir(), `${id}.json`);
+}
+/**
+ * Ensure generation/closed defaults on every session object.
+ * Older persisted sessions predate these fields; we normalise at load and save.
+ */
+function _ensureLifecycleFields(session) {
+    if (typeof session.generation !== 'number') session.generation = 0;
+    if (typeof session.closed !== 'boolean') session.closed = false;
+    if (!Array.isArray(session.messages)) session.messages = [];
+    if (!Array.isArray(session.tools)) session.tools = [];
+    return session;
+}
+
+/** Module-level map tracking in-flight saves per session ID to prevent concurrent write corruption. */
+const _savePending = new Map();
+
+/** Same-process authoritative session snapshots (createSession → loadSession / askSession). */
+const _liveSessions = new Map();
+
+export function setLiveSession(session) {
+    if (!session?.id) return;
+    _liveSessions.set(session.id, session);
+}
+
+function _clearLiveSession(id) {
+    if (id) _liveSessions.delete(id);
+}
+
+// ── Heartbeat publish ─────────────────────────────────────
+// Lightweight per-session timestamp file (`<id>.hb`) consumed by the
+// status aggregator for fresh-session detection. Decoupled from the
+// full session JSON save so it can fire at a tight cadence (≤5s)
+// without serialising the whole payload. The .hb file holds a single
+// ASCII line: `<msTimestamp>\n`. Aggregator scans the same sessions/
+// directory and matches `<id>.hb` to `<id>.json`.
+const _HEARTBEAT_THROTTLE_MS = 5_000;
+const _hbLastAt = new Map();
+
+function _heartbeatPath(id) {
+    if (!id || typeof id !== 'string' || !/^[A-Za-z0-9_-]+$/.test(id)) {
+        throw new Error(`[session-store] invalid session id: ${JSON.stringify(id)}`);
+    }
+    return join(getStoreDir(), `${id}.hb`);
+}
+
+export function publishHeartbeat(id, ts) {
+    if (!id) return;
+    const now = ts || Date.now();
+    const last = _hbLastAt.get(id) || 0;
+    if (now - last < _HEARTBEAT_THROTTLE_MS) return;
+    const target = _heartbeatPath(id);
+    const tmp = `${target}.${randomBytes(4).toString('hex')}.tmp`;
+    try {
+        writeFileSync(tmp, `${now}\n`);
+        _renameWithRetrySync(tmp, target);
+        _hbLastAt.set(id, now);
+    } catch {
+        try { unlinkSync(tmp); } catch { /* ignore */ }
+    }
+}
+
+export function deleteHeartbeat(id) {
+    try { unlinkSync(_heartbeatPath(id)); } catch { /* ignore */ }
+    _hbLastAt.delete(id);
+}
+const _deleteHeartbeat = deleteHeartbeat;
+
+// ── 150 ms debounce window ────────────────────────────────────────────────────
+// Multiple tool-result writes within a turn collapse to one tmp+rename per
+// session. The timer is unref'd so it never keeps the process alive.
+const _debounceTimers = new Map(); // id → NodeJS.Timeout
+function _clearDebounce(id) {
+    const t = _debounceTimers.get(id);
+    if (t) { clearTimeout(t); _debounceTimers.delete(id); }
+}
+
+// Flush all debounced sessions synchronously on process exit / SIGTERM.
+// This prevents losing the last turn's tool-result writes.
+function _drainAllDebounced() {
+    for (const [id, t] of _debounceTimers) {
+        clearTimeout(t);
+        _debounceTimers.delete(id);
+        const cur = _savePending.get(id);
+        if (cur && cur.debouncing && cur.payload) {
+            try { _doSaveSync(cur.payload); } catch { /* best-effort */ }
+            _savePending.delete(id);
+        }
+    }
+}
+// SIGTERM/SIGINT drain runs through drain-registry.mjs (single signal owner);
+// bare 'exit' hook stays as an idempotent backup. Use the more comprehensive
+// drainSessionStore so debounce + scheduled + writing payloads all flush.
+process.on('exit', drainSessionStore);
+
+/**
+ * Persist a session. `opts.expectedGeneration` guards against resurrecting a
+ * session that was closed mid-flight: before the rename, we re-read the file
+ * on disk and, if it's already marked closed with a >= generation, drop the
+ * write. `opts.allowClosed=true` is used by `markSessionClosed` itself when
+ * writing the tombstone.
+ */
+export function saveSession(session, opts) {
+    _ensureLifecycleFields(session);
+    const id = session.id;
+    setLiveSession(session);
+    const payload = { session, opts: opts || null };
+    // Synchronous durability path — explicit flush (tombstones, drain hooks).
+    // createSession uses async debounced save + _liveSessions for same-process
+    // read-your-writes; sync remains for callers that require immediate disk.
+    if (opts?.sync) {
+        _doSaveSync(payload);
+        return;
+    }
+    // Immediate-flush override: tombstone plants and explicit flushes skip the
+    // debounce so close-session writes are always durable.
+    if (opts?.immediate) {
+        _clearDebounce(id);
+        const pending = _savePending.get(id);
+        if (pending) {
+            if (pending.writing) {
+                _savePending.set(id, { ...pending, queued: payload });
+            } else {
+                _savePending.set(id, { ...pending, payload });
+                _flushScheduled(id);
+            }
+        } else {
+            _savePending.set(id, { writing: true });
+            _doSave(payload).catch(err => {
+                process.stderr.write(`[session-store] save failed: ${err?.message}\n`);
+                _lastSaveError.set(id, { message: err?.message ?? String(err), at: Date.now() });
+            });
+        }
+        return;
+    }
+    const pending = _savePending.get(id);
+    if (pending) {
+        if (pending.writing) {
+            // Write in flight — overwrite the queued slot. Multiple async
+            // saves for the same id while one is on disk collapse into a
+            // single follow-up write.
+            _savePending.set(id, { ...pending, queued: payload });
+        } else if (pending.scheduled) {
+            // setImmediate already scheduled — coalesce into the same tick
+            // by overwriting the pending payload with the latest state.
+            _savePending.set(id, { scheduled: true, payload });
+        } else if (pending.debouncing) {
+            // 150 ms debounce window active — overwrite payload, timer keeps running.
+            _savePending.set(id, { debouncing: true, payload });
+        }
+        return;
+    }
+    // First save for this id — open a 150 ms debounce window.  Any additional
+    // calls within the window overwrite the payload; only one tmp+rename fires.
+    // The setImmediate inside the timeout body provides the original coalescing
+    // guarantee within the same event-loop tick at the moment the timer fires.
+    _savePending.set(id, { debouncing: true, payload });
+    const t = setTimeout(() => {
+        _debounceTimers.delete(id);
+        const cur = _savePending.get(id);
+        if (!cur || !cur.debouncing) return; // already handled (writing/queued)
+        _savePending.set(id, { scheduled: true, payload: cur.payload });
+        setImmediate(() => _flushScheduled(id));
+    }, 150);
+    if (t.unref) t.unref();
+    _debounceTimers.set(id, t);
+}
+
+function _flushScheduled(id) {
+    const cur = _savePending.get(id);
+    if (!cur || !cur.scheduled) return;
+    _savePending.set(id, { writing: true, payload: cur.payload });
+    _doSave(cur.payload).catch(err => {
+        process.stderr.write(`[session-store] save failed: ${err?.message}\n`);
+        _lastSaveError.set(id, { message: err?.message ?? String(err), at: Date.now() });
+    });
+}
+
+// ── Worker-thread async save ──────────────────────────────────────────────────
+// Single long-lived Worker serializes all saveSessionAsync calls.
+// The worker's message queue preserves generation-race ordering.
+let _saveWorker = null;
+let _saveWorkerPending = new Map(); // reqId → { resolve, reject, session, opts }
+let _saveWorkerReqId = 0;
+let _saveWorkerRefCount = 0;
+
+function _getOrSpawnWorker() {
+    if (_saveWorker) return _saveWorker;
+    _saveWorker = new Worker(new URL('./save-session-worker.mjs', import.meta.url), {
+        execArgv: [],
+    });
+    _saveWorker.on('message', ({ ok, error, reqId }) => {
+        const p = _saveWorkerPending.get(reqId);
+        if (!p) return;
+        _saveWorkerPending.delete(reqId);
+        // Drop the ref AFTER pending was registered ref-up'd so the worker
+        // becomes unref'd again once all in-flight writes settle. _saveWorker
+        // null-check covers the error/exit race where the worker died first.
+        if (--_saveWorkerRefCount === 0 && _saveWorker) _saveWorker.unref();
+        if (ok) p.resolve();
+        else p.reject(new Error(`[session-store] worker save failed: ${error}`));
+    });
+    _saveWorker.on('error', (err) => {
+        for (const [, p] of _saveWorkerPending) p.reject(err);
+        _saveWorkerPending.clear();
+        _saveWorkerRefCount = 0;
+        _saveWorker = null;
+    });
+    _saveWorker.on('exit', (code) => {
+        // Reject pending resolvers on ANY exit (code 0 included) so an idle
+        // worker that races a pending postMessage cannot leak resolvers. The
+        // map is empty on the normal idle-exit path so the loop is a no-op,
+        // but it remains safe for the race window where exit fires after
+        // saveSessionAsync registered a resolver but before the worker
+        // received the message.
+        const err = new Error(`[session-store] save worker exited with code ${code}`);
+        for (const [, p] of _saveWorkerPending) p.reject(err);
+        _saveWorkerPending.clear();
+        _saveWorkerRefCount = 0;
+        _saveWorker = null;
+    });
+    _saveWorker.unref(); // don't keep process alive
+    return _saveWorker;
+}
+
+/**
+ * Async save via a dedicated Worker thread.
+ * Errors surface as thrown Errors — callers must not silently swallow them.
+ */
+export function saveSessionAsync(session, opts) {
+    _ensureLifecycleFields(session);
+    setLiveSession(session);
+    const reqId = ++_saveWorkerReqId;
+    const safeOpts = opts || null;
+    return new Promise((resolve, reject) => {
+        // Persist {session, opts} so drainSessionStore can sync-flush
+        // outstanding writes if process exit interrupts the worker queue.
+        _saveWorkerPending.set(reqId, { resolve, reject, session, opts: safeOpts });
+        try {
+            const w = _getOrSpawnWorker();
+            w.postMessage({ session, opts: safeOpts, reqId });
+            // Ref AFTER successful postMessage so a queue/throw failure path
+            // does not leave the worker held alive with no pending message.
+            // Paired with the unref in the message handler when count hits 0.
+            if (++_saveWorkerRefCount === 1) w.ref();
+        } catch (err) {
+            _saveWorkerPending.delete(reqId);
+            reject(err);
+        }
+    });
+}
+
+/**
+ * Exported for save-session-worker — not part of the public API.
+ * External callers should use saveSession / saveSessionAsync.
+ */
+export function _saveSessionSync(session, opts) {
+    _ensureLifecycleFields(session);
+    _doSaveSync({ session, opts: opts || null });
+}
+
+function _doSaveSync(payload) {
+    const { session, opts } = payload;
+    const id = session.id;
+    if (_shouldDrop(id, opts)) return;
+    const target = sessionPath(id);
+    const tmp = target + '.' + randomBytes(6).toString('hex') + '.tmp';
+    try {
+        writeFileSync(tmp, JSON.stringify(session), 'utf-8');
+        if (_shouldDrop(id, opts)) {
+            try { unlinkSync(tmp); } catch { /* ignore cleanup failure */ }
+            return;
+        }
+        _renameWithRetrySync(tmp, target);
+    } catch (err) {
+        try { unlinkSync(tmp); } catch { /* ignore cleanup failure */ }
+        throw err;
+    }
+}
+
+function _shouldDrop(id, opts) {
+    if (!opts || opts.allowClosed) return false;
+    const expected = typeof opts.expectedGeneration === 'number' ? opts.expectedGeneration : null;
+    if (expected === null) return false;
+    // Re-read current tombstone state from disk. If the session is closed with
+    // a generation >= expected, our write is stale — drop it.
+    const target = sessionPath(id);
+    if (!existsSync(target)) return false;
+    try {
+        const onDisk = JSON.parse(readFileSync(target, 'utf-8'));
+        const diskGen = typeof onDisk.generation === 'number' ? onDisk.generation : 0;
+        return onDisk.closed === true && diskGen >= expected;
+    } catch {
+        return false;
+    }
+}
+
+/** Sync-flush every pending save on exit; per-entry catch matches _flushScheduled. */
+export function drainSessionStore() {
+    for (const t of _debounceTimers.values()) clearTimeout(t);
+    _debounceTimers.clear();
+    for (const [, pending] of _savePending) {
+        if (!pending.payload) continue;
+        try {
+            _doSaveSync(pending.payload);
+        } catch (err) {
+            process.stderr.write(`[session-store] drain save failed: ${err?.message}\n`);
+        }
+    }
+    _savePending.clear();
+    // Outstanding worker-queue writes: process exit may interrupt the worker
+    // thread before it processes its message queue, so each pending payload
+    // is sync-flushed directly here. The Promise is then rejected so the
+    // caller's await site does not leak unresolved (caller is at process
+    // exit so the rejection is informational, not actionable).
+    for (const [, pending] of _saveWorkerPending) {
+        if (!pending.session) continue;
+        try {
+            _saveSessionSync(pending.session, pending.opts);
+        } catch (err) {
+            process.stderr.write(`[session-store] drain worker-queue save failed: ${err?.message}\n`);
+        }
+        try {
+            pending.reject(new Error('[session-store] drain: worker-queue interrupted by process exit'));
+        } catch { /* best-effort */ }
+    }
+    _saveWorkerPending.clear();
+    _saveWorkerRefCount = 0;
+}
+
+function _drainQueue(id) {
+    const pending = _savePending.get(id);
+    if (pending && pending.queued) {
+        const next = pending.queued;
+        _savePending.set(id, { writing: true, payload: next });
+        _doSave(next).catch(err => {
+            process.stderr.write(`[session-store] save failed: ${err?.message}\n`);
+            _lastSaveError.set(id, { message: err?.message ?? String(err), at: Date.now() });
+        });
+    } else {
+        _savePending.delete(id);
+    }
+}
+
+async function _doSave(payload) {
+    const { session, opts } = payload;
+    const id = session.id;
+    // First check: upfront, before any disk I/O. Cheap short-circuit when a
+    // tombstone is already on disk when the caller arrives.
+    if (_shouldDrop(id, opts)) {
+        _drainQueue(id);
+        return;
+    }
+    const target = sessionPath(id);
+    const tmp = target + '.' + randomBytes(6).toString('hex') + '.tmp';
+    try {
+        await fsp.writeFile(tmp, JSON.stringify(session), 'utf-8');
+        // Second check: between the temp write and the rename, closeSession()
+        // may have planted a tombstone. Re-check on disk; if a newer tombstone
+        // now exists, discard our temp file rather than let rename clobber it.
+        if (_shouldDrop(id, opts)) {
+            try { unlinkSync(tmp); } catch { /* ignore cleanup failure */ }
+            process.stderr.write(`[session-store] ${id}: dropped stale save (tombstone planted during write)\n`);
+            _drainQueue(id);
+            return;
+        }
+        _renameWithRetrySync(tmp, target);
+    } catch (err) {
+        try { unlinkSync(tmp); } catch { /* ignore cleanup failure */ }
+        _savePending.delete(id);
+        throw err;
+    }
+    _drainQueue(id);
+}
+
+/**
+ * Atomically mark a session closed on disk with a bumped generation.
+ * Returns the new generation, or null if the session file doesn't exist.
+ * Used by closeSession() to plant a tombstone that races against in-flight
+ * saveSession() calls.
+ */
+export function markSessionClosed(id, reason = 'manual') {
+    // Cancel any pending debounced save so it cannot overwrite the tombstone
+    // that we are about to plant. The _shouldDrop() guard inside _doSave()
+    // provides a second line of defence, but cancelling here is cheaper.
+    _clearDebounce(id);
+    const existing = loadSession(id);
+    if (!existing) return null;
+    const newGen = (typeof existing.generation === 'number' ? existing.generation : 0) + 1;
+    const tombstone = { ...existing, closed: true, closedReason: reason, status: 'closed', generation: newGen, updatedAt: Date.now() };
+    // Bypass the queue + guard — this IS the tombstone write.
+    const target = sessionPath(id);
+    const tmp = target + '.' + randomBytes(6).toString('hex') + '.tmp';
+    try {
+        writeFileSync(tmp, JSON.stringify(tombstone), 'utf-8');
+        _renameWithRetrySync(tmp, target);
+    } catch {
+        try { unlinkSync(tmp); } catch { /* ignore */ }
+        return null;
+    }
+    _savePending.delete(id);
+    _clearLiveSession(id);
+    _deleteHeartbeat(id);
+    // Structured close metric. Single emission point because every close
+    // path funnels through markSessionClosed. lifeMs = updatedAt-createdAt
+    // straddles the tombstone (updatedAt was just set to Date.now()), so
+    // it reflects the session's full lifetime including the close turn.
+    try {
+        const _dataDir = getPluginData();
+        if (_dataDir) {
+            const _ts = new Date().toISOString();
+            const _lifeMs = (typeof existing.createdAt === 'number' && existing.createdAt > 0)
+                ? (tombstone.updatedAt - existing.createdAt)
+                : 0;
+            const _role = existing.role || '-';
+            const _owner = existing.owner || '-';
+            appendFileSync(
+                join(_dataDir, 'tool-events.log'),
+                `[${_ts}] [session-close] owner=${_owner} role=${_role} reason=${reason} lifeMs=${_lifeMs} id=${id}\n`,
+            );
+        }
+    } catch { /* logger never breaks the close path */ }
+    return newGen;
+}
+
+export function loadSession(id) {
+    const path = sessionPath(id);
+    // Read-your-writes: if a save is pending (debouncing, scheduled, or queued
+    // behind an in-flight write) return that payload instead of stale disk state.
+    // The most-recently-queued slot is checked first (queued > payload).
+    const pending = _savePending.get(id);
+    if (pending) {
+        const inMemory = (pending.queued || pending.payload)?.session;
+        if (inMemory) return _ensureLifecycleFields(inMemory);
+    }
+    const live = _liveSessions.get(id);
+    if (live) return _ensureLifecycleFields(live);
+    if (!existsSync(path)) return null;
+    try { return _ensureLifecycleFields(JSON.parse(readFileSync(path, 'utf-8'))); }
+    catch { return null; }
+}
+
+/**
+ * Returns the last save error for a session id, or null if no error has occurred.
+ * Shape: { message: string, at: number } | null
+ */
+export function getSessionSaveError(id) {
+    return _lastSaveError.get(id) ?? null;
+}
+
+export function clearSessionSaveError(id) {
+    _lastSaveError.delete(id);
+}
+
+export function deleteSession(id) {
+    const path = sessionPath(id);
+    let removed = false;
+    if (existsSync(path)) {
+        try {
+            unlinkSync(path);
+            removed = true;
+        }
+        catch { /* fall through to .hb cleanup */ }
+    }
+    _deleteHeartbeat(id);
+    return removed;
+}
+const DEFAULT_SESSION_TTL_MS = 5 * 60 * 1000; // 5 minutes idle — aligned with Anthropic 5m messages tier and OpenAI in-memory cache window
+// Hard wall-clock ceiling for sessions stuck in status='running'. The
+// stream-watchdog should abort stalled streams within ~120s, but if it misses
+// one (process crash, watchdog not started, provider never returned), this
+// backstop reclaims the file so the sweep doesn't leak zombies indefinitely.
+const RUNNING_STALL_MS = 10 * 60 * 1000;
+
+export function listStoredSessions() {
+    const dir = getStoreDir();
+    if (!existsSync(dir))
+        return [];
+    const files = readdirSync(dir).filter(f => f.endsWith('.json'));
+    const sessions = [];
+    for (const f of files) {
+        try {
+            const session = _ensureLifecycleFields(JSON.parse(readFileSync(join(dir, f), 'utf-8')));
+            sessions.push(session);
+        }
+        catch { /* skip corrupt */ }
+    }
+    return sessions.sort((a, b) => b.updatedAt - a.updatedAt);
+}
+
+/**
+ * Raw directory scan — returns every parseable session file without any
+ * TTL-based inline deletion. Callers (e.g. sweepTombstones) need to own the
+ * unlink decision and log it themselves.
+ */
+export function getStoredSessionsRaw() {
+    const dir = getStoreDir();
+    if (!existsSync(dir)) return [];
+    const files = readdirSync(dir).filter(f => f.endsWith('.json'));
+    const sessions = [];
+    for (const f of files) {
+        try {
+            sessions.push(JSON.parse(readFileSync(join(dir, f), 'utf-8')));
+        } catch { /* skip corrupt */ }
+    }
+    return sessions;
+}
+
+/**
+ * Background sweep: delete session files idle longer than ttlMs.
+ * Returns { cleaned, remaining, details } for logging.
+ */
+export function sweepStaleSessions(ttlMs) {
+    const maxAge = ttlMs || DEFAULT_SESSION_TTL_MS;
+    const dir = getStoreDir();
+    if (!existsSync(dir))
+        return { cleaned: 0, remaining: 0, details: [] };
+    const files = readdirSync(dir).filter(f => f.endsWith('.json'));
+    const now = Date.now();
+    let cleaned = 0;
+    let remaining = 0;
+    const details = [];
+    for (const f of files) {
+        try {
+            const session = JSON.parse(readFileSync(join(dir, f), 'utf-8'));
+            // Prefer .hb sidecar mtime — updated at tight cadence (≤5s) without
+            // serialising the full JSON, so it reflects true liveness more
+            // accurately than the JSON timestamp fields.
+            let lastActive = session.lastHeartbeatAt || session.updatedAt || session.createdAt || 0;
+            try {
+                const hbPath = join(dir, f.replace(/\.json$/, '.hb'));
+                if (existsSync(hbPath)) {
+                    const hbMtime = statSync(hbPath).mtimeMs;
+                    if (hbMtime) lastActive = Math.max(lastActive, hbMtime);
+                }
+            } catch { /* .hb unavailable — fall back to JSON fields */ }
+            // Sweep bridge-owned and ownerless (legacy) sessions; skip explicit user sessions.
+            if (typeof session.owner === 'string' && session.owner.length > 0 && session.owner !== 'bridge') {
+                remaining++;
+                continue;
+            }
+            // Already-closed tombstones are handled by the status-server /
+            // manager tombstone reapers. Do not "close" them again here:
+            // markSessionClosed() bumps updatedAt, which makes old tombstones
+            // look fresh and can resurrect stale statusline noise.
+            if (session.closed === true || session.status === 'closed') {
+                remaining++;
+                continue;
+            }
+            // Running sessions are normally reaped by the stream-watchdog
+            // within ~120s. Skip them here unless they've been silent past
+            // RUNNING_STALL_MS, at which point they are treated as zombies.
+            if (session.status === 'running' && now - lastActive <= RUNNING_STALL_MS) {
+                remaining++;
+                continue;
+            }
+            if (now - lastActive > maxAge) {
+                try { markSessionClosed(session.id, 'idle-sweep'); }
+                catch (err) {
+                    process.stderr.write(`[session-store] idle-sweep close failed for ${session.id}: ${err?.message}\n`);
+                    continue;
+                }
+                cleaned++;
+                details.push({
+                    id: session.id,
+                    owner: session.owner || 'unknown',
+                    idleMinutes: Math.round((now - lastActive) / 60000),
+                    bashSessionId: session.implicitBashSessionId || null,
+                });
+            } else {
+                remaining++;
+            }
+        }
+        catch { /* skip corrupt */ }
+    }
+    // Orphan .hb reap: a heartbeat sidecar whose .json no longer exists is dead
+    // weight once it is also stale (older than maxAge) — the session JSON was
+    // swept/closed but the .hb lingered (a pre-fix orphaned heartbeat). The
+    // staleness gate avoids nuking the .hb of a session mid-create whose .json
+    // write has not landed yet.
+    try {
+        for (const h of readdirSync(dir).filter(f => f.endsWith('.hb'))) {
+            if (existsSync(join(dir, h.replace(/\.hb$/, '.json')))) continue;
+            let hbMtime = 0;
+            try { hbMtime = statSync(join(dir, h)).mtimeMs; } catch { continue; }
+            if (now - hbMtime > maxAge) {
+                try { unlinkSync(join(dir, h)); cleaned++; } catch { /* ignore */ }
+            }
+        }
+    } catch { /* dir scan failure — non-fatal */ }
+    return { cleaned, remaining, details };
+}