@maudecode/talaria-web 1.18.0 → 1.19.0

package/dist/sessions/store.js

@@ -1,21 +1,10 @@
+import { markedStateDbGeneration } from './state-db-identity.js';
 import { str } from '../util.js';
-/**
- * The WebUI session store (Python `api/models.py`): `sessions/<sid>.json`
- * sidecars written atomically with a `.bak` on shrink, the sorted
- * `sessions/_index.json` sidebar index with incremental patching, a bounded
- * LRU of resident sessions that never evicts active or unsaved work, the
- * deleted-session tombstone, composer draft overlays, and per-session
- * mutation locks.
- *
- * The state.db projection (CLI sessions, lineage metadata, transcript
- * reconciliation) is not part of this store; it layers on in the sidebar
- * builder once the read-only SQLite projection lands.
- */
-import { closeSync, existsSync, fstatSync, fsyncSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, rmSync, statSync, unlinkSync } from 'node:fs';
-import { writeFully } from '../fs/atomic.js';
-import { basename, join } from 'node:path';
 import { sanitizeSessionRow } from './list.js';
+import { withBackgroundDisplayKinds } from './background-updates.js';
 import { anchorSceneIndexFromRecords, collapseAdjacentDuplicatePartials, isSafeSessionId, Session } from './session.js';
+import { RevisionConflict } from './storage/backend.js';
+import { sessionSearchMatches, sessionSearchMessageText } from './storage/search-text.js';
 export class SessionNotFound extends Error {
     sid;
     constructor(sid) {
@@ -24,175 +13,44 @@ export class SessionNotFound extends Error {
         this.name = 'SessionNotFound';
     }
 }
-const LOAD_STABLE_READ_ATTEMPTS = 3;
 const UNSAVED_SHELL_GRACE_S = 1800;
-const STALE_TMP_AGE_S = 3600;
-const DELETED_TOMBSTONE_CAP = 1000;
-const DELETED_TOMBSTONE_VERSION = 1;
-let tmpCounter = 0;
-function tmpName(path) {
-    return `${path}.tmp.${process.pid}.${++tmpCounter}`;
-}
-function writeAtomic(path, text) {
-    const tmp = tmpName(path);
-    const fd = openSync(tmp, 'w');
-    try {
-        writeFully(fd, text);
-        fsyncSync(fd);
-        closeSync(fd);
-        renameSync(tmp, path);
-    }
-    catch (error) {
-        try {
-            closeSync(fd);
-        }
-        catch { /* closed */ }
-        try {
-            unlinkSync(tmp);
-        }
-        catch { /* gone */ }
-        throw error;
-    }
-}
-export function statSignature(path) {
-    try {
-        const st = statSync(path, { bigint: true });
-        return `${path}:${st.mtimeNs}:${st.size}:${st.ctimeNs}`;
-    }
-    catch {
-        return null;
-    }
-}
-/** Python `_read_metadata_json_prefix`: everything before the top-level `messages` (or `anchor_activity_scenes`) key. */
-export function readMetadataJsonPrefix(path, maxBytes = 1024 * 1024) {
-    return readMetadataJsonPrefixWithSignature(path, maxBytes).prefix;
-}
-/**
- * The metadata prefix together with the signature of the inode it was read from (fstat of the open descriptor), so a
- * file atomically replaced during the read is never cached under the replacement's identity.
- */
-export function readMetadataJsonPrefixWithSignature(path, maxBytes = 1024 * 1024) {
-    const fd = openSync(path, 'r');
-    try {
-        const st = fstatSync(fd, { bigint: true });
-        const signature = `${path}:${st.mtimeNs}:${st.size}:${st.ctimeNs}`;
-        return { prefix: readPrefixFromFd(fd, maxBytes, Math.min(64 * 1024, maxBytes)), signature };
-    }
-    finally {
-        closeSync(fd);
-    }
-}
-function readPrefixFromFd(fd, maxBytes, initialStage) {
-    let stage = initialStage;
-    {
-        let raw = Buffer.alloc(0);
-        let text = '';
-        let stopPos = null;
-        while (raw.length < maxBytes) {
-            const chunk = Buffer.alloc(Math.min(stage, maxBytes - raw.length));
-            const n = readSyncFully(fd, chunk);
-            if (n === 0)
-                return null;
-            raw = Buffer.concat([raw, chunk.subarray(0, n)]);
-            text = raw.toString('utf8');
-            const messagesPos = findTopLevelJsonKey(text, 'messages');
-            const scenesPos = findTopLevelJsonKey(text, 'anchor_activity_scenes');
-            stopPos = messagesPos;
-            if (scenesPos !== null && (stopPos === null || scenesPos < stopPos))
-                stopPos = scenesPos;
-            if (stopPos !== null)
-                break;
-            stage *= 2;
-        }
-        if (stopPos === null)
-            return null;
-        let prefix = text.slice(0, stopPos).trimEnd();
-        if (prefix.endsWith(','))
-            prefix = prefix.slice(0, -1).trimEnd();
-        return `${prefix}\n}`;
-    }
-}
-import { readSync } from 'node:fs';
-function readSyncFully(fd, buf) {
-    let total = 0;
-    while (total < buf.length) {
-        const n = readSync(fd, buf, total, buf.length - total, null);
-        if (n === 0)
-            break;
-        total += n;
-    }
-    return total;
-}
-/** Offset of `"key":` at JSON nesting depth 1, or null. */
-export function findTopLevelJsonKey(text, key) {
-    let depth = 0;
-    let inString = false;
-    let escape = false;
-    let stringStart = -1;
-    for (let i = 0; i < text.length; i += 1) {
-        const ch = text[i];
-        if (inString) {
-            if (escape)
-                escape = false;
-            else if (ch === '\\')
-                escape = true;
-            else if (ch === '"') {
-                inString = false;
-                if (depth === 1 && text.slice(stringStart + 1, i) === key) {
-                    let j = i + 1;
-                    while (j < text.length && /\s/.test(text[j] ?? ''))
-                        j += 1;
-                    if (text[j] === ':')
-                        return stringStart;
-                }
-            }
-            continue;
-        }
-        if (ch === '"') {
-            inString = true;
-            stringStart = i;
-            continue;
-        }
-        if (ch === '{' || ch === '[')
-            depth += 1;
-        else if (ch === '}' || ch === ']')
-            depth -= 1;
-    }
-    return null;
-}
-export function readPersistedMessageCount(path) {
-    try {
-        const prefix = readMetadataJsonPrefix(path);
-        if (!prefix)
-            return null;
-        const value = JSON.parse(prefix).message_count;
-        if (typeof value === 'boolean')
-            return null;
-        const n = Number(value);
-        return Number.isInteger(n) && n >= 0 ? n : null;
-    }
-    catch {
-        return null;
-    }
-}
 export class SessionStore {
     deps;
-    sessionDir;
-    indexFile;
-    /** Resident sessions in LRU order (oldest first). */
     sessions = new Map();
     locks = new Map();
-    persistedIdsCache = null;
-    parsedIndexCache = null;
-    indexFlush = null;
+    writes = new Map();
+    resolutions = new Map();
+    persistedMessages = new WeakMap();
+    indexWriter = Promise.resolve();
     indexPending = new Map();
+    indexFlush = null;
     constructor(deps) {
         this.deps = deps;
-        this.sessionDir = deps.sessionDir;
-        this.indexFile = join(deps.sessionDir, '_index.json');
     }
-    pathFor(sid) {
-        return join(this.sessionDir, `${sid}.json`);
+    get backend() { return this.deps.storage.sessions; }
+    async exists(sid) { return this.backend.exists(sid); }
+    async revision(sid) { return this.backend.revision(sid); }
+    readMessages(sid, range) { return this.backend.readMessages(sid, range); }
+    async index() { return this.backend.index(); }
+    async hasIndex() { return this.backend.hasIndex(); }
+    get shrinkBackup() { return this.backend.shrinkBackup; }
+    async diagnose() { return this.backend.diagnose(); }
+    async repair(issue) {
+        const repaired = await this.backend.repair(issue);
+        if (repaired)
+            this.sessions.delete(issue.session_id);
+        return repaired;
+    }
+    async close() {
+        try {
+            await Promise.allSettled(this.resolutions.values());
+            await Promise.allSettled(this.writes.values());
+            await this.indexFlush;
+            await this.indexWriter;
+        }
+        finally {
+            await this.deps.storage.close();
+        }
     }
     // ── locks ────────────────────────────────────────────────────────────────
     /** Serialize one session's read-modify-write sequences (Python `_get_session_agent_lock`). */
@@ -222,17 +80,17 @@ export class SessionStore {
         }
     }
     // ── creation / resolution ────────────────────────────────────────────────
-    construct(init, profile) {
-        const session = new Session(init, this.deps.defaults(profile));
+    async construct(init, profile) {
+        const session = new Session(init, (await this.deps.defaults(profile)));
         // New-session defaults must not replace the title supplied by the read projection.
         if (typeof init.title === 'string')
             session.title = init.title;
         return session;
     }
     /** In-memory only until the first message is persisted (Python `new_session`). */
-    newSession(opts = {}) {
+    async newSession(opts = {}) {
         const profile = opts.profile ?? null;
-        const defaults = this.deps.defaults(profile);
+        const defaults = (await this.deps.defaults(profile));
         const wt = opts.worktree ?? null;
         const s = new Session({
             workspace: (wt ? wt.path : opts.workspace) || defaults.workspace,
@@ -247,97 +105,81 @@ export class SessionStore {
             worktree_created_at: wt?.created_at ?? null,
             enabled_toolsets: opts.enabledToolsets ?? null,
         }, defaults);
-        this.clearDeletedTombstone(s.session_id);
-        this.touch(s);
+        await this.clearDeletedTombstone(s.session_id);
+        await this.touch(s);
         if (wt)
-            this.save(s);
+            (await this.save(s));
         return s;
     }
     /** Insert or refresh a session in the LRU and evict over the cap. */
-    touch(session) {
+    async touch(session) {
         this.sessions.delete(session.session_id);
         this.sessions.set(session.session_id, session);
-        this.evictOverCap();
+        await this.evictOverCap();
     }
-    load(sid) {
+    async load(sid, opts = {}) {
         if (!isSafeSessionId(sid))
             return null;
-        const path = this.pathFor(sid);
-        if (!existsSync(path))
-            return null;
-        // Another process may replace the file atomically while we read it: retry until one read is bracketed by the
-        // same signature. A read that never stabilises keeps a null signature, which `cachedLagsDisk` treats as stale.
-        let data = {};
-        let signature = null;
-        for (let attempt = 0; attempt < LOAD_STABLE_READ_ATTEMPTS; attempt += 1) {
-            const preSig = statSignature(path);
-            data = JSON.parse(readFileSync(path, 'utf8'));
-            const postSig = statSignature(path);
-            if (preSig !== null && preSig === postSig) {
-                signature = postSig;
-                break;
+        for (let attempt = 0; attempt < 3; attempt += 1) {
+            const stored = await this.backend.readDocument(sid);
+            if (!stored)
+                return null;
+            const data = sanitizeSessionRow(stored.doc, this, sid);
+            if (data?.session_id !== sid)
+                return null;
+            const messages = await this.readMessages(sid, { start: 0, end: Infinity });
+            if (stored.revision === null || stored.revision !== await this.revision(sid))
+                continue;
+            const [rows, collapsed] = collapseAdjacentDuplicatePartials(messages);
+            data.messages = rows;
+            const session = (await this.construct(data, data.profile ?? null));
+            session.sidecarLoadedSignature = stored.revision;
+            this.persistedMessages.set(session, messages.map((row) => JSON.stringify(row)));
+            if (collapsed && (opts.repairDuplicates ?? true)) {
+                try {
+                    await this.save(session, { touchUpdatedAt: false, skipIndex: true });
+                }
+                catch { /* best effort */ }
             }
-        }
-        const clean = sanitizeSessionRow(data, this, basename(path));
-        if (!clean)
-            return null;
-        data = clean;
-        const [messages, collapsed] = collapseAdjacentDuplicatePartials(data.messages);
-        data.messages = messages;
-        const session = this.construct(data, data.profile ?? null);
-        if (collapsed) {
             try {
-                this.save(session, { touchUpdatedAt: false, skipIndex: true });
+                if (opts.drafts ?? true)
+                    session.composer_draft = (await this.deps.drafts.read(sid, session.composer_draft));
             }
-            catch { /* best effort */ }
-        }
-        else {
-            session.sidecarLoadedSignature = signature;
-        }
-        try {
-            session.composer_draft = this.deps.drafts.read(sid, session.composer_draft);
+            catch { /* ignore */ }
+            return session;
         }
-        catch { /* ignore */ }
-        return session;
+        throw new RevisionConflict(sid);
     }
-    loadMetadataOnly(sid, opts = {}) {
+    async loadMetadataOnly(sid, opts = {}) {
         if (!isSafeSessionId(sid))
             return null;
-        const path = this.pathFor(sid);
-        if (!existsSync(path))
-            return null;
         try {
-            const { prefix, signature } = readMetadataJsonPrefixWithSignature(path);
-            if (!prefix)
-                return this.load(sid);
-            const parsed = sanitizeSessionRow(JSON.parse(prefix), this, basename(path));
-            if (!parsed)
+            const stored = await this.backend.readDocument(sid, { metadataOnly: true });
+            if (!stored)
+                return null;
+            if (!stored.metadataOnly)
+                return (await this.load(sid));
+            const parsed = sanitizeSessionRow(stored.doc, this, sid);
+            if (parsed?.session_id !== sid)
                 return null;
-            for (const key of ['session_id', 'title', 'created_at', 'updated_at'])
-                if (!(key in parsed))
-                    return this.load(sid);
-            const sidecarCount = parsed.message_count;
-            const modernCount = typeof sidecarCount === 'number' && Number.isInteger(sidecarCount) && sidecarCount >= 0 ? sidecarCount : null;
-            if (modernCount === null && !('anchor_scene_index' in parsed))
-                return this.load(sid);
             parsed.messages = [];
             parsed.tool_calls = [];
-            const session = this.construct(parsed, parsed.profile ?? null);
-            let indexCount = null;
-            if (modernCount === null)
-                indexCount = (opts.indexMessageCounts ?? this.indexMessageCounts()).get(sid) ?? null;
-            const known = [indexCount, modernCount].filter((c) => c !== null);
-            session.metadataMessageCount = known.length ? Math.max(...known) : null;
+            const session = (await this.construct(parsed, parsed.profile ?? null));
+            session.metadataMessageCount = stored.messageCount ?? (opts.indexMessageCounts ?? await this.indexMessageCounts()).get(sid) ?? null;
             session.loadedMetadataOnly = true;
-            session.sidecarLoadedSignature = signature;
+            session.sidecarLoadedSignature = stored.revision;
             return session;
         }
         catch {
-            return this.load(sid);
+            return (await this.load(sid));
         }
     }
-    /** Resolve a session through the cache with disk-freshness checks (Python `get_session`). Throws `SessionNotFound`. */
     get(sid, opts = {}) {
+        return this.serializeSession(sid, () => this.getNow(sid, opts), this.resolutions);
+    }
+    async getNow(sid, opts) {
+        // A local commit updates the resident revision before a reader can mistake it for an external edit.
+        await this.writes.get(sid)?.catch(() => { });
         const cached = this.sessions.get(sid);
         if (cached) {
             if (cached.session_id !== sid) {
@@ -349,15 +191,13 @@ export class SessionStore {
                     this.sessions.delete(sid);
                     this.sessions.set(sid, cached);
                 }
-                const lags = this.cachedLagsDisk(cached);
-                // A persisted session whose file vanished was deleted underneath us: evict it so nothing recreates the sidecar.
-                if (lags && !existsSync(this.pathFor(sid))) {
+                const lags = await this.cachedLagsStorage(cached);
+                if (lags && !await this.exists(sid)) {
                     this.sessions.delete(sid);
                     throw new SessionNotFound(sid);
                 }
-                // A sidebar-only stub (metadata load) must be upgraded to the full transcript when messages are requested.
                 if (!opts.metadataOnly && (cached.loadedMetadataOnly || lags)) {
-                    const fresh = this.load(sid);
+                    const fresh = await this.load(sid);
                     if (fresh) {
                         this.sessions.set(sid, fresh);
                         return fresh;
@@ -366,381 +206,263 @@ export class SessionStore {
                 return cached;
             }
         }
-        const loaded = opts.metadataOnly ? this.loadMetadataOnly(sid) : this.load(sid);
+        const loaded = opts.metadataOnly ? await this.loadMetadataOnly(sid) : await this.load(sid);
         if (!loaded)
             throw new SessionNotFound(sid);
         if (opts.cacheOnMiss ?? true)
-            this.touch(loaded);
+            await this.touch(loaded);
         return loaded;
     }
-    /** Reload a metadata-only stub before mutating persisted fields (Python `_ensure_full_session_before_mutation`). */
-    ensureFull(sid, session) {
+    async ensureFull(sid, session) {
         if (!session.loadedMetadataOnly)
             return session;
-        const full = this.load(sid);
+        const full = await this.load(sid);
         if (!full)
             throw new SessionNotFound(sid);
-        this.touch(full);
+        await this.touch(full);
         return full;
     }
-    /** A cached full session is stale when its sidecar changed on disk and it carries no unsaved runtime state. */
-    cachedLagsDisk(cached) {
+    async cachedLagsStorage(cached) {
         if (cached.active_stream_id || cached.pending_user_message || cached.pending_started_at)
             return false;
-        const current = statSignature(this.pathFor(cached.session_id));
-        // A session that was persisted and whose file has since vanished was deleted underneath us: it is stale, and the
-        // reload's miss evicts it rather than letting a later mutation recreate the deleted sidecar.
-        if (current === null)
-            return cached.sidecarLoadedSignature !== null;
-        // An unknown read identity (the file changed underneath the load) must not be trusted: reload it.
-        if (cached.sidecarLoadedSignature === null)
-            return true;
-        return current !== cached.sidecarLoadedSignature;
+        return await this.revision(cached.session_id) !== cached.sidecarLoadedSignature;
     }
-    // ── persistence ──────────────────────────────────────────────────────────
     save(session, opts = {}) {
-        if (!isSafeSessionId(session.session_id))
-            throw new Error(`Unsafe session_id ${JSON.stringify(session.session_id)}; refusing to write outside session store`);
-        if (session.loadedMetadataOnly) {
-            throw new Error(`Refusing to save metadata-only session ${JSON.stringify(session.session_id)}: would atomically overwrite on-disk messages with []. Reload with metadata_only=False before mutating state. See #1558.`);
-        }
-        // TAL-493: a save carries a current state.db marker forward and never revives a stale one (an older release's save
-        // moved `updated_at` past its stamp); only a fresh marker is made current.
+        return this.serializeSession(session.session_id, () => this.saveNow(session, opts));
+    }
+    serializeSession(sid, fn, queue = this.writes) {
+        const result = (queue.get(sid) ?? Promise.resolve()).then(fn);
+        const settled = result.then(() => { }, () => { });
+        queue.set(sid, settled);
+        return result.finally(() => { if (queue.get(sid) === settled)
+            queue.delete(sid); });
+    }
+    async saveNow(session, opts) {
+        const sid = session.session_id;
+        if (!isSafeSessionId(sid))
+            throw new Error(`Unsafe session_id ${JSON.stringify(sid)}; refusing to write outside session store`);
+        if (session.loadedMetadataOnly)
+            throw new Error(`Refusing to save metadata-only session ${JSON.stringify(sid)}: would overwrite messages with []. Reload before mutating state.`);
         const markerCurrent = session.state_db_seen_stamp === session.updated_at;
         if (opts.touchUpdatedAt ?? true)
             session.updated_at = this.deps.now();
         if (markerCurrent)
             session.state_db_seen_stamp = session.updated_at;
-        const payload = JSON.stringify(session.toDocument(), null, 2);
-        const path = session.path = this.pathFor(session.session_id);
-        mkdirSync(this.sessionDir, { recursive: true });
-        try {
-            if (existsSync(path)) {
-                const incoming = session.messages.length;
-                let existingCount = readPersistedMessageCount(path);
-                let existingText = null;
-                if (existingCount === null) {
-                    existingText = readFileSync(path, 'utf8');
-                    try {
-                        const existing = JSON.parse(existingText);
-                        existingCount = Array.isArray(existing.messages) ? existing.messages.length : 0;
-                    }
-                    catch {
-                        existingCount = -1;
-                    }
-                }
-                if (existingCount > 0 && incoming === 0 && (session.active_stream_id || session.pending_user_message)) {
-                    this.deps.log(`[webui] WARNING: refusing to overwrite session ${session.session_id} messages with empty active/pending snapshot (existing=${existingCount}, incoming=${incoming}, stream=${session.active_stream_id ?? ''})`);
-                    return;
-                }
-                if (existingCount > incoming) {
-                    existingText ??= readFileSync(path, 'utf8');
-                    try {
-                        writeAtomic(`${path}.bak`, existingText);
-                    }
-                    catch { /* backup is best effort */ }
-                }
+        session.messages = withBackgroundDisplayKinds(session.messages, session);
+        const prefix = session.prefixIndex;
+        let appendOnly = Boolean(prefix && session.messages.length >= prefix.length && prefix.generation === markedStateDbGeneration(session) && prefix.matchesToolCalls(session.tool_calls));
+        const payload = JSON.stringify(session.toDocument(), function (key, value) {
+            if (appendOnly && this === session.messages && Number(key) < prefix.length && !prefix.matchesRow(Number(key), value))
+                appendOnly = false;
+            return value;
+        });
+        const doc = JSON.parse(payload);
+        const rows = doc.messages;
+        delete doc.messages;
+        const snapshot = rows.map((row) => JSON.stringify(row));
+        const indexEntry = session.compact();
+        const previous = this.persistedMessages.get(session);
+        let messages = { kind: 'replace', rows };
+        if (previous) {
+            let from = 0;
+            while (from < previous.length && from < snapshot.length && previous[from] === snapshot[from])
+                from += 1;
+            if (from === previous.length)
+                messages = from === snapshot.length ? { kind: 'unchanged' } : { kind: 'append', rows: rows.slice(from) };
+            else if (snapshot.length >= previous.length) {
+                let tail = 0;
+                while (tail < previous.length - from && tail < snapshot.length - from && previous[previous.length - 1 - tail] === snapshot[snapshot.length - 1 - tail])
+                    tail += 1;
+                messages = { kind: 'splice', from, deleteCount: previous.length - from - tail, rows: rows.slice(from, rows.length - tail) };
             }
         }
-        catch { /* stat failures never block the save */ }
-        writeAtomic(path, payload);
-        session.sidecarLoadedSignature = statSignature(path);
-        this.invalidatePersistedIds();
-        if (!(opts.skipIndex ?? false))
-            this.queueIndexUpdate([session]);
-        if (session.messages.length)
-            this.clearDeletedTombstone(session.session_id);
-    }
-    // ── index ────────────────────────────────────────────────────────────────
-    cleanupStaleTmpFiles() {
-        const cutoff = this.deps.now() - STALE_TMP_AGE_S;
-        try {
-            for (const name of readdirSync(this.sessionDir)) {
-                if (!name.includes('.tmp.'))
-                    continue;
-                const p = join(this.sessionDir, name);
-                try {
-                    if (statSync(p).mtimeMs / 1000 < cutoff)
-                        unlinkSync(p);
-                }
-                catch { /* best effort */ }
+        const expected = session.sidecarLoadedSignature;
+        if (!rows.length && (session.active_stream_id || session.pending_user_message)) {
+            const stored = await this.backend.readDocument(sid, { metadataOnly: true });
+            if ((stored?.messageCount ?? 0) > 0) {
+                this.deps.log(`[webui] WARNING: refusing to overwrite session ${sid} messages with empty active/pending snapshot`);
+                return;
             }
         }
-        catch { /* dir may not exist */ }
-    }
-    invalidatePersistedIds() {
-        this.persistedIdsCache = null;
-    }
-    persistedIds() {
-        let mtimeNs = null;
         try {
-            mtimeNs = statSync(this.sessionDir, { bigint: true }).mtimeNs;
+            session.sidecarLoadedSignature = await this.backend.write(sid, { doc, messages }, expected);
         }
-        catch {
-            mtimeNs = null;
-        }
-        if (this.persistedIdsCache?.mtimeNs === mtimeNs && mtimeNs !== null)
-            return this.persistedIdsCache.ids;
-        const ids = new Set();
-        try {
-            for (const name of readdirSync(this.sessionDir))
-                if (name.endsWith('.json') && !name.startsWith('_'))
-                    ids.add(name.slice(0, -5));
+        catch (error) {
+            if (error instanceof RevisionConflict) {
+                this.sessions.delete(sid);
+                const fresh = await this.load(sid, { repairDuplicates: false });
+                if (fresh)
+                    this.sessions.set(sid, fresh);
+            }
+            throw error;
         }
-        catch { /* empty */ }
-        this.persistedIdsCache = { mtimeNs, ids };
-        return ids;
-    }
-    hasPersistedSessionFiles() {
-        return this.persistedIds().size > 0;
-    }
-    indexSignature() {
-        return statSignature(this.indexFile);
-    }
-    /** Parsed `_index.json` rows via the stat-validated cache; throws on a corrupt index. */
-    readIndexEntries() {
-        const signature = this.indexSignature();
-        if (this.parsedIndexCache && signature !== null && this.parsedIndexCache.signature === signature)
-            return [...this.parsedIndexCache.entries];
-        const entries = JSON.parse(readFileSync(this.indexFile, 'utf8'));
-        if (!Array.isArray(entries))
-            throw new Error('session index must be a list');
-        if (signature !== null && signature === this.indexSignature())
-            this.parsedIndexCache = { signature, entries: entries };
-        return [...entries];
-    }
-    indexMessageCounts(entries) {
-        const out = new Map();
+        this.persistedMessages.set(session, snapshot);
+        if (appendOnly)
+            prefix.savedAppend(rows, session.sidecarLoadedSignature);
+        else
+            delete session.prefixIndex;
+        if (!(opts.skipIndex ?? false))
+            await this.queueIndexUpdate([indexEntry]);
+        if (rows.length)
+            await this.clearDeletedTombstone(sid);
+    }
+    async searchMessages(sids, terms, depth) {
+        const matches = new Map();
+        const remaining = [];
+        for (const sid of sids) {
+            const cached = this.sessions.get(sid);
+            if (!cached || cached.loadedMetadataOnly || await this.cachedLagsStorage(cached)) {
+                remaining.push(sid);
+                continue;
+            }
+            const rows = depth ? cached.messages.slice(0, depth) : cached.messages;
+            const idx = rows.findIndex((row) => sessionSearchMatches(sessionSearchMessageText(row), terms));
+            if (idx >= 0)
+                matches.set(sid, { idx, text: sessionSearchMessageText(rows[idx]) });
+        }
+        for (const [sid, match] of await this.backend.searchMessages(remaining, terms, depth))
+            matches.set(sid, match);
+        return matches;
+    }
+    async persistedIds() { return this.backend.ids(); }
+    async hasPersistedSessionFiles() { return (await this.persistedIds()).size > 0; }
+    async readIndexEntries() { return (await this.backend.index()).entries; }
+    async indexMessageCounts(entries) {
         let rows = entries;
         if (!rows) {
             try {
-                rows = existsSync(this.indexFile) ? this.readIndexEntries() : [];
+                rows = await this.readIndexEntries();
             }
             catch {
                 rows = [];
             }
         }
+        const out = new Map();
         for (const row of rows) {
-            const sid = str(row.session_id);
-            const n = Number(row.message_count);
+            const sid = str(row.session_id), n = Number(row.message_count);
             if (sid && Number.isInteger(n) && n >= 0)
                 out.set(sid, n);
         }
         return out;
     }
-    writeIndexPayload(entries) {
-        writeAtomic(this.indexFile, JSON.stringify(entries));
-        const signature = this.indexSignature();
-        if (signature !== null)
-            this.parsedIndexCache = { signature, entries };
-    }
-    loadSessionFromPath(path) {
-        try {
-            const data = sanitizeSessionRow(JSON.parse(readFileSync(path, 'utf8')), this, basename(path));
-            if (!data)
-                return null;
-            const [messages] = collapseAdjacentDuplicatePartials(data.messages);
-            data.messages = messages;
-            return this.construct(data, data.profile ?? null);
-        }
-        catch {
-            return null;
-        }
+    async serializeIndex(fn) {
+        const pending = this.indexWriter.then(fn, fn);
+        this.indexWriter = pending.catch(() => { });
+        return pending;
     }
-    /**
-     * Rebuild `_index.json` from scratch. Resident sessions without a sidecar join it unless `diskOnly` (TAL-259: a recovery
-     * rebuild lists only persisted sessions, so an unsaved shell never reads as index drift).
-     */
-    rebuildIndex(opts = {}) {
-        mkdirSync(this.sessionDir, { recursive: true });
-        this.cleanupStaleTmpFiles();
-        const entryMap = new Map();
-        for (const name of readdirSync(this.sessionDir)) {
-            if (!name.endsWith('.json') || name.startsWith('_'))
-                continue;
-            const s = this.loadSessionFromPath(join(this.sessionDir, name));
-            if (!s)
-                continue;
-            const c = s.compact();
-            const sid = str(c.session_id);
-            if (!sid)
-                continue;
-            const existing = entryMap.get(sid);
-            if (!existing || Number(c.message_count ?? 0) > Number(existing.message_count ?? 0))
-                entryMap.set(sid, c);
+    async rebuildIndexNow(opts = {}) {
+        const map = new Map();
+        for (const sid of await this.persistedIds()) {
+            try {
+                const session = await this.load(sid, { drafts: false, repairDuplicates: false });
+                if (session)
+                    map.set(session.session_id, session.compact());
+            }
+            catch { /* corrupt sessions are omitted */ }
         }
-        const entries = [...entryMap.values()];
         if (!opts.diskOnly)
             for (const s of this.sessions.values())
-                if (!entryMap.has(s.session_id))
-                    entries.push(s.compact());
-        entries.sort((a, b) => Number(b.updated_at ?? 0) - Number(a.updated_at ?? 0));
-        this.writeIndexPayload(entries);
-    }
-    /** Rebuild or patch `_index.json` (Python `_write_session_index`). */
-    writeIndex(updates) {
-        mkdirSync(this.sessionDir, { recursive: true });
-        if (!updates || !existsSync(this.indexFile)) {
-            this.rebuildIndex();
-            return;
-        }
-        try {
-            const onDisk = this.persistedIds();
-            let existing = this.readIndexEntries();
-            const inMemory = new Set(this.sessions.keys());
-            const updatedMap = new Map();
-            for (const update of updates) {
-                if (update instanceof Session)
-                    updatedMap.set(update.session_id, update.compact());
-                else if (typeof update.session_id === 'string' && update.session_id)
-                    updatedMap.set(update.session_id, update);
+                if (!map.has(s.session_id))
+                    map.set(s.session_id, s.compact());
+        await this.backend.writeIndex([...map.values()].sort((a, b) => Number(b.updated_at ?? 0) - Number(a.updated_at ?? 0)));
+    }
+    async rebuildIndex(opts = {}) { await this.serializeIndex(async () => { await this.rebuildIndexNow(opts); }); }
+    async writeIndex(updates) {
+        const snapshots = updates?.map((s) => s instanceof Session ? s.compact() : s);
+        await this.serializeIndex(async () => {
+            if (!snapshots || !await this.backend.hasIndex()) {
+                await this.rebuildIndexNow();
+                return;
             }
-            const filtered = existing.filter((e) => inMemory.has(String(e.session_id)) || onDisk.has(String(e.session_id)));
-            let changed = filtered.length !== existing.length;
-            existing = filtered;
-            const positions = new Map(existing.map((e, i) => [String(e.session_id), i]));
-            for (const [sid, entry] of updatedMap) {
-                const position = positions.get(sid);
-                if (position === undefined) {
-                    existing.push(entry);
-                    positions.set(sid, existing.length - 1);
-                    changed = true;
-                }
-                else if (JSON.stringify(existing[position]) !== JSON.stringify(entry)) {
-                    existing[position] = entry;
-                    changed = true;
-                }
+            let rows;
+            try {
+                rows = await this.readIndexEntries();
             }
-            const oldOrder = existing.map((e) => e.session_id).join('\u0000');
-            existing.sort((a, b) => Number(b.updated_at ?? 0) - Number(a.updated_at ?? 0));
-            if (oldOrder !== existing.map((e) => e.session_id).join('\u0000'))
-                changed = true;
-            if (!changed)
+            catch {
+                await this.rebuildIndexNow();
                 return;
-            this.writeIndexPayload(existing);
-        }
-        catch {
-            this.writeIndex();
+            }
+            const previous = JSON.stringify(rows);
+            const ids = await this.persistedIds();
+            rows = rows.filter((r) => ids.has(str(r.session_id)) || this.sessions.has(str(r.session_id)));
+            const positions = new Map(rows.map((r, i) => [str(r.session_id), i]));
+            for (const row of snapshots) {
+                const sid = str(row.session_id);
+                if (!sid)
+                    continue;
+                const i = positions.get(sid);
+                if (i === undefined) {
+                    positions.set(sid, rows.length);
+                    rows.push(row);
+                }
+                else
+                    rows[i] = row;
+            }
+            rows.sort((a, b) => Number(b.updated_at ?? 0) - Number(a.updated_at ?? 0));
+            if (JSON.stringify(rows) !== previous)
+                await this.backend.writeIndex(rows);
+        });
+    }
+    queueIndexUpdate(updates) {
+        for (const update of updates) {
+            const row = update instanceof Session ? update.compact() : update;
+            const sid = str(row.session_id);
+            if (sid)
+                this.indexPending.set(sid, row);
         }
+        this.indexFlush ??= Promise.resolve().then(async () => {
+            try {
+                while (this.indexPending.size) {
+                    const rows = [...this.indexPending.values()];
+                    this.indexPending.clear();
+                    await this.writeIndex(rows);
+                }
+            }
+            finally {
+                this.indexFlush = null;
+            }
+        });
+        return this.indexFlush;
     }
-    /** Coalesce index rewrites from concurrent saves (Python `_queue_session_index_update`). */
-    queueIndexUpdate(sessions) {
-        for (const s of sessions)
-            this.indexPending.set(s.session_id, s.compact());
-        this.flushIndexNow();
-    }
-    flushIndexNow() {
-        const pending = [...this.indexPending.values()];
-        this.indexPending.clear();
-        if (pending.length)
-            this.writeIndex(pending);
-    }
-    pruneFromIndex(sid) {
-        if (!sid || !existsSync(this.indexFile))
-            return;
-        try {
-            const existing = JSON.parse(readFileSync(this.indexFile, 'utf8'));
-            if (!Array.isArray(existing))
-                throw new Error('session index must be a list');
-            const pruned = existing.filter((e) => e.session_id !== sid);
-            if (pruned.length === existing.length)
+    async pruneFromIndex(sid) {
+        await this.serializeIndex(async () => {
+            if (!sid || !await this.backend.hasIndex())
                 return;
-            this.writeIndexPayload(pruned);
-        }
-        catch {
-            this.writeIndex();
-        }
-    }
-    // ── tombstones ───────────────────────────────────────────────────────────
-    get deletedTombstoneFile() {
-        return join(this.sessionDir, '_deleted_webui_sessions.json');
-    }
-    loadDeletedTombstone() {
-        try {
-            if (!existsSync(this.deletedTombstoneFile))
-                return new Set();
-            const raw = JSON.parse(readFileSync(this.deletedTombstoneFile, 'utf8'));
-            if (!raw || typeof raw !== 'object' || Number(raw.version) !== DELETED_TOMBSTONE_VERSION || !Array.isArray(raw.ids))
-                return new Set();
-            return new Set(raw.ids.map((v) => String(v ?? '').trim()).filter(Boolean));
-        }
-        catch {
-            return new Set();
-        }
-    }
-    saveDeletedTombstone(ids) {
-        let sorted = [...ids].sort();
-        if (sorted.length > DELETED_TOMBSTONE_CAP)
-            sorted = sorted.slice(-DELETED_TOMBSTONE_CAP);
-        try {
-            mkdirSync(this.sessionDir, { recursive: true });
-            writeAtomic(this.deletedTombstoneFile, JSON.stringify({ version: DELETED_TOMBSTONE_VERSION, ids: sorted }, null, 2));
-        }
-        catch { /* best effort */ }
-    }
-    recordDeletedTombstone(sid) {
-        const ids = this.loadDeletedTombstone();
-        if (ids.has(sid))
-            return;
-        ids.add(sid);
-        this.saveDeletedTombstone(ids);
-    }
-    clearDeletedTombstone(sid) {
-        const ids = this.loadDeletedTombstone();
-        if (!ids.has(sid))
-            return;
-        ids.delete(sid);
-        if (ids.size)
-            this.saveDeletedTombstone(ids);
-        else
-            rmSync(this.deletedTombstoneFile, { force: true });
-    }
-    /** The index marked this id as a deleted WebUI session (Python `_marks_deleted_webui_session`, tombstone half). */
-    wasDeleted(sid) {
-        return this.loadDeletedTombstone().has(sid);
-    }
-    // ── eviction ─────────────────────────────────────────────────────────────
-    persistedMessageCount(sid) {
-        const path = this.pathFor(sid);
-        if (!existsSync(path))
-            return null;
-        const count = readPersistedMessageCount(path);
-        if (count !== null)
-            return count;
-        try {
-            const data = JSON.parse(readFileSync(path, 'utf8'));
-            return Array.isArray(data.messages) ? data.messages.length : 0;
-        }
-        catch {
-            return null;
-        }
+            try {
+                const rows = await this.readIndexEntries();
+                const pruned = rows.filter((r) => r.session_id !== sid);
+                if (pruned.length !== rows.length)
+                    await this.backend.writeIndex(pruned);
+            }
+            catch {
+                await this.rebuildIndexNow();
+            }
+        });
     }
-    /** Python `_session_is_evictable`: never drop active, pending, or unsaved sessions. */
-    isEvictable(s) {
+    async loadDeletedTombstone() { return this.backend.tombstones.all(); }
+    async recordDeletedTombstone(sid) { return this.backend.tombstones.add(sid); }
+    async clearDeletedTombstone(sid) { return this.backend.tombstones.remove(sid); }
+    async wasDeleted(sid) { return this.backend.tombstones.has(sid); }
+    async isEvictable(s) {
         if (!s)
             return true;
-        if (s.active_stream_id || s.pending_user_message || s.pending_started_at)
-            return false;
-        if (!s.session_id)
+        if (s.active_stream_id || s.pending_user_message || s.pending_started_at || !s.session_id)
             return false;
         if (s.loadedMetadataOnly)
             return true;
-        const inMemory = s.messages.length;
-        const diskCount = this.persistedMessageCount(s.session_id);
-        if (diskCount === null) {
-            if (inMemory > 0)
-                return false;
-            if (Object.keys(s.composer_draft).length)
-                return false;
-            if (existsSync(this.pathFor(s.session_id)))
+        let count = null;
+        try {
+            count = (await this.backend.readDocument(s.session_id, { metadataOnly: true }))?.messageCount ?? null;
+        }
+        catch { /* corrupt */ }
+        if (count === null) {
+            if (s.messages.length || Object.keys(s.composer_draft).length || await this.exists(s.session_id))
                 return false;
             return this.deps.now() - s.created_at > UNSAVED_SHELL_GRACE_S;
         }
-        if (inMemory === 0)
-            return true;
-        return diskCount >= inMemory;
+        return count >= s.messages.length;
     }
-    evictOverCap(cap) {
+    async evictOverCap(cap) {
         let limit = cap ?? this.deps.cacheMax();
         if (!Number.isInteger(limit) || limit < 1)
             limit = 100;
@@ -748,63 +470,35 @@ export class SessionStore {
         for (const sid of [...this.sessions.keys()]) {
             if (this.sessions.size <= limit)
                 break;
-            if (this.isEvictable(this.sessions.get(sid))) {
+            const session = this.sessions.get(sid);
+            if (await this.isEvictable(session) && this.sessions.get(sid) === session && !session?.active_stream_id && !session?.pending_user_message && !session?.pending_started_at) {
                 this.sessions.delete(sid);
                 evicted += 1;
             }
         }
         return evicted;
     }
-    // ── deletion ─────────────────────────────────────────────────────────────
-    /** Remove the sidecar, backup, draft, index row, and tombstone the id. Returns false when the sidecar survived. */
-    deleteFiles(sid, opts = {}) {
-        const path = this.pathFor(sid);
-        try {
-            rmSync(path, { force: true });
-        }
-        catch {
-            return false;
-        }
-        if (existsSync(path))
-            return false;
-        this.sessions.delete(sid);
-        this.invalidatePersistedIds();
-        try {
-            this.pruneFromIndex(sid);
-        }
-        catch { /* ignore */ }
-        try {
-            rmSync(`${path}.bak`, { force: true });
-        }
-        catch { /* ignore */ }
-        try {
-            this.deps.drafts.delete(sid);
-        }
-        catch { /* ignore */ }
-        // TAL-372: the session's background work records (`BackgroundTaskStore`) go with it.
-        try {
-            rmSync(join(this.sessionDir, '_background', `${sid}.json`), { force: true });
-        }
-        catch { /* ignore */ }
-        this.deps.onDeleted?.(sid);
-        if (opts.tombstone ?? true)
-            this.recordDeletedTombstone(sid);
-        return true;
+    delete(sid, opts = {}) {
+        return this.serializeSession(sid, async () => {
+            if (!await this.backend.delete(sid, { tombstone: opts.tombstone ?? true }))
+                return false;
+            this.sessions.delete(sid);
+            try {
+                await this.pruneFromIndex(sid);
+            }
+            catch { /* ignore */ }
+            try {
+                (await this.deps.drafts.delete(sid));
+            }
+            catch { /* ignore */ }
+            await this.deps.onDeleted?.(sid);
+            return true;
+        });
     }
-    /** Every persisted session as a fresh full load (Python full-scan paths). */
-    scanAll() {
+    async scanAll() {
         const out = [];
-        let names = [];
-        try {
-            names = readdirSync(this.sessionDir);
-        }
-        catch {
-            return out;
-        }
-        for (const name of names) {
-            if (!name.endsWith('.json') || name.startsWith('_'))
-                continue;
-            const s = this.load(name.slice(0, -5));
+        for (const sid of await this.persistedIds()) {
+            const s = await this.load(sid);
             if (s)
                 out.push(s);
         }