session-steward 0.1.1 → 0.3.0

package/lib/cli.mjs

@@ -5,23 +5,25 @@ import process, { stdin as input, stdout as output } from "node:process";
 
 import { getProvider } from "./providers/index.mjs";
 
-const {
-  assertDeepCleanupSupported,
-  executeSessionDeletion,
-  formatSessionForJson,
-  getSessionRecord,
-  listSessions,
-  loadDeletionStore,
-  planSessionDeletion,
-  verifySessionDeletion,
-} = getProvider("codex");
+function providerOptions(providerId, home) {
+  return providerId === "codex" ? { codexHome: home } : { claudeHome: home };
+}
 
 const PAGE_SIZE = 20;
+const ALLOWED_INACTIVE_DAYS = new Set([30, 60, 90]);
+const ALLOWED_ARCHIVE_STATUSES = new Set(["all", "active", "archived"]);
+const ALLOWED_CLEANUP_MODES = new Set(["standard", "thorough"]);
 const HELP_TEXT = `
 Commands
   search <text>                 Set the active search filter
   search                        Clear the active search filter
-  sort <updated|created|name|cwd>
+  workspace <path>              Show one exact workspace
+  workspace                     Clear the workspace filter
+  inactive <30|60|90>           Show sessions last active that many days ago
+  inactive                      Clear the inactivity filter
+  archive <all|active|archived> Filter sessions by archive status
+  archive                       Clear the archive filter
+  sort <updated|created|name|cwd|size>
                                 Change sort order
   inspect <index|id-prefix>     Show session details
   delete <selector> [...]       Delete one or more sessions
@@ -29,6 +31,12 @@ Commands
   next                          Next page
   prev                          Previous page
   internals                     Toggle subagent visibility
+  supporting                    Toggle supporting-session visibility
+  cleanup <standard|thorough>   Choose the cleanup level
+  overview                      Show storage and workspace totals
+  backups                       Show retained recovery backups
+  restore <index|backup-id>     Restore a recovery backup
+  delete-backup <index|id>      Permanently remove a recovery backup
   refresh                       Reload sessions from sqlite and disk
   help                          Show this help
   quit                          Exit
@@ -40,6 +48,29 @@ Selectors
   delete 1 4-6 019dd26c
 `.trim();
 
+const CLI_HELP_TEXT = `
+Usage: session-steward-cli [options]
+
+Options
+  --provider <codex|claude-code> Choose the session provider
+  --codex-home <path>            Use another Codex session folder for this run
+  --claude-home <path>           Use another Claude session folder for this run
+  --json                         Print sessions as JSON
+  --include-internals            Include subagent sessions
+  --include-supporting           Include supporting sessions
+  --cleanup <standard|thorough>  Choose the interactive cleanup level
+  --overview                     Print storage and workspace totals
+  --backups                      Print retained recovery backups
+  --search <text>                Search names, workspaces, and session IDs
+  --workspace <path>             Show one exact workspace
+  --inactive-days <30|60|90>     Show sessions last active at least this long ago
+  --archive-status <status>      Show all, active, or archived sessions
+  --sort <updated|created|name|cwd|size>
+                                 Choose the session order
+  --limit <number>               Limit JSON results
+  -h, --help                     Show this help
+`.trim();
+
 function truncate(value, maxLength) {
   if (value.length <= maxLength) {
     return value;
@@ -101,6 +132,31 @@ function absoluteTime(timestampMs) {
   return new Date(timestampMs).toLocaleString();
 }
 
+function formatBytes(bytes) {
+  if (!Number.isFinite(bytes) || bytes < 0) return "-";
+  if (bytes < 1024) return `${bytes} B`;
+
+  const units = ["KB", "MB", "GB", "TB"];
+  let value = bytes;
+  let unit = "B";
+
+  for (const nextUnit of units) {
+    value /= 1024;
+    unit = nextUnit;
+    if (value < 1024) break;
+  }
+
+  return `${value.toFixed(value < 10 ? 1 : 0)} ${unit}`;
+}
+
+function cleanupScope(cleanupMode) {
+  return cleanupMode === "thorough" ? "deep" : "core";
+}
+
+function cleanupLabel(scope) {
+  return scope === "deep" ? "Thorough" : scope === "core" ? "Standard" : "Unknown";
+}
+
 function getCwdDisplay(record) {
   if (!record.cwd) {
     return "-";
@@ -138,26 +194,32 @@ function getMarkerText(record) {
   return markers.join(", ");
 }
 
-function printScreen({ codexHome, result, search, showInternals, sort }) {
+function printScreen({ archiveStatus, cleanupMode, inactiveDays, providerHome, providerName, result, search, showInternals, showSupporting, sort, workspace }) {
   if (output.isTTY) {
     output.write("\x1Bc");
   }
 
   output.write("Session Steward\n");
   output.write(
-    `Home: ${codexHome} | Sessions: ${result.total} | Page: ${result.page}/${result.pageCount}\n`,
+    `${providerName} home: ${providerHome} | Sessions: ${result.total} | Page: ${result.page}/${result.pageCount}\n`,
+  );
+  output.write(
+    `Sort: ${sort} | Search: ${search || "-"} | Cleanup: ${cleanupLabel(cleanupScope(cleanupMode))}\n`,
   );
   output.write(
-    `Sort: ${sort} | Search: ${search || "-"} | Internals: ${showInternals ? "shown" : "hidden"}\n`,
+    `Subagents: ${showInternals ? "shown" : "hidden"} | Supporting: ${showSupporting ? "shown" : "hidden"}\n`,
   );
   output.write(
-    "Commands: search | sort | inspect | delete | page | next | prev | internals | refresh | help | quit\n\n",
+    `Last active: ${inactiveDays ? `${inactiveDays}+ days ago` : "any time"} | Workspace: ${workspace || "all"} | Status: ${archiveStatus}\n`,
+  );
+  output.write(
+    "Commands: search | workspace | inactive | archive | sort | inspect | delete | overview | backups | help | quit\n\n",
   );
 
   output.write(
-    `${pad("#", 4)} ${pad("Name", 64)} ${pad("Updated", 8)} ${pad("Cwd", 20)} Markers\n`,
+    `${pad("#", 4)} ${pad("Name", 52)} ${pad("Updated", 8)} ${pad("Size", 10)} ${pad("Cwd", 18)} Markers\n`,
   );
-  output.write(`${"-".repeat(4)} ${"-".repeat(64)} ${"-".repeat(8)} ${"-".repeat(20)} ${"-".repeat(24)}\n`);
+  output.write(`${"-".repeat(4)} ${"-".repeat(52)} ${"-".repeat(8)} ${"-".repeat(10)} ${"-".repeat(18)} ${"-".repeat(20)}\n`);
 
   if (result.records.length === 0) {
     output.write("No sessions match the current view.\n");
@@ -167,7 +229,7 @@ function printScreen({ codexHome, result, search, showInternals, sort }) {
   result.records.forEach((record, index) => {
     const rowNumber = index + 1;
     output.write(
-      `${pad(String(rowNumber), 4)} ${pad(truncate(record.displayName, 64), 64)} ${pad(relativeTime(record.updatedAtMs), 8)} ${pad(truncate(getCwdDisplay(record), 20), 20)} ${truncate(getMarkerText(record), 24)}\n`,
+      `${pad(String(rowNumber), 4)} ${pad(truncate(record.displayName, 52), 52)} ${pad(relativeTime(record.updatedAtMs), 8)} ${pad(formatBytes(record.transcriptBytes), 10)} ${pad(truncate(getCwdDisplay(record), 18), 18)} ${truncate(getMarkerText(record), 20)}\n`,
     );
   });
 }
@@ -202,12 +264,10 @@ function parseSelectors(selectors, records) {
       const rowIndex = Number.parseInt(selector, 10) - 1;
       const record = records[rowIndex];
 
-      if (!record) {
-        throw new Error(`No session exists at row ${selector}.`);
+      if (record) {
+        resolvedIds.add(record.id);
+        continue;
       }
-
-      resolvedIds.add(record.id);
-      continue;
     }
 
     if (/^\d+-\d+$/u.test(selector)) {
@@ -215,21 +275,19 @@ function parseSelectors(selectors, records) {
       const start = Number.parseInt(startText, 10);
       const end = Number.parseInt(endText, 10);
 
-      if (start > end) {
-        throw new Error(`Invalid range: ${selector}.`);
-      }
-
-      for (let index = start; index <= end; index += 1) {
-        const record = records[index - 1];
+      if (startText.length <= 4 && endText.length <= 4) {
+        if (start > end) {
+          throw new Error(`Invalid range: ${selector}.`);
+        }
 
-        if (!record) {
-          throw new Error(`No session exists at row ${index}.`);
+        for (let index = start; index <= end; index += 1) {
+          const record = records[index - 1];
+          if (!record) throw new Error(`No session exists at row ${index}.`);
+          resolvedIds.add(record.id);
         }
 
-        resolvedIds.add(record.id);
+        continue;
       }
-
-      continue;
     }
 
     const matches = records.filter((record) => record.id.startsWith(selector));
@@ -257,6 +315,7 @@ function printInspect(record, deletionPlan) {
   output.write(`Created: ${absoluteTime(record.createdAtMs)}\n`);
   output.write(`Cwd: ${record.cwd || "-"}\n`);
   output.write(`Transcript: ${record.rolloutPath || "-"}\n`);
+  output.write(`Transcript size: ${formatBytes(record.transcriptBytes)}\n`);
   output.write(`Title source: ${record.titleSource}\n`);
   output.write(`Parent: ${record.parentThreadId || "-"}\n`);
   output.write(`Children: ${record.childThreadIds.length}\n`);
@@ -272,7 +331,9 @@ function printInspect(record, deletionPlan) {
   output.write(`Delete log rows: ${deletionPlan.logRowCount}\n`);
 }
 
-function printDeletionPreview(plan) {
+function printDeletionPreview(plan, preflight, scope) {
+  const fileCount = preflight.transcriptFileCount ?? plan.transcriptFileCount;
+  const sessionBytes = preflight.transcriptBytes ?? plan.transcriptBytes;
   output.write("\nDelete preview\n");
   output.write("--------------\n");
   output.write(`Sessions: ${plan.ids.length}\n`);
@@ -282,6 +343,10 @@ function printDeletionPreview(plan) {
   output.write(`History rows: ${plan.historyMatchCount}\n`);
   output.write(`Spawn edges: ${plan.spawnEdgeCount}\n`);
   output.write(`Log rows: ${plan.logRowCount}\n`);
+  output.write(`Cleanup: ${cleanupLabel(scope)}\n`);
+  output.write(`Files: ${fileCount}\n`);
+  output.write(`Session data: ${formatBytes(sessionBytes)}\n`);
+  output.write(`Temporary backup space needed: ${formatBytes(preflight.estimatedBackupBytes)}\n`);
 
   for (const record of plan.records.slice(0, 20)) {
     output.write(`- ${record.displayName} (${record.id})\n`);
@@ -301,20 +366,146 @@ function printHelp() {
 }
 
 function validateSort(value) {
-  return ["updated", "created", "name", "cwd"].includes(value)
+  return ["updated", "created", "name", "cwd", "size"].includes(value)
     ? value
     : "updated";
 }
 
+function validateInactiveDays(value) {
+  if (value === undefined || value === null || value === "") {
+    return null;
+  }
+
+  const days = Number(value);
+
+  if (!ALLOWED_INACTIVE_DAYS.has(days)) {
+    throw new Error("Inactive days must be 30, 60, or 90.");
+  }
+
+  return days;
+}
+
+function validateArchiveStatus(value) {
+  const status = value || "all";
+
+  if (!ALLOWED_ARCHIVE_STATUSES.has(status)) {
+    throw new Error("Archive status must be all, active, or archived.");
+  }
+
+  return status;
+}
+
+function validateCleanupMode(value) {
+  const cleanupMode = value || "standard";
+
+  if (!ALLOWED_CLEANUP_MODES.has(cleanupMode)) {
+    throw new Error("Cleanup must be standard or thorough.");
+  }
+
+  return cleanupMode;
+}
+
+async function writeJsonValue(value) {
+  const content = `${JSON.stringify(value, null, 2)}\n`;
+  if (!output.write(content)) await once(output, "drain");
+}
+
+async function loadOverview(state) {
+  return state.provider.getSessionOverview({
+    ...providerOptions(state.provider.id, state.providerHome),
+    refresh: true,
+  });
+}
+
+function printOverview(overview, providerName) {
+  output.write(`\n${providerName} overview\n`);
+  output.write(`${"-".repeat(providerName.length + 9)}\n`);
+  output.write(`On disk: ${formatBytes(overview.transcriptBytes)} in ${overview.transcriptFileCount} files\n`);
+  output.write(`All sessions: ${overview.sessionCount}\n`);
+  output.write(`Primary sessions: ${overview.primarySessionCount}\n`);
+  output.write(`Subagent sessions: ${overview.subagentCount}\n`);
+  output.write(`Supporting sessions: ${overview.supportingCount}\n`);
+
+  if (Number.isFinite(overview.cliSessionCount)) {
+    output.write(`CLI sessions: ${overview.cliSessionCount}\n`);
+  }
+
+  if (Number.isFinite(overview.desktopSessionCount)) {
+    output.write(`Desktop sessions: ${overview.desktopSessionCount}\n`);
+  }
+
+  if (overview.workspaces.length === 0) return;
+  output.write("\nWorkspaces\n");
+  output.write(`${pad("Sessions", 10)} ${pad("Size", 10)} Workspace\n`);
+
+  for (const workspace of overview.workspaces) {
+    output.write(
+      `${pad(String(workspace.sessionCount), 10)} ${pad(formatBytes(workspace.transcriptBytes), 10)} ${workspace.path || "Unknown workspace"}\n`,
+    );
+  }
+}
+
+async function loadBackups(state) {
+  return state.provider.listSessionDeletionBackups(
+    providerOptions(state.provider.id, state.providerHome),
+  );
+}
+
+function printBackups(backups) {
+  output.write("\nRecovery backups\n");
+  output.write("----------------\n");
+
+  if (backups.length === 0) {
+    output.write("No recovery backups are stored.\n");
+    return;
+  }
+
+  output.write(`${pad("#", 4)} ${pad("Created", 22)} ${pad("Cleanup", 10)} ${pad("Size", 10)} ${pad("Files", 7)} Status\n`);
+
+  backups.forEach((backup, index) => {
+    output.write(
+      `${pad(String(index + 1), 4)} ${pad(truncate(absoluteTime(backup.createdAtMs), 22), 22)} ${pad(cleanupLabel(backup.scope), 10)} ${pad(formatBytes(backup.bytes), 10)} ${pad(String(backup.fileCount), 7)} ${backup.restorable ? "Ready to restore" : "Manual recovery only"}\n`,
+    );
+    output.write(`     ${backup.id}\n`);
+  });
+}
+
+function resolveBackupSelector(selector, backups) {
+  if (!selector) throw new Error("Choose a recovery backup by number or backup id.");
+
+  if (/^\d+$/u.test(selector)) {
+    const backup = backups[Number.parseInt(selector, 10) - 1];
+    if (!backup) throw new Error(`No recovery backup exists at row ${selector}.`);
+    return backup;
+  }
+
+  const exactMatch = backups.find((backup) => backup.id === selector);
+  if (exactMatch) return exactMatch;
+  const prefixMatches = backups.filter((backup) => backup.id.startsWith(selector));
+  if (prefixMatches.length === 0) throw new Error(`No recovery backup id starts with "${selector}".`);
+  if (prefixMatches.length > 1) throw new Error(`Recovery backup id prefix "${selector}" is ambiguous.`);
+  return prefixMatches[0];
+}
+
+function getInactiveBeforeMs(days) {
+  return days === null ? null : Date.now() - days * 24 * 60 * 60 * 1000;
+}
+
 async function refreshPage(state) {
-  state.result = await listSessions({
-    codexHome: state.codexHome,
+  state.result = await state.provider.listSessions({
+    archiveStatus: state.archiveStatus,
+    ...providerOptions(state.provider.id, state.providerHome),
+    inactiveBeforeMs: getInactiveBeforeMs(state.inactiveDays),
     includeInternals: state.showInternals,
+    includeSupporting: state.showSupporting,
     page: state.page,
     pageSize: PAGE_SIZE,
+    refresh: state.forceRefresh,
     search: state.search,
     sort: state.sort,
+    workspace: state.workspace,
   });
+  state.forceRefresh = false;
   state.page = state.result.page;
 }
 
@@ -323,24 +514,30 @@ async function printJson(options) {
     if (!output.write(chunk)) await once(output, "drain");
   };
   const limit = Number.isFinite(options.limit) && options.limit > 0 ? options.limit : Infinity;
+  const inactiveBeforeMs = getInactiveBeforeMs(validateInactiveDays(options.inactiveDays));
+  const archiveStatus = validateArchiveStatus(options.archiveStatus);
   let page = 1;
   let written = 0;
   let first = true;
   await writeChunk("[\n");
 
   while (written < limit) {
-    const result = await listSessions({
-      codexHome: options.codexHome,
+    const result = await options.provider.listSessions({
+      archiveStatus,
+      ...providerOptions(options.provider.id, options.providerHome),
+      inactiveBeforeMs,
       includeInternals: Boolean(options.includeInternals),
+      includeSupporting: Boolean(options.includeSupporting),
       page,
       pageSize: Math.min(100, limit - written),
       search: options.search || "",
       sort: validateSort(options.sort || "updated"),
+      workspace: options.workspace,
     });
 
     for (const record of result.records) {
       if (written >= limit) break;
-      await writeChunk(`${first ? "" : ",\n"}${JSON.stringify(formatSessionForJson(record), null, 2)}`);
+      await writeChunk(`${first ? "" : ",\n"}${JSON.stringify(options.provider.formatSessionForJson(record), null, 2)}`);
       first = false;
       written += 1;
     }
@@ -362,11 +559,17 @@ async function runInteractive(state) {
     while (true) {
       await refreshPage(state);
       printScreen({
-        codexHome: state.codexHome,
+        archiveStatus: state.archiveStatus,
+        cleanupMode: state.cleanupMode,
+        inactiveDays: state.inactiveDays,
+        providerHome: state.providerHome,
+        providerName: state.provider.displayName,
         result: state.result,
         search: state.search,
         showInternals: state.showInternals,
+        showSupporting: state.showSupporting,
         sort: state.sort,
+        workspace: state.workspace,
       });
 
       const commandInput = await rl.question("\nsession-steward> ");
@@ -387,6 +590,7 @@ async function runInteractive(state) {
       }
 
       if (["refresh", "r"].includes(command.name)) {
+        state.forceRefresh = true;
         state.page = 1;
         continue;
       }
@@ -397,12 +601,161 @@ async function runInteractive(state) {
         continue;
       }
 
+      if (["supporting", "toggle-supporting"].includes(command.name)) {
+        state.showSupporting = !state.showSupporting;
+        state.page = 1;
+        continue;
+      }
+
+      if (command.name === "cleanup") {
+        try {
+          state.cleanupMode = validateCleanupMode(command.args[0]);
+        } catch (error) {
+          output.write(`\n${error instanceof Error ? error.message : String(error)}\n`);
+          await pause(rl);
+        }
+        continue;
+      }
+
+      if (command.name === "overview") {
+        try {
+          printOverview(await loadOverview(state), state.provider.displayName);
+        } catch (error) {
+          output.write(`\n${error instanceof Error ? error.message : String(error)}\n`);
+        }
+        await pause(rl);
+        continue;
+      }
+
+      if (command.name === "backups") {
+        try {
+          printBackups(await loadBackups(state));
+        } catch (error) {
+          output.write(`\n${error instanceof Error ? error.message : String(error)}\n`);
+        }
+        await pause(rl);
+        continue;
+      }
+
+      if (command.name === "restore") {
+        try {
+          const backups = await loadBackups(state);
+          const backup = resolveBackupSelector(command.args[0], backups);
+
+          if (!backup.restorable) {
+            throw new Error("This backup cannot be restored automatically. Its files are still available for manual recovery.");
+          }
+
+          output.write(`\nRestore backup from ${absoluteTime(backup.createdAtMs)} (${formatBytes(backup.bytes)}).\n`);
+          output.write("Current files are saved before the restore begins.\n");
+          const response = await rl.question('\nType "RESTORE" to confirm: ');
+
+          if (response.trim() !== "RESTORE") {
+            output.write("Restore cancelled.\n");
+            await pause(rl);
+            continue;
+          }
+
+          const restoreResult = await state.provider.restoreSessionDeletionBackup({
+            backupDirectory: backup.backupDirectory,
+            ...providerOptions(state.provider.id, state.providerHome),
+            onProgress: ({ message }) => {
+              if (message) output.write(`${message}...\n`);
+            },
+          });
+          const cleanupDirectories = [
+            restoreResult.safetyBackupDirectory,
+            backup.backupDirectory,
+          ].filter(Boolean);
+          const retainedDirectories = [];
+
+          for (const backupDirectory of cleanupDirectories) {
+            try {
+              await state.provider.deleteSessionDeletionBackup({
+                backupDirectory,
+                ...providerOptions(state.provider.id, state.providerHome),
+              });
+            } catch {
+              retainedDirectories.push(backupDirectory);
+            }
+          }
+
+          state.provider.invalidateSessionCache?.(providerOptions(state.provider.id, state.providerHome));
+          const restoredCount = restoreResult.restoredFileCount ?? restoreResult.restoredEntryCount ?? 0;
+          output.write(`Restored and verified ${restoredCount} session data files.\n`);
+          if (retainedDirectories.length > 0) {
+            output.write(`Restore completed, but recovery files remain at ${retainedDirectories.join(", ")}.\n`);
+          }
+          state.page = 1;
+          state.forceRefresh = true;
+        } catch (error) {
+          output.write(`\n${error instanceof Error ? error.message : String(error)}\n`);
+        }
+        await pause(rl);
+        continue;
+      }
+
+      if (command.name === "delete-backup") {
+        try {
+          const backups = await loadBackups(state);
+          const backup = resolveBackupSelector(command.args[0], backups);
+          output.write(`\nDelete recovery backup from ${absoluteTime(backup.createdAtMs)} (${formatBytes(backup.bytes)}).\n`);
+          output.write("You will no longer be able to restore from it.\n");
+          const response = await rl.question('\nType "DELETE BACKUP" to confirm: ');
+
+          if (response.trim() !== "DELETE BACKUP") {
+            output.write("Backup deletion cancelled.\n");
+            await pause(rl);
+            continue;
+          }
+
+          await state.provider.deleteSessionDeletionBackup({
+            backupDirectory: backup.backupDirectory,
+            ...providerOptions(state.provider.id, state.providerHome),
+          });
+          output.write(`Deleted recovery backup ${backup.id}.\n`);
+        } catch (error) {
+          output.write(`\n${error instanceof Error ? error.message : String(error)}\n`);
+        }
+        await pause(rl);
+        continue;
+      }
+
       if (["search", "s"].includes(command.name)) {
         state.search = command.args.join(" ");
         state.page = 1;
         continue;
       }
 
+      if (["workspace", "cwd"].includes(command.name)) {
+        state.workspace = command.args.length > 0 ? command.args.join(" ") : undefined;
+        state.page = 1;
+        continue;
+      }
+
+      if (["inactive", "inactive-days"].includes(command.name)) {
+        try {
+          state.inactiveDays = validateInactiveDays(command.args[0]);
+          state.page = 1;
+          state.forceRefresh = true;
+        } catch (error) {
+          output.write(`\n${error instanceof Error ? error.message : String(error)}\n`);
+          await pause(rl);
+        }
+        continue;
+      }
+
+      if (["archive", "archive-status"].includes(command.name)) {
+        try {
+          state.archiveStatus = validateArchiveStatus(command.args[0]);
+          state.page = 1;
+        } catch (error) {
+          output.write(`\n${error instanceof Error ? error.message : String(error)}\n`);
+          await pause(rl);
+        }
+        continue;
+      }
+
       if (command.name === "sort") {
         state.sort = validateSort(command.args[0] ?? "updated");
         state.page = 1;
@@ -433,12 +786,12 @@ async function runInteractive(state) {
             throw new Error("`inspect` accepts exactly one selector.");
           }
 
-          const record = await getSessionRecord({ codexHome: state.codexHome, id: sessionIds[0] });
-          const deletionStore = await loadDeletionStore({
-            codexHome: state.codexHome,
+          const record = await state.provider.getSessionRecord({ ...providerOptions(state.provider.id, state.providerHome), id: sessionIds[0] });
+          const deletionStore = await state.provider.loadDeletionStore({
+            ...providerOptions(state.provider.id, state.providerHome),
             recordIds: sessionIds,
           });
-          const deletionPlan = await planSessionDeletion({
+          const deletionPlan = await state.provider.planSessionDeletion({
             recordIds: sessionIds,
             store: deletionStore,
           });
@@ -455,19 +808,30 @@ async function runInteractive(state) {
       if (command.name === "delete") {
         try {
           const sessionIds = parseSelectors(command.args, state.result.records);
-          await assertDeepCleanupSupported({ codexHome: state.codexHome });
-          const deletionStore = await loadDeletionStore({
-            codexHome: state.codexHome,
+          if (sessionIds.length === 0) throw new Error("Choose at least one session to delete.");
+          const scope = cleanupScope(state.cleanupMode);
+          if (scope === "deep") {
+            await state.provider.assertDeepCleanupSupported(
+              providerOptions(state.provider.id, state.providerHome),
+            );
+          }
+          const deletionStore = await state.provider.loadDeletionStore({
+            ...providerOptions(state.provider.id, state.providerHome),
             recordIds: sessionIds,
           });
-          const deletionPlan = await planSessionDeletion({
+          const deletionPlan = await state.provider.planSessionDeletion({
             recordIds: sessionIds,
             store: deletionStore,
           });
+          const preflight = await state.provider.preflightSessionDeletion({
+            plan: deletionPlan,
+            scope,
+            store: deletionStore,
+          });
 
-          printDeletionPreview(deletionPlan);
+          printDeletionPreview(deletionPlan, preflight, scope);
           output.write(
-            "\nClose the selected Codex sessions before continuing. Active-session detection is unavailable.\n",
+            `\nClose the selected ${state.provider.displayName} sessions before continuing.\n`,
           );
 
           const confirmationToken =
@@ -499,7 +863,7 @@ async function runInteractive(state) {
           let result;
 
           try {
-            result = await executeSessionDeletion({
+            result = await state.provider.executeSessionDeletion({
               onProgress: ({ canCancel: nextCanCancel, message }) => {
                 canCancel = nextCanCancel;
                 if (message !== lastMessage) {
@@ -508,21 +872,30 @@ async function runInteractive(state) {
                 }
               },
               plan: deletionPlan,
+              scope,
               shouldCancel: () => cancelRequested,
               store: deletionStore,
             });
           } finally {
             process.off("SIGINT", handleInterrupt);
           }
-          const verification = await verifySessionDeletion({
+          const verification = await state.provider.verifySessionDeletion({
             plan: deletionPlan,
-            scope: "deep",
+            scope,
             store: deletionStore,
           });
 
           if (verification.complete) {
+            try {
+              await state.provider.deleteSessionDeletionBackup({
+                backupDirectory: result.backupDirectory,
+                ...providerOptions(state.provider.id, state.providerHome),
+              });
+            } catch {
+              output.write(`Cleanup completed, but its recovery backup remains at ${result.backupDirectory}.\n`);
+            }
             output.write(
-              `Deleted and verified ${result.deletedIds.length} sessions and ${result.deletedTranscriptPaths.length} transcripts.\n`,
+              `Deleted and verified ${result.deletedIds.length} sessions and ${result.deletedTranscriptPaths.length} session paths.\n`,
             );
           } else {
             output.write(
@@ -536,7 +909,11 @@ async function runInteractive(state) {
             );
           }
 
+          state.provider.invalidateSessionCache?.(
+            providerOptions(state.provider.id, state.providerHome),
+          );
           state.page = 1;
+          state.forceRefresh = true;
         } catch (error) {
           output.write(`\n${error instanceof Error ? error.message : String(error)}\n`);
           await pause(rl);
@@ -555,24 +932,50 @@ async function runInteractive(state) {
 
 export async function runCli(options) {
   if (options.help) {
-    output.write(
-      "Usage: session-steward-cli [--codex-home <path>] [--json] [--include-internals] [--search <text>] [--sort <updated|created|name|cwd>] [--limit <n>]\n",
-    );
+    output.write(`${CLI_HELP_TEXT}\n`);
+    return;
+  }
+
+  const provider = options.provider ?? getProvider(options.providerId || "codex");
+  const providerHome = path.resolve(options.providerHome);
+
+  if (options.overview && options.backups) {
+    throw new Error("Choose either overview or backups.");
+  }
+
+  if (options.overview) {
+    const overview = await loadOverview({ provider, providerHome });
+    if (options.json) await writeJsonValue(overview);
+    else printOverview(overview, provider.displayName);
+    return;
+  }
+
+  if (options.backups) {
+    const backups = await loadBackups({ provider, providerHome });
+    if (options.json) await writeJsonValue(backups);
+    else printBackups(backups);
     return;
   }
 
   if (options.json) {
-    await printJson(options);
+    await printJson({ ...options, provider, providerHome });
     return;
   }
 
   const state = {
-    codexHome: path.resolve(options.codexHome),
+    archiveStatus: validateArchiveStatus(options.archiveStatus),
+    cleanupMode: validateCleanupMode(options.cleanup),
+    provider,
+    providerHome,
+    inactiveDays: validateInactiveDays(options.inactiveDays),
+    forceRefresh: false,
     page: 1,
     result: null,
     search: options.search || "",
     showInternals: Boolean(options.includeInternals),
+    showSupporting: Boolean(options.includeSupporting),
     sort: validateSort(options.sort || "updated"),
+    workspace: options.workspace,
   };
 
   await runInteractive(state);