@bitkyc08/opencodex 2.7.42 → 2.7.43

package/src/storage/cleanup.ts

@@ -12,21 +12,29 @@
  * satellite rows before staged files. Success never carries soft `dbWarning` /
  * `failedPaths`.
  */
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import {
+  closeSync,
   existsSync,
+  fsyncSync,
+  linkSync,
   mkdirSync,
+  openSync,
   readdirSync,
+  readFileSync,
   renameSync,
   rmSync,
   statSync,
   unlinkSync,
   writeFileSync,
+  writeSync,
   chmodSync,
 } from "node:fs";
 import { basename, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { Database } from "bun:sqlite";
 import { resolveCodexHomeDir } from "../codex/home";
+import { readThreadFieldsFromRollout } from "../codex/history-provider";
+import { renameAtomicFile } from "../config";
 
 export const ARCHIVED_SESSIONS_DIR = "archived_sessions";
 export const TRASH_DIR = ".trash";
@@ -39,9 +47,11 @@ export type CleanupErrorCode =
   | "invalid_digest"
   | "stale_preview"
   | "codex_busy"
+  | "storage_mutation_busy"
   | "fs_failed"
   | "db_reconcile_failed"
   | "referenced_history"
+  | "restore_pending_overlap"
   | "cleanup_failed";
 
 export interface ArchivedCandidate {
@@ -233,9 +243,8 @@ export function normalizeArchivedRolloutPath(rolloutPath: string, codexHome: str
   return logical;
 }
 
-/** Content digest of the exact previewed candidate set (paths + size + mtime). */
-export function computePreviewDigest(candidates: ArchivedCandidate[], percent: number): string {
-  const lines = candidates
+function candidateDigestLines(candidates: ArchivedCandidate[]): string[] {
+  return candidates
     .map(c => {
       const physical = [...c.physicalFiles]
         .sort((a, b) => a.relPath.localeCompare(b.relPath))
@@ -244,8 +253,22 @@ export function computePreviewDigest(candidates: ArchivedCandidate[], percent: n
       return `${c.relPath}|${c.bytes}|${Math.trunc(c.mtimeMs)}|${physical}`;
     })
     .sort();
+}
+
+/** Content digest of the exact previewed candidate set (paths + size + mtime). */
+export function computePreviewDigest(candidates: ArchivedCandidate[], percent: number): string {
+  return createHash("sha256")
+    .update(`${clampPercent(percent)}\n${candidateDigestLines(candidates).join("\n")}`)
+    .digest("hex");
+}
+
+/**
+ * Digest bound to an explicit candidate list (not a percent selection).
+ * Used when reduceToBytes needs an exact count that percent rounding cannot represent.
+ */
+export function computeExactPreviewDigest(candidates: ArchivedCandidate[]): string {
   return createHash("sha256")
-    .update(`${clampPercent(percent)}\n${lines.join("\n")}`)
+    .update(`exact\n${candidateDigestLines(candidates).join("\n")}`)
     .digest("hex");
 }
 
@@ -314,29 +337,161 @@ export function selectOldestPercent(candidates: ArchivedCandidate[], percent: nu
   const pct = clampPercent(percent);
   if (pct <= 0 || candidates.length === 0) return [];
   if (pct >= 100) return [...candidates];
-  const n = Math.max(1, Math.floor((candidates.length * pct) / 100));
+  const n = percentSelectionTargetCount(candidates.length, pct);
   return candidates.slice(0, n);
 }
 
+/** Count implied by percent selection over the full candidate list. */
+export function percentSelectionTargetCount(totalCount: number, percent: number): number {
+  const pct = clampPercent(percent);
+  if (pct <= 0 || totalCount === 0) return 0;
+  if (pct >= 100) return totalCount;
+  return Math.max(1, Math.floor((totalCount * pct) / 100));
+}
+
+function candidateOverlapsPendingRestore(
+  candidate: ArchivedCandidate,
+  pendingDestRels: ReadonlySet<string>,
+): boolean {
+  if (pendingDestRels.size === 0) return false;
+  for (const rel of candidate.physicalRelPaths) {
+    if (pendingDestRels.has(rel)) return true;
+  }
+  return pendingDestRels.has(candidate.relPath);
+}
+
+/** Drop cleanup candidates whose physical paths overlap an in-progress restore. */
+export function filterCandidatesExcludingPendingRestore(
+  candidates: ArchivedCandidate[],
+  codexHome: string = resolveCodexHomeDir(),
+): ArchivedCandidate[] {
+  const pendingDestRels = collectRestorePendingAcceptedDestRels(codexHome);
+  if (pendingDestRels.size === 0) return candidates;
+  return candidates.filter(c => !candidateOverlapsPendingRestore(c, pendingDestRels));
+}
+
+/**
+ * Oldest-first percent selection that skips pending-restore destinations without
+ * consuming the percent budget, backfilling with the next oldest safe candidates.
+ */
+export function selectOldestPercentSkippingPendingRestore(
+  candidates: ArchivedCandidate[],
+  percent: number,
+  codexHome: string = resolveCodexHomeDir(),
+): ArchivedCandidate[] {
+  const target = percentSelectionTargetCount(candidates.length, percent);
+  if (target === 0) return [];
+  const pendingDestRels = collectRestorePendingAcceptedDestRels(codexHome);
+  const out: ArchivedCandidate[] = [];
+  for (const c of candidates) {
+    if (candidateOverlapsPendingRestore(c, pendingDestRels)) continue;
+    out.push(c);
+    if (out.length >= target) break;
+  }
+  return out;
+}
+
+/**
+ * Reduce archived total toward `reduceToBytes` using oldest safe candidates only.
+ * Pending-restore destinations are skipped and do not count toward bytes freed.
+ */
+export function selectReduceToBytesSkippingPendingRestore(
+  candidates: ArchivedCandidate[],
+  reduceToBytes: number,
+  codexHome: string = resolveCodexHomeDir(),
+): ArchivedCandidate[] {
+  if (!Number.isFinite(reduceToBytes) || reduceToBytes < 0) return [];
+  const total = candidates.reduce((sum, c) => sum + c.bytes, 0);
+  if (total <= reduceToBytes) return [];
+  const need = total - reduceToBytes;
+  const pendingDestRels = collectRestorePendingAcceptedDestRels(codexHome);
+  const out: ArchivedCandidate[] = [];
+  let freed = 0;
+  for (const c of candidates) {
+    if (candidateOverlapsPendingRestore(c, pendingDestRels)) continue;
+    out.push(c);
+    freed += c.bytes;
+    if (freed >= need) break;
+  }
+  return out;
+}
+
+/** Accepted destination paths from every valid in-progress restore marker under `.trash`. */
+export function collectRestorePendingAcceptedDestRels(codexHome: string): Set<string> {
+  const out = new Set<string>();
+  const trashRoot = join(codexHome, TRASH_DIR);
+  if (!existsSync(trashRoot)) return out;
+  for (const name of readdirSync(trashRoot)) {
+    if (!TRASH_EPOCH_DIR.test(name)) continue;
+    const read = readRestorePending(join(trashRoot, name));
+    if (read.status !== "valid") continue;
+    for (const rel of read.state.acceptedDestRels) out.add(rel);
+  }
+  return out;
+}
+
 export function previewArchivedCleanup(
   percent: number,
   codexHome: string = resolveCodexHomeDir(),
 ): CleanupPreview {
   const all = listArchivedCandidates(codexHome);
-  const selected = selectOldestPercent(all, percent);
+  const safe = selectOldestPercentSkippingPendingRestore(all, percent, codexHome);
   const pct = clampPercent(percent);
   return {
     codexHome,
     percent: pct,
-    count: selected.length,
-    bytes: selected.reduce((sum, c) => sum + c.bytes, 0),
-    digest: computePreviewDigest(selected, pct),
-    candidates: selected,
+    count: safe.length,
+    bytes: safe.reduce((sum, c) => sum + c.bytes, 0),
+    digest: computePreviewDigest(safe, pct),
+    candidates: safe,
   };
 }
 
+/** Preview bound to an explicit candidate set (exact digest, percent left at 0). */
+export function previewExactArchivedCleanup(
+  candidates: ArchivedCandidate[],
+  codexHome: string = resolveCodexHomeDir(),
+): CleanupPreview {
+  const safe = filterCandidatesExcludingPendingRestore(candidates, codexHome);
+  return {
+    codexHome,
+    percent: 0,
+    count: safe.length,
+    bytes: safe.reduce((sum, c) => sum + c.bytes, 0),
+    digest: computeExactPreviewDigest(safe),
+    candidates: safe,
+  };
+}
+
+/**
+ * Resolve an exact candidate list from current archive state.
+ * Returns null when any requested path is missing or drifted (caller maps to stale_preview).
+ */
+export function resolveExactArchivedCandidates(
+  candidateRelPaths: string[],
+  codexHome: string = resolveCodexHomeDir(),
+): ArchivedCandidate[] | null {
+  if (!Array.isArray(candidateRelPaths) || candidateRelPaths.length === 0) return [];
+  const all = listArchivedCandidates(codexHome);
+  const byRel = new Map(all.map(c => [c.relPath, c]));
+  const selected: ArchivedCandidate[] = [];
+  for (const rel of candidateRelPaths) {
+    const hit = byRel.get(rel);
+    if (!hit) return null;
+    selected.push(hit);
+  }
+  return selected;
+}
+
 function openDbWritable(dbPath: string, busyTimeoutMs = 100): Database {
   const db = new Database(dbPath);
+  try {
+    // bun:sqlite exposes a binding-level timeout; set both so Windows lock waits
+    // honor the caller's budget (pragma alone has been flaky under CI contention).
+    (db as Database & { timeout?: number }).timeout = busyTimeoutMs;
+  } catch {
+    /* older bindings */
+  }
   try {
     db.exec(`PRAGMA busy_timeout = ${busyTimeoutMs}`);
   } catch {
@@ -552,6 +707,10 @@ type SqlRow = Record<string, string | number | bigint | null | Uint8Array>;
 
 interface SatelliteBackup {
   threadIds: string[];
+  /** Full `threads` row images (SELECT *) captured under the state write lock. */
+  threads?: SqlRow[];
+  dynamicTools?: SqlRow[];
+  spawnEdges?: SqlRow[];
   logs?: { path: string; rows: SqlRow[] };
   memories?: {
     path: string;
@@ -569,6 +728,11 @@ interface SatelliteBackup {
   };
 }
 
+type SatelliteBackupRead =
+  | { status: "missing" }
+  | { status: "ok"; backup: SatelliteBackup }
+  | { status: "invalid" };
+
 interface ReconcileTestHooks {
   failAfterLogsMutation?: boolean;
   failAfterMemoriesMutation?: boolean;
@@ -576,11 +740,42 @@ interface ReconcileTestHooks {
   failBeforeStateCommit?: boolean;
   failSatelliteRestore?: boolean;
   failSatelliteBackupWrite?: boolean;
+  /**
+   * Fail a satellite-backup.json *replacement* after the temp is durable but before
+   * rename — exercises crash-safety of the post-memories rewrite without truncating
+   * the last valid backup.
+   */
+  failSatelliteBackupReplace?: boolean;
   /** Runs after satellite deletes are committed, before state thread deletion. */
   afterSatelliteMutations?: () => void;
 }
 
 const SATELLITE_BACKUP_FILE = "satellite-backup.json";
+/** Marks an incomplete restore so retries can accept dest files and resume metadata. */
+const RESTORE_PENDING_FILE = "restore-pending.json";
+let _satelliteBackupSeq = 0;
+
+type StagedFile = { from: string; to: string; relPath: string };
+
+interface RestorePendingSections {
+  state: boolean;
+  logs: boolean;
+  memories: boolean;
+  goals: boolean;
+}
+
+interface RestorePendingState {
+  version: 1;
+  filesRestored: true;
+  /**
+   * Planned CODEX_HOME-relative destinations for this restore attempt.
+   * Written before moves so a mid-loop failure can still accept placed dests
+   * on resume while finishing files that remain staged.
+   */
+  acceptedDestRels: string[];
+  /** Sections that still need reconciliation on retry. */
+  pending: RestorePendingSections;
+}
 
 function quoteIdent(name: string): string {
   return `"${name.replaceAll('"', '""')}"`;
@@ -590,17 +785,134 @@ function selectRows(db: Database, sql: string, params: Array<string | number>):
   return db.query<SqlRow, Array<string | number>>(sql).all(...params) as SqlRow[];
 }
 
-function insertRowsConflictIgnore(db: Database, table: string, rows: SqlRow[]): void {
+function tableColumnNames(db: Database, table: string): Set<string> {
+  if (!tableExists(db, table)) return new Set();
+  const rows = db.query<{ name: string }, []>(
+    `PRAGMA table_info("${table.replaceAll('"', '""')}")`,
+  ).all();
+  return new Set(rows.map(r => r.name));
+}
+
+/** Insert rows with ON CONFLICT DO NOTHING; returns only rows that were newly inserted. */
+function insertRowsConflictIgnore(db: Database, table: string, rows: SqlRow[]): SqlRow[] {
+  const inserted: SqlRow[] = [];
+  if (rows.length === 0) return inserted;
+  const allowed = tableColumnNames(db, table);
   for (const row of rows) {
-    const cols = Object.keys(row);
+    const cols = Object.keys(row).filter(c => allowed.has(c));
     if (cols.length === 0) continue;
-    db.run(
+    const result = db.run(
       `INSERT INTO ${quoteIdent(table)} (${cols.map(quoteIdent).join(", ")}) VALUES (${cols.map(() => "?").join(", ")}) ON CONFLICT DO NOTHING`,
       cols.map(c => row[c] as string | number | bigint | null | Uint8Array),
     );
+    if (result.changes > 0) inserted.push(row);
+  }
+  return inserted;
+}
+
+/** Snapshot state-DB dependents that cleanup deletes with the thread rows. */
+function snapshotStateDependents(
+  db: Database,
+  threadIds: string[],
+): Pick<SatelliteBackup, "threads" | "dynamicTools" | "spawnEdges"> {
+  const out: Pick<SatelliteBackup, "threads" | "dynamicTools" | "spawnEdges"> = {};
+  if (threadIds.length === 0 || !tableExists(db, "threads")) return out;
+
+  const threads: SqlRow[] = [];
+  for (const chunk of chunkIds(threadIds, SQLITE_ID_CHUNK * 2)) {
+    const placeholders = chunk.map(() => "?").join(",");
+    threads.push(...selectRows(db, `SELECT * FROM threads WHERE id IN (${placeholders})`, chunk));
+  }
+  out.threads = threads;
+
+  if (tableExists(db, "thread_dynamic_tools")) {
+    const dynamicTools: SqlRow[] = [];
+    for (const chunk of chunkIds(threadIds, SQLITE_ID_CHUNK * 2)) {
+      const placeholders = chunk.map(() => "?").join(",");
+      dynamicTools.push(...selectRows(
+        db,
+        `SELECT * FROM thread_dynamic_tools WHERE thread_id IN (${placeholders})`,
+        chunk,
+      ));
+    }
+    out.dynamicTools = dynamicTools;
+  }
+
+  if (tableExists(db, "thread_spawn_edges")) {
+    const spawnEdges: SqlRow[] = [];
+    for (const chunk of chunkIds(threadIds, SQLITE_ID_CHUNK)) {
+      const placeholders = chunk.map(() => "?").join(",");
+      spawnEdges.push(...selectRows(
+        db,
+        `SELECT * FROM thread_spawn_edges
+         WHERE parent_thread_id IN (${placeholders}) OR child_thread_id IN (${placeholders})`,
+        [...chunk, ...chunk],
+      ));
+    }
+    out.spawnEdges = spawnEdges;
+  }
+
+  return out;
+}
+
+/** Remap serialized absolute DB paths onto the newest DBs under the current Codex home. */
+function remapSatelliteBackupPaths(
+  backup: SatelliteBackup,
+  paths: RuntimeDbPaths,
+): { ok: true; backup: SatelliteBackup } | { ok: false } {
+  const next: SatelliteBackup = {
+    threadIds: backup.threadIds,
+    ...(backup.threads ? { threads: backup.threads } : {}),
+    ...(backup.dynamicTools ? { dynamicTools: backup.dynamicTools } : {}),
+    ...(backup.spawnEdges ? { spawnEdges: backup.spawnEdges } : {}),
+  };
+  if (backup.logs) {
+    if (!paths.logs) return { ok: false };
+    next.logs = { ...backup.logs, path: paths.logs };
+  }
+  if (backup.memories) {
+    if (!paths.memories) return { ok: false };
+    next.memories = { ...backup.memories, path: paths.memories };
+  }
+  if (backup.goals) {
+    if (!paths.goals) return { ok: false };
+    next.goals = { ...backup.goals, path: paths.goals };
+  }
+  return { ok: true, backup: next };
+}
+
+/**
+ * Same-volume move that never replaces an existing destination.
+ *
+ * `existsSync` + `renameSync` is TOCTOU: a live file created between the check
+ * and rename can be overwritten (Windows rename replaces files). Hard-link then
+ * unlink fails with EEXIST if `to` appears, which is what trash → archived_sessions
+ * restore needs. Callers under the same `CODEX_HOME` volume should not hit EXDEV.
+ */
+function renameNoReplace(from: string, to: string): void {
+  try {
+    linkSync(from, to);
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException | undefined)?.code;
+    // Hard links unavailable (rare FS) — refuse rather than clobber via rename.
+    if (code === "EXDEV" || code === "EPERM" || code === "ENOTSUP" || code === "EINVAL") {
+      throw Object.assign(new Error("rename_no_replace_unsupported"), { code, cause: error });
+    }
+    throw error;
+  }
+  try {
+    unlinkSync(from);
+  } catch (error) {
+    // Roll back the hard link so we do not leave the file at both paths.
+    try { unlinkSync(to); } catch { /* best-effort */ }
+    throw error;
   }
 }
 
+function isExistError(error: unknown): boolean {
+  return (error as NodeJS.ErrnoException | undefined)?.code === "EEXIST";
+}
+
 function updateRowFromSnapshot(
   db: Database,
   table: string,
@@ -667,8 +979,66 @@ function restoreConsolidateGlobalJob(
   }
 }
 
-function writeSatelliteBackup(stageDir: string, backup: SatelliteBackup): void {
-  writePrivateFile(join(stageDir, SATELLITE_BACKUP_FILE), JSON.stringify(backup));
+/**
+ * Best-effort directory fsync so a preceding rename is durable on crash.
+ * Unsupported on some Windows setups — never treat failure as fatal.
+ */
+function fsyncDirectoryBestEffort(dirPath: string): void {
+  let fd: number | undefined;
+  try {
+    fd = openSync(dirPath, "r");
+    fsyncSync(fd);
+  } catch {
+    /* best-effort */
+  } finally {
+    if (fd !== undefined) {
+      try { closeSync(fd); } catch { /* */ }
+    }
+  }
+}
+
+/**
+ * Atomically replace satellite-backup.json: private temp in the stage, full write + fsync,
+ * rename (with Windows sharing-violation retries), then best-effort directory fsync.
+ * An interrupted update never truncates the last valid backup that was written before a
+ * satellite DB commit.
+ */
+function writeSatelliteBackup(
+  stageDir: string,
+  backup: SatelliteBackup,
+  options?: { failWrite?: boolean; failReplaceBeforeRename?: boolean },
+): void {
+  if (options?.failWrite) throw new Error("test_fail_satellite_backup_write");
+  const dest = join(stageDir, SATELLITE_BACKUP_FILE);
+  const replacing = existsSync(dest);
+  const tmp = join(stageDir, `${SATELLITE_BACKUP_FILE}.${process.pid}.${++_satelliteBackupSeq}.tmp`);
+  const payload = Buffer.from(JSON.stringify(backup), "utf8");
+  const fd = openSync(tmp, "w", 0o600);
+  try {
+    let offset = 0;
+    while (offset < payload.length) {
+      offset += writeSync(fd, payload, offset, payload.length - offset, null);
+    }
+    fsyncSync(fd);
+  } catch (error) {
+    try { closeSync(fd); } catch { /* */ }
+    try { unlinkSync(tmp); } catch { /* */ }
+    throw error;
+  }
+  closeSync(fd);
+  chmodPrivatePath(tmp, 0o600);
+  if (options?.failReplaceBeforeRename && replacing) {
+    try { unlinkSync(tmp); } catch { /* */ }
+    throw new Error("test_fail_satellite_backup_replace");
+  }
+  try {
+    renameAtomicFile(tmp, dest);
+  } catch (error) {
+    try { unlinkSync(tmp); } catch { /* */ }
+    throw error;
+  }
+  chmodPrivatePath(dest, 0o600);
+  fsyncDirectoryBestEffort(stageDir);
 }
 
 function clearSatelliteBackup(stageDir: string): void {
@@ -690,6 +1060,7 @@ interface SatelliteWriteLocks {
 function beginSatelliteWriteLocks(
   paths: RuntimeDbPaths,
   busyTimeoutMs: number,
+  only?: Partial<Record<"logs" | "memories" | "goals", boolean>>,
 ): SatelliteWriteLocks {
   const locks: SatelliteWriteLocks = {};
   const order: Array<{ key: "logs" | "memories" | "goals"; path: string | null }> = [
@@ -699,6 +1070,7 @@ function beginSatelliteWriteLocks(
   ];
   try {
     for (const { key, path } of order) {
+      if (only && !only[key]) continue;
       if (!path || !existsSync(path)) continue;
       const db = openDbWritable(path, busyTimeoutMs);
       try {
@@ -933,11 +1305,19 @@ function deleteAndCommitSatellites(
     if (locks.memories && backup.memories) {
       deleteMemoriesInTx(locks.memories.db, backup.memories);
       if (backup.memories.consolidateTouched) {
+        // Capture under the write lock, but persist only after COMMIT+close.
+        // Holding BEGIN IMMEDIATE across a durable backup rewrite lets Windows CI
+        // disk/AV latency stall the lock long enough for concurrent reopen hooks
+        // (and bun's default 5s test timeout) to hang — see PR #558 windows-latest.
         backup.memories.consolidatePostImage = readConsolidateGlobalJob(locks.memories.db);
-        writeSatelliteBackup(stageDir, backup);
       }
       commitSatelliteLock(locks.memories);
       locks.memories = undefined;
+      if (backup.memories.consolidateTouched) {
+        writeSatelliteBackup(stageDir, backup, {
+          failReplaceBeforeRename: hooks?.failSatelliteBackupReplace,
+        });
+      }
       if (hooks?.failAfterMemoriesMutation) throw new Error("test_fail_after_memories");
     }
     if (locks.goals && backup.goals) {
@@ -1103,11 +1483,14 @@ function reconcileDeletedThreads(
     satelliteLocks = beginSatelliteWriteLocks(paths, busyTimeoutMs);
     try {
       backup = snapshotSatelliteBackupInLocks(satelliteLocks, threadIds);
+      const stateDeps = snapshotStateDependents(stateDb, threadIds);
+      backup.threads = stateDeps.threads;
+      backup.dynamicTools = stateDeps.dynamicTools;
+      backup.spawnEdges = stateDeps.spawnEdges;
       try {
-        if (hooks?.failSatelliteBackupWrite) {
-          throw new Error("test_fail_satellite_backup_write");
-        }
-        writeSatelliteBackup(stageDir, backup);
+        writeSatelliteBackup(stageDir, backup, {
+          failWrite: hooks?.failSatelliteBackupWrite,
+        });
       } catch {
         rollbackAllSatelliteLocks(satelliteLocks);
         stateDb.exec("ROLLBACK");
@@ -1134,7 +1517,7 @@ function reconcileDeletedThreads(
       deleteThreadsAndDependents(stateDb, threadIds);
       if (hooks?.failBeforeStateCommit) throw new Error("test_fail_before_state_commit");
       stateDb.exec("COMMIT");
-      clearSatelliteBackup(stageDir);
+      // Keep satellite-backup.json for quarantine restore; permanent purge removes the stage.
       return { ok: true, threads };
     } catch (error) {
       if (satelliteLocks) rollbackAllSatelliteLocks(satelliteLocks);
@@ -1148,8 +1531,6 @@ function reconcileDeletedThreads(
   }
 }
 
-type StagedFile = { from: string; to: string; relPath: string };
-
 function absFromRel(codexHome: string, relPath: string): string {
   if (relPath.includes("..") || isAbsolute(relPath) || /^[A-Za-z]:[\\/]/.test(relPath)) {
     throw new Error("invalid_rel_path");
@@ -1271,6 +1652,11 @@ export interface ExecuteCleanupOptions {
   mode: CleanupMode;
   /** Required digest from preview; rejects when the candidate set drifted. */
   digest: string;
+  /**
+   * Optional exact candidate set (logical relPaths). When set, selection bypasses
+   * percent rounding and the digest must match `computeExactPreviewDigest`.
+   */
+  candidateRelPaths?: string[];
   codexHome?: string;
   /** Test-only: shrink busy_timeout so lock tests fail fast. */
   busyTimeoutMs?: number;
@@ -1287,6 +1673,7 @@ export interface ExecuteCleanupOptions {
     failBeforeStateCommit?: boolean;
     failSatelliteRestore?: boolean;
     failSatelliteBackupWrite?: boolean;
+    failSatelliteBackupReplace?: boolean;
     afterSatelliteMutations?: () => void;
   };
 }
@@ -1316,6 +1703,7 @@ export function pickWireCleanupTestHooks(raw: unknown): CleanupWireTestHooks | u
   if (typeof o.failBeforeStateCommit === "boolean") out.failBeforeStateCommit = o.failBeforeStateCommit;
   if (typeof o.failSatelliteRestore === "boolean") out.failSatelliteRestore = o.failSatelliteRestore;
   if (typeof o.failSatelliteBackupWrite === "boolean") out.failSatelliteBackupWrite = o.failSatelliteBackupWrite;
+  if (typeof o.failSatelliteBackupReplace === "boolean") out.failSatelliteBackupReplace = o.failSatelliteBackupReplace;
   return Object.keys(out).length > 0 ? out : undefined;
 }
 
@@ -1358,10 +1746,38 @@ export function executeArchivedCleanup(options: ExecuteCleanupOptions): CleanupR
     return fail(mode, percent, "invalid_digest");
   }
 
-  const preview = previewArchivedCleanup(percent, codexHome);
+  let preview: CleanupPreview;
+  let unfilteredSelected: ArchivedCandidate[];
+  if (options.candidateRelPaths !== undefined) {
+    const selected = resolveExactArchivedCandidates(options.candidateRelPaths, codexHome);
+    if (selected === null) {
+      return fail(mode, percent, "stale_preview");
+    }
+    unfilteredSelected = selected;
+    preview = previewExactArchivedCleanup(selected, codexHome);
+  } else {
+    const all = listArchivedCandidates(codexHome);
+    unfilteredSelected = selectOldestPercent(all, percent);
+    preview = previewArchivedCleanup(percent, codexHome);
+  }
   if (preview.digest.toLowerCase() !== options.digest.toLowerCase()) {
+    const pendingDestRels = collectRestorePendingAcceptedDestRels(codexHome);
+    const blocked = unfilteredSelected.filter(c => candidateOverlapsPendingRestore(c, pendingDestRels));
+    const unfilteredDigest = options.candidateRelPaths !== undefined
+      ? computeExactPreviewDigest(unfilteredSelected)
+      : computePreviewDigest(unfilteredSelected, percent);
+    if (
+      unfilteredDigest.toLowerCase() === options.digest.toLowerCase()
+      && blocked.length > 0
+    ) {
+      return fail(mode, percent, "restore_pending_overlap");
+    }
     return fail(mode, percent, "stale_preview");
   }
+  const pendingDestRels = collectRestorePendingAcceptedDestRels(codexHome);
+  if (preview.candidates.some(c => candidateOverlapsPendingRestore(c, pendingDestRels))) {
+    return fail(mode, percent, "restore_pending_overlap");
+  }
 
   if (preview.candidates.length === 0) {
     return {
@@ -1505,9 +1921,12 @@ export function executeArchivedCleanup(options: ExecuteCleanupOptions): CleanupR
           digest: preview.digest,
           purgeIncomplete: true,
           purgedRelPaths: purge.purged.map(item => item.relPath),
-          entries: manifestEntries.filter(entry =>
-            entry.physicalRelPaths.some(rel => survivingRelPaths.has(rel)),
-          ),
+          entries: manifestEntries
+            .map(entry => ({
+              ...entry,
+              physicalRelPaths: entry.physicalRelPaths.filter(rel => survivingRelPaths.has(rel)),
+            }))
+            .filter(entry => entry.physicalRelPaths.length > 0),
         }, null, 2),
       );
     } catch { /* best-effort: the pre-commit manifest is still on disk */ }
@@ -1536,3 +1955,1060 @@ export function executeArchivedCleanup(options: ExecuteCleanupOptions): CleanupR
     removedPaths,
   };
 }
+
+// ---------------------------------------------------------------------------
+// Phase 2.1 — quarantine list + restore
+// ---------------------------------------------------------------------------
+
+export type RestoreErrorCode =
+  | "invalid_trash"
+  | "missing_trash"
+  | "codex_busy"
+  | "storage_mutation_busy"
+  | "fs_failed"
+  | "db_reconcile_failed"
+  | "dest_exists"
+  | "restore_failed"
+  | "restore_worker_timeout"
+  | "restore_worker_aborted"
+  | "restore_worker_failed";
+
+export interface TrashEntrySummary {
+  /** CODEX_HOME-relative path, e.g. `.trash/1700000000000`. */
+  id: string;
+  /** Epoch directory name (may include collision suffix, e.g. `1700-1`). */
+  epoch: string;
+  fileCount: number;
+  bytes: number;
+  quarantinedAt?: number;
+  mode?: CleanupMode;
+}
+
+export interface RestoreResult {
+  ok: boolean;
+  trashDir?: string;
+  count: number;
+  bytes: number;
+  restoredPaths: string[];
+  error?: RestoreErrorCode;
+  /** Optional operator-facing detail when the error code alone is insufficient. */
+  message?: string;
+}
+
+interface TrashManifest {
+  quarantinedAt?: number;
+  mode?: CleanupMode;
+  entries?: CleanupManifestEntry[];
+}
+
+/** Epoch dir names: digits, optionally `-N` from createExclusiveStageDir collision. */
+const TRASH_EPOCH_DIR = /^(\d+)(-\d+)?$/;
+
+/**
+ * Parse a trash `manifest.json` atomically.
+ *
+ * Any missing `entries` array, or any malformed entry / `physicalRelPaths` value /
+ * required field, rejects the **entire** manifest (returns null). Individual bad
+ * entries are never filtered out so a partial parse cannot silently drop evidence.
+ */
+function parseTrashManifest(raw: string): TrashManifest | null {
+  try {
+    const parsed = JSON.parse(raw) as unknown;
+    if (!parsed || typeof parsed !== "object") return null;
+    const o = parsed as Record<string, unknown>;
+    if (!Array.isArray(o.entries)) return null;
+
+    const entries: CleanupManifestEntry[] = [];
+    for (const e of o.entries) {
+      if (!e || typeof e !== "object" || Array.isArray(e)) return null;
+      const entry = e as Record<string, unknown>;
+      if (typeof entry.relPath !== "string" || entry.relPath.length === 0) return null;
+      if (typeof entry.bytes !== "number" || !Number.isFinite(entry.bytes)) return null;
+      if (typeof entry.mtimeMs !== "number" || !Number.isFinite(entry.mtimeMs)) return null;
+      if (!Array.isArray(entry.physicalRelPaths) || entry.physicalRelPaths.length === 0) return null;
+      const physical: string[] = [];
+      for (const p of entry.physicalRelPaths) {
+        // Do not strip bad elements — one malformed path invalidates the whole manifest.
+        if (typeof p !== "string" || p.length === 0) return null;
+        physical.push(p);
+      }
+      if ("threadId" in entry && typeof entry.threadId !== "string") return null;
+      if ("rolloutPath" in entry && typeof entry.rolloutPath !== "string") return null;
+      if (
+        "archived" in entry
+        && entry.archived !== null
+        && typeof entry.archived !== "number"
+      ) {
+        return null;
+      }
+      entries.push({
+        relPath: entry.relPath,
+        bytes: entry.bytes,
+        mtimeMs: entry.mtimeMs,
+        physicalRelPaths: physical,
+        ...(typeof entry.threadId === "string" ? { threadId: entry.threadId } : {}),
+        ...(typeof entry.rolloutPath === "string" ? { rolloutPath: entry.rolloutPath } : {}),
+        ...(entry.archived === null || typeof entry.archived === "number"
+          ? { archived: entry.archived as number | null }
+          : {}),
+      });
+    }
+
+    const out: TrashManifest = { entries };
+    if (typeof o.quarantinedAt === "number" && Number.isFinite(o.quarantinedAt)) {
+      out.quarantinedAt = o.quarantinedAt;
+    }
+    if (o.mode === "quarantine" || o.mode === "permanent") out.mode = o.mode;
+    return out;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Validate a trash entry id as a single `.trash/<epoch>` segment under CODEX_HOME.
+ * Returns the absolute stage directory, or null when the id is unsafe / missing.
+ */
+export function resolveTrashStageDir(
+  trashId: string,
+  codexHome: string,
+): { ok: true; stageDir: string; id: string } | { ok: false; error: RestoreErrorCode } {
+  const normalized = toForwardSlash(trashId.trim()).replace(/\/+$/, "");
+  if (!normalized.startsWith(`${TRASH_DIR}/`)) return { ok: false, error: "invalid_trash" };
+  const rest = normalized.slice(TRASH_DIR.length + 1);
+  if (!rest || rest.includes("/") || rest.includes("\\") || rest.includes("..")) {
+    return { ok: false, error: "invalid_trash" };
+  }
+  if (!TRASH_EPOCH_DIR.test(rest)) return { ok: false, error: "invalid_trash" };
+  let stageDir: string;
+  try {
+    stageDir = absFromRel(codexHome, `${TRASH_DIR}/${rest}`);
+  } catch {
+    return { ok: false, error: "invalid_trash" };
+  }
+  if (!existsSync(stageDir)) return { ok: false, error: "missing_trash" };
+  try {
+    if (!statSync(stageDir).isDirectory()) return { ok: false, error: "invalid_trash" };
+  } catch {
+    return { ok: false, error: "missing_trash" };
+  }
+  return { ok: true, stageDir, id: `${TRASH_DIR}/${rest}` };
+}
+
+function sumTrashEntryBytes(stageDir: string, manifest: TrashManifest | null): {
+  fileCount: number;
+  bytes: number;
+} {
+  let fileCount = 0;
+  let bytes = 0;
+  let names: string[] = [];
+  try {
+    names = readdirSync(stageDir);
+  } catch {
+    return { fileCount: 0, bytes: 0 };
+  }
+  for (const name of names) {
+    if (
+      name === "manifest.json"
+      || name === SATELLITE_BACKUP_FILE
+      || name === RESTORE_PENDING_FILE
+    ) {
+      continue;
+    }
+    if (!isRolloutFileName(name)) continue;
+    try {
+      const st = statSync(join(stageDir, name));
+      if (!st.isFile()) continue;
+      fileCount += 1;
+      bytes += st.size;
+    } catch { /* */ }
+  }
+  // Prefer live FS counts; fall back to manifest totals when the stage is empty of rollouts.
+  if (fileCount === 0 && manifest?.entries?.length) {
+    fileCount = manifest.entries.reduce((n, e) => n + Math.max(1, e.physicalRelPaths.length), 0);
+    bytes = manifest.entries.reduce((n, e) => n + (e.bytes || 0), 0);
+  }
+  return { fileCount, bytes };
+}
+
+/** List quarantine entries under `CODEX_HOME/.trash/` (relative ids only). */
+export function listTrashEntries(
+  codexHome: string = resolveCodexHomeDir(),
+): TrashEntrySummary[] {
+  const trashRoot = join(codexHome, TRASH_DIR);
+  let names: string[] = [];
+  try {
+    names = readdirSync(trashRoot);
+  } catch {
+    return [];
+  }
+  const out: TrashEntrySummary[] = [];
+  for (const name of names) {
+    if (!TRASH_EPOCH_DIR.test(name)) continue;
+    const stageDir = join(trashRoot, name);
+    try {
+      if (!statSync(stageDir).isDirectory()) continue;
+    } catch {
+      continue;
+    }
+    let manifest: TrashManifest | null = null;
+    try {
+      manifest = parseTrashManifest(readFileSync(join(stageDir, "manifest.json"), "utf8"));
+    } catch {
+      manifest = null;
+    }
+    const { fileCount, bytes } = sumTrashEntryBytes(stageDir, manifest);
+    // Skip empty collision placeholders left behind without a manifest or rollouts.
+    if (fileCount === 0 && !manifest?.entries?.length) {
+      try {
+        if (!existsSync(join(stageDir, "manifest.json"))) continue;
+      } catch {
+        continue;
+      }
+    }
+    out.push({
+      id: `${TRASH_DIR}/${name}`,
+      epoch: name,
+      fileCount,
+      bytes,
+      ...(manifest?.quarantinedAt !== undefined ? { quarantinedAt: manifest.quarantinedAt } : {}),
+      ...(manifest?.mode ? { mode: manifest.mode } : {}),
+    });
+  }
+  out.sort((a, b) => {
+    const aq = a.quarantinedAt ?? (Number(a.epoch.split("-")[0]) || 0);
+    const bq = b.quarantinedAt ?? (Number(b.epoch.split("-")[0]) || 0);
+    return bq - aq || b.epoch.localeCompare(a.epoch);
+  });
+  return out;
+}
+
+function readSatelliteBackupFile(stageDir: string): SatelliteBackupRead {
+  const path = join(stageDir, SATELLITE_BACKUP_FILE);
+  if (!existsSync(path)) return { status: "missing" };
+  try {
+    const raw = JSON.parse(readFileSync(path, "utf8")) as unknown;
+    if (!raw || typeof raw !== "object") return { status: "invalid" };
+    const o = raw as SatelliteBackup;
+    if (!Array.isArray(o.threadIds)) return { status: "invalid" };
+    return { status: "ok", backup: o };
+  } catch {
+    // File exists but is truncated / malformed — distinct from a missing backup.
+    return { status: "invalid" };
+  }
+}
+
+function isSqlRowArray(value: unknown): value is SqlRow[] {
+  return Array.isArray(value) && value.every(row => row && typeof row === "object" && !Array.isArray(row));
+}
+
+/** True when a snapshotted thread row covers every NOT NULL column on the live schema. */
+function threadSnapshotCoversRequiredColumns(row: SqlRow, requiredCols: string[]): boolean {
+  for (const col of requiredCols) {
+    if (!(col in row) || row[col] === undefined) return false;
+  }
+  return true;
+}
+
+function requiredThreadColumnNames(db: Database): string[] {
+  if (!tableExists(db, "threads")) return [];
+  const rows = db.query<{ name: string; notnull: number }, []>(
+    `PRAGMA table_info("threads")`,
+  ).all();
+  return rows.filter(r => r.notnull === 1).map(r => r.name);
+}
+
+/**
+ * Build a production-shaped thread row for schemas that predate full satellite snapshots.
+ * Prefer `readThreadFieldsFromRollout` (canonical history/session_meta path); fall back to
+ * the sparse manifest fields only when the live schema does not require model/source/message.
+ */
+function reconstructThreadRowFromRollout(
+  entry: CleanupManifestEntry,
+  rolloutAbsPath: string,
+  allowedCols: Set<string>,
+  requiredCols: string[],
+): SqlRow | null {
+  if (typeof entry.threadId !== "string" || typeof entry.rolloutPath !== "string") return null;
+
+  const fields = readThreadFieldsFromRollout(rolloutAbsPath);
+  const row: SqlRow = {
+    id: entry.threadId,
+    rollout_path: entry.rolloutPath,
+  };
+
+  if (fields) {
+    // Prefer manifest thread id (binding) but keep rollout-derived listing fields.
+    if (allowedCols.has("model_provider")) row.model_provider = fields.modelProvider;
+    if (allowedCols.has("source")) row.source = fields.source;
+    if (allowedCols.has("first_user_message")) row.first_user_message = fields.firstUserMessage;
+    if (allowedCols.has("has_user_event")) row.has_user_event = fields.hasUserEvent;
+    if (allowedCols.has("cwd") && fields.cwd !== undefined) row.cwd = fields.cwd;
+    if (allowedCols.has("history_mode") && fields.historyMode !== undefined) {
+      row.history_mode = fields.historyMode;
+    }
+    if (allowedCols.has("cli_version") && fields.cliVersion !== undefined) {
+      row.cli_version = fields.cliVersion;
+    }
+  }
+
+  if (allowedCols.has("archived")) {
+    row.archived = entry.archived ?? 1;
+  }
+  if (allowedCols.has("archived_at")) {
+    row.archived_at = null;
+  }
+
+  // Fill remaining NOT NULL columns with safe empties when the rollout lacked them
+  // (e.g. fixture rollouts without a user turn still need first_user_message = '').
+  for (const col of requiredCols) {
+    if (row[col] !== undefined) continue;
+    if (col === "id" || col === "rollout_path") continue;
+    if (col === "model_provider") row[col] = "openai";
+    else if (col === "source") row[col] = "cli";
+    else if (col === "first_user_message") row[col] = "";
+    else if (col === "has_user_event") row[col] = 0;
+    else if (col === "archived") row[col] = entry.archived ?? 1;
+    else return null; // unknown required column we cannot invent
+  }
+
+  // If the schema requires listing fields, refuse when the rollout was unreadable.
+  const needsSessionMeta = requiredCols.some(
+    c => c === "model_provider" || c === "source" || c === "first_user_message",
+  );
+  if (needsSessionMeta && !fields) return null;
+
+  return row;
+}
+
+type RestorePendingRead =
+  | { status: "missing" }
+  | { status: "valid"; state: RestorePendingState }
+  | { status: "invalid" };
+
+let _restorePendingSeq = 0;
+
+function parseRestorePendingState(raw: unknown): RestorePendingState | null {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const o = raw as Record<string, unknown>;
+  if (o.version !== 1 || o.filesRestored !== true) return null;
+  if (!Array.isArray(o.acceptedDestRels)) return null;
+  const acceptedDestRels = o.acceptedDestRels.filter((r): r is string => typeof r === "string");
+  if (acceptedDestRels.length !== o.acceptedDestRels.length) return null;
+  const pendingRaw = o.pending;
+  if (!pendingRaw || typeof pendingRaw !== "object" || Array.isArray(pendingRaw)) return null;
+  const p = pendingRaw as Record<string, unknown>;
+  if (
+    typeof p.state !== "boolean"
+    || typeof p.logs !== "boolean"
+    || typeof p.memories !== "boolean"
+    || typeof p.goals !== "boolean"
+  ) {
+    return null;
+  }
+  return {
+    version: 1,
+    filesRestored: true,
+    acceptedDestRels,
+    pending: {
+      state: p.state,
+      logs: p.logs,
+      memories: p.memories,
+      goals: p.goals,
+    },
+  };
+}
+
+/**
+ * Distinguish a missing marker from a present-but-malformed one. An invalid marker
+ * must never be treated as a fresh restore (that would ignore already-moved files).
+ */
+function readRestorePending(stageDir: string): RestorePendingRead {
+  const path = join(stageDir, RESTORE_PENDING_FILE);
+  if (!existsSync(path)) return { status: "missing" };
+  try {
+    const state = parseRestorePendingState(JSON.parse(readFileSync(path, "utf8")) as unknown);
+    if (!state) return { status: "invalid" };
+    return { status: "valid", state };
+  } catch {
+    return { status: "invalid" };
+  }
+}
+
+/**
+ * Atomically replace restore-pending.json: private temp in the stage, fsync, then rename.
+ * An interrupted update leaves the previous valid marker intact.
+ */
+function writeRestorePending(
+  stageDir: string,
+  state: RestorePendingState,
+  options?: { failBeforeRename?: boolean; failWrite?: boolean },
+): void {
+  if (options?.failWrite) throw new Error("test_fail_pending_write");
+  const dest = join(stageDir, RESTORE_PENDING_FILE);
+  const tmp = join(stageDir, `${RESTORE_PENDING_FILE}.${process.pid}.${++_restorePendingSeq}.tmp`);
+  const payload = JSON.stringify(state);
+  const fd = openSync(tmp, "w", 0o600);
+  try {
+    writeSync(fd, payload, null, "utf8");
+    fsyncSync(fd);
+  } catch (error) {
+    try { closeSync(fd); } catch { /* */ }
+    try { unlinkSync(tmp); } catch { /* */ }
+    throw error;
+  }
+  closeSync(fd);
+  chmodPrivatePath(tmp, 0o600);
+  if (options?.failBeforeRename) {
+    try { unlinkSync(tmp); } catch { /* */ }
+    throw new Error("test_fail_pending_rename");
+  }
+  try {
+    renameSync(tmp, dest);
+  } catch (error) {
+    try { unlinkSync(tmp); } catch { /* */ }
+    throw error;
+  }
+}
+
+function restoreThreadsFromManifest(
+  stateDbPath: string | null,
+  entries: CleanupManifestEntry[],
+  backup: SatelliteBackup | null,
+  busyTimeoutMs: number,
+  codexHome: string,
+): { ok: true } | ReconcileErr {
+  const manifestThreadIds = entries
+    .map(e => e.threadId)
+    .filter((id): id is string => typeof id === "string");
+  const backupThreadIds = backup?.threadIds ?? [];
+  const needsThreads = manifestThreadIds.length > 0
+    || backupThreadIds.length > 0
+    || Boolean(backup?.threads?.length);
+
+  if (needsThreads && (!stateDbPath || !existsSync(stateDbPath))) {
+    return { ok: false, error: "db_reconcile_failed" };
+  }
+  if (!stateDbPath || !existsSync(stateDbPath)) {
+    return { ok: true };
+  }
+
+  const result = withWritableDb(stateDbPath, busyTimeoutMs, db => {
+    if (!tableExists(db, "threads")) throw new Error("missing_threads_table");
+
+    const requiredCols = requiredThreadColumnNames(db);
+    const allowedCols = tableColumnNames(db, "threads");
+    const snapshotThreads = backup?.threads && isSqlRowArray(backup.threads)
+      ? backup.threads
+      : [];
+    const completeSnapshots = snapshotThreads.filter(row =>
+      threadSnapshotCoversRequiredColumns(row, requiredCols),
+    );
+    const coveredIds = new Set(
+      completeSnapshots
+        .map(r => r.id)
+        .filter((id): id is string => typeof id === "string"),
+    );
+
+    // Legacy Phase-2 quarantine (no / incomplete satellite thread snapshots): reconstruct
+    // every required column from the restored rollout via the history-provider session path.
+    const toReconstruct = entries.filter(
+      e => typeof e.threadId === "string"
+        && typeof e.rolloutPath === "string"
+        && !coveredIds.has(e.threadId!),
+    );
+    const reconstructed: SqlRow[] = [];
+    for (const entry of toReconstruct) {
+      let abs: string | undefined;
+      try {
+        abs = absFromRel(codexHome, entry.rolloutPath!);
+      } catch {
+        abs = undefined;
+      }
+      // Legacy compressed-only quarantine: manifest rolloutPath is often the logical
+      // `.jsonl` name while the only restored physical file is `.jsonl.zst`.
+      if (!abs || !existsSync(abs)) {
+        for (const rel of entry.physicalRelPaths) {
+          try {
+            const candidate = absFromRel(codexHome, rel);
+            if (existsSync(candidate)) {
+              abs = candidate;
+              break;
+            }
+          } catch {
+            /* try next physical path */
+          }
+        }
+      }
+      if (!abs) throw new Error("missing_rollout_for_thread");
+      // Prefer a plain .jsonl sibling when present; otherwise readThreadFieldsFromRollout
+      // decompresses a lone .jsonl.zst in memory (bounded) for legacy quarantine restores.
+      if (abs.endsWith(ZST_SUFFIX)) {
+        const plain = abs.slice(0, -".zst".length);
+        if (existsSync(plain)) abs = plain;
+      }
+      const row = reconstructThreadRowFromRollout(entry, abs, allowedCols, requiredCols);
+      if (!row) throw new Error("thread_reconstruct_failed");
+      reconstructed.push(row);
+    }
+
+    if (completeSnapshots.length > 0) {
+      insertRowsConflictIgnore(db, "threads", completeSnapshots);
+    }
+    if (reconstructed.length > 0) {
+      insertRowsConflictIgnore(db, "threads", reconstructed);
+    }
+
+    if (backup?.dynamicTools && isSqlRowArray(backup.dynamicTools) && tableExists(db, "thread_dynamic_tools")) {
+      insertRowsConflictIgnore(db, "thread_dynamic_tools", backup.dynamicTools);
+    }
+    if (backup?.spawnEdges && isSqlRowArray(backup.spawnEdges) && tableExists(db, "thread_spawn_edges")) {
+      insertRowsConflictIgnore(db, "thread_spawn_edges", backup.spawnEdges);
+    }
+  });
+  if (!result.ok) return result;
+  return { ok: true };
+}
+
+function isSafeArchivedPhysicalRel(rel: string): boolean {
+  const normalized = toForwardSlash(rel);
+  if (!normalized.startsWith(`${ARCHIVED_SESSIONS_DIR}/`)) return false;
+  if (normalized.includes("..")) return false;
+  const rest = normalized.slice(ARCHIVED_SESSIONS_DIR.length + 1);
+  if (!rest || rest.includes("/")) return false;
+  return isRolloutFileName(rest);
+}
+
+/** Test-only failure injection for restore atomicity regressions. */
+export interface RestoreTestHooks {
+  /** After state threads/dependents commit, before satellite commits. */
+  failAfterStateCommit?: boolean;
+  /** After the first satellite DB commit (logs → memories → goals). */
+  failAfterFirstSatelliteCommit?: boolean;
+  /** When the leftover staged-rollout completeness gate runs. */
+  failAtLeftoverStageGate?: boolean;
+  /** Fail the initial restore-pending.json write (before any file moves). */
+  failInitialPendingWrite?: boolean;
+  /** Fail a later pending update after the temp is written but before rename. */
+  failPendingWriteBeforeRename?: boolean;
+  /** Crash immediately after file moves (marker already durable). */
+  failAfterFileMoves?: boolean;
+  /**
+   * After this many successful rollout moves in the current attempt, throw.
+   * Exercises mid-loop failure with some dests placed and others still staged.
+   */
+  failAfterMoveCount?: number;
+  /** Fail renaming the completed stage to a non-listable tombstone dir. */
+  failStageTombstoneRename?: boolean;
+  /** After tombstone rename, skip best-effort tombstone delete (orphan is OK). */
+  failTombstoneDelete?: boolean;
+  /**
+   * Test-only: spin-wait this many ms after rollout file moves, before DB
+   * reconcile, so cleanup can race an in-flight restore.
+   */
+  holdAfterFileMovesMs?: number;
+}
+
+/**
+ * Resume must not clear owed satellite work when the matching backup section is
+ * absent — fail closed per section instead.
+ */
+function failClosedSatelliteResume(
+  priorPending: RestorePendingState,
+  satelliteBackup: SatelliteBackup | null,
+): RestoreErrorCode | null {
+  const owed = priorPending.pending;
+  if (!owed.logs && !owed.memories && !owed.goals) return null;
+  if (!satelliteBackup) return "db_reconcile_failed";
+  if (owed.logs && !satelliteBackup.logs) return "db_reconcile_failed";
+  if (owed.memories && !satelliteBackup.memories) return "db_reconcile_failed";
+  if (owed.goals && !satelliteBackup.goals) return "db_reconcile_failed";
+  return null;
+}
+
+/**
+ * Successful restore finalization: rename the stage to a tombstone name that
+ * `listTrashEntries` ignores, then delete the tombstone best-effort. A failed
+ * rename leaves the original stage (and all evidence) intact for retry.
+ */
+function finalizeRestoredStage(
+  stageDir: string,
+  codexHome: string,
+  hooks?: Pick<RestoreTestHooks, "failStageTombstoneRename" | "failTombstoneDelete">,
+): boolean {
+  const trashRoot = join(codexHome, TRASH_DIR);
+  const epoch = basename(stageDir);
+  const tombstoneName = `.tombstone-${epoch}-${randomUUID()}`;
+  const tombstonePath = join(trashRoot, tombstoneName);
+  try {
+    if (hooks?.failStageTombstoneRename) throw new Error("test_fail_stage_tombstone_rename");
+    renameSync(stageDir, tombstonePath);
+  } catch {
+    return false;
+  }
+  if (!hooks?.failTombstoneDelete) {
+    try { rmSync(tombstonePath, { recursive: true, force: true }); } catch { /* best-effort */ }
+  }
+  return true;
+}
+
+/**
+ * Restore one quarantine entry: move JSONL back, re-insert threads (+ satellites
+ * when satellite-backup.json is present), then remove the trash directory.
+ *
+ * Late failures after files have moved never compensate metadata or restage.
+ * Instead they persist `restore-pending.json` (accepted dest paths + which
+ * state/logs/memories/goals sections still need work) atomically *before* any
+ * rollout move, then update it after each section so a retry can accept existing
+ * destinations and resume only missing metadata.
+ */
+export function restoreTrashEntry(
+  trashId: string,
+  options?: {
+    codexHome?: string;
+    busyTimeoutMs?: number;
+    _test?: RestoreTestHooks;
+  },
+): RestoreResult {
+  const codexHome = options?.codexHome ?? resolveCodexHomeDir();
+  const busyTimeoutMs = options?.busyTimeoutMs ?? 100;
+  const hooks = options?._test;
+
+  const resolved = resolveTrashStageDir(trashId, codexHome);
+  if (!resolved.ok) {
+    return { ok: false, count: 0, bytes: 0, restoredPaths: [], error: resolved.error };
+  }
+  const { stageDir, id } = resolved;
+
+  let manifestRaw: string;
+  try {
+    manifestRaw = readFileSync(join(stageDir, "manifest.json"), "utf8");
+  } catch {
+    return { ok: false, trashDir: id, count: 0, bytes: 0, restoredPaths: [], error: "invalid_trash" };
+  }
+  const manifest = parseTrashManifest(manifestRaw);
+  if (!manifest?.entries?.length) {
+    return { ok: false, trashDir: id, count: 0, bytes: 0, restoredPaths: [], error: "invalid_trash" };
+  }
+
+  const pendingRead = readRestorePending(stageDir);
+  if (pendingRead.status === "invalid") {
+    // Malformed marker means an incomplete restore may already have moved files;
+    // never treat it as a fresh restore.
+    return { ok: false, trashDir: id, count: 0, bytes: 0, restoredPaths: [], error: "fs_failed" };
+  }
+  const priorPending = pendingRead.status === "valid" ? pendingRead.state : null;
+  const acceptedDest = new Set(priorPending?.acceptedDestRels ?? []);
+
+  // Partial permanent purges may leave only a subset of physical files on disk —
+  // trim to survivors rather than failing the whole entry for a purged twin.
+  // Resume also treats already-restored accepted destinations as survivors.
+  const entries: CleanupManifestEntry[] = [];
+  for (const entry of manifest.entries) {
+    if (!entry.physicalRelPaths.every(isSafeArchivedPhysicalRel)) {
+      return { ok: false, trashDir: id, count: 0, bytes: 0, restoredPaths: [], error: "invalid_trash" };
+    }
+    const surviving = entry.physicalRelPaths.filter(rel => {
+      if (existsSync(join(stageDir, basename(rel)))) return true;
+      if (!acceptedDest.has(rel)) return false;
+      try {
+        return existsSync(absFromRel(codexHome, rel));
+      } catch {
+        return false;
+      }
+    });
+    if (surviving.length === 0) {
+      return { ok: false, trashDir: id, count: 0, bytes: 0, restoredPaths: [], error: "fs_failed" };
+    }
+    entries.push({ ...entry, physicalRelPaths: surviving });
+  }
+
+  const paths = discoverRuntimeDbPaths(codexHome);
+  const backupRead = readSatelliteBackupFile(stageDir);
+  if (backupRead.status === "invalid") {
+    return {
+      ok: false,
+      trashDir: id,
+      count: 0,
+      bytes: 0,
+      restoredPaths: [],
+      error: "db_reconcile_failed",
+    };
+  }
+
+  let satelliteBackup: SatelliteBackup | null = null;
+  if (backupRead.status === "ok") {
+    const remapped = remapSatelliteBackupPaths(backupRead.backup, paths);
+    if (!remapped.ok) {
+      return {
+        ok: false,
+        trashDir: id,
+        count: 0,
+        bytes: 0,
+        restoredPaths: [],
+        error: "db_reconcile_failed",
+      };
+    }
+    satelliteBackup = remapped.backup;
+  }
+
+  if (priorPending) {
+    const resumeErr = failClosedSatelliteResume(priorPending, satelliteBackup);
+    if (resumeErr) {
+      return {
+        ok: false,
+        trashDir: id,
+        count: 0,
+        bytes: 0,
+        restoredPaths: [],
+        error: resumeErr,
+      };
+    }
+  }
+
+  const pendingSections: RestorePendingSections = {
+    state: priorPending ? priorPending.pending.state : true,
+    logs: priorPending ? priorPending.pending.logs : Boolean(satelliteBackup?.logs),
+    memories: priorPending ? priorPending.pending.memories : Boolean(satelliteBackup?.memories),
+    goals: priorPending ? priorPending.pending.goals : Boolean(satelliteBackup?.goals),
+  };
+
+  const needAnySatellite = pendingSections.logs || pendingSections.memories || pendingSections.goals;
+  if (pendingSections.state) {
+    const needsThreads = entries.some(e => typeof e.threadId === "string")
+      || Boolean(satelliteBackup?.threadIds?.length)
+      || Boolean(satelliteBackup?.threads?.length);
+    if (needsThreads && (!paths.state || !existsSync(paths.state))) {
+      return {
+        ok: false,
+        trashDir: id,
+        count: 0,
+        bytes: 0,
+        restoredPaths: [],
+        error: "db_reconcile_failed",
+      };
+    }
+    const probe = probeStateDbWritable(codexHome, busyTimeoutMs);
+    if (!probe.ok) {
+      return {
+        ok: false,
+        trashDir: id,
+        count: 0,
+        bytes: 0,
+        restoredPaths: [],
+        error: probe.error === "codex_busy" ? "codex_busy" : "db_reconcile_failed",
+      };
+    }
+  }
+
+  // Acquire only the satellite locks still needed so a busy DB for an already-
+  // finished section cannot block resume. Locks happen before moves on a fresh
+  // attempt so failure stays retryable (nothing has left the stage yet).
+  let satelliteLocks: SatelliteWriteLocks | undefined;
+  if (needAnySatellite) {
+    try {
+      satelliteLocks = beginSatelliteWriteLocks(paths, busyTimeoutMs, {
+        logs: pendingSections.logs,
+        memories: pendingSections.memories,
+        goals: pendingSections.goals,
+      });
+    } catch (error) {
+      return {
+        ok: false,
+        trashDir: id,
+        count: 0,
+        bytes: 0,
+        restoredPaths: [],
+        error: mapDbError(error) === "codex_busy" ? "codex_busy" : "db_reconcile_failed",
+      };
+    }
+  }
+
+  const failBeforeMoves = (error: RestoreErrorCode): RestoreResult => {
+    if (satelliteLocks) rollbackAllSatelliteLocks(satelliteLocks);
+    return { ok: false, trashDir: id, count: 0, bytes: 0, restoredPaths: [], error };
+  };
+
+  // Plan renames: staged basename → original archived_sessions path.
+  // Resume accepts destinations already restored by this incomplete attempt.
+  const alreadyMoved: StagedFile[] = [];
+  const toMove: StagedFile[] = [];
+  for (const entry of entries) {
+    for (const rel of entry.physicalRelPaths) {
+      const base = basename(rel);
+      const from = join(stageDir, base);
+      let to: string;
+      try {
+        to = absFromRel(codexHome, rel);
+      } catch {
+        return failBeforeMoves("invalid_trash");
+      }
+      const fromExists = existsSync(from);
+      const toExists = existsSync(to);
+      if (toExists && acceptedDest.has(rel) && !fromExists) {
+        alreadyMoved.push({ from, to, relPath: rel });
+        continue;
+      }
+      if (toExists) {
+        return failBeforeMoves("dest_exists");
+      }
+      if (!fromExists) {
+        return failBeforeMoves("fs_failed");
+      }
+      toMove.push({ from, to, relPath: rel });
+    }
+  }
+
+  const planned = [...alreadyMoved, ...toMove];
+  const restoredPaths = [...new Set(entries.map(e => e.relPath))];
+  const bytes = entries.reduce((sum, e) => sum + (e.bytes || 0), 0);
+  const partialCounts = { count: restoredPaths.length, bytes, restoredPaths };
+
+  let pendingWriteCount = 0;
+  const persistPending = (): void => {
+    pendingWriteCount += 1;
+    const isInitial = pendingWriteCount === 1;
+    writeRestorePending(
+      stageDir,
+      {
+        version: 1,
+        filesRestored: true,
+        acceptedDestRels: planned.map(m => m.relPath),
+        pending: { ...pendingSections },
+      },
+      {
+        failWrite: Boolean(isInitial && hooks?.failInitialPendingWrite),
+        failBeforeRename: Boolean(!isInitial && hooks?.failPendingWriteBeforeRename),
+      },
+    );
+  };
+
+  // Durable resume marker before any rollout leaves the stage. Crash after a
+  // later move can still accept destinations from this marker.
+  try {
+    persistPending();
+  } catch {
+    return failBeforeMoves("fs_failed");
+  }
+
+  const newlyMoved: StagedFile[] = [];
+  try {
+    mkdirSync(join(codexHome, ARCHIVED_SESSIONS_DIR), { recursive: true });
+    for (const item of toMove) {
+      // Atomic no-replace (.trash ↔ archived_sessions). Mid-loop failure keeps
+      // already-placed dests and the durable planned acceptedDestRels marker.
+      renameNoReplace(item.from, item.to);
+      newlyMoved.push(item);
+      if (
+        hooks?.failAfterMoveCount !== undefined
+        && newlyMoved.length >= hooks.failAfterMoveCount
+      ) {
+        throw new Error("test_fail_after_move_count");
+      }
+    }
+  } catch (error) {
+    // Marker was written before any move. Never reverse successful renames or
+    // drop/narrow acceptedDestRels — resume must accept placed dests and finish
+    // the remaining staged files.
+    if (satelliteLocks) rollbackAllSatelliteLocks(satelliteLocks);
+    const placed = [...alreadyMoved, ...newlyMoved];
+    const placedPhysical = new Set(placed.map(m => m.relPath));
+    const partialEntries = entries.filter(e =>
+      e.physicalRelPaths.every(rel => placedPhysical.has(rel)),
+    );
+    const midMoveRestored = [...new Set(partialEntries.map(e => e.relPath))];
+    return {
+      ok: false,
+      trashDir: id,
+      count: midMoveRestored.length,
+      bytes: partialEntries.reduce((sum, e) => sum + (e.bytes || 0), 0),
+      restoredPaths: midMoveRestored,
+      error: isExistError(error) ? "dest_exists" : "fs_failed",
+    };
+  }
+
+  const moved = [...alreadyMoved, ...newlyMoved];
+
+  /**
+   * Never compensate DBs or restage files after moves. Keep restored files,
+   * persist which sections remain, and return accurate partial counts.
+   */
+  const abortAfterMoves = (error: RestoreErrorCode): RestoreResult => {
+    if (satelliteLocks) {
+      rollbackAllSatelliteLocks(satelliteLocks);
+      satelliteLocks = undefined;
+    }
+    try {
+      persistPending();
+    } catch {
+      /* best-effort — files already restored; prior atomic marker remains */
+    }
+    return { ok: false, trashDir: id, ...partialCounts, error };
+  };
+
+  if (hooks?.holdAfterFileMovesMs !== undefined) {
+    const holdMs = Math.max(0, Math.floor(hooks.holdAfterFileMovesMs));
+    if (holdMs > 0) {
+      const deadline = Date.now() + holdMs;
+      while (Date.now() < deadline) { /* test-only spin wait */ }
+    }
+  }
+
+  if (hooks?.failAfterFileMoves) {
+    return abortAfterMoves("fs_failed");
+  }
+
+  if (pendingSections.state) {
+    const threadsRestored = restoreThreadsFromManifest(
+      paths.state,
+      entries,
+      satelliteBackup,
+      busyTimeoutMs,
+      codexHome,
+    );
+    if (!threadsRestored.ok) {
+      return abortAfterMoves(
+        threadsRestored.error === "codex_busy" ? "codex_busy" : "db_reconcile_failed",
+      );
+    }
+    pendingSections.state = false;
+    try {
+      persistPending();
+    } catch {
+      return abortAfterMoves("fs_failed");
+    }
+  }
+
+  if (hooks?.failAfterStateCommit) {
+    return abortAfterMoves("db_reconcile_failed");
+  }
+
+  if (satelliteLocks && satelliteBackup) {
+    const locks = satelliteLocks;
+    try {
+      // Commit one satellite DB at a time; uncommitted txs roll back via
+      // rollbackAllSatelliteLocks. Completed sections are cleared in pending.
+      if (pendingSections.logs && satelliteBackup.logs) {
+        if (!locks.logs) throw new Error("missing_logs_lock");
+        if (!tableExists(locks.logs.db, "logs")) throw new Error("missing_logs_table");
+        insertRowsConflictIgnore(locks.logs.db, "logs", satelliteBackup.logs.rows);
+        commitSatelliteLock(locks.logs);
+        locks.logs = undefined;
+        pendingSections.logs = false;
+        persistPending();
+        if (hooks?.failAfterFirstSatelliteCommit) {
+          throw new Error("test_fail_after_first_satellite");
+        }
+      }
+      if (pendingSections.memories && satelliteBackup.memories) {
+        if (!locks.memories) throw new Error("missing_memories_lock");
+        const mem = satelliteBackup.memories;
+        if (!tableExists(locks.memories.db, "stage1_outputs")) {
+          throw new Error("missing_stage1_outputs_table");
+        }
+        insertRowsConflictIgnore(locks.memories.db, "stage1_outputs", mem.stage1);
+        if (tableExists(locks.memories.db, "jobs")) {
+          insertRowsConflictIgnore(locks.memories.db, "jobs", mem.stage1Jobs);
+          if (mem.consolidateTouched) {
+            restoreConsolidateGlobalJob(
+              locks.memories.db,
+              mem.consolidateJob,
+              mem.consolidatePostImage,
+            );
+          }
+        }
+        commitSatelliteLock(locks.memories);
+        locks.memories = undefined;
+        pendingSections.memories = false;
+        persistPending();
+        if (hooks?.failAfterFirstSatelliteCommit && !satelliteBackup.logs) {
+          throw new Error("test_fail_after_first_satellite");
+        }
+      }
+      if (pendingSections.goals && satelliteBackup.goals) {
+        if (!locks.goals) throw new Error("missing_goals_lock");
+        const g = satelliteBackup.goals;
+        if (!tableExists(locks.goals.db, "thread_goals")) {
+          throw new Error("missing_thread_goals_table");
+        }
+        insertRowsConflictIgnore(locks.goals.db, "thread_goals", g.goals);
+        if (tableExists(locks.goals.db, "thread_goal_continuation_deferrals")) {
+          insertRowsConflictIgnore(
+            locks.goals.db,
+            "thread_goal_continuation_deferrals",
+            g.deferrals,
+          );
+        }
+        commitSatelliteLock(locks.goals);
+        locks.goals = undefined;
+        pendingSections.goals = false;
+        persistPending();
+        if (
+          hooks?.failAfterFirstSatelliteCommit
+          && !satelliteBackup.logs
+          && !satelliteBackup.memories
+        ) {
+          throw new Error("test_fail_after_first_satellite");
+        }
+      }
+      // Close any locks acquired for DBs that had no pending work / backup rows.
+      rollbackAllSatelliteLocks(locks);
+      satelliteLocks = undefined;
+    } catch (error) {
+      return abortAfterMoves(
+        mapDbError(error) === "codex_busy" ? "codex_busy" : "db_reconcile_failed",
+      );
+    }
+  }
+
+  if (
+    pendingSections.state
+    || pendingSections.logs
+    || pendingSections.memories
+    || pendingSections.goals
+  ) {
+    return abortAfterMoves("db_reconcile_failed");
+  }
+
+  // Completeness gate: every planned file must sit at its restored path, and the stage
+  // must hold no leftover rollout files, before we destroy the quarantine evidence.
+  for (const item of moved) {
+    if (!existsSync(item.to) || existsSync(item.from)) {
+      return abortAfterMoves("fs_failed");
+    }
+  }
+  try {
+    if (hooks?.failAtLeftoverStageGate) {
+      return abortAfterMoves("fs_failed");
+    }
+    for (const name of readdirSync(stageDir)) {
+      if (
+        name === "manifest.json"
+        || name === SATELLITE_BACKUP_FILE
+        || name === RESTORE_PENDING_FILE
+      ) {
+        continue;
+      }
+      if (!isRolloutFileName(name)) continue;
+      return abortAfterMoves("fs_failed");
+    }
+  } catch {
+    return abortAfterMoves("fs_failed");
+  }
+
+  if (!finalizeRestoredStage(stageDir, codexHome, hooks)) {
+    return {
+      ok: false,
+      trashDir: id,
+      ...partialCounts,
+      error: "fs_failed",
+    };
+  }
+  removeEmptyTrashRoot(codexHome);
+
+  return {
+    ok: true,
+    trashDir: id,
+    ...partialCounts,
+  };
+}