@pentoshi/clai 3.8.36 → 3.8.39

package/dist/store/history.js

@@ -1,4 +1,4 @@
-import { appendFile, copyFile, mkdir, readdir, readFile, rm, writeFile, rename, } from "node:fs/promises";
+import { appendFile, copyFile, mkdir, readdir, open, readFile, rm, stat, utimes, writeFile, rename, } from "node:fs/promises";
 import { join } from "node:path";
 import { isInternalChatMessage, } from "../types.js";
 import { redactSecrets } from "../llm/provider.js";
@@ -17,6 +17,12 @@ function dbFilePath() {
 function jsonlFilePath() {
     return join(historyDirPath(), "history.jsonl");
 }
+function jsonlLockFilePath() {
+    return join(historyDirPath(), "history.jsonl.lock");
+}
+function jsonlLockReaperPath() {
+    return join(historyDirPath(), "history.jsonl.lock.reaper");
+}
 /** Sessions pruned by retention land here — never hard-deleted on autosave. */
 function archiveFilePath() {
     return join(historyDirPath(), "history-archive.jsonl");
@@ -27,14 +33,6 @@ function backupDirPath() {
 }
 /** Max rolling backups kept under history-backups/. */
 const MAX_HISTORY_BACKUPS = 12;
-// We keep this string here (not as a literal) so the bundler doesn't try
-// to statically resolve a module that may not be installed. If a user has
-// `better-sqlite3` available (eg they explicitly added it for a richer
-// history experience) we'll happily use it; otherwise we transparently
-// fall back to the always-available JSONL log. This lets us drop
-// `better-sqlite3` from our optional dependencies — and with it the
-// deprecated `prebuild-install` warning — without losing functionality
-// for users who already had a SQLite-backed history.
 const sqliteModuleName = "better-sqlite3";
 /** Snapshot the active session workspace for history persistence. */
 function workspaceFieldsFromActive(existing) {
@@ -83,6 +81,8 @@ async function loadDatabase() {
         name TEXT,
         created_at TEXT NOT NULL,
         updated_at TEXT NOT NULL,
+        writer_generation TEXT,
+        revision INTEGER NOT NULL DEFAULT 0,
         cwd TEXT NOT NULL,
         messages_json TEXT NOT NULL
       );
@@ -100,6 +100,15 @@ async function loadDatabase() {
       CREATE INDEX IF NOT EXISTS idx_sessions_updated_at ON sessions(updated_at);
       CREATE INDEX IF NOT EXISTS idx_tool_calls_session_id ON tool_calls(session_id);
     `);
+        const sessionColumns = cachedDb
+            .prepare("PRAGMA table_info(sessions)")
+            .all();
+        if (!sessionColumns.some((column) => column.name === "writer_generation")) {
+            cachedDb.exec("ALTER TABLE sessions ADD COLUMN writer_generation TEXT;");
+        }
+        if (!sessionColumns.some((column) => column.name === "revision")) {
+            cachedDb.exec("ALTER TABLE sessions ADD COLUMN revision INTEGER NOT NULL DEFAULT 0;");
+        }
         return cachedDb;
     }
     catch (err) {
@@ -160,11 +169,101 @@ function scrubTranscript(items) {
         }
     });
 }
-async function appendJsonl(record) {
-    await mutateJsonl((records) => {
-        records.push(record);
-        return records;
-    });
+const JSONL_LOCK_STALE_MS = 60_000;
+const JSONL_LOCK_RETRIES = 200;
+/** Serialize stale-lock reclamation and recheck the owner while holding it. */
+async function reapStaleJsonlLock() {
+    let reaper;
+    const reaperToken = `${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    try {
+        reaper = await open(jsonlLockReaperPath(), "wx", 0o600);
+        try {
+            await reaper.writeFile(reaperToken);
+        }
+        catch (error) {
+            await reaper.close().catch(() => undefined);
+            await rm(jsonlLockReaperPath(), { force: true }).catch(() => undefined);
+            throw error;
+        }
+    }
+    catch (error) {
+        if (error?.code !== "EEXIST")
+            throw error;
+        const existingToken = await readFile(jsonlLockReaperPath(), "utf8").catch(() => undefined);
+        const reaperStat = await stat(jsonlLockReaperPath()).catch(() => undefined);
+        if (!reaperStat ||
+            Date.now() - reaperStat.mtimeMs <= JSONL_LOCK_STALE_MS) {
+            return;
+        }
+        const confirmed = await readFile(jsonlLockReaperPath(), "utf8").catch(() => undefined);
+        if (confirmed !== undefined && confirmed === existingToken) {
+            await rm(jsonlLockReaperPath(), { force: true }).catch(() => undefined);
+        }
+        return;
+    }
+    try {
+        const token = await readFile(jsonlLockFilePath(), "utf8").catch(() => undefined);
+        const lockStat = await stat(jsonlLockFilePath()).catch(() => undefined);
+        if (!lockStat || Date.now() - lockStat.mtimeMs <= JSONL_LOCK_STALE_MS) {
+            return;
+        }
+        // The live owner refreshes mtime periodically. A stale marker—including
+        // an empty marker left between open/write—is therefore safe to reclaim.
+        const confirmed = await readFile(jsonlLockFilePath(), "utf8").catch(() => undefined);
+        if (confirmed !== undefined && confirmed === token) {
+            await rm(jsonlLockFilePath(), { force: true });
+        }
+    }
+    finally {
+        await reaper.close().catch(() => undefined);
+        const currentReaper = await readFile(jsonlLockReaperPath(), "utf8").catch(() => undefined);
+        if (currentReaper === reaperToken) {
+            await rm(jsonlLockReaperPath(), { force: true }).catch(() => undefined);
+        }
+    }
+}
+/**
+ * Cross-process lock around JSONL read/modify/rename. Atomic rename protects
+ * readers, but without this lock two clai processes can both read the same
+ * base file and then each replace it, dropping whichever session they did not
+ * observe. The lock is transient and stale crash leftovers self-heal.
+ */
+async function acquireJsonlWriteLock() {
+    await mkdir(historyDirPath(), { recursive: true });
+    for (let attempt = 0; attempt < JSONL_LOCK_RETRIES; attempt += 1) {
+        try {
+            const token = `${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+            const handle = await open(jsonlLockFilePath(), "wx", 0o600);
+            try {
+                await handle.writeFile(token);
+            }
+            catch (error) {
+                await handle.close().catch(() => undefined);
+                await rm(jsonlLockFilePath(), { force: true }).catch(() => undefined);
+                throw error;
+            }
+            const heartbeat = setInterval(() => {
+                const now = new Date();
+                void utimes(jsonlLockFilePath(), now, now).catch(() => undefined);
+            }, JSONL_LOCK_STALE_MS / 3);
+            heartbeat.unref();
+            return async () => {
+                clearInterval(heartbeat);
+                await handle.close().catch(() => undefined);
+                const currentToken = await readFile(jsonlLockFilePath(), "utf8").catch(() => undefined);
+                if (currentToken === token) {
+                    await rm(jsonlLockFilePath(), { force: true }).catch(() => undefined);
+                }
+            };
+        }
+        catch (error) {
+            if (error?.code !== "EEXIST")
+                throw error;
+            await reapStaleJsonlLock();
+            await new Promise((resolve) => setTimeout(resolve, 25));
+        }
+    }
+    throw new Error("timed out waiting for history write lock");
 }
 /**
  * Serializes every JSONL mutation through a single promise chain so concurrent
@@ -180,12 +279,18 @@ function mutateJsonl(update) {
     const run = jsonlWriteChain.then(async () => {
         try {
             await ensureHistoryRecovered();
-            const current = await readJsonlRecordsFrom(jsonlFilePath());
-            const next = update(current);
-            await writeJsonlAtomic(next);
-            // A list may have been loaded after the pre-write invalidation but
-            // before the atomic rename completed. Never leave that snapshot cached.
-            invalidateSessionListCache();
+            const releaseLock = await acquireJsonlWriteLock();
+            try {
+                const current = await readJsonlRecordsFrom(jsonlFilePath());
+                const next = update(current);
+                await writeJsonlAtomic(next);
+                // A list may have been loaded after the pre-write invalidation but
+                // before the atomic rename completed. Never leave that snapshot cached.
+                invalidateSessionListCache();
+            }
+            finally {
+                await releaseLock();
+            }
         }
         catch (err) {
             handlePermissionError(err);
@@ -199,14 +304,62 @@ function updatedAtMs(record) {
     const t = Date.parse(record.updatedAt || record.createdAt || "");
     return Number.isFinite(t) ? t : 0;
 }
-/** Keep the newest version of each session id. */
+function historyRevision(record) {
+    const revision = record?.revision;
+    return typeof revision === "number" &&
+        Number.isSafeInteger(revision) &&
+        revision > 0
+        ? revision
+        : 0;
+}
+function historyWriterGeneration(record) {
+    const generation = record?.writerGeneration;
+    return typeof generation === "string" && generation.length > 0
+        ? generation
+        : undefined;
+}
+/**
+ * Compare snapshots by writer generation, then capture revision. Legacy rows
+ * without a generation retain revision/timestamp fallback for compatibility.
+ */
+export function compareHistoryFreshness(left, right) {
+    const leftGeneration = historyWriterGeneration(left);
+    const rightGeneration = historyWriterGeneration(right);
+    if (leftGeneration || rightGeneration) {
+        if (!leftGeneration)
+            return -1;
+        if (!rightGeneration)
+            return 1;
+        const generationDelta = leftGeneration.localeCompare(rightGeneration);
+        if (generationDelta !== 0)
+            return generationDelta;
+    }
+    const revisionDelta = historyRevision(left) - historyRevision(right);
+    if (revisionDelta !== 0)
+        return revisionDelta;
+    if (historyRevision(left) > 0)
+        return 0;
+    return updatedAtMs(left) - updatedAtMs(right);
+}
+function freshestHistoryRecord(records) {
+    let freshest;
+    for (const record of records) {
+        if (!freshest || compareHistoryFreshness(record, freshest) > 0) {
+            freshest = record;
+        }
+    }
+    return freshest;
+}
+/** Keep the newest captured version of each session id. */
 export function dedupeHistoryById(records) {
     const byId = new Map();
     for (const record of records) {
         if (!record?.id)
             continue;
         const prev = byId.get(record.id);
-        if (!prev || updatedAtMs(record) >= updatedAtMs(prev)) {
+        // Preserve the first source on an exact tie. JSONL is passed first during
+        // cross-backend merge and is the durable canonical copy.
+        if (!prev || compareHistoryFreshness(record, prev) > 0) {
             byId.set(record.id, record);
         }
     }
@@ -297,92 +450,101 @@ async function backupActiveHistory() {
 export async function recoverOrphanedHistory() {
     const sources = [];
     const extras = [];
+    const releaseLock = await acquireJsonlWriteLock();
     try {
-        const names = await readdir(historyDirPath());
-        for (const name of names) {
-            // Live write temps: history.jsonl.<pid>.<stamp>.tmp
-            if (name.startsWith("history.jsonl.") &&
-                name.endsWith(".tmp")) {
-                const path = join(historyDirPath(), name);
-                const rows = await readJsonlRecordsFrom(path);
-                if (rows.length === 0) {
-                    // Empty crash leftovers — safe to remove.
-                    await rm(path, { force: true }).catch(() => undefined);
-                    continue;
+        try {
+            const names = await readdir(historyDirPath());
+            for (const name of names) {
+                // Live write temps: history.jsonl.<pid>.<stamp>.tmp
+                if (name.startsWith("history.jsonl.") &&
+                    name.endsWith(".tmp")) {
+                    const path = join(historyDirPath(), name);
+                    const rows = await readJsonlRecordsFrom(path);
+                    if (rows.length === 0) {
+                        // Empty crash leftovers — safe to remove.
+                        await rm(path, { force: true }).catch(() => undefined);
+                        continue;
+                    }
+                    extras.push(...rows);
+                    sources.push(name);
                 }
-                extras.push(...rows);
-                sources.push(name);
             }
         }
-    }
-    catch {
-        /* dir may not exist yet */
-    }
-    // Also fold in archive (sessions previously pruned).
-    if (await safeExists(archiveFilePath())) {
-        const archived = await readJsonlRecordsFrom(archiveFilePath());
-        if (archived.length > 0) {
-            extras.push(...archived);
-            sources.push("history-archive.jsonl");
+        catch {
+            /* dir may not exist yet */
         }
-    }
-    // Rolling backups (last-resort recovery of wiped active files).
-    try {
-        if (await safeExists(backupDirPath())) {
-            const backups = (await readdir(backupDirPath()))
-                .filter((n) => n.startsWith("history-") && n.endsWith(".jsonl"))
-                .sort()
-                .reverse()
-                .slice(0, 3);
-            for (const name of backups) {
-                const rows = await readJsonlRecordsFrom(join(backupDirPath(), name));
-                if (rows.length > 0) {
-                    extras.push(...rows);
-                    sources.push(`history-backups/${name}`);
+        // Also fold in archive (sessions previously pruned).
+        if (await safeExists(archiveFilePath())) {
+            const archived = await readJsonlRecordsFrom(archiveFilePath());
+            if (archived.length > 0) {
+                extras.push(...archived);
+                sources.push("history-archive.jsonl");
+            }
+        }
+        // Rolling backups (last-resort recovery of wiped active files).
+        try {
+            if (await safeExists(backupDirPath())) {
+                const backups = (await readdir(backupDirPath()))
+                    .filter((n) => n.startsWith("history-") && n.endsWith(".jsonl"))
+                    .sort()
+                    .reverse()
+                    .slice(0, 3);
+                for (const name of backups) {
+                    const rows = await readJsonlRecordsFrom(join(backupDirPath(), name));
+                    if (rows.length > 0) {
+                        extras.push(...rows);
+                        sources.push(`history-backups/${name}`);
+                    }
                 }
             }
         }
-    }
-    catch {
-        /* ignore */
-    }
-    if (extras.length === 0)
-        return { recovered: 0, sources: [] };
-    const active = await readJsonlRecordsFrom(jsonlFilePath());
-    const beforeIds = new Set(active.map((r) => r.id));
-    const merged = dedupeHistoryById([...active, ...extras]);
-    const newCount = merged.filter((r) => !beforeIds.has(r.id)).length;
-    if (newCount === 0 && merged.length <= active.length) {
-        return { recovered: 0, sources };
-    }
-    // Write WITHOUT applying retention so recovery cannot re-prune.
-    await mkdir(historyDirPath(), { recursive: true });
-    await fixOwner(historyDirPath());
-    if (await safeExists(jsonlFilePath()))
-        await backupActiveHistory();
-    const sorted = sortHistoryByUpdatedDesc(merged);
-    // Stable chronological file order (oldest first) for append-friendly diffs.
-    sorted.reverse();
-    const body = sorted.length
-        ? `${sorted.map((item) => JSON.stringify(item)).join("\n")}\n`
-        : "";
-    const tmpFile = `${jsonlFilePath()}.recover.${process.pid}.${Date.now().toString(36)}.tmp`;
-    await writeFile(tmpFile, body, { mode: 0o600 });
-    try {
-        await rename(tmpFile, jsonlFilePath());
-    }
-    catch (err) {
-        await rm(tmpFile, { force: true }).catch(() => undefined);
-        throw err;
-    }
-    await fixOwner(jsonlFilePath());
-    // Successful recovery: drop non-empty orphan temps we already merged.
-    for (const name of sources) {
-        if (name.startsWith("history.jsonl.") && name.endsWith(".tmp")) {
-            await rm(join(historyDirPath(), name), { force: true }).catch(() => undefined);
+        catch {
+            /* ignore */
         }
+        if (extras.length === 0)
+            return { recovered: 0, sources: [] };
+        const active = await readJsonlRecordsFrom(jsonlFilePath());
+        const activeById = new Map(active.map((record) => [record.id, record]));
+        const merged = dedupeHistoryById([...active, ...extras]);
+        const recoveredCount = merged.filter((record) => {
+            const previous = activeById.get(record.id);
+            return !previous || compareHistoryFreshness(record, previous) > 0;
+        }).length;
+        if (recoveredCount === 0) {
+            return { recovered: 0, sources };
+        }
+        // Write WITHOUT applying retention so recovery cannot re-prune.
+        await mkdir(historyDirPath(), { recursive: true });
+        await fixOwner(historyDirPath());
+        if (await safeExists(jsonlFilePath()))
+            await backupActiveHistory();
+        const sorted = sortHistoryByUpdatedDesc(merged);
+        // Stable chronological file order (oldest first) for append-friendly diffs.
+        sorted.reverse();
+        const body = sorted.length
+            ? `${sorted.map((item) => JSON.stringify(item)).join("\n")}\n`
+            : "";
+        const tmpFile = `${jsonlFilePath()}.recover.${process.pid}.${Date.now().toString(36)}.tmp`;
+        await writeFile(tmpFile, body, { mode: 0o600 });
+        try {
+            await rename(tmpFile, jsonlFilePath());
+        }
+        catch (err) {
+            await rm(tmpFile, { force: true }).catch(() => undefined);
+            throw err;
+        }
+        await fixOwner(jsonlFilePath());
+        // Successful recovery: drop non-empty orphan temps we already merged.
+        for (const name of sources) {
+            if (name.startsWith("history.jsonl.") && name.endsWith(".tmp")) {
+                await rm(join(historyDirPath(), name), { force: true }).catch(() => undefined);
+            }
+        }
+        return { recovered: recoveredCount, sources };
+    }
+    finally {
+        await releaseLock();
     }
-    return { recovered: newCount, sources };
 }
 function startHistoryRecovery() {
     if (!recoveryPromise) {
@@ -471,7 +633,40 @@ async function writeJsonlAtomic(records) {
     }
     await fixOwner(jsonlFilePath());
 }
-export async function saveSession(messages, name, transcript, contextUsage) {
+function serializeSessionPayload(record) {
+    return JSON.stringify({
+        messages: record.messages,
+        transcript: record.transcript,
+        ...(record.contextUsage ? { contextUsage: record.contextUsage } : {}),
+        ...(record.workspaceFolder
+            ? {
+                workspaceFolder: record.workspaceFolder,
+                workspaceCode: record.workspaceCode,
+            }
+            : {}),
+    });
+}
+/** SQLite mirror write with atomic generation/revision rejection. */
+function upsertSqlite(db, record) {
+    db.prepare(`INSERT INTO sessions
+       (id, name, created_at, updated_at, writer_generation, revision, cwd, messages_json)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+     ON CONFLICT(id) DO UPDATE SET
+       name = excluded.name,
+       created_at = excluded.created_at,
+       updated_at = excluded.updated_at,
+       writer_generation = excluded.writer_generation,
+       revision = excluded.revision,
+       cwd = excluded.cwd,
+       messages_json = excluded.messages_json
+     WHERE (sessions.writer_generation IS NULL AND excluded.writer_generation IS NOT NULL)
+        OR excluded.writer_generation > sessions.writer_generation
+        OR (excluded.writer_generation = sessions.writer_generation
+            AND excluded.revision >= sessions.revision)
+        OR (sessions.writer_generation IS NULL AND excluded.writer_generation IS NULL
+            AND excluded.revision >= sessions.revision)`).run(record.id, record.name ?? null, record.createdAt, record.updatedAt, historyWriterGeneration(record) ?? null, historyRevision(record), record.cwd, serializeSessionPayload(record));
+}
+export async function saveSession(messages, name, transcript, contextUsage, revision, writerGeneration) {
     // Auto-derive a readable name from the first real user message if none provided
     if (!name) {
         const firstUser = messages.find((m) => m.role === "user" && !isInternalChatMessage(m));
@@ -484,6 +679,10 @@ export async function saveSession(messages, name, transcript, contextUsage) {
     const workspace = workspaceFieldsFromActive();
     const record = {
         id: newId(),
+        ...(writerGeneration ? { writerGeneration } : {}),
+        revision: typeof revision === "number" && Number.isSafeInteger(revision) && revision > 0
+            ? revision
+            : 1,
         name,
         createdAt: now,
         updatedAt: now,
@@ -495,41 +694,38 @@ export async function saveSession(messages, name, transcript, contextUsage) {
     };
     // Private mode: never persist chat content. Caller still gets a record
     // back (so /save echoes a usable id) but nothing hits disk.
-    if (getConfig().privateMode) {
+    if (getConfig().privateMode)
         return record;
-    }
     invalidateSessionListCache();
     const db = await loadDatabase();
+    const canonical = await upsertJsonl(record);
     if (db) {
-        db.prepare("INSERT INTO sessions (id, name, created_at, updated_at, cwd, messages_json) VALUES (?, ?, ?, ?, ?, ?)").run(record.id, record.name ?? null, record.createdAt, record.updatedAt, record.cwd, JSON.stringify({
-            messages: record.messages,
-            transcript: record.transcript,
-            ...(contextUsage ? { contextUsage } : {}),
-            ...(record.workspaceFolder
-                ? {
-                    workspaceFolder: record.workspaceFolder,
-                    workspaceCode: record.workspaceCode,
-                }
-                : {}),
-        }));
+        upsertSqlite(db, canonical);
         await enforceSqliteRetention(db);
         invalidateSessionListCache();
     }
-    else {
-        await appendJsonl(record);
-    }
-    return record;
+    return canonical;
 }
-export async function upsertSession(id, messages, name, transcript, contextUsage) {
+export async function upsertSession(id, messages, name, transcript, contextUsage, revision, writerGeneration) {
     const existing = await getSession(id);
-    const firstUser = messages.find((m) => m.role === "user" && !isInternalChatMessage(m));
+    const requestedRevision = typeof revision === "number" && Number.isSafeInteger(revision) && revision > 0
+        ? revision
+        : undefined;
+    const firstUser = messages.find((message) => message.role === "user" && !isInternalChatMessage(message));
     const derivedName = firstUser
-        ? firstUser.content.slice(0, 60).replace(/\n/g, " ").trim() + (firstUser.content.length > 60 ? "…" : "")
+        ? firstUser.content.slice(0, 60).replace(/\n/g, " ").trim() +
+            (firstUser.content.length > 60 ? "…" : "")
         : undefined;
     const now = new Date().toISOString();
     const workspace = workspaceFieldsFromActive(existing);
+    const effectiveWriterGeneration = writerGeneration ?? existing?.writerGeneration;
     const record = {
         id,
+        ...(effectiveWriterGeneration
+            ? { writerGeneration: effectiveWriterGeneration }
+            : {}),
+        revision: requestedRevision ??
+            (writerGeneration ? 1 : historyRevision(existing) + 1),
         name: name ?? existing?.name ?? derivedName,
         createdAt: existing?.createdAt ?? now,
         updatedAt: now,
@@ -543,29 +739,22 @@ export async function upsertSession(id, messages, name, transcript, contextUsage
                 : {}),
         ...workspace,
     };
+    if (existing &&
+        requestedRevision !== undefined &&
+        compareHistoryFreshness(record, existing) <= 0) {
+        return existing;
+    }
     if (getConfig().privateMode)
         return record;
     invalidateSessionListCache();
     const db = await loadDatabase();
+    const canonical = await upsertJsonl(record);
     if (db) {
-        db.prepare("INSERT OR REPLACE INTO sessions (id, name, created_at, updated_at, cwd, messages_json) VALUES (?, ?, ?, ?, ?, ?)").run(record.id, record.name ?? null, record.createdAt, record.updatedAt, record.cwd, JSON.stringify({
-            messages: record.messages,
-            transcript: record.transcript,
-            ...(record.contextUsage ? { contextUsage: record.contextUsage } : {}),
-            ...(record.workspaceFolder
-                ? {
-                    workspaceFolder: record.workspaceFolder,
-                    workspaceCode: record.workspaceCode,
-                }
-                : {}),
-        }));
+        upsertSqlite(db, canonical);
         await enforceSqliteRetention(db);
         invalidateSessionListCache();
     }
-    else {
-        await upsertJsonl(record);
-    }
-    return record;
+    return canonical;
 }
 async function enforceSqliteRetention(db) {
     const limit = getConfig().historyRetentionLimit;
@@ -575,7 +764,7 @@ async function enforceSqliteRetention(db) {
     // a JSONL archive copy.
     try {
         const doomed = db
-            .prepare(`SELECT id, name, created_at, updated_at, cwd, messages_json FROM sessions
+            .prepare(`SELECT id, name, created_at, updated_at, writer_generation, revision, cwd, messages_json FROM sessions
          WHERE id NOT IN (SELECT id FROM sessions ORDER BY updated_at DESC LIMIT ?)`)
             .all(Math.floor(limit));
         const records = doomed.map(rowToSession);
@@ -588,14 +777,24 @@ async function enforceSqliteRetention(db) {
     db.exec(`DELETE FROM sessions WHERE id NOT IN (SELECT id FROM sessions ORDER BY updated_at DESC LIMIT ${Math.floor(limit)});`);
 }
 async function upsertJsonl(record) {
+    let canonical = record;
     await mutateJsonl((records) => {
         const idx = records.findIndex((item) => item.id === record.id);
-        if (idx >= 0)
-            records[idx] = record;
-        else
+        if (idx >= 0) {
+            const current = records[idx];
+            if (current && compareHistoryFreshness(record, current) > 0) {
+                records[idx] = record;
+            }
+            else if (current) {
+                canonical = current;
+            }
+        }
+        else {
             records.push(record);
+        }
         return records;
     });
+    return canonical;
 }
 export async function saveToolCall(sessionId, call, result) {
     const record = {
@@ -621,6 +820,10 @@ function rowToSession(row) {
     const messages = Array.isArray(parsed) ? parsed : parsed.messages ?? [];
     return {
         id: data.id,
+        writerGeneration: data.writer_generation ?? undefined,
+        revision: typeof data.revision === "number" && data.revision > 0
+            ? data.revision
+            : undefined,
         name: data.name ?? undefined,
         createdAt: data.created_at,
         updatedAt: data.updated_at,
@@ -646,10 +849,6 @@ async function listJsonlSessions(limit) {
         return [];
     }
 }
-/**
- * Merge SQLite + JSONL sources so enabling better-sqlite3 never hides an
- * existing JSONL history (or vice versa). Prefer the newer updatedAt per id.
- */
 function mergeSessionLists(...lists) {
     return sortHistoryByUpdatedDesc(dedupeHistoryById(lists.flat()));
 }
@@ -670,9 +869,6 @@ export async function listSessions(limit = 20, options = {}) {
     // Do not let a slow pre-write/pre-recovery read overwrite a newer cache.
     // Every mutation increments this generation before and after persistence.
     const loadGeneration = sessionListGeneration;
-    // JSONL parsing and optional SQLite startup are independent. Running them
-    // concurrently removes dynamic SQLite import latency from /history's
-    // critical path instead of paying both costs serially.
     const [fromJsonl, db] = await Promise.all([
         listJsonlSessions(0),
         loadDatabase(),
@@ -681,7 +877,7 @@ export async function listSessions(limit = 20, options = {}) {
     if (db) {
         try {
             const rows = db
-                .prepare("SELECT id, name, created_at, updated_at, cwd, messages_json FROM sessions ORDER BY updated_at DESC")
+                .prepare("SELECT id, name, created_at, updated_at, writer_generation, revision, cwd, messages_json FROM sessions ORDER BY updated_at DESC")
                 .all();
             fromDb = rows.map(rowToSession);
         }
@@ -710,7 +906,7 @@ export async function getSession(sessionId) {
     let fromDb;
     if (db) {
         const row = db
-            .prepare("SELECT id, name, created_at, updated_at, cwd, messages_json FROM sessions WHERE id = ?")
+            .prepare("SELECT id, name, created_at, updated_at, writer_generation, revision, cwd, messages_json FROM sessions WHERE id = ?")
             .get(sessionId);
         if (row)
             fromDb = rowToSession(row);
@@ -720,28 +916,30 @@ export async function getSession(sessionId) {
     const fromArchive = fromJsonl
         ? undefined
         : (await readJsonlRecordsFrom(archiveFilePath())).find((s) => s.id === sessionId);
-    const candidates = [fromDb, fromJsonl, fromArchive].filter((r) => Boolean(r));
-    if (candidates.length === 0)
+    const candidates = [fromJsonl, fromDb, fromArchive].filter((record) => Boolean(record));
+    const freshest = freshestHistoryRecord(candidates);
+    if (!freshest)
         return undefined;
-    return sortHistoryByUpdatedDesc(candidates)[0];
+    // Heal split-brain stores on selection. This is especially important across
+    // upgrades where optional SQLite availability changes between launches.
+    if (!fromJsonl || compareHistoryFreshness(freshest, fromJsonl) > 0) {
+        await upsertJsonl(freshest);
+    }
+    if (db && (!fromDb || compareHistoryFreshness(freshest, fromDb) > 0)) {
+        upsertSqlite(db, freshest);
+        await enforceSqliteRetention(db);
+        invalidateSessionListCache();
+    }
+    return freshest;
 }
 export function getHistoryPath() {
     // Prefer JSONL as the durable path users can inspect/backup; SQLite is
     // optional acceleration when better-sqlite3 is installed.
     return jsonlFilePath();
 }
-/**
- * Clear active history after archiving a full snapshot. Never unrecoverably
- * destroys chats — a timestamped copy is written under history-backups/ and
- * the previous active file is moved into history-archive.jsonl.
- */
 export async function clearAllHistory() {
     let detail = "";
     await ensureHistoryRecovered();
-    // Snapshot + move aside. Do NOT write into history-archive.jsonl here —
-    // that file is auto-reimported by recoverOrphanedHistory, which would
-    // immediately undo a clear. Intentional clears go to history-cleared-*.jsonl
-    // (and rolling backups) only.
     try {
         const snapshot = await readJsonlRecordsFrom(jsonlFilePath());
         if (snapshot.length > 0) {