@indigoai-us/hq-cloud 6.14.7 → 6.14.8

package/src/cli/rescue-core.ts

@@ -28,6 +28,17 @@ import { spawnSync } from "child_process";
 import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
+import {
+  assertRescuePathTypeUnchanged,
+  isRescueTransientDirectory,
+  type RescuePathKind,
+} from "./rescue-snapshot.js";
+import {
+  applyBackupPrune,
+  canonicalRootHash,
+  inventoryManagedSnapshots,
+  type SnapshotManifest,
+} from "../backup-prune.js";
 
 export interface RunRescueResult {
   status: number;
@@ -61,6 +72,13 @@ const ALWAYS_PRESERVED_NAMES = [
   // these too (hq-cloud DEFAULT_IGNORES).
   ".pnpm-store",
   "node_modules",
+  // Local worktrees and updater/build sandboxes are reproducible, often huge,
+  // and never owned by an hq-core release. Keep these root-only names outside
+  // both the wipe set and the safety snapshot.
+  "worktrees",
+  ".worktrees",
+  ".sst-sandbox-home",
+  ".tmp-codex-asar",
 ];
 
 interface Config {
@@ -78,6 +96,7 @@ interface Config {
   doBackup: boolean;
   backupRoot: string;
   backupRetentionDays: string;
+  backupRetentionCount: string;
 }
 
 class ExitError extends Error {
@@ -132,7 +151,18 @@ function redactGitDiagnostic(output: string, ghToken: string): string {
 /** `command -v <bin>` — is a binary on PATH? */
 function hasCmd(bin: string, env: NodeJS.ProcessEnv): boolean {
   const r = spawnSync(bin, ["--version"], { env, stdio: "ignore" });
-  return !r.error;
+  return !r.error && r.status === 0;
+}
+
+/** The overlay requires rsync; do not allocate a recovery copy when it cannot run. */
+function requireWorkingRsync(env: NodeJS.ProcessEnv, err: (s: string) => void): void {
+  const probe = run("rsync", ["--version"], { env });
+  const output = `${probe.stdout}\n${probe.stderr}`;
+  if (probe.status === 0 && /\brsync\b.*\bversion\b/i.test(output)) return;
+  err("error: rsync preflight failed before any safety snapshot was allocated.\n");
+  err(`       resolved PATH: ${env.PATH ?? "(unset)"}\n`);
+  err("       Install or repair rsync, then retry the HQ update.\n");
+  throw new ExitError(probe.status || 127);
 }
 
 // fs predicates mirroring bash test operators.
@@ -165,6 +195,14 @@ function lstatOrNull(p: string): fs.Stats | null {
     return null;
   }
 }
+function rescuePathKind(p: string): RescuePathKind {
+  const st = lstatOrNull(p);
+  if (!st) return "missing";
+  if (st.isSymbolicLink()) return "symlink";
+  if (st.isFile()) return "file";
+  if (st.isDirectory()) return "directory";
+  return "other";
+}
 function lexists(p: string): boolean {
   return lstatOrNull(p) !== null;
 }
@@ -211,6 +249,7 @@ export function parseRescueArgs(argv: string[]): Config {
     doBackup: process.env.HQ_RESCUE_NO_BACKUP === "1" ? false : true,
     backupRoot: process.env.HQ_BACKUP_DIR || path.join(os.homedir(), ".hq", "backups"),
     backupRetentionDays: process.env.HQ_BACKUP_RETENTION_DAYS || "7",
+    backupRetentionCount: process.env.HQ_BACKUP_RETENTION_COUNT || "2",
   };
 
   const usage = (): never => {
@@ -437,6 +476,10 @@ function doRescue(
   }
 
   const RUN_TS = utcStamp(new Date(), "dash");
+  // Both the release overlay and a restorable snapshot require rsync.  A shim
+  // which merely starts but exits non-zero used to trigger an enormous cp -a
+  // fallback, then fail later at overlay.  Stop before classification/allocation.
+  requireWorkingRsync(env, err);
 
   // --- Read prior sync-point metadata (BEFORE the wipe) ---
   let prevSyncSha = "";
@@ -488,7 +531,7 @@ function doRescue(
     out("==> Mode:       preserve-list (default)\n");
     const extra = cfg.extraPreserve.length ? `, ${cfg.extraPreserve.join(" ")}` : "";
     out(
-      `==> Preserved:  .git, companies (except companies/_template), personal, workspace, repos, .github, .leak-scan, .hq-sync-journal.json, .hq, .hq-conflicts${extra}\n`,
+      `==> Preserved:  .git, companies (except companies/_template), personal, workspace, repos, worktrees, .worktrees, .sst-sandbox-home, .tmp-codex-asar, .github, .leak-scan, .hq-sync-journal.json, .hq, .hq-conflicts${extra}\n`,
     );
   }
   if (cfg.preserveSubpaths.length !== 0) {
@@ -513,7 +556,7 @@ function doRescue(
   }
   if (cfg.doBackup) {
     out(
-      `==> Safety backup: ON  -> ${cfg.backupRoot}/pre-update-${RUN_TS} (retention ${cfg.backupRetentionDays}d)\n`,
+      `==> Safety backup: ON  -> ${cfg.backupRoot}/pre-update-${RUN_TS} (retention ${cfg.backupRetentionDays}d / ${cfg.backupRetentionCount} completed)\n`,
     );
   } else {
     out("==> Safety backup: OFF (--no-backup / HQ_RESCUE_NO_BACKUP=1)\n");
@@ -524,7 +567,7 @@ function doRescue(
   if (!cfg.assumeYes && !cfg.dryRun) {
     let backupLine = "  * NO pre-op backup (--no-backup),";
     if (cfg.doBackup)
-      backupLine = `  * snapshot the wipe set to ${cfg.backupRoot}/pre-update-${RUN_TS} first,`;
+      backupLine = `  * snapshot the release-managed wipe set (excluding worktrees/build caches) to ${cfg.backupRoot}/pre-update-${RUN_TS} first,`;
     let cloudLine = "";
     if (cfg.cloudUpdate)
       cloudLine =
@@ -677,6 +720,10 @@ function doRescue(
       "--exclude=.hq-sync-journal.json",
       "--exclude=.hq",
       "--exclude=.hq-conflicts",
+      "--exclude=/worktrees",
+      "--exclude=/.worktrees",
+      "--exclude=/.sst-sandbox-home",
+      "--exclude=/.tmp-codex-asar",
       "--include=/companies/",
       "--include=/companies/_template/***",
       "--exclude=/companies/*",
@@ -738,42 +785,6 @@ function doRescue(
     actions: [],
   };
 
-  // --- Pre-operation safety snapshot (BEFORE any destructive op) ---
-  let backupDir = "";
-  if (cfg.doBackup && !cfg.dryRun && wipeToplevel.length !== 0) {
-    backupDir = path.join(cfg.backupRoot, `pre-update-${RUN_TS}`);
-    out("\n");
-    out(`==> Safety snapshot -> ${backupDir}\n`);
-    fs.mkdirSync(backupDir, { recursive: true });
-    const rsyncAvailable = hasCmd("rsync", env);
-    for (const rootRel of wipeToplevel) {
-      const srcAbs = path.join(hqRoot, rootRel);
-      if (!lexists(srcAbs)) continue;
-      const parentRel = path.dirname(rootRel);
-      const destParent = path.join(backupDir, parentRel);
-      fs.mkdirSync(destParent, { recursive: true });
-      if (rsyncAvailable) {
-        const r = run(
-          "rsync",
-          [
-            "-a",
-            "--exclude=node_modules/",
-            "--exclude=.git/",
-            toCygwinRsyncPath(srcAbs),
-            toCygwinRsyncPath(destParent + "/"),
-          ],
-          { env },
-        );
-        if (r.status !== 0) cpA(srcAbs, destParent);
-      } else {
-        cpA(srcAbs, destParent);
-      }
-    }
-    out(
-      `    snapshot complete (restore any file: cp "${backupDir}/<relpath>" "${hqRoot}/<relpath>")\n`,
-    );
-  }
-
   // --- Walk + classify (PHASE 1: read-only) ---
   // Classification mutates nothing on disk: every outcome is recorded as a
   // typed RescueDecision. Destructive ops (delete, rescue-move,
@@ -882,7 +893,50 @@ function doRescue(
     throw new ExitError(overlayPreflight.status || 1);
   }
   ctx.actions = buildRescueActions(ctx);
-  applyClassifiedActions(ctx, backupDir);
+
+  // Snapshot allocation is deliberately after the entire read-only walk and
+  // action-plan build. A no-op (or a classifier fault above) cannot consume
+  // backup space.
+  let backupDir = "";
+  let mutationStarted = false;
+  const hasDestructivePaths = ctx.actions.some((action) => action.affectedRels.length > 0);
+  if (cfg.doBackup && !cfg.dryRun && wipeToplevel.length !== 0 && hasDestructivePaths) {
+    const prePlan = pruneManagedBackups(cfg, hqRoot, out, false);
+    const unresolved = prePlan.protected.filter((x) => x.reason === "recovery-required-no-later-good");
+    if (unresolved.length >= 2) {
+      err("error: safety snapshot circuit breaker is open: two unresolved recovery-required snapshots exist.\n");
+      err("       Inspect/restore those snapshots and repair the release source before retrying (operator override required).\n");
+      throw new ExitError(1);
+    }
+    requireBackupCapacity(cfg, hqRoot, wipeToplevel, env, err);
+    fs.mkdirSync(cfg.backupRoot, { recursive: true });
+    const runId = `${process.pid}-${Date.now().toString(36)}`;
+    backupDir = allocateSnapshotDir(cfg.backupRoot, RUN_TS, canonicalRootHash(hqRoot), runId);
+    out("\n");
+    out(`==> Safety snapshot -> ${backupDir}\n`);
+    try {
+      fs.mkdirSync(backupDir, { recursive: false });
+      writeSnapshotManifest(backupDir, snapshotManifest("copying", hqRoot, runId, cfg, srcSha, wipeToplevel));
+      for (const rootRel of wipeToplevel) {
+        const srcAbs = path.join(hqRoot, rootRel);
+        if (!lexists(srcAbs) || isRescueTransientDirectory(rootRel)) continue;
+        cpAToFiltered(srcAbs, path.join(backupDir, rootRel), rootRel);
+      }
+      updateSnapshotStatus(backupDir, "ready");
+    } catch (error) {
+      updateSnapshotStatus(backupDir, "failed-pre-mutation");
+      throw error;
+    }
+    pruneManagedBackups(cfg, hqRoot, out, true);
+    out(
+      `    snapshot ready (restore any file: cp "${backupDir}/<relpath>" "${hqRoot}/<relpath>")\n`,
+    );
+  } else if (cfg.doBackup && !cfg.dryRun && wipeToplevel.length !== 0) {
+    out("\n==> Safety snapshot skipped (classification found no destructive paths).\n");
+  }
+  try {
+    mutationStarted = true;
+    applyClassifiedActions(ctx, backupDir);
 
   // --- Back up preserve-subpaths to a mktemp shuttle ---
   const shuttle = path.join(tmpdir, "preserve");
@@ -1117,20 +1171,26 @@ function doRescue(
       lines.push("  (no files were moved or deleted)");
     }
     lines.push("", "## Restore");
-    lines.push("This directory holds the wipe set exactly as it was before the update.");
+    lines.push(
+      "This directory holds the release-managed wipe set as it was before the update; reproducible worktrees and build caches are intentionally excluded.",
+    );
     lines.push("Restore a single file:");
     lines.push(`  cp "${backupDir}/<relpath>" "${hqRoot}/<relpath>"`);
     lines.push("Restore everything (overwrites current scaffold — use with care):");
     lines.push(`  rsync -a "${backupDir}/" "${hqRoot}/"`);
-    lines.push("", `Auto-pruned after ${cfg.backupRetentionDays} days (HQ_BACKUP_RETENTION_DAYS).`);
+    lines.push(
+      "",
+      `Retention: ${cfg.backupRetentionDays} days and ${cfg.backupRetentionCount} completed snapshots (latest recovery floor retained).`,
+    );
     try {
       fs.writeFileSync(path.join(backupDir, "RECOVERY.md"), lines.join("\n") + "\n");
     } catch {
       /* best-effort, matches `|| true` */
     }
+    updateSnapshotStatus(backupDir, "completed-good", RUN_TS);
     out("\n");
     out(`==> Pre-update snapshot + recovery manifest: ${backupDir}\n`);
-    pruneOldBackups(cfg, out);
+    pruneManagedBackups(cfg, hqRoot, out, true);
   }
 
   out("\n");
@@ -1138,10 +1198,19 @@ function doRescue(
   out("    User-edited files were rescued under personal/ (see scan output above).\n");
   out("    User-only files (created by you, unknown to upstream) were left untouched.\n");
   if (cfg.doBackup && backupDir) {
-    out(`    A full pre-update snapshot is at ${backupDir} (RECOVERY.md explains restore).\n`);
+    out(
+      `    A filtered pre-update snapshot is at ${backupDir} (RECOVERY.md explains restore).\n`,
+    );
   }
 
-  return { status: 0 };
+    return { status: 0 };
+  } catch (error) {
+    if (backupDir && isDir(backupDir)) {
+      updateSnapshotStatus(backupDir, mutationStarted ? "recovery-required" : "failed-pre-mutation");
+      pruneManagedBackups(cfg, hqRoot, out, true);
+    }
+    throw error;
+  }
 }
 
 interface WalkCtx {
@@ -1196,6 +1265,7 @@ interface WalkCtx {
 interface RescueAction {
   label: string;
   affectedRels: string[];
+  expectedPaths: { rel: string; kind: RescuePathKind }[];
   run: () => void;
 }
 
@@ -1242,8 +1312,16 @@ function recordDecision(ctx: WalkCtx, decision: RescueDecision): void {
 
 function applyClassifiedActions(ctx: WalkCtx, backupDir: string): void {
   const completed: RescueAction[] = [];
+  injectApplyPathChangeForTest(ctx);
   for (const action of ctx.actions) {
     try {
+      for (const expected of action.expectedPaths) {
+        assertRescuePathTypeUnchanged(
+          expected.rel,
+          expected.kind,
+          rescuePathKind(path.join(ctx.hqRoot, expected.rel)),
+        );
+      }
       action.run();
       completed.push(action);
     } catch (err) {
@@ -1269,6 +1347,20 @@ function applyClassifiedActions(ctx: WalkCtx, backupDir: string): void {
   }
 }
 
+/** Deterministic seam for the real reindex-vs-rescue race; never set in production. */
+function injectApplyPathChangeForTest(ctx: WalkCtx): void {
+  const rel = ctx.env.HQ_RESCUE_FAULT_BEFORE_APPLY_REL;
+  const kind = ctx.env.HQ_RESCUE_FAULT_BEFORE_APPLY_KIND;
+  if (!rel || !kind) return;
+  const abs = path.join(ctx.hqRoot, rel);
+  fs.rmSync(abs, { recursive: true, force: true });
+  if (kind === "directory") fs.mkdirSync(abs, { recursive: true });
+  else if (kind === "file") {
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, "fault-injected path replacement\n");
+  }
+}
+
 function rollbackCompletedActions(
   ctx: WalkCtx,
   completed: RescueAction[],
@@ -1847,7 +1939,15 @@ function renderDryRunDecision(ctx: WalkCtx, decision: RescueDecision): void {
 function buildRescueActions(ctx: WalkCtx): RescueAction[] {
   const actions: RescueAction[] = [];
   const add = (label: string, affectedRels: string[], runAction: () => void) => {
-    actions.push({ label, affectedRels, run: runAction });
+    actions.push({
+      label,
+      affectedRels,
+      expectedPaths: affectedRels.map((rel) => ({
+        rel,
+        kind: rescuePathKind(path.join(ctx.hqRoot, rel)),
+      })),
+      run: runAction,
+    });
   };
 
   for (const decision of ctx.decisions) {
@@ -2073,17 +2173,16 @@ function walkAndProcess(ctx: WalkCtx, rootRel: string): void {
     return;
   }
 
-  // Top-level directory: recursive walk, pruning node_modules + nested .git.
+  // Top-level directory: recursive walk, pruning canonical transient state.
   for (const rel of findFilesAndSymlinks(rootAbs, ctx.hqRoot)) {
     recordDecision(ctx, classifyOne(ctx, rel));
   }
 }
 
 /**
- * Mirror of `find "$root" \( -type d \( -name node_modules -o -name .git \)
- * -prune \) -o \( \( -type f -o -type l \) -print0 \)`: yield repo-relative
- * paths of regular files and symlinks, pruning node_modules/.git dirs and not
- * descending into directory symlinks (find -P default). Deterministic order.
+ * Yield repo-relative regular files and symlinks while pruning canonical
+ * transient directories and never descending into directory symlinks. Order is
+ * deterministic so classification and apply plans remain reproducible.
  */
 function findFilesAndSymlinks(rootAbs: string, hqRoot: string): string[] {
   const found: string[] = [];
@@ -2110,13 +2209,8 @@ function findFilesAndSymlinks(rootAbs: string, hqRoot: string): string[] {
         //   - .claude/worktrees: Claude Code per-agent worktree sandboxes —
         //     each holds a full nested HQ checkout, so not pruning them means
         //     walking 100k+ throwaway files. The sync engine ignores them too.
-        if (
-          ent.name === "node_modules" ||
-          ent.name === ".git" ||
-          ent.name === ".pnpm-store" ||
-          (ent.name === "worktrees" && dir.endsWith("/.claude"))
-        )
-          continue; // prune
+        const rel = abs.slice(hqRoot.length + 1);
+        if (isRescueTransientDirectory(rel)) continue;
         walk(abs);
         continue;
       }
@@ -2178,34 +2272,82 @@ function restoreMtimesFromGit(
   }
 }
 
-// --- prune old pre-update-* snapshots past retention ---
-function pruneOldBackups(cfg: Config, out: (s: string) => void): void {
-  if (!isDir(cfg.backupRoot)) return;
-  if (!/^[0-9]+$/.test(cfg.backupRetentionDays)) return;
-  const days = Number(cfg.backupRetentionDays);
-  if (!(days > 0)) return;
-  // `find -mtime +N`: strictly older than (N+1)*24h by mtime.
-  const cutoffMs = Date.now() - (days + 1) * 24 * 60 * 60 * 1000;
-  let entries: string[] = [];
+function allocateSnapshotDir(backupRoot: string, runTs: string, rootHash: string, runId: string): string {
+  return path.join(backupRoot, `pre-update-${runTs}-${rootHash}-${runId}`);
+}
+
+function snapshotManifest(
+  status: SnapshotManifest["status"], hqRoot: string, runId: string, cfg: Config,
+  sourceSha: string, includedRoots: string[],
+): SnapshotManifest {
+  const now = new Date().toISOString();
+  return { schemaVersion: 1, status, canonicalHqRoot: hqRoot, rootHash: canonicalRootHash(hqRoot), runId,
+    creatorPid: process.pid, creatorStartedAt: now, source: cfg.sourceRepo, ref: cfg.ref, sourceSha,
+    createdAt: now, includedRoots, fileCount: 0, byteCount: 0 };
+}
+
+function readSnapshotManifest(backupDir: string): SnapshotManifest | null {
+  try { return JSON.parse(fs.readFileSync(path.join(backupDir, "SNAPSHOT.json"), "utf8")) as SnapshotManifest; }
+  catch { return null; }
+}
+
+/** Publish only complete JSON; a crash can leave a temp file but never a torn manifest. */
+function writeSnapshotManifest(backupDir: string, manifest: SnapshotManifest): void {
+  const target = path.join(backupDir, "SNAPSHOT.json");
+  const temp = `${target}.${process.pid}.tmp`;
+  fs.writeFileSync(temp, JSON.stringify(manifest, null, 2) + "\n");
+  fs.renameSync(temp, target);
+}
+
+function updateSnapshotStatus(backupDir: string, status: SnapshotManifest["status"], completedAt?: string): void {
+  const manifest = readSnapshotManifest(backupDir);
+  if (!manifest) return;
+  const stats = estimateFiltered(backupDir, "");
+  writeSnapshotManifest(backupDir, { ...manifest, status, fileCount: stats.files, byteCount: stats.bytes,
+    ...(completedAt ? { completedAt: new Date().toISOString() } : {}) });
+}
+
+function pruneManagedBackups(cfg: Config, hqRoot: string, out: (s: string) => void, apply: boolean) {
+  const inventory = inventoryManagedSnapshots(cfg.backupRoot, hqRoot, (m) => {
+    try { process.kill(m.creatorPid, 0); return true; } catch { return false; }
+  }, { keepGood: Number(cfg.backupRetentionCount), maxAgeDays: Number(cfg.backupRetentionDays) });
+  const plan = { candidates: inventory.candidates, protected: inventory.protected, unmanaged: inventory.unmanaged };
+  out(`==> Backup retention dry-run: ${plan.candidates.length} candidate(s), ${plan.protected.length} protected, ${plan.unmanaged.length} unmanaged.\n`);
+  for (const item of plan.candidates) out(`    candidate ${item.entry.name}: ${item.reason}\n`);
+  for (const item of plan.protected) out(`    protected ${item.entry.name}: ${item.reason}\n`);
+  if (apply && plan.candidates.length > 0) {
+    const result = applyBackupPrune(cfg.backupRoot, hqRoot, plan, { keepGood: Number(cfg.backupRetentionCount), maxAgeDays: Number(cfg.backupRetentionDays) });
+    for (const name of result.deleted) out(`    deleted snapshot: ${name}\n`);
+    for (const failure of result.failures) out(`    retention delete failed (retained): ${failure}\n`);
+  }
+  return plan;
+}
+
+function estimateFiltered(abs: string, rel: string): { files: number; bytes: number } {
+  const st = lstatOrNull(abs);
+  if (!st || (st.isDirectory() && rel && isRescueTransientDirectory(rel))) return { files: 0, bytes: 0 };
+  if (st.isSymbolicLink()) return { files: 1, bytes: Buffer.byteLength(fs.readlinkSync(abs)) };
+  if (st.isFile()) return { files: 1, bytes: st.size };
+  if (!st.isDirectory()) return { files: 0, bytes: 0 };
+  let files = 0, bytes = 0;
+  for (const name of fs.readdirSync(abs)) { const x = estimateFiltered(path.join(abs, name), path.posix.join(rel, name)); files += x.files; bytes += x.bytes; }
+  return { files, bytes };
+}
+
+function requireBackupCapacity(cfg: Config, hqRoot: string, roots: string[], _env: NodeJS.ProcessEnv, err: (s: string) => void): void {
   try {
-    entries = fs.readdirSync(cfg.backupRoot);
-  } catch {
-    return;
-  }
-  for (const name of entries) {
-    if (!name.startsWith("pre-update-")) continue;
-    const abs = path.join(cfg.backupRoot, name);
-    const st = lstatOrNull(abs);
-    if (!st || !st.isDirectory()) continue;
-    if (st.mtimeMs < cutoffMs) {
-      out(`    pruned old snapshot (> ${cfg.backupRetentionDays}d): ${name}\n`);
-      try {
-        fs.rmSync(abs, { recursive: true, force: true });
-      } catch {
-        /* best-effort */
-      }
-    }
-  }
+    const estimate = roots.reduce((total, root) => total + estimateFiltered(path.join(hqRoot, root), root).bytes, 0);
+    const stat = fs.statfsSync(isDir(cfg.backupRoot) ? cfg.backupRoot : path.dirname(cfg.backupRoot));
+    const free = Number(stat.bavail) * Number(stat.bsize);
+    const capacity = Number(stat.blocks) * Number(stat.bsize);
+    const required = estimate + Math.max(5 * 1024 ** 3, Math.ceil(capacity * 0.1));
+    if (free >= required) return;
+    err(`error: insufficient free space for safety snapshot (need ${required} bytes, have ${free}).\n`);
+  } catch (error) {
+    err(`error: could not measure snapshot size/free space (${error instanceof Error ? error.message : String(error)}).\n`);
+  }
+  if (cfg.cloudUpdate) throw new ExitError(1);
+  err("       Continuing only because this is an interactive rescue; use --cloud-update to fail closed.\n");
 }
 
 // --- recursive file count (`find <dir> -type f | wc -l`) ---
@@ -2279,6 +2421,39 @@ function cpATo(src: string, dest: string): void {
   }
 }
 
+/** Snapshot copy that preserves metadata while pruning canonical transient directories. */
+function cpAToFiltered(src: string, dest: string, rel: string): void {
+  const st = lstatOrNull(src);
+  if (!st) return;
+  if (st.isDirectory() && isRescueTransientDirectory(rel)) return;
+  if (st.isSymbolicLink()) {
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.symlinkSync(fs.readlinkSync(src), dest);
+    return;
+  }
+  if (st.isDirectory()) {
+    fs.mkdirSync(dest, { recursive: true });
+    for (const name of fs.readdirSync(src)) {
+      cpAToFiltered(path.join(src, name), path.join(dest, name), path.posix.join(rel, name));
+    }
+    try {
+      fs.chmodSync(dest, st.mode);
+      fs.utimesSync(dest, st.atime, st.mtime);
+    } catch {
+      /* metadata preservation is best-effort */
+    }
+    return;
+  }
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.copyFileSync(src, dest);
+  try {
+    fs.chmodSync(dest, st.mode);
+    fs.utimesSync(dest, st.atime, st.mtime);
+  } catch {
+    /* metadata preservation is best-effort */
+  }
+}
+
 /** Synchronous single-line read from stdin (mirrors bash `read -r`). */
 function readLineSync(): string {
   const fd = 0;

package/src/cli/rescue-snapshot.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from "vitest";
+import {
+  RescuePathChangedError,
+  assertRescuePathTypeUnchanged,
+  isRescueTransientDirectory,
+} from "./rescue-snapshot.js";
+
+describe("rescue transient path policy", () => {
+  it.each([
+    "worktrees",
+    ".worktrees",
+    ".claude/worktrees",
+    ".claude/worktrees/agent/repo",
+    ".sst-sandbox-home",
+    ".tmp-codex-asar",
+    ".claude/skills/demo/node_modules",
+    ".claude/skills/demo/.pnpm-store",
+    ".claude/skills/demo/.sst",
+    ".claude/skills/demo/.next",
+    ".claude/skills/demo/target",
+  ])("excludes reproducible directory %s", (rel) => {
+    expect(isRescueTransientDirectory(rel)).toBe(true);
+  });
+
+  it.each([
+    "core/worktrees.md",
+    "core/target-audience",
+    "companies/acme/knowledge/.next-steps",
+    "core/packages",
+  ])("does not overmatch meaningful path %s", (rel) => {
+    expect(isRescueTransientDirectory(rel)).toBe(false);
+  });
+});
+
+describe("rescue apply path-type revalidation", () => {
+  it("accepts an unchanged path type", () => {
+    expect(() => assertRescuePathTypeUnchanged("core/a.md", "file", "file")).not.toThrow();
+  });
+
+  it("raises a typed state-change error before a classified symlink is treated as a directory", () => {
+    let thrown: unknown;
+    try {
+      assertRescuePathTypeUnchanged(
+        ".claude/skills/personal:foreman/tests",
+        "symlink",
+        "directory",
+      );
+    } catch (error) {
+      thrown = error;
+    }
+
+    expect(thrown).toBeInstanceOf(RescuePathChangedError);
+    expect(String(thrown)).toContain("changed after classification");
+    expect(String(thrown)).toContain("expected symlink, found directory");
+    expect(String(thrown)).not.toContain("EISDIR");
+  });
+});

package/src/cli/rescue-snapshot.ts

@@ -0,0 +1,51 @@
+/** Filesystem shape captured during rescue classification. */
+export type RescuePathKind = "missing" | "file" | "directory" | "symlink" | "other";
+
+
+/** Raised when a path changes shape between read-only classification and apply. */
+export class RescuePathChangedError extends Error {
+  constructor(
+    public readonly rel: string,
+    public readonly expected: RescuePathKind,
+    public readonly actual: RescuePathKind,
+  ) {
+    super(
+      `rescue path changed after classification: ${rel} (expected ${expected}, found ${actual}); ` +
+        "another process may be rebuilding generated HQ paths, so rescue stopped before mutation",
+    );
+    this.name = "RescuePathChangedError";
+  }
+}
+
+/** Return whether a directory is reproducible state that rescue must not snapshot or classify. */
+export function isRescueTransientDirectory(rel: string): boolean {
+  const normalized = rel.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/$/, "");
+  if (
+    normalized === "worktrees" ||
+    normalized.startsWith("worktrees/") ||
+    normalized === ".worktrees" ||
+    normalized.startsWith(".worktrees/") ||
+    normalized === ".sst-sandbox-home" ||
+    normalized.startsWith(".sst-sandbox-home/") ||
+    normalized === ".tmp-codex-asar" ||
+    normalized.startsWith(".tmp-codex-asar/") ||
+    normalized === ".claude/worktrees" ||
+    normalized.startsWith(".claude/worktrees/")
+  ) {
+    return true;
+  }
+  return normalized
+    .split("/")
+    .some((part) =>
+      ["node_modules", ".git", ".pnpm-store", ".sst", ".next", "target"].includes(part),
+    );
+}
+
+/** Fail safely when apply observes a different path shape than classification did. */
+export function assertRescuePathTypeUnchanged(
+  rel: string,
+  expected: RescuePathKind,
+  actual: RescuePathKind,
+): void {
+  if (expected !== actual) throw new RescuePathChangedError(rel, expected, actual);
+}