@xrkseek/harness 0.6.23 → 0.7.0-rc.2

package/node_modules/@xrkseek/core-session/dist/sqlite-store.js

@@ -1,8 +1,8 @@
 import { mkdirSync, statSync } from "node:fs";
 import path from "node:path";
-import { assertSessionEvent } from "@xrkseek/protocol";
+import { assertSessionEvent, SessionEventParseError, } from "@xrkseek/protocol";
 import { expandPackedStorageRecords, isPackedChunkRow, isTextChunkRow, isToolCallChunkRow, packChunkRunsForExport, } from "./chunk-pack.js";
-import { deepFreeze, newSessionId } from "./freeze.js";
+import { freezeSessionEvent, newSessionId } from "./freeze.js";
 import { repairOpenTurnEvents, sessionHasOpenTurn, } from "./repair-open-turn.js";
 import { extractEventSearchText } from "./search-text.js";
 import { snapshotEvents } from "./seq.js";
@@ -21,6 +21,11 @@ const ID_RE = /^[A-Za-z0-9._-]+$/;
 const DEBUG_WAL_CHECKPOINT = Boolean(process.env.XRK_DEBUG_WAL);
 /** Physical schema v3: durable rows may be packed chunk rows (expanded on load). */
 const SCHEMA_VERSION = SQLITE_SCHEMA_CURRENT;
+/**
+ * Consecutive searches that had to fall back because the FTS index could not
+ * be read. Only used to throttle the diagnostic line.
+ */
+let searchIndexFailures = 0;
 const DB_NAME = "sessions.db";
 /** Cold sibling of {@link DB_NAME}: archived session logs live here. */
 const ARCHIVE_DB_NAME = "sessions-archive.db";
@@ -40,6 +45,31 @@ function deleteSessionRows(db, id) {
     db.prepare("DELETE FROM events WHERE session_id = ?").run(id);
     db.prepare("DELETE FROM sessions WHERE id = ?").run(id);
 }
+/**
+ * Run `fn` inside one `BEGIN IMMEDIATE … COMMIT`, rolling back on throw.
+ *
+ * The three deletes above are a single logical removal: they used to autocommit
+ * one by one, so a crash (or a locked FTS index) between them left "skull" rows
+ * — `events` gone while `search_fts` still matched, so search returned a
+ * sessionId that `has()` reports as missing. Callers that already hold a
+ * transaction (`copySessionRows`) must not wrap again.
+ */
+function withImmediate(db, run) {
+    db.exec("BEGIN IMMEDIATE");
+    try {
+        run();
+        db.exec("COMMIT");
+    }
+    catch (err) {
+        try {
+            db.exec("ROLLBACK");
+        }
+        catch {
+            /* already rolled back / connection gone */
+        }
+        throw err;
+    }
+}
 /** Copy one session's sessions/events/FTS rows from `from` into `to` (replace). */
 function copySessionRows(from, to, id) {
     const eventRows = from
@@ -48,10 +78,23 @@ function copySessionRows(from, to, id) {
     const ftsRows = from
         .prepare("SELECT seq, text FROM search_fts WHERE session_id = ?")
         .all(id);
+    // Hints travel with the rows. Inserting a bare `id` left every archived or
+    // restored session at event_count/last_ts 0 forever (the backfill only runs
+    // on a schema bump), which made `session.list` fall back to a full event scan
+    // and reported the session as blank. A missing row stays 0 on purpose: the
+    // hint reader treats <= 0 as "unknown" and rescans correctly.
+    const hints = from
+        .prepare("SELECT last_ts, event_count, has_turn_start, has_command_run FROM sessions WHERE id = ?")
+        .get(id);
     to.exec("BEGIN IMMEDIATE");
     try {
         deleteSessionRows(to, id);
-        to.prepare("INSERT INTO sessions (id) VALUES (?)").run(id);
+        to.prepare("INSERT INTO sessions (id, last_ts, event_count, has_turn_start, has_command_run) VALUES (?, ?, ?, ?, ?)").run(id, hints?.last_ts ?? 0, hints?.event_count ?? 0, hints?.has_turn_start ?? 0, hints?.has_command_run ?? 0);
+        // One prepared statement reused per row beats chunked multi-value INSERTs
+        // here: measured on an 18,370-row / 45.8 MB session, batching made
+        // offload/restore ~25% *slower* (2,744 / 2,726 ms vs 2,197 / 2,116 ms),
+        // because every chunk needs a fresh `prepare` and SQLite's per-row path
+        // already reuses the compiled statement.
         const insertEvent = to.prepare("INSERT INTO events (session_id, seq, ts, payload) VALUES (?, ?, ?, ?)");
         for (const row of eventRows) {
             insertEvent.run(id, row.seq, row.ts, row.payload);
@@ -132,6 +175,19 @@ export function ftsMatchQuery(query) {
         return '""';
     return `"${trimmed.replace(/"/g, '""')}"`;
 }
+export function planFtsQuery(query) {
+    const trimmed = query.trim();
+    if (!trimmed)
+        return null;
+    // Code points, not UTF-16 units: the tokenizer counts characters.
+    if ([...trimmed].length >= 3) {
+        return { kind: "match", value: ftsMatchQuery(trimmed) };
+    }
+    return {
+        kind: "like",
+        value: `%${trimmed.replace(/[\\%_]/g, (c) => `\\${c}`)}%`,
+    };
+}
 /**
  * Join text chunks so a token split across indexes stays searchable after flush.
  * `prefix` is the nearest earlier text chunk before this batch (flush boundary).
@@ -180,13 +236,13 @@ function storageTs(record) {
     return isPackedChunkRow(record) ? record.ts0 : record.ts;
 }
 function ensureFts(db) {
-    db.exec(`
-    CREATE VIRTUAL TABLE IF NOT EXISTS search_fts USING fts5(
-      session_id UNINDEXED,
-      seq UNINDEXED,
-      text,
-      tokenize = 'trigram'
-    );
+    db.exec(`
+    CREATE VIRTUAL TABLE IF NOT EXISTS search_fts USING fts5(
+      session_id UNINDEXED,
+      seq UNINDEXED,
+      text,
+      tokenize = 'trigram'
+    );
   `);
 }
 function schemaVersion(db) {
@@ -234,24 +290,24 @@ function addSessionHintColumns(db) {
 function backfillSessionHints(db) {
     db.exec("INSERT OR IGNORE INTO sessions (id) SELECT DISTINCT session_id FROM events");
     db.exec("DROP TABLE IF EXISTS temp._session_hint_agg");
-    db.exec(`
-    CREATE TEMP TABLE _session_hint_agg AS
-    SELECT session_id,
-           MAX(ts) AS last_ts,
-           COUNT(*) AS event_count,
-           MAX(CASE WHEN json_extract(payload, '$.type') = 'turn/start' THEN 1 ELSE 0 END) AS has_turn_start,
-           MAX(CASE WHEN json_extract(payload, '$.type') = 'command/run' THEN 1 ELSE 0 END) AS has_command_run
-    FROM events
-    GROUP BY session_id
+    db.exec(`
+    CREATE TEMP TABLE _session_hint_agg AS
+    SELECT session_id,
+           MAX(ts) AS last_ts,
+           COUNT(*) AS event_count,
+           MAX(CASE WHEN json_extract(payload, '$.type') = 'turn/start' THEN 1 ELSE 0 END) AS has_turn_start,
+           MAX(CASE WHEN json_extract(payload, '$.type') = 'command/run' THEN 1 ELSE 0 END) AS has_command_run
+    FROM events
+    GROUP BY session_id
   `);
-    db.exec(`
-    UPDATE sessions SET
-      last_ts = a.last_ts,
-      event_count = a.event_count,
-      has_turn_start = a.has_turn_start,
-      has_command_run = a.has_command_run
-    FROM _session_hint_agg a
-    WHERE a.session_id = sessions.id
+    db.exec(`
+    UPDATE sessions SET
+      last_ts = a.last_ts,
+      event_count = a.event_count,
+      has_turn_start = a.has_turn_start,
+      has_command_run = a.has_command_run
+    FROM _session_hint_agg a
+    WHERE a.session_id = sessions.id
   `);
     db.exec("DROP TABLE temp._session_hint_agg");
 }
@@ -299,32 +355,32 @@ function initSchema(db, journalMode = "WAL") {
         db.exec("PRAGMA wal_autocheckpoint = 1000");
         db.exec("PRAGMA journal_size_limit = 67108864");
     }
-    db.exec(`
-    CREATE TABLE IF NOT EXISTS meta (
-      key TEXT PRIMARY KEY,
-      value TEXT NOT NULL
-    );
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS meta (
+      key TEXT PRIMARY KEY,
+      value TEXT NOT NULL
+    );
   `);
     const hooks = {
         ensureTables: () => {
-            db.exec(`
-        CREATE TABLE IF NOT EXISTS sessions (
-          id TEXT PRIMARY KEY,
-          last_ts INTEGER NOT NULL DEFAULT 0,
-          event_count INTEGER NOT NULL DEFAULT 0,
-          has_turn_start INTEGER NOT NULL DEFAULT 0,
-          has_command_run INTEGER NOT NULL DEFAULT 0
-        );
-        CREATE TABLE IF NOT EXISTS events (
-          session_id TEXT NOT NULL,
-          seq INTEGER NOT NULL,
-          ts INTEGER NOT NULL,
-          payload TEXT NOT NULL,
-          PRIMARY KEY (session_id, seq),
-          FOREIGN KEY (session_id) REFERENCES sessions(id)
-        );
-        CREATE INDEX IF NOT EXISTS idx_events_session_seq
-          ON events (session_id, seq);
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS sessions (
+          id TEXT PRIMARY KEY,
+          last_ts INTEGER NOT NULL DEFAULT 0,
+          event_count INTEGER NOT NULL DEFAULT 0,
+          has_turn_start INTEGER NOT NULL DEFAULT 0,
+          has_command_run INTEGER NOT NULL DEFAULT 0
+        );
+        CREATE TABLE IF NOT EXISTS events (
+          session_id TEXT NOT NULL,
+          seq INTEGER NOT NULL,
+          ts INTEGER NOT NULL,
+          payload TEXT NOT NULL,
+          PRIMARY KEY (session_id, seq),
+          FOREIGN KEY (session_id) REFERENCES sessions(id)
+        );
+        CREATE INDEX IF NOT EXISTS idx_events_session_seq
+          ON events (session_id, seq);
       `);
         },
         ensureSessionHints: () => {
@@ -340,6 +396,14 @@ function initSchema(db, journalMode = "WAL") {
         },
     };
     const stored = schemaVersion(db);
+    if (stored > SCHEMA_VERSION) {
+        // Direction-aware refusal. A newer build already migrated this file and may
+        // have written rows this build would misread; opening it "successfully"
+        // would rewrite that data under the old shape — silent corruption instead
+        // of a message the user can act on.
+        throw new Error(`sessions.db schema v${stored} is newer than this build (v${SCHEMA_VERSION}):`
+            + " it was written by a newer XRK Harness — upgrade instead of opening it");
+    }
     if (stored >= SCHEMA_VERSION) {
         // A current schema_version means the migration chain already built every
         // table/index/FTS object. Re-running the full DDL on every Host start takes
@@ -361,21 +425,219 @@ function parseStoragePayload(payload) {
     }
     return [assertSessionEvent(raw)];
 }
+/** True when `prefix` is `full[0..prefix.length)` (JSON-stable event equality). */
+function logicalEventsEqualPrefix(full, prefix) {
+    if (prefix.length > full.length)
+        return false;
+    for (let i = 0; i < prefix.length; i++) {
+        // Truncate / edit-resubmit usually passes a `slice` of the resident log —
+        // same object identity. JSON.stringify of 16k events was dominating the
+        // R7 fast path (~hundreds of ms) before the cheap DELETE.
+        if (full[i] === prefix[i])
+            continue;
+        if (JSON.stringify(full[i]) !== JSON.stringify(prefix[i]))
+            return false;
+    }
+    return true;
+}
+/**
+ * Map a logical keep-count onto the first *physical* `events.seq` to delete.
+ * Packed chunk rows that straddle the cut force a full rewrite.
+ *
+ * When `totalLogical` is known (resident length / healed hints), walk **DESC**
+ * and only expand the discarded suffix — edit-resubmit / truncate usually drop
+ * a few hundred events off a multi-10k log; ASC-scanning the whole prefix was
+ * the R7 fast-path bottleneck (~1–2 s).
+ */
+function physicalTailCutSeq(db, sessionId, keepLogical, totalLogical) {
+    if (keepLogical <= 0)
+        return "empty";
+    if (typeof totalLogical === "number"
+        && totalLogical >= keepLogical
+        && Number.isFinite(totalLogical)) {
+        const needDrop = totalLogical - keepLogical;
+        if (needDrop === 0)
+            return "noop";
+        const iter = db
+            .prepare("SELECT seq, payload FROM events WHERE session_id = ? ORDER BY seq DESC")
+            .iterate(sessionId);
+        let dropped = 0;
+        let sawRow = false;
+        for (const row of iter) {
+            sawRow = true;
+            let n;
+            try {
+                n = parseStoragePayload(row.payload).length;
+            }
+            catch {
+                return "rewrite";
+            }
+            if (dropped + n < needDrop) {
+                dropped += n;
+                continue;
+            }
+            if (dropped + n === needDrop) {
+                return row.seq;
+            }
+            // Packed row straddles the logical cut.
+            return "rewrite";
+        }
+        if (!sawRow)
+            return "noop";
+        return "rewrite";
+    }
+    const rows = db
+        .prepare("SELECT seq, payload FROM events WHERE session_id = ? ORDER BY seq ASC")
+        .all(sessionId);
+    if (rows.length === 0)
+        return "noop";
+    let logical = 0;
+    for (const row of rows) {
+        if (logical >= keepLogical)
+            return row.seq;
+        let n;
+        try {
+            n = parseStoragePayload(row.payload).length;
+        }
+        catch {
+            return "rewrite";
+        }
+        if (logical + n <= keepLogical) {
+            logical += n;
+            continue;
+        }
+        return "rewrite";
+    }
+    return logical === keepLogical ? "noop" : "rewrite";
+}
+/**
+ * A stored row this build cannot read: corrupt JSON, an unknown event type, or
+ * a row written by a newer format.
+ *
+ * Loading stops here instead of returning the rows that happened to work,
+ * because `ensureLoaded` feeds whatever it gets straight into crash repair: a
+ * silently truncated view makes the store append a synthetic `turn/end` into
+ * the real log, which pushes every surviving event behind a turn boundary that
+ * never existed. Refusing to load is the only failure that leaves the log
+ * intact, so the caller can tell the user to upgrade instead.
+ */
+export class SessionLogUnreadableError extends Error {
+    sessionId;
+    seq;
+    reason;
+    constructor(sessionId, 
+    /** Position of the first unreadable row. */
+    seq, reason) {
+        super(`session log unreadable: ${sessionId} seq ${seq} (${reason}) — refusing to load a partial log`);
+        this.sessionId = sessionId;
+        this.seq = seq;
+        this.reason = reason;
+        this.name = "SessionLogUnreadableError";
+    }
+}
 function loadSessionEvents(db, id) {
     const rows = db
-        .prepare("SELECT payload FROM events WHERE session_id = ? ORDER BY seq ASC")
+        .prepare("SELECT seq, payload FROM events WHERE session_id = ? ORDER BY seq ASC")
         .all(id);
     const events = [];
     for (const row of rows) {
         try {
             events.push(...parseStoragePayload(row.payload));
         }
-        catch {
-            break;
+        catch (error) {
+            // Newer Harness may write pure-info rows with `ignorable: true`. Skipping
+            // keeps the readable prefix intact; required unknowns still refuse load.
+            if (error instanceof SessionEventParseError
+                && error.code === "unknown-ignorable") {
+                continue;
+            }
+            throw new SessionLogUnreadableError(id, row.seq, error instanceof Error ? error.message : String(error));
         }
     }
     return events;
 }
+/**
+ * Expand a physical suffix until at least `maxLogical` events (or the whole log).
+ * Rows are read newest-first then reversed so the result is a chronological suffix.
+ */
+/**
+ * True when `hintedCount` is safe as a logical length for absolute seq.
+ * Packed logs with a stale physical backfill look like count === row count.
+ */
+function eventCountLooksLogical(db, id, hintedCount) {
+    const physical = db
+        .prepare("SELECT COUNT(*) AS n FROM events WHERE session_id = ?")
+        .get(id)?.n ?? 0;
+    if (hintedCount > physical)
+        return true;
+    if (hintedCount < physical)
+        return false;
+    // Equal: only safe when no packed chunk rows (1 event per physical row).
+    const packed = db
+        .prepare(`SELECT 1 AS hit FROM events WHERE session_id = ? AND (
+         json_extract(payload, '$.type') = 'text-chunks'
+         OR json_extract(payload, '$.type') = 'tool-call-chunks'
+       ) LIMIT 1`)
+        .get(id);
+    return packed === undefined;
+}
+function loadSessionEventsTail(db, id, maxLogical) {
+    if (maxLogical <= 0)
+        return [];
+    const rows = db
+        .prepare("SELECT seq, payload FROM events WHERE session_id = ? ORDER BY seq DESC")
+        .all(id);
+    const newestFirst = [];
+    let logical = 0;
+    for (const row of rows) {
+        try {
+            const expanded = parseStoragePayload(row.payload);
+            newestFirst.push(expanded);
+            logical += expanded.length;
+            if (logical >= maxLogical)
+                break;
+        }
+        catch (error) {
+            if (error instanceof SessionEventParseError
+                && error.code === "unknown-ignorable") {
+                continue;
+            }
+            throw new SessionLogUnreadableError(id, row.seq, error instanceof Error ? error.message : String(error));
+        }
+    }
+    const out = [];
+    for (let i = newestFirst.length - 1; i >= 0; i--) {
+        out.push(...newestFirst[i]);
+    }
+    return out;
+}
+/** Visit non-packed durable events in seq order (no chunk expansion). */
+function scanDurableSinglesFromDb(db, id, visit) {
+    const rows = db
+        .prepare("SELECT seq, payload FROM events WHERE session_id = ? ORDER BY seq ASC")
+        .all(id);
+    for (const row of rows) {
+        let raw;
+        try {
+            raw = JSON.parse(row.payload);
+        }
+        catch (error) {
+            throw new SessionLogUnreadableError(id, row.seq, error instanceof Error ? error.message : String(error));
+        }
+        if (isPackedChunkRow(raw))
+            continue;
+        try {
+            visit(assertSessionEvent(raw));
+        }
+        catch (error) {
+            if (error instanceof SessionEventParseError
+                && error.code === "unknown-ignorable") {
+                continue;
+            }
+            throw new SessionLogUnreadableError(id, row.seq, error instanceof Error ? error.message : String(error));
+        }
+    }
+}
 function nextSeqFromDb(db, sessionId) {
     const row = db
         .prepare("SELECT COALESCE(MAX(seq), -1) AS maxSeq FROM events WHERE session_id = ?")
@@ -384,16 +646,16 @@ function nextSeqFromDb(db, sessionId) {
 }
 function hasTurnStartInDb(db, sessionId) {
     const row = db
-        .prepare(`SELECT 1 AS hit FROM events
-       WHERE session_id = ? AND json_extract(payload, '$.type') = 'turn/start'
+        .prepare(`SELECT 1 AS hit FROM events
+       WHERE session_id = ? AND json_extract(payload, '$.type') = 'turn/start'
        LIMIT 1`)
         .get(sessionId);
     return row !== undefined;
 }
 function hasCommandRunInDb(db, sessionId) {
     const row = db
-        .prepare(`SELECT 1 AS hit FROM events
-       WHERE session_id = ? AND json_extract(payload, '$.type') = 'command/run'
+        .prepare(`SELECT 1 AS hit FROM events
+       WHERE session_id = ? AND json_extract(payload, '$.type') = 'command/run'
        LIMIT 1`)
         .get(sessionId);
     return row !== undefined;
@@ -423,6 +685,7 @@ function sessionHintsFromDb(db, sessionId) {
         return undefined;
     return {
         lastEventTs: row.last_ts > 0 ? row.last_ts : null,
+        eventCount: row.event_count,
         hasTurnStart: row.has_turn_start === 1,
         hasCommandRun: row.has_command_run === 1,
     };
@@ -482,7 +745,7 @@ export function createPersistentSessionStore(dir, options = {}) {
     for (const id of [...coldIds]) {
         if (hotIds.has(id)) {
             try {
-                deleteSessionRows(archiveDb, id);
+                withImmediate(archiveDb, () => deleteSessionRows(archiveDb, id));
             }
             catch {
                 /* best-effort */
@@ -549,14 +812,18 @@ export function createPersistentSessionStore(dir, options = {}) {
     // newest ts and the sticky flags monotonic under out-of-order batches.
     const upsertSessionHints = shared
         ? undefined
-        : db.prepare(`INSERT INTO sessions (id, last_ts, event_count, has_turn_start, has_command_run)
-         VALUES (?, ?, ?, ?, ?)
-         ON CONFLICT(id) DO UPDATE SET
-           last_ts = MAX(sessions.last_ts, excluded.last_ts),
-           event_count = sessions.event_count + excluded.event_count,
-           has_turn_start = MAX(sessions.has_turn_start, excluded.has_turn_start),
+        : db.prepare(`INSERT INTO sessions (id, last_ts, event_count, has_turn_start, has_command_run)
+         VALUES (?, ?, ?, ?, ?)
+         ON CONFLICT(id) DO UPDATE SET
+           last_ts = MAX(sessions.last_ts, excluded.last_ts),
+           event_count = sessions.event_count + excluded.event_count,
+           has_turn_start = MAX(sessions.has_turn_start, excluded.has_turn_start),
            has_command_run = MAX(sessions.has_command_run, excluded.has_command_run)`);
-    const updateSessionHints = (sessionId, events) => {
+    /**
+     * Append-only flush: **add** this batch's length to `event_count`.
+     * Do not use for seed / replacePrefix / repair (those need an absolute set).
+     */
+    const bumpSessionHints = (sessionId, events) => {
         if (upsertSessionHints === undefined)
             return;
         let lastTs = 0;
@@ -572,6 +839,26 @@ export function createPersistentSessionStore(dir, options = {}) {
         }
         upsertSessionHints.run(sessionId, lastTs, events.length, turnStart, commandRun);
     };
+    /**
+     * Absolute list hints from a full logical log (seed / truncate / hydrate repair).
+     * `bumpSessionHints` alone would ADD `events.length` onto a stale counter.
+     */
+    const setSessionHints = (sessionId, events) => {
+        if (shared)
+            return;
+        let lastTs = 0;
+        let turnStart = 0;
+        let commandRun = 0;
+        for (const event of events) {
+            if (event.ts > lastTs)
+                lastTs = event.ts;
+            if (event.type === "turn/start")
+                turnStart = 1;
+            else if (event.type === "command/run")
+                commandRun = 1;
+        }
+        db.prepare("UPDATE sessions SET last_ts = ?, event_count = ?, has_turn_start = ?, has_command_run = ? WHERE id = ?").run(lastTs, events.length, turnStart, commandRun, sessionId);
+    };
     const allocateSeq = (sessionId) => {
         let next = nextSeqBySession.get(sessionId);
         if (next === undefined) {
@@ -583,6 +870,15 @@ export function createPersistentSessionStore(dir, options = {}) {
     const writeRecord = (sessionId, record) => {
         const seq = allocateSeq(sessionId);
         insertEvent.run(sessionId, seq, storageTs(record), JSON.stringify(record));
+        // `text-chunks` rows are indexed by `indexJoinedTextChunks`, whose row
+        // carries the flush-boundary prefix and therefore the whole text of this
+        // row as a strict subset. Writing both stored the same conversation twice
+        // in `search_fts` (measured: 165 fully-overlapping (session_id, seq)
+        // pairs in one live session), doubling the index and every archive /
+        // restore / delete copy of it. `MATCH` recall is unchanged: the kept row
+        // is the superset, and search only returns DISTINCT session_id.
+        if (isTextChunkRow(record))
+            return;
         const text = extractStorageSearchText(record);
         if (text)
             insertFts.run(sessionId, seq, text);
@@ -716,11 +1012,13 @@ export function createPersistentSessionStore(dir, options = {}) {
         // Human input is the one thing a power cut must not swallow: upgrade to
         // FULL for the transaction carrying it, then fall back to NORMAL. PRAGMA
         // synchronous cannot change inside a transaction, so it brackets BEGIN.
+        // BEGIN (and the FULL pragma) must sit inside try: a busy/IO throw before
+        // COMMIT would otherwise drop `batch` from `pending` with no restore.
         const needsFullSync = batch.some((row) => row.event.type === "user/message");
-        if (needsFullSync)
-            db.exec("PRAGMA synchronous = FULL");
-        db.exec("BEGIN IMMEDIATE");
         try {
+            if (needsFullSync)
+                db.exec("PRAGMA synchronous = FULL");
+            db.exec("BEGIN IMMEDIATE");
             for (const sessionId of order) {
                 const events = bySession.get(sessionId);
                 const packed = packChunkRunsForExport(events);
@@ -728,7 +1026,7 @@ export function createPersistentSessionStore(dir, options = {}) {
                     writeRecord(sessionId, record);
                 }
                 indexJoinedTextChunks(sessionId, events);
-                updateSessionHints(sessionId, events);
+                bumpSessionHints(sessionId, events);
             }
             db.exec("COMMIT");
         }
@@ -737,7 +1035,7 @@ export function createPersistentSessionStore(dir, options = {}) {
                 db.exec("ROLLBACK");
             }
             catch {
-                /* already rolled back / closed */
+                /* already rolled back / closed / never began */
             }
             restoreSeqMap(seqSnapshot);
             // Prepend this flush's batch so later flush/close can retry; keep any
@@ -783,8 +1081,11 @@ export function createPersistentSessionStore(dir, options = {}) {
     const flushMicrotaskIds = new Set();
     let flushMicrotaskQueued = false;
     let storeClosed = false;
+    let backgroundFlushFailures = 0;
+    let backgroundFlushPaused = false;
+    let lastBackgroundFlushError;
     const scheduleFlushPending = (sessionId) => {
-        if (shared || storeClosed)
+        if (shared || storeClosed || backgroundFlushPaused)
             return;
         flushMicrotaskIds.add(sessionId);
         if (flushMicrotaskQueued)
@@ -792,7 +1093,7 @@ export function createPersistentSessionStore(dir, options = {}) {
         flushMicrotaskQueued = true;
         queueMicrotask(() => {
             flushMicrotaskQueued = false;
-            if (storeClosed) {
+            if (storeClosed || backgroundFlushPaused) {
                 flushMicrotaskIds.clear();
                 return;
             }
@@ -802,8 +1103,20 @@ export function createPersistentSessionStore(dir, options = {}) {
                 try {
                     flushPending(id);
                 }
-                catch {
+                catch (error) {
                     /* pending restored inside flushPending; close()/flush() retries */
+                    // A retry that never succeeds is data loss with no trail: the events
+                    // look saved in memory and vanish on exit. Pause auto-drain (DSH) so
+                    // the next explicit flush()/close() is the only path forward.
+                    backgroundFlushFailures += 1;
+                    backgroundFlushPaused = true;
+                    lastBackgroundFlushError =
+                        error instanceof Error ? error.message : String(error);
+                    if (backgroundFlushFailures <= 3 || backgroundFlushFailures % 100 === 0) {
+                        console.error(`[session-store] background flush failed #${backgroundFlushFailures}`
+                            + ` for ${id}; auto-drain paused, events stay queued: `
+                            + lastBackgroundFlushError);
+                    }
                 }
             }
         });
@@ -838,7 +1151,7 @@ export function createPersistentSessionStore(dir, options = {}) {
         const events = loadSessionEvents(sourceDbFor(id), id);
         const repairs = repairOpenTurnEvents(events);
         if (repairs.length > 0) {
-            const frozenRepairs = repairs.map((ev) => deepFreeze(structuredClone(assertSessionEvent(ev))));
+            const frozenRepairs = repairs.map((ev) => freezeSessionEvent(ev));
             // Cold / shared: memory-only repair (archive is read for turns; shared is RO).
             if (!shared && !offloaded) {
                 const seqSnapshot = new Map(nextSeqBySession);
@@ -847,7 +1160,9 @@ export function createPersistentSessionStore(dir, options = {}) {
                     for (const frozen of frozenRepairs) {
                         persistImmediate(id, frozen);
                     }
-                    updateSessionHints(id, frozenRepairs);
+                    // Repairs are appends — bump; absolute set happens below against the
+                    // full logical log (also heals stale event_count from older builds).
+                    bumpSessionHints(id, frozenRepairs);
                     db.exec("COMMIT");
                 }
                 catch (err) {
@@ -867,6 +1182,19 @@ export function createPersistentSessionStore(dir, options = {}) {
         }
         sessions.set(id, events);
         touchResident(id);
+        // Heal durable event_count when it drifted (R7 ADD-bug / partial bump).
+        // R8 cold tail keys absolute seq off this column.
+        if (!shared && !offloaded) {
+            const hinted = sessionHintsFromDb(sourceDbFor(id), id)?.eventCount;
+            if (hinted !== events.length) {
+                try {
+                    setSessionHints(id, events);
+                }
+                catch {
+                    /* RO / closed */
+                }
+            }
+        }
         return events;
     };
     const assertHotMutable = (id) => {
@@ -907,11 +1235,11 @@ export function createPersistentSessionStore(dir, options = {}) {
                 return;
             flushPending(sid);
             if (hotIds.has(sid)) {
-                deleteSessionRows(db, sid);
+                withImmediate(db, () => deleteSessionRows(db, sid));
                 hotIds.delete(sid);
             }
             if (coldIds.has(sid)) {
-                deleteSessionRows(archiveDb, sid);
+                withImmediate(archiveDb, () => deleteSessionRows(archiveDb, sid));
                 coldIds.delete(sid);
             }
             sessionIds.delete(sid);
@@ -942,7 +1270,7 @@ export function createPersistentSessionStore(dir, options = {}) {
                 return;
             flushPending(sid);
             copySessionRows(db, archiveDb, sid);
-            deleteSessionRows(db, sid);
+            withImmediate(db, () => deleteSessionRows(db, sid));
             hotIds.delete(sid);
             coldIds.add(sid);
             dropResident(sid);
@@ -961,7 +1289,7 @@ export function createPersistentSessionStore(dir, options = {}) {
                 return;
             flushPending(sid);
             copySessionRows(archiveDb, db, sid);
-            deleteSessionRows(archiveDb, sid);
+            withImmediate(archiveDb, () => deleteSessionRows(archiveDb, sid));
             coldIds.delete(sid);
             hotIds.add(sid);
             dropResident(sid);
@@ -980,8 +1308,7 @@ export function createPersistentSessionStore(dir, options = {}) {
             }
             assertHotMutable(id);
             const events = ensureLoaded(id);
-            const parsed = assertSessionEvent(event);
-            const frozen = deepFreeze(structuredClone(parsed));
+            const frozen = freezeSessionEvent(event);
             events.push(frozen);
             try {
                 persistEvent(id, frozen);
@@ -1009,7 +1336,7 @@ export function createPersistentSessionStore(dir, options = {}) {
             }
             const frozen = [];
             for (const event of eventsInput) {
-                frozen.push(deepFreeze(structuredClone(assertSessionEvent(event))));
+                frozen.push(freezeSessionEvent(event));
             }
             // Create + one packed transaction (not N persistEvent flushes). Chunk
             // runs pack the same way as flushPending so fork seed matches live shape.
@@ -1031,6 +1358,12 @@ export function createPersistentSessionStore(dir, options = {}) {
                     writeRecord(sid, record);
                 }
                 indexJoinedTextChunks(sid, frozen);
+                // Same hints `replacePrefix` maintains. Without this a freshly forked
+                // child sits at event_count 0 / has_turn_start 0 until its first
+                // non-turn-start append, at which point the hint reader stops falling
+                // back to an event scan and `blank` flips true — the sidebar then
+                // offers the new-session button a 6-figure-event branch to reuse.
+                setSessionHints(sid, frozen);
                 db.exec("COMMIT");
             }
             catch (err) {
@@ -1054,6 +1387,89 @@ export function createPersistentSessionStore(dir, options = {}) {
             }
             return { id: sid, events: frozen };
         },
+        /**
+         * Fork R6: `INSERT…SELECT` the parent's durable prefix, then write only
+         * `suffix` (closers + end-seed). Returns undefined → {@link forkSession}
+         * falls back to full `seed` (packed row straddles the cut, or cold source).
+         */
+        seedFromSession(sourceId, keepLogical, childId, suffix) {
+            assertWritable();
+            const src = assertSafeId(sourceId);
+            if (!sessionIds.has(src) || coldIds.has(src))
+                return undefined;
+            flushPending(src);
+            assertHotMutable(src);
+            const sourceEvents = ensureLoaded(src);
+            if (keepLogical > sourceEvents.length)
+                return undefined;
+            const cut = physicalTailCutSeq(db, src, keepLogical, sourceEvents.length);
+            if (cut === "rewrite")
+                return undefined;
+            const sid = assertSafeId(childId ?? newSessionId());
+            if (sessionIds.has(sid)) {
+                throw new Error(`session already exists: ${sid}`);
+            }
+            const prefix = sourceEvents.slice(0, keepLogical);
+            const frozenSuffix = [];
+            for (const event of suffix) {
+                frozenSuffix.push(freezeSessionEvent(event));
+            }
+            const frozen = prefix.concat(frozenSuffix);
+            const sourceNext = nextSeqBySession.get(src) ?? nextSeqFromDb(db, src);
+            const nextAfterCopy = cut === "empty" ? 0 : cut === "noop" ? sourceNext : cut;
+            sessionIds.add(sid);
+            hotIds.add(sid);
+            evictResidents(sid);
+            sessions.set(sid, frozen);
+            touchResident(sid);
+            nextSeqBySession.set(sid, nextAfterCopy);
+            insertSession.run(sid);
+            const seqSnapshot = new Map(nextSeqBySession);
+            db.exec("BEGIN IMMEDIATE");
+            try {
+                if (cut === "noop") {
+                    db.prepare("INSERT INTO events (session_id, seq, ts, payload) "
+                        + "SELECT ?, seq, ts, payload FROM events WHERE session_id = ?").run(sid, src);
+                    db.prepare("INSERT INTO search_fts (session_id, seq, text) "
+                        + "SELECT ?, seq, text FROM search_fts WHERE session_id = ?").run(sid, src);
+                }
+                else if (typeof cut === "number") {
+                    db.prepare("INSERT INTO events (session_id, seq, ts, payload) "
+                        + "SELECT ?, seq, ts, payload FROM events WHERE session_id = ? AND seq < ?").run(sid, src, cut);
+                    db.prepare("INSERT INTO search_fts (session_id, seq, text) "
+                        + "SELECT ?, seq, text FROM search_fts WHERE session_id = ? AND seq < ?").run(sid, src, cut);
+                }
+                if (frozenSuffix.length > 0) {
+                    const packed = packChunkRunsForExport(frozenSuffix);
+                    for (const record of packed) {
+                        writeRecord(sid, record);
+                    }
+                    indexJoinedTextChunks(sid, frozenSuffix);
+                }
+                setSessionHints(sid, frozen);
+                db.exec("COMMIT");
+            }
+            catch (err) {
+                try {
+                    db.exec("ROLLBACK");
+                }
+                catch {
+                    /* already rolled back / closed */
+                }
+                restoreSeqMap(seqSnapshot);
+                sessionIds.delete(sid);
+                hotIds.delete(sid);
+                dropResident(sid);
+                try {
+                    db.prepare("DELETE FROM sessions WHERE id = ?").run(sid);
+                }
+                catch {
+                    /* best-effort */
+                }
+                throw err;
+            }
+            return { id: sid, events: frozen };
+        },
         replacePrefix(id, eventsInput = []) {
             assertWritable();
             const sid = assertSafeId(id);
@@ -1064,7 +1480,56 @@ export function createPersistentSessionStore(dir, options = {}) {
             flushPending(sid);
             const frozen = [];
             for (const event of eventsInput) {
-                frozen.push(deepFreeze(structuredClone(assertSessionEvent(event))));
+                frozen.push(freezeSessionEvent(event));
+            }
+            // Fast path (edit-resubmit / truncate): prefix unchanged → DELETE tail
+            // rows only. Full wipe+rewrite was ~1.6s on a 16k-event session.
+            const current = ensureLoaded(sid);
+            if (frozen.length <= current.length
+                && logicalEventsEqualPrefix(current, frozen)) {
+                const cut = physicalTailCutSeq(db, sid, frozen.length, current.length);
+                if (cut === "noop") {
+                    sessions.set(sid, frozen);
+                    touchResident(sid);
+                    return { id: sid, events: frozen };
+                }
+                if (cut === "empty" || typeof cut === "number") {
+                    const seqSnapshot = new Map(nextSeqBySession);
+                    db.exec("BEGIN IMMEDIATE");
+                    try {
+                        if (cut === "empty") {
+                            db.prepare("DELETE FROM search_fts WHERE session_id = ?").run(sid);
+                            db.prepare("DELETE FROM events WHERE session_id = ?").run(sid);
+                            nextSeqBySession.set(sid, 0);
+                        }
+                        else {
+                            db.prepare("DELETE FROM search_fts WHERE session_id = ? AND seq >= ?").run(sid, cut);
+                            db.prepare("DELETE FROM events WHERE session_id = ? AND seq >= ?").run(sid, cut);
+                            nextSeqBySession.set(sid, cut);
+                        }
+                        if (frozen.length === 0) {
+                            db.prepare("UPDATE sessions SET last_ts = 0, event_count = 0, has_turn_start = 0, has_command_run = 0 WHERE id = ?").run(sid);
+                        }
+                        else {
+                            setSessionHints(sid, frozen);
+                        }
+                        db.exec("COMMIT");
+                    }
+                    catch (err) {
+                        try {
+                            db.exec("ROLLBACK");
+                        }
+                        catch {
+                            /* already rolled back / closed */
+                        }
+                        restoreSeqMap(seqSnapshot);
+                        throw err;
+                    }
+                    sessions.set(sid, frozen);
+                    touchResident(sid);
+                    return { id: sid, events: frozen };
+                }
+                // cut === "rewrite" (packed row straddles the logical boundary)
             }
             const seqSnapshot = new Map(nextSeqBySession);
             db.exec("BEGIN IMMEDIATE");
@@ -1079,7 +1544,7 @@ export function createPersistentSessionStore(dir, options = {}) {
                         writeRecord(sid, record);
                     }
                     indexJoinedTextChunks(sid, frozen);
-                    updateSessionHints(sid, frozen);
+                    setSessionHints(sid, frozen);
                 }
                 db.exec("COMMIT");
             }
@@ -1113,8 +1578,12 @@ export function createPersistentSessionStore(dir, options = {}) {
             if (hints !== undefined)
                 return hints;
             // Pre-v4 rows (or a stripped archive) still fall back to the scans.
+            const lastEventTs = lastEventTsFromDb(source, id);
             return {
-                lastEventTs: lastEventTsFromDb(source, id),
+                lastEventTs,
+                eventCount: source
+                    .prepare("SELECT COUNT(*) AS n FROM events WHERE session_id = ?")
+                    .get(id)?.n ?? 0,
                 hasTurnStart: hasTurnStartInDb(source, id),
                 hasCommandRun: hasCommandRunInDb(source, id),
             };
@@ -1122,28 +1591,108 @@ export function createPersistentSessionStore(dir, options = {}) {
         isLoaded(id) {
             return sessions.has(id);
         },
+        readEventsTail(id, maxLogical) {
+            if (!sessionIds.has(id)) {
+                throw new Error(`session not found: ${id}`);
+            }
+            const cap = Math.max(0, Math.floor(maxLogical));
+            if (cap <= 0) {
+                return { events: [], baseIndex: 0 };
+            }
+            const cached = sessions.get(id);
+            if (cached !== undefined) {
+                touchResident(id);
+                if (cached.length <= cap) {
+                    return { events: cached, baseIndex: 0 };
+                }
+                const baseIndex = cached.length - cap;
+                return { events: cached.slice(baseIndex), baseIndex };
+            }
+            const source = sourceDbFor(id);
+            const hints = sessionHintsFromDb(source, id);
+            const total = hints?.eventCount;
+            if (typeof total !== "number" || total <= 0)
+                return undefined;
+            // v4 hint backfill used physical COUNT(*). Packed sessions then report
+            // event_count === row count while logical length is larger — refuse the
+            // fast path so Face falls back to a full expand (correct absolute seq).
+            if (!eventCountLooksLogical(source, id, total))
+                return undefined;
+            const events = loadSessionEventsTail(source, id, cap);
+            if (events.length === 0)
+                return { events: [], baseIndex: total };
+            if (events.length > total)
+                return undefined;
+            return { events, baseIndex: total - events.length };
+        },
+        scanDurableSingles(id, visit) {
+            if (!sessionIds.has(id)) {
+                throw new Error(`session not found: ${id}`);
+            }
+            const cached = sessions.get(id);
+            if (cached !== undefined) {
+                touchResident(id);
+                for (const event of cached)
+                    visit(event);
+                return;
+            }
+            scanDurableSinglesFromDb(sourceDbFor(id), id, visit);
+        },
         searchSessionIds(query) {
-            const match = ftsMatchQuery(query);
-            if (match === '""')
+            const plan = planFtsQuery(query);
+            if (plan === null)
                 return [];
             const ids = new Set();
+            // A common word ("session", "测试"→LIKE) matches thousands of rows. Face
+            // shows 20 with a hasMore flag and then reads every candidate's full log,
+            // so an uncapped candidate list pulls hundreds of sessions into the LRU
+            // and evicts them again one by one.
+            const CANDIDATE_LIMIT = 200;
+            let ftsFailed = false;
             const run = (target) => {
                 try {
-                    const rows = target
-                        .prepare("SELECT DISTINCT session_id AS id FROM search_fts WHERE search_fts MATCH ?")
-                        .all(match);
+                    const rows = (plan.kind === "match"
+                        ? target
+                            .prepare("SELECT DISTINCT session_id AS id FROM search_fts WHERE search_fts MATCH ? LIMIT ?")
+                            .all(plan.value, CANDIDATE_LIMIT)
+                        : target
+                            .prepare("SELECT DISTINCT session_id AS id FROM search_fts WHERE text LIKE ? ESCAPE '\\' LIMIT ?")
+                            .all(plan.value, CANDIDATE_LIMIT));
                     for (const row of rows)
                         ids.add(row.id);
                 }
                 catch {
-                    /* corrupt / missing FTS — skip that DB */
+                    /* corrupt / missing FTS — skip that DB, but say so below */
+                    ftsFailed = true;
                 }
             };
             run(db);
             run(archiveDb);
+            const needle = query.trim().toLowerCase();
+            if (ftsFailed) {
+                // A damaged index must not read as "no results": that is indistinguishable
+                // from a real miss and sends the user hunting for content that is right
+                // there. Scan the resident logs (the same text the index would hold) and
+                // leave a throttled trace for diagnosis.
+                for (const [id, events] of sessions) {
+                    if (ids.has(id))
+                        continue;
+                    for (const event of events) {
+                        const text = extractEventSearchText(event);
+                        if (text !== undefined && text.toLowerCase().includes(needle)) {
+                            ids.add(id);
+                            break;
+                        }
+                    }
+                }
+                searchIndexFailures += 1;
+                if (searchIndexFailures <= 3 || searchIndexFailures % 100 === 0) {
+                    console.error(`[session-store] search index unavailable (#${searchIndexFailures});`
+                        + " falling back to resident logs — rebuild FTS to restore cold search");
+                }
+            }
             // Pending batches are not in FTS yet. Match them in memory so a search
             // does not COMMIT every other session's interior events.
-            const needle = query.trim().toLowerCase();
             const chunkText = new Map();
             for (const row of pending) {
                 const text = extractEventSearchText(row.event);
@@ -1172,8 +1721,37 @@ export function createPersistentSessionStore(dir, options = {}) {
             }
             return [...ids];
         },
+        releaseResident(sessionId) {
+            const sid = sessionId;
+            if (!sessionIds.has(sid))
+                return false;
+            const events = sessions.get(sid);
+            if (events === undefined)
+                return true;
+            // Same pin as LRU eviction: re-hydrate mid-turn would re-run repair and
+            // can insert a synthetic interrupted assistant while the live loop still
+            // streams.
+            if (sessionHasOpenTurn(events))
+                return false;
+            flushPending(sid);
+            onEvict?.(sid);
+            dropResident(sid);
+            return true;
+        },
+        flushFailureReport() {
+            return {
+                failures: backgroundFlushFailures,
+                paused: backgroundFlushPaused,
+                ...(lastBackgroundFlushError !== undefined
+                    ? { lastError: lastBackgroundFlushError }
+                    : {}),
+            };
+        },
         flush(sessionId) {
             flushPending(sessionId);
+            // Explicit barrier cleared the pause — resume microtask auto-drain.
+            backgroundFlushPaused = false;
+            lastBackgroundFlushError = undefined;
         },
         close() {
             storeClosed = true;