session-steward 0.1.1 → 0.3.0

package/lib/server.mjs

@@ -5,25 +5,10 @@ import { promises as fs } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
-import { getProvider } from "./providers/index.mjs";
+import { getProvider, listProviders } from "./providers/index.mjs";
 import { createProviderSettings } from "./settings.mjs";
 import { classifyInstalledVersion } from "./version-support.mjs";
 
-const {
-  assertDeepCleanupSupported,
-  formatSessionForJson,
-  executeSessionDeletion,
-  fingerprintSessionDeletion,
-  diagnoseStorageCompatibility,
-  getSessionRecord,
-  listSessions,
-  loadDeletionStore,
-  planSessionDeletion,
-  preflightSessionDeletion,
-  restoreSessionDeletionBackup,
-  verifySessionDeletion,
-} = getProvider("codex");
-
 const MAX_BODY_BYTES = 64 * 1024;
 const ALLOWED_SCOPES = new Set(["core", "deep"]);
 const PLAN_TTL_MS = 10 * 60 * 1000;
@@ -32,6 +17,10 @@ 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 SESSION_OVERVIEW_TTL_MS = 45 * 1000;
+const ALLOWED_INACTIVE_DAYS = new Set([30, 60, 90]);
+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");
 const staticAssets = new Map([
   ["/", { fileName: "index.html", contentType: "text/html; charset=utf-8" }],
@@ -46,22 +35,43 @@ function readCommandVersion(command, args) {
 }
 
 async function getInstalledProductVersions() {
-  const versions = { chatgptDesktop: null, codexCli: readCommandVersion("codex", ["--version"]) };
+  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 };
+}
+
+function resolveProviderId(value) {
+  const providerId = value || "codex";
+  getProvider(providerId);
+  return providerId;
+}
+
 function getStaticAsset(requestPath) {
   const knownAsset = staticAssets.get(requestPath);
 
@@ -164,6 +174,40 @@ function getPositiveInteger(value, fallback, maximum = Number.MAX_SAFE_INTEGER)
   return Math.min(parsed, maximum);
 }
 
+function getInactiveBeforeMs(value) {
+  if (value === null || value === "") {
+    return null;
+  }
+
+  const days = Number(value);
+
+  if (!ALLOWED_INACTIVE_DAYS.has(days)) {
+    throw new Error("Last activity must be 30, 60, or 90 days.");
+  }
+
+  return Date.now() - days * 24 * 60 * 60 * 1000;
+}
+
+function getArchiveStatus(value) {
+  const status = value || "all";
+
+  if (!ALLOWED_ARCHIVE_STATUSES.has(status)) {
+    throw new Error("Session status must be all, active, or archived.");
+  }
+
+  return status;
+}
+
+function getSort(value) {
+  const sort = value || "updated";
+
+  if (!ALLOWED_SORTS.has(sort)) {
+    throw new Error("Session order is not available.");
+  }
+
+  return sort;
+}
+
 function getLocalRequestOrigin({ hostHeader, server }) {
   if (typeof hostHeader !== "string") {
     return null;
@@ -196,7 +240,15 @@ function requireMutationAuthorization({ request, requestUrl, token }) {
   }
 }
 
-function summarizePlan(plan, preflight) {
+function summarizePlan(plan, preflight, scope) {
+  const relatedRecordCount = plan.historyMatchCount
+    + plan.sessionIndexMatchCount
+    + plan.logRowCount
+    + plan.spawnEdgeCount
+    + (scope === "deep"
+      ? plan.goalRowCount + plan.memoryRowCount + preflight.desktopStateMatchCount
+      : 0);
+
   return {
     availableDiskBytes: preflight.availableDiskBytes,
     childCount: plan.childCount,
@@ -208,6 +260,7 @@ function summarizePlan(plan, preflight) {
     logRowCount: plan.logRowCount,
     memoryRowCount: plan.memoryRowCount,
     missingTranscriptCount: plan.missingTranscriptPaths.length,
+    newestLinkedActivityAtMs: plan.newestLinkedActivityAtMs,
     recordSamples: plan.records.slice(0, PLAN_RECORD_SAMPLE_LIMIT).map((record) => ({
       displayName: record.displayName,
       id: record.id,
@@ -215,7 +268,9 @@ function summarizePlan(plan, preflight) {
     sessionIndexMatchCount: plan.sessionIndexMatchCount,
     sessionCount: plan.ids.length,
     spawnEdgeCount: plan.spawnEdgeCount,
-    transcriptCount: plan.transcriptPaths.length,
+    relatedRecordCount,
+    transcriptBytes: preflight.transcriptBytes ?? plan.transcriptBytes,
+    transcriptCount: preflight.transcriptFileCount ?? plan.transcriptFileCount,
   };
 }
 
@@ -235,9 +290,9 @@ function summarizeVerification(verification) {
 
 function summarizeDeletionResult(result) {
   return {
-    backupDirectory: result.backupDirectory,
     deletedSessionCount: result.deletedIds.length,
     deletedTranscriptCount: result.deletedTranscriptPaths.length,
+    recoveryBackupDeleted: false,
     skippedTranscriptCount: result.skippedTranscriptPaths.length,
   };
 }
@@ -245,7 +300,9 @@ function summarizeDeletionResult(result) {
 function publicOperation(operation) {
   return {
     backupDirectory: operation.backupDirectory ?? null,
+    backupDeleteError: operation.backupDeleteError ?? null,
     canCancel: Boolean(operation.canCancel),
+    canDeleteBackup: Boolean(operation.canDeleteBackup),
     canRestore: Boolean(operation.canRestore),
     cancelRequested: Boolean(operation.cancelRequested),
     error: operation.error ?? null,
@@ -276,14 +333,17 @@ function removeExpiredEntries(entries, ttlMs, maximum) {
   }
 }
 
-export async function startLocalServer({ codexHome, configDirectory, port = 0 }) {
+export async function startLocalServer({ claudeHome, codexHome, configDirectory, port = 0 }) {
   if (!Number.isInteger(port) || port < 0 || port > 65535) {
     throw new Error("port must be an integer between 0 and 65535.");
   }
 
   const settings = await createProviderSettings({
     configDirectory,
-    providerHomeOverrides: codexHome === undefined ? {} : { codex: codexHome },
+    providerHomeOverrides: {
+      ...(codexHome === undefined ? {} : { codex: codexHome }),
+      ...(claudeHome === undefined ? {} : { "claude-code": claudeHome }),
+    },
   });
   const mutationToken = randomBytes(32).toString("base64url");
   let mutationInProgress = false;
@@ -291,6 +351,63 @@ export async function startLocalServer({ codexHome, configDirectory, port = 0 })
   const deletionPlans = new Map();
   const operations = new Map();
   const activeTasks = new Set();
+  let overviewCache = null;
+
+  function invalidateSessionOverview() {
+    overviewCache = null;
+  }
+
+  async function readSessionOverview({ providerId, refresh = false } = {}) {
+    const home = settings.getHome(providerId);
+
+    if (
+      !refresh
+      && overviewCache?.providerId === providerId
+      && overviewCache?.home === home
+      && overviewCache.expiresAtMs > Date.now()
+    ) {
+      return overviewCache.overview;
+    }
+
+    const overview = await getProvider(providerId).getSessionOverview({
+      ...providerOptions(providerId, home),
+      refresh,
+    });
+    overviewCache = {
+      home,
+      providerId,
+      expiresAtMs: Date.now() + SESSION_OVERVIEW_TTL_MS,
+      overview,
+    };
+    return overview;
+  }
+
+  async function removeOperationBackups(operation, additionalDirectories = []) {
+    const provider = getProvider(operation.providerId);
+    const candidates = [...new Set([
+      ...(operation.backupDirectories ?? []),
+      operation.backupDirectory,
+      ...additionalDirectories,
+    ].filter(Boolean))]
+      .sort((left, right) => right.length - left.length);
+    const remaining = [];
+
+    for (const backupDirectory of candidates) {
+      try {
+        await provider.deleteSessionDeletionBackup({
+          backupDirectory,
+          ...providerOptions(operation.providerId, operation.home),
+        });
+      } catch {
+        remaining.push(backupDirectory);
+      }
+    }
+
+    operation.backupDirectories = remaining;
+    operation.backupDirectory = remaining[0] ?? null;
+    operation.canDeleteBackup = remaining.length > 0;
+    return remaining.length === 0;
+  }
 
   function getDeletionPlan(planId) {
     const savedPlan = typeof planId === "string" ? deletionPlans.get(planId) : null;
@@ -310,10 +427,10 @@ export async function startLocalServer({ codexHome, configDirectory, port = 0 })
       );
     }
 
-    if (savedPlan.codexHome !== settings.getHome("codex")) {
+    if (savedPlan.home !== settings.getHome(savedPlan.providerId)) {
       deletionPlans.delete(planId);
       throw codedError(
-        "The Codex session folder changed. Review the selection again.",
+        `The ${getProvider(savedPlan.providerId).displayName} session folder changed. Review the selection again.`,
         PLAN_REVIEW_REQUIRED,
       );
     }
@@ -334,11 +451,13 @@ export async function startLocalServer({ codexHome, configDirectory, port = 0 })
     operation.progress = 2;
 
     try {
+      const provider = getProvider(savedPlan.providerId);
+      const options = providerOptions(savedPlan.providerId, savedPlan.home);
       let currentStore;
 
       try {
-        currentStore = await loadDeletionStore({
-          codexHome: savedPlan.codexHome,
+        currentStore = await provider.loadDeletionStore({
+          ...options,
           recordIds: savedPlan.requestedIds,
         });
       } catch (error) {
@@ -351,11 +470,11 @@ export async function startLocalServer({ codexHome, configDirectory, port = 0 })
         throw error;
       }
 
-      const currentPlan = await planSessionDeletion({
+      const currentPlan = await provider.planSessionDeletion({
         recordIds: savedPlan.requestedIds,
         store: currentStore,
       });
-      const currentFingerprint = await fingerprintSessionDeletion({
+      const currentFingerprint = await provider.fingerprintSessionDeletion({
         plan: currentPlan,
         scope: savedPlan.scope,
         store: currentStore,
@@ -368,11 +487,17 @@ export async function startLocalServer({ codexHome, configDirectory, port = 0 })
         );
       }
 
+      await provider.preflightSessionDeletion({
+        plan: currentPlan,
+        scope: savedPlan.scope,
+        store: currentStore,
+      });
+
       if (savedPlan.scope === "deep") {
-        await assertDeepCleanupSupported({ codexHome: savedPlan.codexHome });
+        await provider.assertDeepCleanupSupported(options);
       }
 
-      const result = await executeSessionDeletion({
+      const result = await provider.executeSessionDeletion({
         onProgress: (update) => Object.assign(operation, update),
         plan: currentPlan,
         scope: savedPlan.scope,
@@ -380,12 +505,13 @@ export async function startLocalServer({ codexHome, configDirectory, port = 0 })
         store: currentStore,
       });
       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 verifySessionDeletion({
+      const verification = await provider.verifySessionDeletion({
         plan: currentPlan,
         scope: savedPlan.scope,
         store: currentStore,
@@ -395,8 +521,14 @@ export async function startLocalServer({ codexHome, configDirectory, port = 0 })
 
       if (verification.complete) {
         operation.message = "Cleanup completed";
+        if (await removeOperationBackups(operation)) {
+          operation.result.recoveryBackupDeleted = true;
+        } else {
+          operation.backupDeleteError = "Cleanup completed, but its recovery backup could not be removed.";
+        }
         operation.status = "completed";
       } else {
+        operation.canDeleteBackup = true;
         operation.canRestore = true;
         operation.error = "Cleanup finished, but some selected items remain. You can restore the recovery backup.";
         operation.message = "Cleanup needs attention";
@@ -404,6 +536,7 @@ export async function startLocalServer({ codexHome, configDirectory, port = 0 })
       }
     } catch (error) {
       operation.backupDirectory = error?.backupDirectory ?? null;
+      operation.backupDirectories = operation.backupDirectory ? [operation.backupDirectory] : [];
       operation.canCancel = false;
       operation.errorCode = error?.code ?? null;
       operation.progress = error?.cancelled ? operation.progress : 100;
@@ -411,14 +544,22 @@ export async function startLocalServer({ codexHome, configDirectory, port = 0 })
       if (error?.cancelled) {
         operation.error = null;
         operation.message = "Cleanup cancelled before session data changed";
+        if (!(await removeOperationBackups(operation))) {
+          operation.backupDeleteError = "Cleanup was cancelled, but its temporary backup could not be removed.";
+        }
         operation.status = "cancelled";
       } else {
+        operation.canDeleteBackup = Boolean(operation.backupDirectory);
         operation.canRestore = Boolean(operation.backupDirectory);
         operation.error = error instanceof Error ? error.message : "Cleanup could not be completed.";
         operation.message = "Cleanup could not be completed";
         operation.status = "failed";
       }
     } finally {
+      getProvider(savedPlan.providerId).invalidateSessionCache?.(
+        providerOptions(savedPlan.providerId, savedPlan.home),
+      );
+      invalidateSessionOverview();
       savedPlan.consumed = true;
       deletionPlans.delete(savedPlan.id);
       operation.finishedAtMs = Date.now();
@@ -431,10 +572,14 @@ export async function startLocalServer({ codexHome, configDirectory, port = 0 })
     const id = randomBytes(18).toString("base64url");
     const operation = {
       backupDirectory: null,
+      backupDirectories: [],
+      backupDeleteError: null,
       canCancel: true,
+      canDeleteBackup: false,
       canRestore: false,
       cancelRequested: false,
-      codexHome: savedPlan.codexHome,
+      home: savedPlan.home,
+      providerId: savedPlan.providerId,
       createdAtMs: Date.now(),
       error: null,
       errorCode: null,
@@ -457,7 +602,9 @@ export async function startLocalServer({ codexHome, configDirectory, port = 0 })
 
   function startRestoreOperation(operation) {
     operation.canCancel = false;
+    operation.canDeleteBackup = false;
     operation.canRestore = false;
+    operation.backupDeleteError = null;
     operation.error = null;
     operation.errorCode = null;
     operation.message = "Restore queued";
@@ -467,20 +614,41 @@ export async function startLocalServer({ codexHome, configDirectory, port = 0 })
     activeOperationId = operation.id;
     const task = (async () => {
       try {
-        operation.restoreResult = await restoreSessionDeletionBackup({
+        const restoreResult = await getProvider(operation.providerId).restoreSessionDeletionBackup({
           backupDirectory: operation.backupDirectory,
-          codexHome: operation.codexHome,
+          ...providerOptions(operation.providerId, operation.home),
           onProgress: (update) => Object.assign(operation, update),
         });
+        operation.restoreResult = restoreResult;
         operation.message = "Recovery backup restored";
         operation.progress = 100;
+        if (await removeOperationBackups(operation, [restoreResult.safetyBackupDirectory])) {
+          operation.restoreResult = {
+            ...restoreResult,
+            recoveryBackupsDeleted: true,
+            safetyBackupDirectory: null,
+          };
+        } else {
+          operation.backupDeleteError = "The sessions were restored, but temporary recovery files could not be removed.";
+        }
         operation.status = "restored";
       } catch (error) {
+        if (error?.safetyBackupDirectory) {
+          operation.backupDirectories = [...new Set([
+            ...(operation.backupDirectories ?? []),
+            error.safetyBackupDirectory,
+          ])];
+        }
+        operation.canDeleteBackup = true;
         operation.canRestore = true;
         operation.error = error instanceof Error ? error.message : "The recovery backup could not be restored.";
         operation.message = "Restore could not be completed";
         operation.status = "restore-failed";
       } finally {
+        getProvider(operation.providerId).invalidateSessionCache?.(
+          providerOptions(operation.providerId, operation.home),
+        );
+        invalidateSessionOverview();
         operation.finishedAtMs = Date.now();
         if (activeOperationId === operation.id) activeOperationId = null;
       }
@@ -527,7 +695,34 @@ export async function startLocalServer({ codexHome, configDirectory, port = 0 })
       }
 
       if (request.method === "GET" && requestUrl.pathname === "/api/config") {
-        sendJson(response, 200, { mutationToken, providers: settings.getAll() });
+        sendJson(response, 200, {
+          activeProviderId: settings.getActiveProviderId(),
+          mutationToken,
+          providerOrder: listProviders().map(({ id }) => id),
+          providers: settings.getAll(),
+        });
+        return;
+      }
+
+      if (request.method === "PUT" && requestUrl.pathname === "/api/settings/active-provider") {
+        requireMutationAuthorization({ request, requestUrl, token: mutationToken });
+
+        if (mutationInProgress || activeOperationId) {
+          sendJson(response, 409, { error: "Wait for the current change to finish before switching providers." });
+          return;
+        }
+
+        mutationInProgress = true;
+
+        try {
+          const activeProviderId = await settings.setActiveProviderId(
+            (await readJsonBody(request)).providerId,
+          );
+          sendJson(response, 200, { activeProviderId });
+        } finally {
+          mutationInProgress = false;
+        }
+
         return;
       }
 
@@ -552,6 +747,7 @@ export async function startLocalServer({ codexHome, configDirectory, port = 0 })
             ? await settings.resetProviderHome(providerId)
             : await settings.setProviderHome(providerId, (await readJsonBody(request)).home);
           deletionPlans.clear();
+          invalidateSessionOverview();
           sendJson(response, 200, { provider });
         } finally {
           mutationInProgress = false;
@@ -561,7 +757,10 @@ export async function startLocalServer({ codexHome, configDirectory, port = 0 })
       }
 
       if (request.method === "GET" && requestUrl.pathname === "/api/compatibility") {
-        const diagnostic = await diagnoseStorageCompatibility({ codexHome: settings.getHome("codex") });
+        const providerId = resolveProviderId(requestUrl.searchParams.get("provider"));
+        const provider = getProvider(providerId);
+        const home = settings.getHome(providerId);
+        const diagnostic = await provider.diagnoseStorageCompatibility(providerOptions(providerId, home));
         const currentVersions = await getInstalledProductVersions();
         const versionSupport = Object.fromEntries(
           Object.entries(diagnostic.builtFor).map(([product, supportedVersions]) => [
@@ -572,64 +771,91 @@ export async function startLocalServer({ codexHome, configDirectory, port = 0 })
             }),
           ]),
         );
-        sendJson(response, 200, { ...diagnostic, currentVersions, versionSupport });
+        sendJson(response, 200, { ...diagnostic, currentVersions, providerId, versionSupport });
+        return;
+      }
+
+      if (request.method === "GET" && requestUrl.pathname === "/api/session-overview") {
+        const providerId = resolveProviderId(requestUrl.searchParams.get("provider"));
+        const overview = await readSessionOverview({
+          providerId,
+          refresh: requestUrl.searchParams.get("refresh") === "true",
+        });
+        sendJson(response, 200, { overview });
         return;
       }
 
       if (request.method === "GET" && requestUrl.pathname === "/api/sessions") {
-        const result = await listSessions({
-          codexHome: settings.getHome("codex"),
+        const providerId = resolveProviderId(requestUrl.searchParams.get("provider"));
+        const provider = getProvider(providerId);
+        const result = await provider.listSessions({
+          archiveStatus: getArchiveStatus(requestUrl.searchParams.get("archiveStatus")),
+          ...providerOptions(providerId, settings.getHome(providerId)),
+          inactiveBeforeMs: getInactiveBeforeMs(requestUrl.searchParams.get("inactiveDays")),
           includeInternals: requestUrl.searchParams.get("includeInternals") === "true",
           includeSupporting: requestUrl.searchParams.get("includeSupporting") === "true",
           page: getPositiveInteger(requestUrl.searchParams.get("page"), 1),
           pageSize: getPositiveInteger(requestUrl.searchParams.get("pageSize"), 25, 100),
+          refresh: requestUrl.searchParams.get("refresh") === "true",
           search: requestUrl.searchParams.get("search"),
-          sort: requestUrl.searchParams.get("sort"),
+          sort: getSort(requestUrl.searchParams.get("sort")),
+          workspace: requestUrl.searchParams.has("workspace")
+            ? requestUrl.searchParams.get("workspace")
+            : undefined,
         });
         sendJson(response, 200, {
           ...result,
-          records: result.records.map(formatSessionForJson),
+          records: result.records.map(provider.formatSessionForJson),
         });
         return;
       }
 
       if (request.method === "GET" && requestUrl.pathname.startsWith("/api/sessions/")) {
+        const providerId = resolveProviderId(requestUrl.searchParams.get("provider"));
+        const provider = getProvider(providerId);
         const id = decodeURIComponent(requestUrl.pathname.slice("/api/sessions/".length));
-        const record = await getSessionRecord({ codexHome: settings.getHome("codex"), id });
+        const record = await provider.getSessionRecord({
+          ...providerOptions(providerId, settings.getHome(providerId)),
+          id,
+        });
 
         if (!record) {
           sendJson(response, 404, { error: "Session not found." });
           return;
         }
 
-        sendJson(response, 200, { record: formatSessionForJson(record) });
+        sendJson(response, 200, { record: provider.formatSessionForJson(record) });
         return;
       }
 
       if (request.method === "POST" && requestUrl.pathname === "/api/deletion-plans") {
         const body = await readJsonBody(request);
+        const providerId = resolveProviderId(body.providerId);
+        const provider = getProvider(providerId);
         const ids = normalizeIds(body.ids);
         const scope = getScope(body.scope);
-        const activeCodexHome = settings.getHome("codex");
+        const home = settings.getHome(providerId);
+        const options = providerOptions(providerId, home);
 
         if (scope === "deep") {
-          await assertDeepCleanupSupported({ codexHome: activeCodexHome });
+          await provider.assertDeepCleanupSupported(options);
         }
 
-        const store = await loadDeletionStore({
-          codexHome: activeCodexHome,
+        const store = await provider.loadDeletionStore({
+          ...options,
           recordIds: ids,
         });
-        const plan = await planSessionDeletion({ recordIds: ids, store });
-        const preflight = await preflightSessionDeletion({ plan, store });
+        const plan = await provider.planSessionDeletion({ recordIds: ids, store });
+        const preflight = await provider.preflightSessionDeletion({ plan, scope, store });
         const id = randomBytes(18).toString("base64url");
         const expiresAtMs = Date.now() + PLAN_TTL_MS;
         const savedPlan = {
-          codexHome: activeCodexHome,
+          home,
           consumed: false,
           expiresAtMs,
-          fingerprint: await fingerprintSessionDeletion({ plan, scope, store }),
+          fingerprint: await provider.fingerprintSessionDeletion({ plan, scope, store }),
           id,
+          providerId,
           requestedIds: ids,
           scope,
         };
@@ -638,16 +864,18 @@ export async function startLocalServer({ codexHome, configDirectory, port = 0 })
           deletionPlans.delete(deletionPlans.keys().next().value);
         }
         deletionPlans.set(id, savedPlan);
+        const warnings = preflight.activeThreadDetection === "unavailable"
+          ? [`The current ${provider.displayName} runtime cannot identify an active session. Confirm it is safe to delete the selected sessions.`]
+          : [];
         sendJson(response, 200, {
           plan: {
-            ...summarizePlan(plan, preflight),
+            ...summarizePlan(plan, preflight, scope),
             expiresAtMs,
             id,
+            warnings,
           },
           scope,
-          warnings: preflight.activeThreadDetection === "unavailable"
-            ? ["The current Codex runtime cannot identify an active session. Confirm it is safe to delete the selected sessions."]
-            : [],
+          warnings,
         });
         return;
       }
@@ -674,18 +902,20 @@ export async function startLocalServer({ codexHome, configDirectory, port = 0 })
         return;
       }
 
-      const operationRoute = /^\/api\/deletions\/([^/]+)(\/restore)?$/u.exec(requestUrl.pathname);
+      const operationRoute = /^\/api\/deletions\/([^/]+)(\/restore|\/backup)?$/u.exec(requestUrl.pathname);
 
       if (operationRoute) {
         const operation = getOperation(decodeURIComponent(operationRoute[1]));
-        const restoreRoute = Boolean(operationRoute[2]);
+        const operationAction = operationRoute[2] ?? "";
+        const restoreRoute = operationAction === "/restore";
+        const backupRoute = operationAction === "/backup";
 
-        if (request.method === "GET" && !restoreRoute) {
+        if (request.method === "GET" && !operationAction) {
           sendJson(response, 200, { operation: publicOperation(operation) });
           return;
         }
 
-        if (request.method === "DELETE" && !restoreRoute) {
+        if (request.method === "DELETE" && !operationAction) {
           requireMutationAuthorization({ request, requestUrl, token: mutationToken });
           const cancelAccepted = operation.status === "queued" || (
             operation.status === "running" && operation.canCancel
@@ -698,6 +928,33 @@ export async function startLocalServer({ codexHome, configDirectory, port = 0 })
           return;
         }
 
+        if (request.method === "DELETE" && backupRoute) {
+          requireMutationAuthorization({ request, requestUrl, token: mutationToken });
+
+          if (!operation.canDeleteBackup || !operation.backupDirectory) {
+            throw new Error("A recovery backup is not available for deletion.");
+          }
+
+          if (mutationInProgress || activeOperationId) {
+            sendJson(response, 409, { error: "Wait for the current cleanup to finish before deleting its backup." });
+            return;
+          }
+
+          mutationInProgress = true;
+          try {
+            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) });
+          } finally {
+            mutationInProgress = false;
+          }
+          return;
+        }
+
         if (request.method === "POST" && restoreRoute) {
           requireMutationAuthorization({ request, requestUrl, token: mutationToken });