@indigoai-us/hq-cloud 6.14.7 → 6.14.9

package/dist/cli/rescue-core.js

@@ -28,6 +28,8 @@ import { spawnSync } from "child_process";
 import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
+import { assertRescuePathTypeUnchanged, isRescueTransientDirectory, } from "./rescue-snapshot.js";
+import { applyBackupPrune, canonicalRootHash, inventoryManagedSnapshots, } from "../backup-prune.js";
 // Paths always preserved across wipe+overlay (shuttled out, restored after).
 const CARVE_OUT_PATHS = [
     "core/packages",
@@ -55,6 +57,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",
 ];
 class ExitError extends Error {
     code;
@@ -103,7 +112,18 @@ function redactGitDiagnostic(output, ghToken) {
 /** `command -v <bin>` — is a binary on PATH? */
 function hasCmd(bin, env) {
     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, err) {
+    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.
 function isDir(p) {
@@ -139,6 +159,18 @@ function lstatOrNull(p) {
         return null;
     }
 }
+function rescuePathKind(p) {
+    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) {
     return lstatOrNull(p) !== null;
 }
@@ -184,6 +216,7 @@ export function parseRescueArgs(argv) {
         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 = () => {
         // The legacy script printed its comment header here; we emit a concise
@@ -381,6 +414,10 @@ function doRescue(cfg, env, out, err, setTmp) {
         throw new ExitError(3);
     }
     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 = "";
     let prevSyncSource = "";
@@ -419,7 +456,7 @@ function doRescue(cfg, env, out, err, setTmp) {
     else {
         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`);
+        out(`==> 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) {
         out("==> Preserved subpaths (backed up + restored across the overlay):\n");
@@ -439,7 +476,7 @@ function doRescue(cfg, env, out, err, setTmp) {
         out("==> History gate: OFF (--no-history-check; every diff rescued)\n");
     }
     if (cfg.doBackup) {
-        out(`==> Safety backup: ON  -> ${cfg.backupRoot}/pre-update-${RUN_TS} (retention ${cfg.backupRetentionDays}d)\n`);
+        out(`==> 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");
@@ -450,7 +487,7 @@ function doRescue(cfg, env, out, err, setTmp) {
     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 =
@@ -594,6 +631,10 @@ function doRescue(cfg, env, out, err, setTmp) {
             "--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/*",
@@ -656,38 +697,6 @@ function doRescue(cfg, env, out, err, setTmp) {
         decisions: [],
         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,
@@ -800,246 +809,298 @@ function doRescue(cfg, env, out, err, setTmp) {
         throw new ExitError(overlayPreflight.status || 1);
     }
     ctx.actions = buildRescueActions(ctx);
-    applyClassifiedActions(ctx, backupDir);
-    // --- Back up preserve-subpaths to a mktemp shuttle ---
-    const shuttle = path.join(tmpdir, "preserve");
-    fs.mkdirSync(shuttle, { recursive: true });
-    const preserveMap = [];
-    let shuttleId = 0;
-    for (const sp of cfg.preserveSubpaths) {
-        const src = path.join(hqRoot, sp);
-        if (lexists(src)) {
-            shuttleId += 1;
-            cpA(src, shuttle, String(shuttleId));
-            preserveMap.push({ id: shuttleId, rel: sp });
-            out(`==> Backed up ${sp} -> shuttle/${shuttleId}\n`);
+    // 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);
         }
-    }
-    out("\n");
-    out(`==> Walk complete (user-only: ${counts.userOnly}, unchanged: ${counts.unchanged}, user-edit-rescued: ${counts.userEdit}, conflict-quarantined: ${counts.userConflict}, overwrite-safe: ${counts.userOverwrite}, cloud-symlink-reconciled: ${counts.cloudSymlinkReconciled}, symlinks-dropped: ${counts.symlinkDropped})\n`);
-    // --- Overlay source onto HQ root ---
-    out("==> Overlaying source onto HQ root ...\n");
-    // `unchangedList` is only populated during applyClassifiedActions above, so
-    // re-derive the --exclude-from protect list HERE. Building overlayArgs before
-    // classification left the list empty, so unchanged files were overlaid and
-    // their mtimes reset to clone time (rescue-mtime-preserve regression). The
-    // early overlayArgs remain correct for the pre-classification dry-run.
-    const overlayRunArgs = fs.statSync(unchangedList).size > 0
-        ? [
-            "-a",
-            `--exclude-from=${unchangedList}`,
-            ...rsyncExcludes,
-            toCygwinRsyncPath(srcDir + "/"),
-            toCygwinRsyncPath(hqRoot + "/"),
-        ]
-        : overlayArgs;
-    const overlay = run("rsync", overlayRunArgs, { env });
-    if (overlay.status !== 0) {
-        // bash runs under set -e: a failed rsync aborts with its status.
-        err(overlay.stderr);
-        throw new ExitError(overlay.status || 1);
-    }
-    // --- Restore preserved sub-paths ---
-    if (preserveMap.length > 0) {
-        out("==> Restoring preserved sub-paths ...\n");
-        for (const { id, rel } of preserveMap) {
-            const dest = path.join(hqRoot, rel);
-            fs.mkdirSync(path.dirname(dest), { recursive: true });
-            const shuttleItem = path.join(shuttle, String(id));
-            if (isDir(shuttleItem)) {
-                fs.rmSync(dest, { recursive: true, force: true });
-                cpATo(shuttleItem, dest);
-            }
-            else {
-                cpATo(shuttleItem, dest);
+        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);
             }
-            out(`    restored ${rel}\n`);
-        }
-    }
-    // --- Restore executable bit on shipped shebang scripts (defense-in-depth) ---
-    // rsync -a already propagated each file's upstream git tree mode; this guards
-    // the case where upstream itself committed an executable script as 0644 -- a
-    // hook the runtime exec's then dies with EACCES and is silently disabled. A
-    // shebang is an unambiguous "meant to be run" marker. See restoreShebangExecBits.
-    const execBitFixes = restoreShebangExecBits(srcDir, hqRoot, env);
-    if (execBitFixes > 0) {
-        out(`==> Restored executable bit on ${execBitFixes} shipped shebang script(s) lacking +x\n`);
-    }
-    // --- Stamp sync-point provenance into core/core.yaml ---
-    // `last_sync_at` = the source commit's committer time, NOT wall-clock now:
-    // the stamp must be a pure function of srcSha so every machine rescuing the
-    // same release writes byte-identical core.yaml (see srcCommitIsoRaw). An
-    // unparseable commit timestamp skips the stamp entirely — a nondeterministic
-    // stamp is worse than no stamp (it re-creates cross-machine conflict mirrors).
-    const srcCommitDate = new Date(srcCommitIsoRaw);
-    if (cfg.narrowPaths.length === 0 && isFileFollow(coreYaml) && Number.isNaN(srcCommitDate.getTime())) {
-        err(`    WARN: could not parse source commit timestamp (${JSON.stringify(srcCommitIsoRaw)}); skipping core/core.yaml stamp to keep it deterministic\n`);
-    }
-    if (cfg.narrowPaths.length === 0 &&
-        isFileFollow(coreYaml) &&
-        !Number.isNaN(srcCommitDate.getTime())) {
-        const nowUtc = utcStamp(srcCommitDate, "colon");
-        if (yqAvailable) {
-            const stampEnv = {
-                ...env,
-                SHA: srcSha,
-                SOURCE: cfg.sourceRepo,
-                THE_REF: cfg.ref,
-                AT: nowUtc,
-            };
-            run("yq", [
-                "-i",
-                ".replaced_from_source.source       = strenv(SOURCE) |\n" +
-                    "        .replaced_from_source.ref          = strenv(THE_REF) |\n" +
-                    "        .replaced_from_source.last_sync_sha = strenv(SHA) |\n" +
-                    "        .replaced_from_source.last_sync_at  = strenv(AT) |\n" +
-                    "        del(.replaced_from_staging)",
-                coreYaml,
-            ], { env: stampEnv });
-            out(`==> Stamped core/core.yaml: replaced_from_source.last_sync_sha=${srcSha}\n`);
-        }
-        else if (hasCmd("python3", env) &&
-            run("python3", ["-c", "import yaml"], { env }).status === 0) {
-            const pyEnv = {
-                ...env,
-                SHA: srcSha,
-                SOURCE: cfg.sourceRepo,
-                THE_REF: cfg.ref,
-                AT: nowUtc,
-                CORE: coreYaml,
-            };
-            run("python3", [
-                "-c",
-                [
-                    "import os, yaml",
-                    'path = os.environ["CORE"]',
-                    "try:",
-                    "    with open(path) as f:",
-                    "        d = yaml.safe_load(f) or {}",
-                    "except FileNotFoundError:",
-                    "    d = {}",
-                    'd["replaced_from_source"] = {',
-                    '    "source": os.environ["SOURCE"],',
-                    '    "ref": os.environ["THE_REF"],',
-                    '    "last_sync_sha": os.environ["SHA"],',
-                    '    "last_sync_at": os.environ["AT"],',
-                    "}",
-                    'd.pop("replaced_from_staging", None)',
-                    'with open(path, "w") as f:',
-                    "    yaml.safe_dump(d, f, default_flow_style=False, sort_keys=False)",
-                ].join("\n"),
-            ], { env: pyEnv });
-            out(`==> Stamped core/core.yaml: replaced_from_source.last_sync_sha=${srcSha}\n`);
+            updateSnapshotStatus(backupDir, "ready");
         }
-        else {
-            err("    WARN: neither yq nor python3+PyYAML available — skipping core/core.yaml stamp\n");
-        }
-    }
-    // NOTE (6.2.4): the post-rescue "sync-journal baseline reconcile" that lived
-    // here (6.2.1 itemize-parse, 6.2.3 hash-diff) is intentionally GONE. Masking
-    // rescue-changed scaffold as already-synced starved the push leg — the vault
-    // silently kept stale scaffold bytes while the journal claimed convergence.
-    // Correct semantics: leave rescue-changed files visible as "local changed";
-    // the next bidirectional sync pushes them up (vault converges to the rescue
-    // output), and the pull-side byte-identical convergence probe (6.2.0)
-    // absorbs cross-machine races without minting `.conflict-*` mirrors.
-    // --- File count summary ---
-    out("\n");
-    out("==> File count summary:\n");
-    for (const rootRel of wipeToplevel) {
-        const abs = path.join(hqRoot, rootRel);
-        if (lexists(abs)) {
-            const n = countFiles(abs);
-            out(`    ${rootRel}: ${n} files\n`);
+        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`);
     }
-    out("\n");
-    out("==> Classification:\n");
-    out(`    user-only (left in place):        ${counts.userOnly} files\n`);
-    out(`    unchanged (preserved/re-laid):    ${counts.unchanged} files\n`);
-    out(`    user-edits (rescued):             ${counts.userEdit} files\n`);
-    out(`    user-edits (conflict quarantine): ${counts.userConflict} files\n`);
-    out(`    user-edits (overwrite-safe):      ${counts.userOverwrite} files\n`);
-    out(`    cloud-symlink reconciled:         ${counts.cloudSymlinkReconciled} files\n`);
-    out(`    drift reconciled (== upstream):   ${counts.driftReconciled} files\n`);
-    out(`    reindex symlinks dropped:     ${counts.symlinkDropped} entries\n`);
-    if (counts.claudeDiffAppend > 0) {
-        out("      of which .claude/CLAUDE.md diff-appended to personal/CLAUDE.md\n");
-    }
-    if (counts.userConflict > 0) {
-        out(`      conflict bucket: .hq-conflicts/rescue-${RUN_TS}/\n`);
-    }
-    if (baselineMode === "history_floor") {
-        out(`    baseline:                          last-sync floor ${historyFloor}\n`);
+    else if (cfg.doBackup && !cfg.dryRun && wipeToplevel.length !== 0) {
+        out("\n==> Safety snapshot skipped (classification found no destructive paths).\n");
     }
-    else {
-        out("    baseline:                          upstream HEAD (no stamp; first run / floor unreachable)\n");
-    }
-    // --- Write recovery manifest into the snapshot + prune old snapshots ---
-    if (cfg.doBackup && backupDir && isDir(backupDir)) {
-        const lines = [];
-        lines.push("# HQ pre-update safety snapshot", "");
-        lines.push(`Created:   ${RUN_TS}`);
-        lines.push(`HQ root:   ${hqRoot}`);
-        lines.push(`Source:    ${cfg.sourceRepo}@${cfg.ref} (${srcSha})`);
-        if (baselineMode === "history_floor") {
-            lines.push(`Baseline:  history_floor (${historyFloor})`);
+    try {
+        mutationStarted = true;
+        applyClassifiedActions(ctx, backupDir);
+        // --- Back up preserve-subpaths to a mktemp shuttle ---
+        const shuttle = path.join(tmpdir, "preserve");
+        fs.mkdirSync(shuttle, { recursive: true });
+        const preserveMap = [];
+        let shuttleId = 0;
+        for (const sp of cfg.preserveSubpaths) {
+            const src = path.join(hqRoot, sp);
+            if (lexists(src)) {
+                shuttleId += 1;
+                cpA(src, shuttle, String(shuttleId));
+                preserveMap.push({ id: shuttleId, rel: sp });
+                out(`==> Backed up ${sp} -> shuttle/${shuttleId}\n`);
+            }
         }
-        else {
-            lines.push("Baseline:  head_compare (no last-sync stamp; first run or floor unreachable)");
-        }
-        lines.push("", "## What the rescue did");
-        lines.push(`  user-only  (left in place):              ${counts.userOnly}`);
-        lines.push(`  unchanged  (preserved/re-laid):          ${counts.unchanged}`);
-        lines.push(`  user-edit  (rescued into personal/):     ${counts.userEdit}`);
-        lines.push(`  user-edit  (conflict quarantine):        ${counts.userConflict}`);
-        lines.push(`  user-edit  (overwrite-safe):             ${counts.userOverwrite}`);
-        lines.push(`  cloud-symlink reconciled:                ${counts.cloudSymlinkReconciled}`);
-        lines.push(`  drift reconciled (== upstream HEAD):     ${counts.driftReconciled}`);
-        lines.push(`  reindex symlinks dropped:            ${counts.symlinkDropped}`);
-        if (counts.userConflict > 0) {
-            lines.push(`  conflict bucket: .hq-conflicts/rescue-${RUN_TS}/`);
+        out("\n");
+        out(`==> Walk complete (user-only: ${counts.userOnly}, unchanged: ${counts.unchanged}, user-edit-rescued: ${counts.userEdit}, conflict-quarantined: ${counts.userConflict}, overwrite-safe: ${counts.userOverwrite}, cloud-symlink-reconciled: ${counts.cloudSymlinkReconciled}, symlinks-dropped: ${counts.symlinkDropped})\n`);
+        // --- Overlay source onto HQ root ---
+        out("==> Overlaying source onto HQ root ...\n");
+        // `unchangedList` is only populated during applyClassifiedActions above, so
+        // re-derive the --exclude-from protect list HERE. Building overlayArgs before
+        // classification left the list empty, so unchanged files were overlaid and
+        // their mtimes reset to clone time (rescue-mtime-preserve regression). The
+        // early overlayArgs remain correct for the pre-classification dry-run.
+        const overlayRunArgs = fs.statSync(unchangedList).size > 0
+            ? [
+                "-a",
+                `--exclude-from=${unchangedList}`,
+                ...rsyncExcludes,
+                toCygwinRsyncPath(srcDir + "/"),
+                toCygwinRsyncPath(hqRoot + "/"),
+            ]
+            : overlayArgs;
+        const overlay = run("rsync", overlayRunArgs, { env });
+        if (overlay.status !== 0) {
+            // bash runs under set -e: a failed rsync aborts with its status.
+            err(overlay.stderr);
+            throw new ExitError(overlay.status || 1);
+        }
+        // --- Restore preserved sub-paths ---
+        if (preserveMap.length > 0) {
+            out("==> Restoring preserved sub-paths ...\n");
+            for (const { id, rel } of preserveMap) {
+                const dest = path.join(hqRoot, rel);
+                fs.mkdirSync(path.dirname(dest), { recursive: true });
+                const shuttleItem = path.join(shuttle, String(id));
+                if (isDir(shuttleItem)) {
+                    fs.rmSync(dest, { recursive: true, force: true });
+                    cpATo(shuttleItem, dest);
+                }
+                else {
+                    cpATo(shuttleItem, dest);
+                }
+                out(`    restored ${rel}\n`);
+            }
         }
-        lines.push("", "## Moved / deleted files (tab-separated: action, path, detail)");
-        let rescueLogContent = "";
-        try {
-            rescueLogContent = fs.readFileSync(rescueLog, "utf-8");
+        // --- Restore executable bit on shipped shebang scripts (defense-in-depth) ---
+        // rsync -a already propagated each file's upstream git tree mode; this guards
+        // the case where upstream itself committed an executable script as 0644 -- a
+        // hook the runtime exec's then dies with EACCES and is silently disabled. A
+        // shebang is an unambiguous "meant to be run" marker. See restoreShebangExecBits.
+        const execBitFixes = restoreShebangExecBits(srcDir, hqRoot, env);
+        if (execBitFixes > 0) {
+            out(`==> Restored executable bit on ${execBitFixes} shipped shebang script(s) lacking +x\n`);
+        }
+        // --- Stamp sync-point provenance into core/core.yaml ---
+        // `last_sync_at` = the source commit's committer time, NOT wall-clock now:
+        // the stamp must be a pure function of srcSha so every machine rescuing the
+        // same release writes byte-identical core.yaml (see srcCommitIsoRaw). An
+        // unparseable commit timestamp skips the stamp entirely — a nondeterministic
+        // stamp is worse than no stamp (it re-creates cross-machine conflict mirrors).
+        const srcCommitDate = new Date(srcCommitIsoRaw);
+        if (cfg.narrowPaths.length === 0 && isFileFollow(coreYaml) && Number.isNaN(srcCommitDate.getTime())) {
+            err(`    WARN: could not parse source commit timestamp (${JSON.stringify(srcCommitIsoRaw)}); skipping core/core.yaml stamp to keep it deterministic\n`);
+        }
+        if (cfg.narrowPaths.length === 0 &&
+            isFileFollow(coreYaml) &&
+            !Number.isNaN(srcCommitDate.getTime())) {
+            const nowUtc = utcStamp(srcCommitDate, "colon");
+            if (yqAvailable) {
+                const stampEnv = {
+                    ...env,
+                    SHA: srcSha,
+                    SOURCE: cfg.sourceRepo,
+                    THE_REF: cfg.ref,
+                    AT: nowUtc,
+                };
+                run("yq", [
+                    "-i",
+                    ".replaced_from_source.source       = strenv(SOURCE) |\n" +
+                        "        .replaced_from_source.ref          = strenv(THE_REF) |\n" +
+                        "        .replaced_from_source.last_sync_sha = strenv(SHA) |\n" +
+                        "        .replaced_from_source.last_sync_at  = strenv(AT) |\n" +
+                        "        del(.replaced_from_staging)",
+                    coreYaml,
+                ], { env: stampEnv });
+                out(`==> Stamped core/core.yaml: replaced_from_source.last_sync_sha=${srcSha}\n`);
+            }
+            else if (hasCmd("python3", env) &&
+                run("python3", ["-c", "import yaml"], { env }).status === 0) {
+                const pyEnv = {
+                    ...env,
+                    SHA: srcSha,
+                    SOURCE: cfg.sourceRepo,
+                    THE_REF: cfg.ref,
+                    AT: nowUtc,
+                    CORE: coreYaml,
+                };
+                run("python3", [
+                    "-c",
+                    [
+                        "import os, yaml",
+                        'path = os.environ["CORE"]',
+                        "try:",
+                        "    with open(path) as f:",
+                        "        d = yaml.safe_load(f) or {}",
+                        "except FileNotFoundError:",
+                        "    d = {}",
+                        'd["replaced_from_source"] = {',
+                        '    "source": os.environ["SOURCE"],',
+                        '    "ref": os.environ["THE_REF"],',
+                        '    "last_sync_sha": os.environ["SHA"],',
+                        '    "last_sync_at": os.environ["AT"],',
+                        "}",
+                        'd.pop("replaced_from_staging", None)',
+                        'with open(path, "w") as f:',
+                        "    yaml.safe_dump(d, f, default_flow_style=False, sort_keys=False)",
+                    ].join("\n"),
+                ], { env: pyEnv });
+                out(`==> Stamped core/core.yaml: replaced_from_source.last_sync_sha=${srcSha}\n`);
+            }
+            else {
+                err("    WARN: neither yq nor python3+PyYAML available — skipping core/core.yaml stamp\n");
+            }
         }
-        catch {
-            rescueLogContent = "";
+        // NOTE (6.2.4): the post-rescue "sync-journal baseline reconcile" that lived
+        // here (6.2.1 itemize-parse, 6.2.3 hash-diff) is intentionally GONE. Masking
+        // rescue-changed scaffold as already-synced starved the push leg — the vault
+        // silently kept stale scaffold bytes while the journal claimed convergence.
+        // Correct semantics: leave rescue-changed files visible as "local changed";
+        // the next bidirectional sync pushes them up (vault converges to the rescue
+        // output), and the pull-side byte-identical convergence probe (6.2.0)
+        // absorbs cross-machine races without minting `.conflict-*` mirrors.
+        // --- File count summary ---
+        out("\n");
+        out("==> File count summary:\n");
+        for (const rootRel of wipeToplevel) {
+            const abs = path.join(hqRoot, rootRel);
+            if (lexists(abs)) {
+                const n = countFiles(abs);
+                out(`    ${rootRel}: ${n} files\n`);
+            }
         }
-        if (rescueLogContent.length > 0) {
-            // `cat` includes the trailing content verbatim.
-            lines.push(rescueLogContent.replace(/\n$/, ""));
+        out("\n");
+        out("==> Classification:\n");
+        out(`    user-only (left in place):        ${counts.userOnly} files\n`);
+        out(`    unchanged (preserved/re-laid):    ${counts.unchanged} files\n`);
+        out(`    user-edits (rescued):             ${counts.userEdit} files\n`);
+        out(`    user-edits (conflict quarantine): ${counts.userConflict} files\n`);
+        out(`    user-edits (overwrite-safe):      ${counts.userOverwrite} files\n`);
+        out(`    cloud-symlink reconciled:         ${counts.cloudSymlinkReconciled} files\n`);
+        out(`    drift reconciled (== upstream):   ${counts.driftReconciled} files\n`);
+        out(`    reindex symlinks dropped:     ${counts.symlinkDropped} entries\n`);
+        if (counts.claudeDiffAppend > 0) {
+            out("      of which .claude/CLAUDE.md diff-appended to personal/CLAUDE.md\n");
         }
-        else {
-            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("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).`);
-        try {
-            fs.writeFileSync(path.join(backupDir, "RECOVERY.md"), lines.join("\n") + "\n");
+        if (counts.userConflict > 0) {
+            out(`      conflict bucket: .hq-conflicts/rescue-${RUN_TS}/\n`);
         }
-        catch {
-            /* best-effort, matches `|| true` */
+        if (baselineMode === "history_floor") {
+            out(`    baseline:                          last-sync floor ${historyFloor}\n`);
+        }
+        else {
+            out("    baseline:                          upstream HEAD (no stamp; first run / floor unreachable)\n");
+        }
+        // --- Write recovery manifest into the snapshot + prune old snapshots ---
+        if (cfg.doBackup && backupDir && isDir(backupDir)) {
+            const lines = [];
+            lines.push("# HQ pre-update safety snapshot", "");
+            lines.push(`Created:   ${RUN_TS}`);
+            lines.push(`HQ root:   ${hqRoot}`);
+            lines.push(`Source:    ${cfg.sourceRepo}@${cfg.ref} (${srcSha})`);
+            if (baselineMode === "history_floor") {
+                lines.push(`Baseline:  history_floor (${historyFloor})`);
+            }
+            else {
+                lines.push("Baseline:  head_compare (no last-sync stamp; first run or floor unreachable)");
+            }
+            lines.push("", "## What the rescue did");
+            lines.push(`  user-only  (left in place):              ${counts.userOnly}`);
+            lines.push(`  unchanged  (preserved/re-laid):          ${counts.unchanged}`);
+            lines.push(`  user-edit  (rescued into personal/):     ${counts.userEdit}`);
+            lines.push(`  user-edit  (conflict quarantine):        ${counts.userConflict}`);
+            lines.push(`  user-edit  (overwrite-safe):             ${counts.userOverwrite}`);
+            lines.push(`  cloud-symlink reconciled:                ${counts.cloudSymlinkReconciled}`);
+            lines.push(`  drift reconciled (== upstream HEAD):     ${counts.driftReconciled}`);
+            lines.push(`  reindex symlinks dropped:            ${counts.symlinkDropped}`);
+            if (counts.userConflict > 0) {
+                lines.push(`  conflict bucket: .hq-conflicts/rescue-${RUN_TS}/`);
+            }
+            lines.push("", "## Moved / deleted files (tab-separated: action, path, detail)");
+            let rescueLogContent = "";
+            try {
+                rescueLogContent = fs.readFileSync(rescueLog, "utf-8");
+            }
+            catch {
+                rescueLogContent = "";
+            }
+            if (rescueLogContent.length > 0) {
+                // `cat` includes the trailing content verbatim.
+                lines.push(rescueLogContent.replace(/\n$/, ""));
+            }
+            else {
+                lines.push("  (no files were moved or deleted)");
+            }
+            lines.push("", "## Restore");
+            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("", `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`);
+            pruneManagedBackups(cfg, hqRoot, out, true);
         }
         out("\n");
-        out(`==> Pre-update snapshot + recovery manifest: ${backupDir}\n`);
-        pruneOldBackups(cfg, out);
+        out(`==> Done. Source: ${cfg.sourceRepo}@${cfg.ref} (${srcSha})\n`);
+        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 filtered pre-update snapshot is at ${backupDir} (RECOVERY.md explains restore).\n`);
+        }
+        return { status: 0 };
     }
-    out("\n");
-    out(`==> Done. Source: ${cfg.sourceRepo}@${cfg.ref} (${srcSha})\n`);
-    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`);
+    catch (error) {
+        if (backupDir && isDir(backupDir)) {
+            updateSnapshotStatus(backupDir, mutationStarted ? "recovery-required" : "failed-pre-mutation");
+            pruneManagedBackups(cfg, hqRoot, out, true);
+        }
+        throw error;
     }
-    return { status: 0 };
 }
 function recordDecision(ctx, decision) {
     ctx.decisions.push(decision);
@@ -1068,8 +1129,12 @@ function recordDecision(ctx, decision) {
 }
 function applyClassifiedActions(ctx, backupDir) {
     const completed = [];
+    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);
         }
@@ -1088,6 +1153,21 @@ function applyClassifiedActions(ctx, backupDir) {
         }
     }
 }
+/** Deterministic seam for the real reindex-vs-rescue race; never set in production. */
+function injectApplyPathChangeForTest(ctx) {
+    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, completed, backupDir) {
     if (!backupDir || !isDir(backupDir))
         return [];
@@ -1639,7 +1719,15 @@ function renderDryRunDecision(ctx, decision) {
 function buildRescueActions(ctx) {
     const actions = [];
     const add = (label, affectedRels, runAction) => {
-        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) {
         const localPath = path.join(ctx.hqRoot, decision.rel);
@@ -1838,16 +1926,15 @@ function walkAndProcess(ctx, rootRel) {
         recordDecision(ctx, classifyOne(ctx, rootRel));
         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, hqRoot) {
     const found = [];
@@ -1875,11 +1962,9 @@ function findFilesAndSymlinks(rootAbs, hqRoot) {
                 //   - .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;
             }
@@ -1934,41 +2019,98 @@ function restoreMtimesFromGit(srcDir, env, out) {
         }
     }
 }
-// --- prune old pre-update-* snapshots past retention ---
-function pruneOldBackups(cfg, out) {
-    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 = [];
+function allocateSnapshotDir(backupRoot, runTs, rootHash, runId) {
+    return path.join(backupRoot, `pre-update-${runTs}-${rootHash}-${runId}`);
+}
+function snapshotManifest(status, hqRoot, runId, cfg, sourceSha, includedRoots) {
+    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) {
     try {
-        entries = fs.readdirSync(cfg.backupRoot);
+        return JSON.parse(fs.readFileSync(path.join(backupDir, "SNAPSHOT.json"), "utf8"));
     }
     catch {
-        return;
+        return null;
     }
-    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 */
-            }
+}
+/** Publish only complete JSON; a crash can leave a temp file but never a torn manifest. */
+function writeSnapshotManifest(backupDir, manifest) {
+    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, status, completedAt) {
+    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, hqRoot, out, apply) {
+    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, rel) {
+    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, hqRoot, roots, _env, err) {
+    try {
+        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`) ---
 function countFiles(dir) {
@@ -2048,6 +2190,42 @@ function cpATo(src, dest) {
         /* ignore */
     }
 }
+/** Snapshot copy that preserves metadata while pruning canonical transient directories. */
+function cpAToFiltered(src, dest, rel) {
+    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() {
     const fd = 0;