session-steward 0.10.2 → 0.11.0

package/lib/providers/claude-code/store.mjs

@@ -4,6 +4,7 @@ import { createReadStream, createWriteStream } from "node:fs";
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import { finished, pipeline } from "node:stream/promises";
+import lockfile from "proper-lockfile";
 
 import {
   expandHomePath,
@@ -12,19 +13,20 @@ import {
 } from "../../platform.mjs";
 import { measurePath } from "../../storage/files.mjs";
 import { readJsonlEntries, rewriteJsonlFile } from "../../storage/jsonl.mjs";
+import { claudeProcessState, localClaudePidDomain } from "./process-state.mjs";
 
 const PROVIDER_ID = "claude-code";
 const COMPATIBILITY_PROFILE = Object.freeze({
   id: "claude-local-store-2026-08",
   builtFor: {
-    claudeCli: ["2.1.199", "2.1.220", "2.1.228", "2.1.237"],
-    claudeDesktop: ["1.24012.9", "1.28929.0", "1.32885.1", "1.40609.0"],
+    claudeCli: ["2.1.199", "2.1.220", "2.1.228", "2.1.237", "2.1.267"],
+    claudeDesktop: ["1.24012.9", "1.28929.0", "1.32885.1", "1.40609.0", "1.49585.0"],
   },
 });
 const SUPPORTED_ENTRYPOINTS = new Set(["cli", "claude-desktop"]);
 const SHARED_DESKTOP_STATE_FILES = new Set(["scheduled-tasks.json"]);
 const KNOWN_TOP_LEVEL = new Set([
-  ".DS_Store", ".last-cleanup", ".last-update-result.json", "agents", "backups", "cache", "commands", "debug", "downloads", "file-history", "history.jsonl",
+  ".DS_Store", ".last-cleanup", ".last-update-result.json", "agents", "backups", "cache", "commands", "debug", "downloads", "file-history", "history.jsonl", "history.jsonl.lock",
   "ide", "paste-cache", "plans", "plugins", "projects", "session-env", "sessions", "settings.json",
   "settings.local.json", "shell-snapshots", "skills", "stats-cache.json", "tasks", "telemetry",
   "todos", "uploads", "usage-data", "mcp-needs-auth-cache.json", "session-steward-backups",
@@ -330,6 +332,26 @@ async function listDesktopStates(directory) {
   return { byCliSessionId, unlinked };
 }
 
+// Claude's project-level siblings. Do not use a broad session-ID prefix:
+// unknown suffixes and another session's files must remain untouched.
+function indexSessionSidecars(directory, entries) {
+  const byId = new Map();
+  for (const entry of entries) {
+    const id = /^(.*)\.(?:ccr-tip|precompact|desktop-released|dir-sync)\.json$/u.exec(entry.name)?.[1]
+      ?? /^(.*)-[0-9]{1,16}\.cast$/u.exec(entry.name)?.[1];
+    if (!id) continue;
+    const paths = byId.get(id) ?? [];
+    paths.push(path.join(directory, entry.name));
+    byId.set(id, paths);
+  }
+  return byId;
+}
+
+function sidecarsForTranscript(index, transcriptPath, id) {
+  // Conflicting transcript filenames/content do not establish ownership.
+  return path.basename(transcriptPath) === `${id}.jsonl` ? index.get(id) ?? [] : [];
+}
+
 async function discover(claudeHome, desktopDataHome) {
   const paths = getPaths(claudeHome, desktopDataHome);
   const desktop = await listDesktopStates(paths.desktopSessionsDirectory);
@@ -345,10 +367,12 @@ async function discover(claudeHome, desktopDataHome) {
     const projectDirectory = path.join(paths.projectsDirectory, projectEntry.name);
     let files;
     try { files = await fs.readdir(projectDirectory, { withFileTypes: true }); } catch { continue; }
+    const sidecars = indexSessionSidecars(projectDirectory, files);
     for (const file of files) {
       if (!file.isFile() || !file.name.endsWith(".jsonl")) continue;
       const fallbackId = file.name.slice(0, -6);
       const summary = await readTranscriptSummary(path.join(projectDirectory, file.name), fallbackId);
+      summary.sidecarPaths = sidecarsForTranscript(sidecars, summary.transcriptPath, summary.id);
       if (!SUPPORTED_ENTRYPOINTS.has(summary.entrypoint)) { unknown.push(summary.transcriptPath); continue; }
       const copies = summariesById.get(summary.id) ?? [];
       copies.push(summary); summariesById.set(summary.id, copies);
@@ -390,6 +414,7 @@ async function discover(claudeHome, desktopDataHome) {
       titleSource: cleanTitle(state?.title) ? "Desktop title" : (copies.find((item) => item.titleSource)?.titleSource || "session ID"),
       transcriptBytes: copies.reduce((sum, item) => sum + item.transcriptBytes, 0),
       transcriptPaths: copies.map((item) => item.transcriptPath),
+      sidecarPaths: copies.flatMap((item) => item.sidecarPaths),
       updatedAtMs: Math.max(...copies.map((item) => item.activityAtMs)),
     });
   }
@@ -421,6 +446,7 @@ export function invalidateSessionCache({ claudeHome, desktopDataHome }) {
 function filterRecords(records, options) {
   const search = String(options.search || "").trim().toLowerCase();
   return records.filter((record) => {
+    if (typeof options.recordFilter === "function" && !options.recordFilter(record)) return false;
     if (options.archiveStatus === "active" && record.archived) return false;
     if (options.archiveStatus === "archived" && !record.archived) return false;
     if (options.inactiveBeforeMs && (!record.updatedAtMs || record.updatedAtMs >= options.inactiveBeforeMs)) return false;
@@ -486,6 +512,14 @@ export async function getSessionOverview({ claudeHome, desktopDataHome, refresh
       storageTargets.add(path.join(path.dirname(target), record.id));
     });
     record.desktopStatePaths.forEach((target) => storageTargets.add(target));
+    for (const target of record.sidecarPaths) {
+      // Unknown directory/symlink layouts are not part of the recognized size.
+      const stats = await fs.lstat(target).catch((error) => {
+        if (error.code === "ENOENT") return null;
+        throw error;
+      });
+      if (stats?.isFile()) storageTargets.add(target);
+    }
     storageTargets.add(path.join(store.paths.sessionEnvDirectory, record.id));
     storageTargets.add(path.join(store.paths.tasksDirectory, record.id));
     storageTargets.add(path.join(store.paths.debugDirectory, `${record.id}.txt`));
@@ -607,6 +641,15 @@ export async function planSessionDeletion({ recordIds, store }) {
   for (const record of records) {
     record.transcriptPaths.forEach((item) => selectedPaths.add(item));
     record.desktopStatePaths.forEach((item) => selectedPaths.add(item));
+    for (const target of record.sidecarPaths) {
+      const stats = await fs.lstat(target).catch((error) => {
+        if (error.code === "ENOENT") return null;
+        throw error;
+      });
+      if (!stats) continue;
+      if (!stats.isFile()) throw new Error("Cleanup stopped because a Claude session sidecar is not a regular file. It was left unchanged.");
+      selectedPaths.add(target);
+    }
     for (const candidate of [
       path.join(store.paths.sessionEnvDirectory, record.id),
       path.join(store.paths.tasksDirectory, record.id),
@@ -656,34 +699,79 @@ export async function planSessionDeletion({ recordIds, store }) {
   };
 }
 
-async function activeSessionIds(paths) {
+async function activeSessionIds(paths, selectedIds) {
   const active = new Set();
-  if (!(await exists(paths.sessionsDirectory))) return { active, detection: "unavailable" };
+  const unverified = new Set();
+  const selected = new Set(selectedIds);
+  const pidDomain = await localClaudePidDomain();
+  const buffer = Buffer.alloc(256 * 1024 + 1);
   const pending = [paths.sessionsDirectory];
   while (pending.length) {
     const current = pending.pop();
     let entries;
-    try { entries = await fs.readdir(current, { withFileTypes: true }); } catch { continue; }
+    try { entries = await fs.readdir(current, { withFileTypes: true }); } catch (error) {
+      if (error.code === "ENOENT") continue;
+      for (const id of selected) unverified.add(id);
+      continue;
+    }
     for (const entry of entries) {
       const target = path.join(current, entry.name);
       if (entry.isDirectory()) { pending.push(target); continue; }
-      const match = /([0-9a-f]{8}-[0-9a-f-]{27,})/iu.exec(entry.name);
-      if (match) active.add(match[1]);
-      if (!entry.name.endsWith(".json")) continue;
+      const nameId = /([0-9a-f]{8}-[0-9a-f-]{27,})/iu.exec(entry.name)?.[1];
+      const filenamePid = /^([1-9]\d*)\.json$/u.exec(entry.name)?.[1];
+      if (!entry.isFile()) {
+        if (selected.has(nameId)) unverified.add(nameId);
+        else if (filenamePid) for (const id of selected) unverified.add(id);
+        continue;
+      }
+      if (!entry.name.endsWith(".json")) {
+        if (selected.has(nameId)) unverified.add(nameId);
+        continue;
+      }
+      let parsed;
       try {
-        const parsed = JSON.parse(await fs.readFile(target, "utf8"));
-        const id = parsed.sessionId ?? parsed.session_id;
-        if (typeof id === "string" && !["stopped", "completed", "failed"].includes(parsed.status ?? parsed.state)) active.add(id);
-      } catch {}
+        // Registry metadata is small; do not read an arbitrary large file.
+        const handle = await fs.open(target, "r");
+        try {
+          const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+          if (bytesRead === buffer.length) throw new Error("Oversized session marker.");
+          parsed = JSON.parse(buffer.toString("utf8", 0, bytesRead));
+          if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("Invalid session marker.");
+        } finally { await handle.close(); }
+      } catch (error) {
+        if (error.code === "ENOENT") continue;
+        if (selected.has(nameId)) unverified.add(nameId);
+        else if (filenamePid && await claudeProcessState({ pid: Number(filenamePid) }) !== "inactive") {
+          for (const id of selected) unverified.add(id);
+        }
+        continue;
+      }
+      const id = parsed.sessionId ?? parsed.session_id ?? nameId;
+      if (selected.has(nameId) && id !== nameId) unverified.add(nameId);
+      if (!selected.has(id)) continue;
+      const pid = parsed.pid ?? (filenamePid ? Number(filenamePid) : undefined);
+      if (filenamePid && parsed.pid !== undefined && parsed.pid !== Number(filenamePid)) {
+        unverified.add(id);
+        continue;
+      }
+      if (pid === undefined && ["stopped", "completed", "failed"].includes(parsed.status ?? parsed.state)) continue;
+      const state = await claudeProcessState({ ...parsed, pid }, { pidDomain });
+      if (state === "active") active.add(id);
+      if (state === "unverified") unverified.add(id);
     }
   }
-  return { active, detection: "available" };
+  return { active, unverified, detection: await exists(paths.sessionsDirectory) ? "available" : "unavailable" };
+}
+
+async function assertSelectedSessionsClosed(paths, ids) {
+  const result = await activeSessionIds(paths, ids);
+  if (result.active.size) throw new Error("Close the selected Claude sessions before cleanup.");
+  if (result.unverified.size) throw new Error("Could not verify whether the selected Claude sessions are closed. Their process markers could not be checked safely; retry cleanup after Claude has exited.");
+  return result;
 }
 
 export async function preflightSessionDeletion({ availableDiskBytes, plan, scope, store }) {
-  const active = await activeSessionIds(store.paths);
-  const selectedActive = plan.ids.filter((id) => active.active.has(id));
-  if (selectedActive.length) throw new Error("Close the selected Claude sessions before cleanup.");
+  const active = await assertSelectedSessionsClosed(store.paths, plan.ids);
   const deepBytes = scope === "deep" ? plan.deepFiles.reduce((sum, file) => sum + file.size, 0) : 0;
   const estimatedBackupBytes = plan.transcriptBytes + deepBytes + plan.historyMatchBytes + 4096;
   let diskBytes = availableDiskBytes;
@@ -784,7 +872,42 @@ async function backupHistoryRows(historyPath, destination, ids) {
   }
 }
 
-async function createBackup(plan, store, scope) {
+// Claude's prompt-history writer uses proper-lockfile with a 10-second stale
+// threshold. Use the same canonical path, directory lock and heartbeat rather
+// than Session Steward's separate mutation lock (which Claude does not know).
+async function lockHistory(historyPath) {
+  const canonicalPath = path.join(await fs.realpath(path.dirname(historyPath)), path.basename(historyPath));
+  const stats = await fs.lstat(canonicalPath).catch((error) => {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  });
+  if (stats && !stats.isFile()) throw new Error("Claude prompt history is not a regular file. It was left unchanged.");
+  let compromised;
+  let released = false;
+  const release = await lockfile.lock(canonicalPath, {
+    realpath: false, // Restore also needs to lock history that does not exist yet.
+    stale: 10_000,
+    retries: { retries: 3, minTimeout: 50 },
+    onCompromised: (error) => { compromised = error; },
+  }).catch((error) => {
+    if (error.code === "ELOCKED") {
+      throw new Error("Claude prompt history is busy. Retry cleanup or restore in a moment.", { cause: error });
+    }
+    throw error;
+  });
+  return {
+    assertHeld() {
+      if (compromised) throw new Error("Claude prompt-history lock was lost. No further history changes were made.", { cause: compromised });
+    },
+    async release() {
+      if (released) return;
+      released = true;
+      if (!compromised) await release();
+    },
+  };
+}
+
+async function createBackup(plan, store, scope, acquireHistoryLock) {
   const backupDirectory = path.join(store.paths.backupRoot, `${new Date().toISOString().replaceAll(":", "-")}-${randomBytes(6).toString("hex")}`);
   const entries = [];
   await fs.mkdir(backupDirectory, { mode: 0o700, recursive: true });
@@ -802,6 +925,9 @@ async function createBackup(plan, store, scope) {
     }
     const sharedJsonl = [];
     if (plan.historyMatchCount) {
+      // Do not block other sessions while the large transcript copies run.
+      // Keep this lock from the history backup through its replacement.
+      await acquireHistoryLock();
       const backupRelative = path.join("shared", "history.jsonl");
       const destination = path.join(backupDirectory, backupRelative);
       await backupHistoryRows(store.paths.historyPath, destination, new Set(plan.ids));
@@ -832,21 +958,25 @@ async function createBackup(plan, store, scope) {
 export async function executeSessionDeletion({ onProgress = () => {}, plan, scope, shouldCancel = () => false, store }) {
   onProgress({ canCancel: true, message: "Creating recovery backup", phase: "backup", progress: 8 });
   let backupDirectory;
-  try {
-    backupDirectory = await createBackup(plan, store, scope);
-  } catch (error) {
-    error.mutationStarted = false;
-    throw error;
-  }
+  let historyLock;
   let mutationStarted = false;
   try {
+    backupDirectory = await createBackup(plan, store, scope, async () => {
+      historyLock = await lockHistory(store.paths.historyPath);
+    });
     if (shouldCancel()) { const error = new Error("Cleanup cancelled."); error.cancelled = true; error.backupDirectory = backupDirectory; error.mutationStarted = false; throw error; }
     onProgress({ canCancel: false, message: "Removing selected session data", phase: "cleanup", progress: 55 });
+    await assertSelectedSessionsClosed(store.paths, plan.ids);
+    historyLock?.assertHeld();
     mutationStarted = true;
     if (plan.historyMatchCount && await exists(store.paths.historyPath)) {
       const ids = new Set(plan.ids);
-      await rewriteJsonlFile(store.paths.historyPath, (entry) => !entry.parsed || !ids.has(entry.parsed.sessionId ?? entry.parsed.session_id));
+      await rewriteJsonlFile(store.paths.historyPath, (entry) => !entry.parsed || !ids.has(entry.parsed.sessionId ?? entry.parsed.session_id), {
+        beforeCommit: () => historyLock.assertHeld(),
+      });
     }
+    await historyLock?.release();
+    historyLock = null;
     const targets = [...plan.transcriptPaths];
     if (scope === "deep") targets.push(...plan.deepPaths);
     for (const target of [...new Set(targets)].sort((a, b) => b.length - a.length)) await fs.rm(target, { force: true, recursive: true });
@@ -859,9 +989,18 @@ export async function executeSessionDeletion({ onProgress = () => {}, plan, scop
       unrecognizedLocationCount: plan.unrecognizedLocationCount,
     };
   } catch (error) {
-    error.backupDirectory = backupDirectory;
+    error.backupDirectory ??= backupDirectory;
+    backupDirectory = error.backupDirectory;
     error.mutationStarted ??= mutationStarted;
     throw error;
+  } finally {
+    try {
+      await historyLock?.release();
+    } catch (error) {
+      error.backupDirectory = backupDirectory;
+      error.mutationStarted = mutationStarted;
+      throw error;
+    }
   }
 }
 
@@ -869,6 +1008,23 @@ export async function verifySessionDeletion({ plan, scope, store }) {
   const remainingTranscriptPaths = [];
   for (const target of plan.transcriptPaths) if (await exists(target)) remainingTranscriptPaths.push(target);
   if (scope === "deep") for (const target of plan.deepPaths) if (await exists(target)) remainingTranscriptPaths.push(target);
+  // Also catch known sidecars created/recreated after the selection was planned.
+  const sidecarsByDirectory = new Map();
+  for (const record of plan.records) {
+    for (const transcriptPath of record.transcriptPaths) {
+      const directory = path.dirname(transcriptPath);
+      if (!sidecarsByDirectory.has(directory)) {
+        const entries = await fs.readdir(directory, { withFileTypes: true }).catch((error) => {
+          if (error.code === "ENOENT") return [];
+          throw error;
+        });
+        sidecarsByDirectory.set(directory, indexSessionSidecars(directory, entries));
+      }
+      for (const target of sidecarsForTranscript(sidecarsByDirectory.get(directory), transcriptPath, record.id)) {
+        if (!remainingTranscriptPaths.includes(target)) remainingTranscriptPaths.push(target);
+      }
+    }
+  }
   const remainingHistoryEntryCount = (await matchingHistoryStats(store.paths.historyPath, new Set(plan.ids))).count;
   return {
     complete: remainingTranscriptPaths.length === 0 && remainingHistoryEntryCount === 0,
@@ -974,14 +1130,21 @@ export async function restoreSessionDeletionBackup({ backupDirectory, claudeHome
         const id = row.parsed?.sessionId ?? row.parsed?.session_id;
         if (typeof id === "string") selectedIds.add(id);
       }
-      if (await exists(destination)) {
-        const safety = path.join(safetyBackupDirectory, entry.root, entry.relative);
-        await copyTarget(destination, safety);
-        await rewriteJsonlFile(destination, (row) => !row.parsed || !selectedIds.has(row.parsed.sessionId ?? row.parsed.session_id));
-      } else {
-        await fs.mkdir(path.dirname(destination), { recursive: true });
+      await fs.mkdir(path.dirname(destination), { recursive: true });
+      const historyLock = await lockHistory(destination);
+      try {
+        if (await exists(destination)) {
+          const safety = path.join(safetyBackupDirectory, entry.root, entry.relative);
+          await copyTarget(destination, safety);
+          await rewriteJsonlFile(destination, (row) => !row.parsed || !selectedIds.has(row.parsed.sessionId ?? row.parsed.session_id), {
+            beforeCommit: () => historyLock.assertHeld(),
+          });
+        }
+        historyLock.assertHeld();
+        await pipeline(createReadStream(source), createWriteStream(destination, { flags: "a", mode: 0o600 }));
+      } finally {
+        await historyLock.release();
       }
-      await pipeline(createReadStream(source), createWriteStream(destination, { flags: "a", mode: 0o600 }));
     }
     onProgress({ message: "Checking restored sessions", progress: 92 });
     const layoutChanged = manifest.version === 2 && (

package/lib/providers/codex/database-families.mjs

@@ -8,8 +8,8 @@ const CACHE_TTL_MS = 2_000;
 export const CODEX_DATABASE_PROFILE = Object.freeze({
   id: "codex-local-store-2026-08",
   builtFor: {
-    chatgptDesktop: ["26.727.40816", "26.803.61601", "26.818.21641", "26.818.22352", "26.825.41651"],
-    codexCli: ["0.144.1", "0.146.0", "0.147.0", "0.148.0"],
+    chatgptDesktop: ["26.727.40816", "26.803.61601", "26.818.21641", "26.818.22352", "26.825.41651", "26.903.61454", "26.903.71938"],
+    codexCli: ["0.144.1", "0.146.0", "0.147.0", "0.148.0", "0.153.4", "0.154.0"],
   },
 });
 

package/lib/providers/codex/desktop-catalog.mjs

@@ -0,0 +1,179 @@
+import { lstatSync } from "node:fs";
+import path from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { batches, placeholders } from "../../storage/sqlite.mjs";
+
+const FILENAMES = ["codex.db", "codex-dev.db"];
+const TABLE = "local_thread_catalog";
+const SCAN_TABLE = "local_thread_catalog_scan_entries";
+const REQUIREMENTS = {
+  [TABLE]: ["host_id", "thread_id", "observation_sequence", "missing_candidate"],
+  [SCAN_TABLE]: ["host_id", "thread_id", "removed"],
+  local_thread_catalog_hosts: ["host_id", "host_kind"],
+  local_thread_catalog_metadata: ["id", "catalog_revision"],
+  local_thread_catalog_scan_checkpoints: ["host_id", "checkpoint"],
+  local_thread_catalog_sync_state: ["host_id", "observation_sequence"],
+};
+
+function regularPath(filePath, directory = false) {
+  try {
+    const stats = lstatSync(filePath);
+    if (directory ? !stats.isDirectory() : !stats.isFile()) {
+      throw new Error("The Codex desktop catalogue path is not a regular file or directory. It was left unchanged.");
+    }
+    return true;
+  } catch (error) {
+    if (error.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+function catalogPath(codexHome, filename) {
+  if (!FILENAMES.includes(filename)) throw new Error("Unrecognized Codex desktop catalogue backup.");
+  const directory = path.join(codexHome, "sqlite");
+  return regularPath(directory, true) ? path.join(directory, filename) : null;
+}
+
+function schema(db) {
+  if (!db.prepare("select 1 from sqlite_master where type = 'table' and name = ?").get(TABLE)) return null;
+  const columns = {};
+  for (const [table, required] of Object.entries(REQUIREMENTS)) {
+    const info = db.prepare(`pragma table_info(${table})`).all();
+    columns[table] = info.map((column) => column.name);
+    if (!required.every((name) => columns[table].includes(name))
+      || ([TABLE, SCAN_TABLE].includes(table)
+        && info.filter((column) => column.pk).sort((a, b) => a.pk - b.pk).map((column) => column.name).join() !== "host_id,thread_id")) {
+      throw new Error("The Codex desktop catalogue layout is not recognized. Cleanup stopped without changing it.");
+    }
+  }
+  const host = db.prepare("select host_kind from local_thread_catalog_hosts where host_id = 'local'").get();
+  const hasLocalRows = db.prepare(`select 1 from ${TABLE} where host_id = 'local' limit 1`).get();
+  if ((host && host.host_kind !== "local") || (hasLocalRows && !host)) {
+    throw new Error("The Codex desktop catalogue local host could not be verified.");
+  }
+  if (!db.prepare("select 1 from local_thread_catalog_metadata where id = 1").get()) {
+    throw new Error("The Codex desktop catalogue revision is missing.");
+  }
+  return columns;
+}
+
+function selectedRows(db, table, ids) {
+  return [...batches([...new Set(ids)].sort())].flatMap((batch) => db.prepare(
+    `select * from ${table} where host_id = 'local' and thread_id in (${placeholders(batch)}) order by thread_id`,
+  ).all(...batch));
+}
+
+function snapshot(db, filename, ids) {
+  const columns = schema(db);
+  return columns ? {
+    filename,
+    columns: columns[TABLE],
+    rows: selectedRows(db, TABLE, ids),
+    scanRows: selectedRows(db, SCAN_TABLE, ids),
+  } : null;
+}
+
+// Only known app-owned databases beneath this run's Codex home, never a
+// process-global/default home or arbitrary database supplied by a backup.
+export function readDesktopCatalogs(codexHome, ids) {
+  const result = [];
+  for (const filename of FILENAMES) {
+    const filePath = catalogPath(codexHome, filename);
+    if (!filePath || !regularPath(filePath)) continue;
+    const db = new DatabaseSync(filePath, { readOnly: true, timeout: 5_000 });
+    try {
+      db.exec("begin");
+      const entry = snapshot(db, filename, ids);
+      if (entry) result.push(entry);
+    } finally { db.close(); }
+  }
+  return result;
+}
+
+function transaction(codexHome, entry, callback) {
+  const filePath = catalogPath(codexHome, entry.filename);
+  if (!filePath || !regularPath(filePath)) throw new Error("The Codex desktop catalogue disappeared. Restart cleanup after refreshing.");
+  const db = new DatabaseSync(filePath, { timeout: 5_000 });
+  try {
+    db.exec("begin immediate");
+    const columns = schema(db);
+    if (!columns) throw new Error("The Codex desktop catalogue layout changed.");
+    callback(db, columns);
+    db.exec("commit");
+  } catch (error) {
+    if (db.isTransaction) db.exec("rollback");
+    throw error;
+  } finally { db.close(); }
+}
+
+export function deleteDesktopCatalogs(codexHome, ids, backup) {
+  if (JSON.stringify(readDesktopCatalogs(codexHome, ids)) !== JSON.stringify(backup)) {
+    throw new Error("The selected Codex desktop catalogue entries changed after backup. Refresh and try again.");
+  }
+  for (const entry of backup) {
+    transaction(codexHome, entry, (db) => {
+      if (JSON.stringify(snapshot(db, entry.filename, ids)) !== JSON.stringify(entry)) {
+        throw new Error("The selected Codex desktop catalogue entries changed after backup. Refresh and try again.");
+      }
+      if (entry.rows.length === 0) return;
+      // Match the app's authoritative-removal behavior: an in-flight scan
+      // must not reinsert an entry from a page fetched before deletion.
+      db.prepare("update local_thread_catalog_sync_state set observation_sequence = observation_sequence + 1 where host_id = 'local'").run();
+      for (const batch of batches(entry.rows.map((row) => row.thread_id))) {
+        // Also protect a scan whose first page is still in flight (it has no
+        // persisted checkpoint yet). The app clears these at the next scan.
+        const tombstone = db.prepare(`insert into ${SCAN_TABLE} (host_id, thread_id, removed) values ('local', ?, 1)
+          on conflict(host_id, thread_id) do update set removed = 1`);
+        for (const id of batch) tombstone.run(id);
+        db.prepare(`delete from ${TABLE} where host_id = 'local' and thread_id in (${placeholders(batch)})`).run(...batch);
+      }
+      db.prepare("update local_thread_catalog_metadata set catalog_revision = catalog_revision + 1 where id = 1").run();
+    });
+  }
+}
+
+export function validateDesktopCatalogBackup(codexHome, ids, backup) {
+  if (!Array.isArray(backup)) throw new Error("Invalid Codex desktop catalogue backup.");
+  const allowed = new Set(ids);
+  const names = new Set();
+  for (const entry of backup) {
+    if (!FILENAMES.includes(entry?.filename) || names.has(entry.filename)
+      || !Array.isArray(entry.columns) || !Array.isArray(entry.rows) || !Array.isArray(entry.scanRows)
+      || ![...entry.rows, ...entry.scanRows].every((row) => row.host_id === "local" && allowed.has(row.thread_id))) {
+      throw new Error("Invalid Codex desktop catalogue backup.");
+    }
+    names.add(entry.filename);
+    if (entry.rows.length === 0) continue;
+    transaction(codexHome, entry, (_db, columns) => {
+      if (JSON.stringify(columns[TABLE]) !== JSON.stringify(entry.columns)
+        || entry.rows.some((row) => Object.keys(row).join() !== entry.columns.join())
+        || entry.scanRows.some((row) => Object.keys(row).join() !== columns[SCAN_TABLE].join())) {
+        throw new Error("The Codex desktop catalogue schema changed since backup. Its rows were left unchanged.");
+      }
+    });
+  }
+}
+
+export function restoreDesktopCatalogs(codexHome, ids, backup) {
+  validateDesktopCatalogBackup(codexHome, ids, backup);
+  for (const entry of backup) {
+    if (entry.rows.length === 0) continue;
+    transaction(codexHome, entry, (db, columns) => {
+      if (JSON.stringify(columns[TABLE]) !== JSON.stringify(entry.columns)) throw new Error("The Codex desktop catalogue schema changed during restore.");
+      const quoted = entry.columns.map((column) => `"${column.replaceAll('"', '""')}"`).join(", ");
+      const insert = db.prepare(`insert into ${TABLE} (${quoted}) values (${placeholders(entry.columns)}) on conflict(host_id, thread_id) do nothing`);
+      const restored = [];
+      for (const row of entry.rows) {
+        if (insert.run(...entry.columns.map((column) => row[column])).changes) restored.push(row.thread_id);
+      }
+      // Merge selected rows only: never restore the entire app database or
+      // overwrite a newer entry, other hosts, settings, or scan checkpoints.
+      for (const id of restored) {
+        const prior = entry.scanRows.find((row) => row.thread_id === id);
+        db.prepare(`delete from ${SCAN_TABLE} where host_id = 'local' and thread_id = ?`).run(id);
+        if (prior) db.prepare(`insert into ${SCAN_TABLE} (host_id, thread_id, removed) values ('local', ?, ?)`).run(id, prior.removed);
+      }
+      if (restored.length) db.prepare("update local_thread_catalog_metadata set catalog_revision = catalog_revision + 1 where id = 1").run();
+    });
+  }
+}