mixdog 0.7.18 → 0.8.0

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

@@ -1,632 +0,0 @@
-/**
- * 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
-// Completed bridge workers (idle/done/error) live until terminal reap — must
-// match TERMINAL_REAP_MS / _scheduleBridgeReap (3_600_000) in index.mjs and
-// bridge-stall-watchdog.mjs so the store sweep is the durable 1h reaper.
-const BRIDGE_TERMINAL_TTL_MS = 60 * 60 * 1000;
-const BRIDGE_TERMINAL_STATUSES = new Set(['idle', 'done', 'error']);
-// 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;
-            }
-            const isCompletedBridge = session.owner === 'bridge'
-                && BRIDGE_TERMINAL_STATUSES.has(session.status);
-            const sessionMaxAge = isCompletedBridge ? BRIDGE_TERMINAL_TTL_MS : maxAge;
-            if (now - lastActive > sessionMaxAge) {
-                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 };
-}