session-steward 0.9.0 → 0.10.1

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

@@ -31,6 +31,8 @@ const RECORD_CLASSIFICATION = Object.freeze({
 const SKIPPED_CONTENT_TYPES = new Set(["attachment", "image", "thinking"]);
 const SKIPPED_RECORD_TYPES = new Set([
   "attachment",
+  "atis-latch",
+  "bridge-session",
   "custom-title",
   "file-history-snapshot",
   "frame-link",

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

@@ -18,7 +18,7 @@ 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"],
+    claudeDesktop: ["1.24012.9", "1.28929.0", "1.32885.1", "1.40609.0"],
   },
 });
 const SUPPORTED_ENTRYPOINTS = new Set(["cli", "claude-desktop"]);
@@ -831,10 +831,18 @@ 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 });
-  const backupDirectory = await createBackup(plan, store, scope);
+  let backupDirectory;
   try {
-    if (shouldCancel()) { const error = new Error("Cleanup cancelled."); error.cancelled = true; error.backupDirectory = backupDirectory; throw error; }
+    backupDirectory = await createBackup(plan, store, scope);
+  } catch (error) {
+    error.mutationStarted = false;
+    throw error;
+  }
+  let mutationStarted = false;
+  try {
+    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 });
+    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));
@@ -852,6 +860,7 @@ export async function executeSessionDeletion({ onProgress = () => {}, plan, scop
     };
   } catch (error) {
     error.backupDirectory = backupDirectory;
+    error.mutationStarted ??= mutationStarted;
     throw error;
   }
 }

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

@@ -8,7 +8,7 @@ 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"],
+    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"],
   },
 });
@@ -53,6 +53,7 @@ const SCHEMA_REQUIREMENTS = Object.freeze({
     required: false,
     tables: [
       { name: "thread_items", requiredColumns: ["thread_id"] },
+      { name: "thread_realtime_items", optional: true, requiredColumns: ["thread_id"] },
       { name: "thread_turns", requiredColumns: ["thread_id"] },
       { name: "thread_history_projection_state", requiredColumns: ["thread_id"] },
     ],
@@ -91,7 +92,8 @@ function inspectCandidate(codexHome, filename, version, family) {
     );
     const invalidTable = family.tables.find((requirement) => {
       const table = tables[requirement.name];
-      return !table.exists || table.missingColumns.length > 0;
+      return (!table.exists && !requirement.optional) ||
+        (table.exists && table.missingColumns.length > 0);
     });
     return {
       filename,

package/lib/providers/codex/store.mjs

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { spawn } from "node:child_process";
 import { constants as fsConstants, createReadStream } from "node:fs";
 import { promises as fs } from "node:fs";
 import path from "node:path";
@@ -1515,6 +1516,7 @@ export async function loadDeletionStore({ codexHome, recordIds }) {
     stateDatabasePath: paths.stateDatabasePath,
     stateDatabasePaths: paths.stateDatabasePaths,
     stateDatabases: paths.stateDatabases,
+    threadWriterLocksDirectory: paths.threadWriterLocksDirectory,
     resolvedDatabases: paths.resolvedDatabases,
     logsDatabasePaths: paths.logsDatabasePaths,
     memoryDatabasePaths: paths.memoryDatabasePaths,
@@ -1902,6 +1904,24 @@ function* deleteStatements(tableName, columnName, ids) {
   }
 }
 
+const REQUIRED_THREAD_HISTORY_TABLES = Object.freeze([
+  "thread_items",
+  "thread_turns",
+  "thread_history_projection_state",
+]);
+const THREAD_HISTORY_TABLES_WITH_REALTIME = Object.freeze([
+  "thread_items",
+  "thread_realtime_items",
+  "thread_turns",
+  "thread_history_projection_state",
+]);
+
+function threadHistoryTables(databasePath) {
+  return inspectSqliteTable(databasePath, "thread_realtime_items").exists
+    ? THREAD_HISTORY_TABLES_WITH_REALTIME
+    : REQUIRED_THREAD_HISTORY_TABLES;
+}
+
 export async function planSessionDeletion({ recordIds, store }) {
   const idsToDelete = new Set();
   const pendingIds = [...recordIds];
@@ -1999,11 +2019,7 @@ export async function planSessionDeletion({ recordIds, store }) {
       ? countRowsForIds(databasePath, "queued_thread_revisions", "thread_id", deletionIds)
       : 0), 0);
   const threadHistoryRowCount = (store.threadHistoryDatabasePaths ?? [store.threadHistoryDatabasePath].filter(Boolean))
-    .reduce((total, databasePath) => total + [
-      "thread_items",
-      "thread_turns",
-      "thread_history_projection_state",
-    ].reduce((databaseTotal, tableName) =>
+    .reduce((total, databasePath) => total + threadHistoryTables(databasePath).reduce((databaseTotal, tableName) =>
       databaseTotal + countRowsForIds(databasePath, tableName, "thread_id", deletionIds), 0), 0);
   const stateTargets = (store.stateDatabases ?? [{ path: store.stateDatabasePath }]).map((database) => ({
     database,
@@ -2147,9 +2163,9 @@ export async function fingerprintSessionDeletion({ plan, scope, store }) {
     }
   }
   for (const databasePath of store.threadHistoryDatabasePaths ?? [store.threadHistoryDatabasePath].filter(Boolean)) {
-    fingerprintRowsForIds(hash, databasePath, "thread_items", "thread_id", plan.ids);
-    fingerprintRowsForIds(hash, databasePath, "thread_turns", "thread_id", plan.ids);
-    fingerprintRowsForIds(hash, databasePath, "thread_history_projection_state", "thread_id", plan.ids);
+    for (const tableName of threadHistoryTables(databasePath)) {
+      fingerprintRowsForIds(hash, databasePath, tableName, "thread_id", plan.ids);
+    }
   }
   if (scope === "deep") {
     for (const databasePath of store.memoryDatabasePaths ?? [store.memoryDatabasePath].filter(Boolean)) {
@@ -2219,6 +2235,108 @@ async function getAvailableDiskBytes(directoryPath) {
   return stats.bavail * stats.bsize;
 }
 
+const LOCK_PROBE_CONFLICT_EXIT_CODE = 75;
+const LOCK_PROBE_CONCURRENCY = 8;
+const LOCK_PROBE_TIMEOUT_MS = 5_000;
+const WINDOWS_LOCK_PROBE_SCRIPT = String.raw`
+$ErrorActionPreference = "Stop"
+$stream = $null
+try {
+  $stream = [System.IO.File]::Open(
+    $env:SESSION_STEWARD_WRITER_LOCK_PATH,
+    [System.IO.FileMode]::Open,
+    [System.IO.FileAccess]::ReadWrite,
+    ([System.IO.FileShare]::ReadWrite -bor [System.IO.FileShare]::Delete)
+  )
+  try {
+    $stream.Lock(0, 1)
+    $stream.Unlock(0, 1)
+    exit 0
+  } catch [System.IO.IOException] {
+    if (($_.Exception.HResult -band 0xffff) -eq 33) { exit 75 }
+    exit 70
+  }
+} catch [System.IO.FileNotFoundException] {
+  exit 66
+} catch [System.IO.DirectoryNotFoundException] {
+  exit 66
+} catch {
+  exit 70
+} finally {
+  if ($null -ne $stream) { $stream.Dispose() }
+}
+`;
+
+function runLockProbe(command, args, options = {}) {
+  return new Promise((resolve) => {
+    let settled = false;
+    let child;
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      resolve(result);
+    };
+    const timeout = setTimeout(() => {
+      child?.kill();
+      finish({ error: new Error("The writer-lock probe timed out."), exitCode: null });
+    }, LOCK_PROBE_TIMEOUT_MS);
+
+    try {
+      child = spawn(command, args, {
+        stdio: "ignore",
+        windowsHide: true,
+        ...options,
+      });
+    } catch (error) {
+      finish({ error, exitCode: null });
+      return;
+    }
+
+    child.once("error", (error) => finish({ error, exitCode: null }));
+    child.once("exit", (exitCode) => finish({ error: null, exitCode }));
+  });
+}
+
+async function probeWriterLock(lockPath) {
+  if (process.platform === "win32") {
+    const result = await runLockProbe(
+      "powershell.exe",
+      ["-NoLogo", "-NoProfile", "-NonInteractive", "-Command", WINDOWS_LOCK_PROBE_SCRIPT],
+      {
+        env: { ...process.env, SESSION_STEWARD_WRITER_LOCK_PATH: lockPath },
+      },
+    );
+    if (result.exitCode === 0) return "free";
+    if (result.exitCode === LOCK_PROBE_CONFLICT_EXIT_CODE) return "held";
+    if (result.exitCode === 66) return "missing";
+    return "unknown";
+  }
+
+  let handle;
+  try {
+    handle = await fs.open(lockPath, "r+");
+  } catch (error) {
+    if (error?.code === "ENOENT") return "missing";
+    return "unknown";
+  }
+
+  try {
+    const command = process.platform === "darwin" ? "/usr/bin/lockf" : "flock";
+    const args = process.platform === "darwin"
+      ? ["-s", "-t", "0", "3"]
+      : ["-n", "-E", String(LOCK_PROBE_CONFLICT_EXIT_CODE), "3"];
+    const result = await runLockProbe(command, args, {
+      stdio: ["ignore", "ignore", "ignore", handle.fd],
+    });
+    if (result.exitCode === 0) return "free";
+    if (result.exitCode === LOCK_PROBE_CONFLICT_EXIT_CODE) return "held";
+    return "unknown";
+  } finally {
+    await handle.close();
+  }
+}
+
 async function findActiveThreadIds(store, ids) {
   if (!store.threadWriterLocksDirectory) return { available: false, ids: [] };
 
@@ -2230,20 +2348,48 @@ async function findActiveThreadIds(store, ids) {
     throw error;
   }
 
-  const lockedIds = new Set(entries
+  const lockPathsById = new Map(entries
     .filter((entry) => entry.isFile() && entry.name.endsWith(".lock"))
-    .map((entry) => entry.name.slice(0, -5)));
+    .map((entry) => {
+      const id = entry.name.slice(0, -5);
+      return [id, path.join(store.threadWriterLocksDirectory, entry.name)];
+    }));
+  const candidates = ids.filter((id) => lockPathsById.has(id));
+  const states = new Array(candidates.length);
+  let nextIndex = 0;
+  await Promise.all(Array.from(
+    { length: Math.min(LOCK_PROBE_CONCURRENCY, candidates.length) },
+    async () => {
+      while (nextIndex < candidates.length) {
+        const index = nextIndex;
+        nextIndex += 1;
+        const id = candidates[index];
+        states[index] = { id, state: await probeWriterLock(lockPathsById.get(id)) };
+      }
+    },
+  ));
   return {
     available: true,
-    ids: ids.filter((id) => lockedIds.has(id)),
+    ids: states.filter(({ state }) => state === "held").map(({ id }) => id),
+    unverifiedIds: states.filter(({ state }) => state === "unknown").map(({ id }) => id),
   };
 }
 
 function activeThreadError(ids) {
   const error = new Error(
     ids.length === 1
-      ? "Close the selected Codex session before cleanup."
-      : `Close the ${ids.length} selected Codex sessions that are still open before cleanup.`,
+      ? "Quit ChatGPT or Codex completely before cleaning up the selected Codex session."
+      : `Quit ChatGPT or Codex completely before cleaning up the ${ids.length} selected Codex sessions that are still open.`,
+  );
+  error.activeThreadIds = ids;
+  return error;
+}
+
+function unverifiedThreadError(ids) {
+  const error = new Error(
+    ids.length === 1
+      ? "Session Steward could not verify whether the selected Codex session is still open. Try cleanup again."
+      : `Session Steward could not verify whether ${ids.length} selected Codex sessions are still open. Try cleanup again.`,
   );
   error.activeThreadIds = ids;
   return error;
@@ -2286,6 +2432,7 @@ export async function preflightSessionDeletion({ availableDiskBytes, plan, scope
 
   const activeThreads = await findActiveThreadIds(store, plan.ids);
   if (activeThreads.ids.length > 0) throw activeThreadError(activeThreads.ids);
+  if (activeThreads.unverifiedIds?.length > 0) throw unverifiedThreadError(activeThreads.unverifiedIds);
 
   const deletedIdSet = new Set(plan.ids);
   const desktopStates = await Promise.all([
@@ -2457,13 +2604,14 @@ async function createOperationBackup({ onProgress, plan, scope, store }) {
   return backupDirectory;
 }
 
-function cleanupErrorWithBackup(error, backupDirectory) {
+function cleanupErrorWithBackup(error, backupDirectory, { mutationStarted = false } = {}) {
   const detail = error instanceof Error ? error.message : "The cleanup could not be completed.";
   const wrappedError = new Error(
     `Cleanup stopped after the backup was created. Backup: ${backupDirectory}. ${detail}`,
     { cause: error },
   );
   wrappedError.backupDirectory = backupDirectory;
+  wrappedError.mutationStarted = mutationStarted;
   return wrappedError;
 }
 
@@ -2513,6 +2661,9 @@ export async function executeSessionDeletion({
   if (activeThreads.ids.length > 0) {
     throw cleanupErrorWithBackup(activeThreadError(activeThreads.ids), backupDirectory);
   }
+  if (activeThreads.unverifiedIds?.length > 0) {
+    throw cleanupErrorWithBackup(unverifiedThreadError(activeThreads.unverifiedIds), backupDirectory);
+  }
 
   await reportProgress(onProgress, {
     canCancel: false,
@@ -2553,11 +2704,8 @@ export async function executeSessionDeletion({
     }
     if (store.hasThreadHistoryDatabase) {
       for (const databasePath of store.threadHistoryDatabasePaths ?? [store.threadHistoryDatabasePath]) {
-        executeTransaction(databasePath, [
-          ...deleteStatements("thread_items", "thread_id", plan.ids),
-          ...deleteStatements("thread_turns", "thread_id", plan.ids),
-          ...deleteStatements("thread_history_projection_state", "thread_id", plan.ids),
-        ]);
+        executeTransaction(databasePath, threadHistoryTables(databasePath).flatMap((tableName) =>
+          [...deleteStatements(tableName, "thread_id", plan.ids)]));
       }
     }
     for (const { database, ids } of plan.stateTargets ?? (store.stateDatabases ?? [{ path: store.stateDatabasePath }]).map((database) => ({ database, ids: plan.ids }))) {
@@ -2655,7 +2803,7 @@ export async function executeSessionDeletion({
       skippedTranscriptPaths,
     };
   } catch (error) {
-    throw cleanupErrorWithBackup(error, backupDirectory);
+    throw cleanupErrorWithBackup(error, backupDirectory, { mutationStarted: true });
   }
 }
 
@@ -2930,11 +3078,9 @@ export async function verifySessionDeletion({ plan, scope = "deep", store }) {
     ])
     : [];
   const remainingThreadHistoryRecords = store.hasThreadHistoryDatabase
-    ? (store.threadHistoryDatabasePaths ?? [store.threadHistoryDatabasePath]).flatMap((databasePath) => [
-      ...findRowsForIds(databasePath, "thread_items", "thread_id", plan.ids, { limitOne: true }),
-      ...findRowsForIds(databasePath, "thread_turns", "thread_id", plan.ids, { limitOne: true }),
-      ...findRowsForIds(databasePath, "thread_history_projection_state", "thread_id", plan.ids, { limitOne: true }),
-    ])
+    ? (store.threadHistoryDatabasePaths ?? [store.threadHistoryDatabasePath]).flatMap((databasePath) =>
+      threadHistoryTables(databasePath).flatMap((tableName) =>
+        findRowsForIds(databasePath, tableName, "thread_id", plan.ids, { limitOne: true })))
     : [];
   const [sessionIndexMatches, historyMatches] = await Promise.all([
     inspectJsonlMatches(

package/lib/server.mjs

@@ -1,18 +1,23 @@
 import { createServer } from "node:http";
 import { randomBytes } from "node:crypto";
-import { execFileSync } from "node:child_process";
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { getProvider, listProviders } from "./providers/index.mjs";
+import { getInstalledProductVersions } from "./installed-products.mjs";
 import {
   DEFAULT_SESSION_EVENT_LIMIT,
   MAX_SESSION_EVENT_LIMIT,
 } from "./session-event-reader.mjs";
 import { createProviderSettings } from "./settings.mjs";
 import { classifyInstalledVersion } from "./version-support.mjs";
-import { getCommandInvocation } from "./platform.mjs";
+import {
+  acquireSessionMutationLock,
+  executePreparedSessionCleanup,
+  prepareSessionCleanup,
+  SESSION_CLEANUP_REVIEW_REQUIRED,
+} from "./session-cleanup.mjs";
 
 const MAX_BODY_BYTES = 64 * 1024;
 const ALLOWED_SCOPES = new Set(["core", "deep"]);
@@ -21,9 +26,9 @@ const OPERATION_TTL_MS = 60 * 60 * 1000;
 const MAX_SAVED_PLANS = 20;
 const MAX_SAVED_OPERATIONS = 50;
 const PLAN_RECORD_SAMPLE_LIMIT = 20;
-const PLAN_REVIEW_REQUIRED = "DELETION_PLAN_REVIEW_REQUIRED";
+const PLAN_REVIEW_REQUIRED = SESSION_CLEANUP_REVIEW_REQUIRED;
 const SESSION_OVERVIEW_TTL_MS = 45 * 1000;
-const ALLOWED_INACTIVE_DAYS = new Set([30, 60, 90]);
+const MAX_INACTIVE_DAYS = 3_650;
 const ALLOWED_ARCHIVE_STATUSES = new Set(["all", "active", "archived"]);
 const ALLOWED_SORTS = new Set(["created", "cwd", "name", "size", "updated"]);
 const publicDirectory = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "dist");
@@ -31,47 +36,6 @@ const staticAssets = new Map([
   ["/", { fileName: "index.html", contentType: "text/html; charset=utf-8" }],
 ]);
 
-function readCommandVersion(command, args) {
-  try {
-    const invocation = getCommandInvocation(command, args);
-    return execFileSync(invocation.command, invocation.args, {
-      encoding: "utf8",
-      stdio: ["ignore", "pipe", "ignore"],
-      windowsHide: invocation.windowsHide,
-    }).trim() || null;
-  } catch {
-    return null;
-  }
-}
-
-async function getInstalledProductVersions() {
-  const versions = {
-    chatgptDesktop: null,
-    claudeCli: readCommandVersion("claude", ["--version"]),
-    claudeDesktop: null,
-    codexCli: readCommandVersion("codex", ["--version"]),
-  };
-
-  if (process.platform !== "darwin") {
-    return versions;
-  }
-
-  const chatGptInfoPath = "/Applications/ChatGPT.app/Contents/Info.plist";
-  const claudeInfoPath = "/Applications/Claude.app/Contents/Info.plist";
-  try {
-    await fs.access(chatGptInfoPath);
-    versions.chatgptDesktop = readCommandVersion("/usr/libexec/PlistBuddy", ["-c", "Print :CFBundleShortVersionString", chatGptInfoPath]);
-  } catch {
-  }
-  try {
-    await fs.access(claudeInfoPath);
-    versions.claudeDesktop = readCommandVersion("/usr/libexec/PlistBuddy", ["-c", "Print :CFBundleShortVersionString", claudeInfoPath]);
-  } catch {
-  }
-
-  return versions;
-}
-
 function providerOptions(providerId, home) {
   return providerId === "codex" ? { codexHome: home } : { claudeHome: home };
 }
@@ -220,8 +184,8 @@ function getInactiveBeforeMs(value) {
 
   const days = Number(value);
 
-  if (!ALLOWED_INACTIVE_DAYS.has(days)) {
-    throw new Error("Last activity must be 30, 60, or 90 days.");
+  if (!Number.isSafeInteger(days) || days < 1 || days > MAX_INACTIVE_DAYS) {
+    throw new Error(`Last activity must be a whole number between 1 and ${MAX_INACTIVE_DAYS} days.`);
   }
 
   return Date.now() - days * 24 * 60 * 60 * 1000;
@@ -490,72 +454,26 @@ export async function startLocalServer({ claudeHome, codexHome, configDirectory,
     operation.phase = "preflight";
     operation.progress = 2;
 
+    let releaseMutationLock;
     try {
       const provider = getProvider(savedPlan.providerId);
       const options = providerOptions(savedPlan.providerId, savedPlan.home);
-      let currentStore;
-
-      try {
-        currentStore = await provider.loadDeletionStore({
-          ...options,
-          recordIds: savedPlan.requestedIds,
-        });
-      } catch (error) {
-        if (error?.message === "One or more selected sessions are no longer available.") {
-          throw codedError(
-            "The selected sessions changed after this preview. Review the selection again.",
-            PLAN_REVIEW_REQUIRED,
-          );
-        }
-        throw error;
-      }
-
-      const currentPlan = await provider.planSessionDeletion({
-        recordIds: savedPlan.requestedIds,
-        store: currentStore,
-      });
-      const currentFingerprint = await provider.fingerprintSessionDeletion({
-        plan: currentPlan,
-        scope: savedPlan.scope,
-        store: currentStore,
-      });
-
-      if (currentFingerprint !== savedPlan.fingerprint) {
-        throw codedError(
-          "Session data changed after this preview. Review the selection again.",
-          PLAN_REVIEW_REQUIRED,
-        );
-      }
-
-      await provider.preflightSessionDeletion({
-        plan: currentPlan,
-        scope: savedPlan.scope,
-        store: currentStore,
-      });
-
-      if (savedPlan.scope === "deep") {
-        await provider.assertDeepCleanupSupported(options);
-      }
-
-      const result = await provider.executeSessionDeletion({
+      releaseMutationLock = await acquireSessionMutationLock({ options, provider });
+      const execution = await executePreparedSessionCleanup({
+        expectedFingerprint: savedPlan.fingerprint,
         onProgress: (update) => Object.assign(operation, update),
-        plan: currentPlan,
+        options,
+        provider,
+        recordIds: savedPlan.requestedIds,
         scope: savedPlan.scope,
         shouldCancel: () => operation.cancelRequested,
-        store: currentStore,
       });
+      const result = execution.deletion;
       operation.backupDirectory = result.backupDirectory;
       operation.backupDirectories = [result.backupDirectory];
       operation.result = summarizeDeletionResult(result);
       operation.canCancel = false;
-      operation.message = "Checking that cleanup completed";
-      operation.phase = "verification";
-      operation.progress = 94;
-      const verification = await provider.verifySessionDeletion({
-        plan: currentPlan,
-        scope: savedPlan.scope,
-        store: currentStore,
-      });
+      const verification = execution.verification;
       operation.verification = summarizeVerification(verification);
       operation.progress = 100;
 
@@ -596,6 +514,9 @@ export async function startLocalServer({ claudeHome, codexHome, configDirectory,
         operation.status = "failed";
       }
     } finally {
+      const terminalStatus = operation.status;
+      operation.status = "running";
+      await releaseMutationLock?.().catch(() => {});
       getProvider(savedPlan.providerId).invalidateSessionCache?.(
         providerOptions(savedPlan.providerId, savedPlan.home),
       );
@@ -604,6 +525,7 @@ export async function startLocalServer({ claudeHome, codexHome, configDirectory,
       deletionPlans.delete(savedPlan.id);
       operation.finishedAtMs = Date.now();
       if (activeOperationId === operation.id) activeOperationId = null;
+      operation.status = terminalStatus;
     }
   }
 
@@ -653,10 +575,14 @@ export async function startLocalServer({ claudeHome, codexHome, configDirectory,
     operation.status = "restoring";
     activeOperationId = operation.id;
     const task = (async () => {
+      let releaseMutationLock;
       try {
-        const restoreResult = await getProvider(operation.providerId).restoreSessionDeletionBackup({
+        const provider = getProvider(operation.providerId);
+        const options = providerOptions(operation.providerId, operation.home);
+        releaseMutationLock = await acquireSessionMutationLock({ options, provider });
+        const restoreResult = await provider.restoreSessionDeletionBackup({
           backupDirectory: operation.backupDirectory,
-          ...providerOptions(operation.providerId, operation.home),
+          ...options,
           onProgress: (update) => Object.assign(operation, update),
         });
         operation.restoreResult = restoreResult;
@@ -685,12 +611,16 @@ export async function startLocalServer({ claudeHome, codexHome, configDirectory,
         operation.message = "Restore could not be completed";
         operation.status = "restore-failed";
       } finally {
+        const terminalStatus = operation.status;
+        operation.status = "restoring";
+        await releaseMutationLock?.().catch(() => {});
         getProvider(operation.providerId).invalidateSessionCache?.(
           providerOptions(operation.providerId, operation.home),
         );
         invalidateSessionOverview();
         operation.finishedAtMs = Date.now();
         if (activeOperationId === operation.id) activeOperationId = null;
+        operation.status = terminalStatus;
       }
     })();
     activeTasks.add(task);
@@ -935,26 +865,23 @@ export async function startLocalServer({ claudeHome, codexHome, configDirectory,
         const home = settings.getHome(providerId);
         const options = providerOptions(providerId, home);
 
-        if (scope === "deep") {
-          await provider.assertDeepCleanupSupported(options);
-        }
-
-        const store = await provider.loadDeletionStore({
-          ...options,
+        const prepared = await prepareSessionCleanup({
+          options,
+          provider,
           recordIds: ids,
+          scope,
         });
-        const plan = await provider.planSessionDeletion({ recordIds: ids, store });
-        const preflight = await provider.preflightSessionDeletion({ plan, scope, store });
+        const { plan, preflight } = prepared;
         const id = randomBytes(18).toString("base64url");
         const expiresAtMs = Date.now() + PLAN_TTL_MS;
         const savedPlan = {
           home,
           consumed: false,
           expiresAtMs,
-          fingerprint: await provider.fingerprintSessionDeletion({ plan, scope, store }),
+          fingerprint: prepared.fingerprint,
           id,
           providerId,
-          requestedIds: ids,
+          requestedIds: prepared.requestedIds,
           scope,
         };
         removeExpiredEntries(deletionPlans, PLAN_TTL_MS, MAX_SAVED_PLANS);
@@ -1043,17 +970,24 @@ export async function startLocalServer({ claudeHome, codexHome, configDirectory,
           }
 
           mutationInProgress = true;
+          let releaseMutationLock;
+          let responsePayload;
           try {
+            const provider = getProvider(operation.providerId);
+            const options = providerOptions(operation.providerId, operation.home);
+            releaseMutationLock = await acquireSessionMutationLock({ options, provider });
             if (!(await removeOperationBackups(operation))) {
               throw new Error("The recovery backup could not be deleted.");
             }
             operation.backupDeleteError = null;
             operation.canRestore = false;
             if (operation.result) operation.result.recoveryBackupDeleted = true;
-            sendJson(response, 200, { operation: publicOperation(operation) });
+            responsePayload = { operation: publicOperation(operation) };
           } finally {
+            await releaseMutationLock?.().catch(() => {});
             mutationInProgress = false;
           }
+          sendJson(response, 200, responsePayload);
           return;
         }