@indigoai-us/hq-cloud 6.14.7 → 6.14.8

package/src/backup-prune.test.ts

@@ -0,0 +1,98 @@
+import { describe, expect, it } from "vitest";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import {
+  applyBackupPrune,
+  canonicalRootHash,
+  inventoryManagedSnapshots,
+  planBackupPrune,
+  type BackupEntry,
+  type SnapshotStatus,
+} from "./backup-prune.js";
+
+const DAY = 86_400_000;
+const now = Date.UTC(2026, 6, 15, 12);
+const rootA = "/tmp/hq-a";
+const rootB = "/tmp/hq-b";
+function entry(name: string, age: number, status: SnapshotStatus, root = rootA): BackupEntry {
+  const at = new Date(now - age * DAY).toISOString();
+  return { name, createdMs: now - age * DAY, completedMs: now - age * DAY, bytes: 1,
+    manifest: { schemaVersion: 1, status, canonicalHqRoot: root, rootHash: canonicalRootHash(root), runId: name,
+      creatorPid: 1, creatorStartedAt: at, source: "source", ref: "main", sourceSha: "sha", createdAt: at,
+      completedAt: at, includedRoots: ["core"], fileCount: 1, byteCount: 1 } };
+}
+const names = (x: ReturnType<typeof planBackupPrune>) => x.candidates.map((c) => c.entry.name).sort();
+const protectedNames = (x: ReturnType<typeof planBackupPrune>) => x.protected.map((p) => `${p.entry.name}:${p.reason}`).sort();
+
+describe("planBackupPrune", () => {
+  it("keeps the newest two known-good snapshots per canonical root", () => {
+    const p = planBackupPrune([entry("a1", 0, "completed-good"), entry("a2", 1, "completed-good"), entry("a3", 2, "completed-good"), entry("a4", 3, "completed-good"), entry("b1", 0, "completed-good", rootB)], now);
+    expect(names(p)).toEqual(["a3", "a4"]);
+    expect(protectedNames(p)).toContain("a1:newest-good");
+    expect(protectedNames(p)).toContain("b1:newest-good");
+  });
+
+  it("never selects the sole, old known-good snapshot", () => {
+    const p = planBackupPrune([entry("only", 30, "completed-good")], now);
+    expect(names(p)).toEqual([]);
+    expect(protectedNames(p)).toEqual(["only:newest-good"]);
+  });
+
+  it("retains copying and unsuperseded recovery evidence", () => {
+    const p = planBackupPrune([entry("copy", 40, "copying"), entry("recovery", 40, "recovery-required")], now);
+    expect(names(p)).toEqual([]);
+    expect(protectedNames(p)).toContain("copy:copying-not-superseded");
+    expect(protectedNames(p)).toContain("recovery:recovery-required-no-later-good");
+  });
+
+  it("requires a later good run before pruning recovery-required snapshots", () => {
+    const p = planBackupPrune([entry("recovery-old", 30, "recovery-required"), entry("recovery-new", 2, "recovery-required"), entry("good", 1, "completed-good")], now);
+    expect(names(p)).toEqual(["recovery-old"]);
+    expect(protectedNames(p)).toContain("recovery-new:newest-recovery-required-grace");
+  });
+
+  it("only prunes failed-pre-mutation snapshots after a newer ready/good snapshot", () => {
+    const noSuccess = planBackupPrune([entry("failure", 20, "failed-pre-mutation")], now);
+    expect(names(noSuccess)).toEqual([]);
+    const p = planBackupPrune([entry("failure-new", 1, "failed-pre-mutation"), entry("failure-old", 2, "failed-pre-mutation"), entry("ready", 0, "ready")], now);
+    expect(names(p)).toEqual(["failure-old"]);
+  });
+
+  it("clamps malformed retention so the newest good is still protected", () => {
+    const p = planBackupPrune([entry("one", 30, "completed-good"), entry("two", 31, "completed-good"), entry("three", 32, "completed-good")], now, { keepGood: 0, maxAgeDays: Number.NaN });
+    expect(names(p)).toEqual(["three"]);
+    expect(protectedNames(p)).toContain("one:newest-good");
+  });
+});
+
+describe("managed snapshot filesystem boundary", () => {
+  it("does not select prefix matches, mcp, symlinks, malformed metadata, or changed candidates", () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "hq-prune-root-"));
+    const backup = fs.mkdtempSync(path.join(os.tmpdir(), "hq-prune-backup-"));
+    try {
+      const make = (name: string, age: number) => {
+        const dir = path.join(backup, name); fs.mkdirSync(dir);
+        const at = new Date(now - age * DAY).toISOString();
+        fs.writeFileSync(path.join(dir, "SNAPSHOT.json"), JSON.stringify({ ...entry(name, age, "completed-good", root).manifest, runId: name, createdAt: at, completedAt: at }));
+        return dir;
+      };
+      const good1 = make("pre-update-2026-07-15T12-00-00Z-" + canonicalRootHash(root) + "-one", 0);
+      const good2 = make("pre-update-2026-07-14T12-00-00Z-" + canonicalRootHash(root) + "-two", 1);
+      const old = make("pre-update-2026-07-13T12-00-00Z-" + canonicalRootHash(root) + "-three", 2);
+      fs.mkdirSync(path.join(backup, "mcp"));
+      fs.mkdirSync(path.join(backup, "pre-update-not-managed"));
+      fs.symlinkSync(good1, path.join(backup, "pre-update-2026-07-12T12-00-00Z-" + canonicalRootHash(root) + "-symlink"));
+      const inventory = inventoryManagedSnapshots(backup, root);
+      expect(inventory.candidates.map((x) => x.entry.name)).toEqual([path.basename(old)]);
+      expect(inventory.unmanaged.map((x) => x.name)).toEqual(expect.arrayContaining(["mcp", "pre-update-not-managed"]));
+      // A changed manifest invalidates the dry-run identity and cannot be removed.
+      fs.writeFileSync(path.join(old, "SNAPSHOT.json"), JSON.stringify({ ...entry("replacement", 2, "completed-good", root).manifest }));
+      const result = applyBackupPrune(backup, root, inventory);
+      expect(result.deleted).toEqual([]);
+      expect(fs.existsSync(old)).toBe(true);
+      expect(fs.existsSync(path.join(backup, "mcp"))).toBe(true);
+      expect(fs.existsSync(good2)).toBe(true);
+    } finally { fs.rmSync(root, { recursive: true, force: true }); fs.rmSync(backup, { recursive: true, force: true }); }
+  });
+});

package/src/backup-prune.ts

@@ -0,0 +1,182 @@
+/**
+ * Safety-first inventory and retention policy for HQ rescue snapshots.
+ *
+ * This file deliberately separates policy from filesystem access.  In
+ * particular, `planBackupPrune` cannot remove, create, or mutate anything.
+ */
+import * as crypto from "crypto";
+import * as fs from "fs";
+import * as path from "path";
+
+export const SNAPSHOT_SCHEMA_VERSION = 1;
+export const SNAPSHOT_FILE = "SNAPSHOT.json";
+export const MANAGED_SNAPSHOT_RE = /^pre-update-\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}Z-[a-f0-9]{16}-[A-Za-z0-9_-]+$/;
+export type SnapshotStatus = "copying" | "ready" | "completed-good" | "failed-pre-mutation" | "recovery-required";
+
+export interface SnapshotManifest {
+  schemaVersion: 1;
+  status: SnapshotStatus;
+  canonicalHqRoot: string;
+  rootHash: string;
+  runId: string;
+  creatorPid: number;
+  creatorStartedAt: string;
+  source: string;
+  ref: string;
+  sourceSha: string;
+  createdAt: string;
+  completedAt?: string;
+  includedRoots: string[];
+  fileCount: number;
+  byteCount: number;
+}
+
+export interface BackupEntry {
+  name: string;
+  manifest: SnapshotManifest;
+  createdMs: number;
+  completedMs: number;
+  bytes: number;
+  identity?: { dev: number; ino: number };
+  copyingOwnerLive?: boolean;
+}
+export interface ProtectedEntry { entry: BackupEntry; reason: string }
+export interface DeletionCandidate { entry: BackupEntry; reason: string }
+export interface BackupPrunePlan { candidates: DeletionCandidate[]; protected: ProtectedEntry[]; unmanaged: { name: string; reason: string }[] }
+export interface RetentionConfig { keepGood: number; keepFailedPreMutation: number; maxAgeDays: number }
+
+export const DEFAULT_RETENTION: RetentionConfig = { keepGood: 2, keepFailedPreMutation: 1, maxAgeDays: 7 };
+const day = 24 * 60 * 60 * 1000;
+
+export function canonicalRootHash(root: string): string {
+  return crypto.createHash("sha256").update(root).digest("hex").slice(0, 16);
+}
+
+export function safeRetention(input: Partial<RetentionConfig> = {}): RetentionConfig {
+  const integer = (value: unknown, fallback: number, minimum: number) =>
+    typeof value === "number" && Number.isInteger(value) && value >= minimum ? value : fallback;
+  return {
+    keepGood: integer(input.keepGood, DEFAULT_RETENTION.keepGood, 1),
+    keepFailedPreMutation: integer(input.keepFailedPreMutation, DEFAULT_RETENTION.keepFailedPreMutation, 1),
+    maxAgeDays: integer(input.maxAgeDays, DEFAULT_RETENTION.maxAgeDays, 0),
+  };
+}
+
+const newestFirst = (a: BackupEntry, b: BackupEntry) => b.completedMs - a.completedMs || b.createdMs - a.createdMs || b.name.localeCompare(a.name);
+
+/** Every managed entry receives either a retention reason or a deletion reason. */
+export function planBackupPrune(entries: BackupEntry[], nowMs: number, input: Partial<RetentionConfig> = {}): BackupPrunePlan {
+  const cfg = safeRetention(input);
+  const candidates: DeletionCandidate[] = [];
+  const protectedEntries: ProtectedEntry[] = [];
+  const byRoot = new Map<string, BackupEntry[]>();
+  for (const entry of entries) {
+    const group = byRoot.get(entry.manifest.canonicalHqRoot) ?? [];
+    group.push(entry);
+    byRoot.set(entry.manifest.canonicalHqRoot, group);
+  }
+  for (const group of byRoot.values()) {
+    const good = group.filter((e) => e.manifest.status === "completed-good").sort(newestFirst);
+    const readyOrGood = group.filter((e) => e.manifest.status === "ready" || e.manifest.status === "completed-good").sort(newestFirst);
+    const laterGood = (e: BackupEntry) => good.some((g) => g.completedMs > e.completedMs || (g.completedMs === e.completedMs && g.name > e.name));
+    const newestRecovery = group.filter((e) => e.manifest.status === "recovery-required").sort(newestFirst)[0];
+    for (const entry of group) {
+      const status = entry.manifest.status;
+      if (status === "copying") {
+        protectedEntries.push({ entry, reason: entry.copyingOwnerLive ? "copying-owner-live" : "copying-not-superseded" });
+        continue;
+      }
+      if (status === "completed-good") {
+        const rank = good.indexOf(entry);
+        if (rank < cfg.keepGood) {
+          protectedEntries.push({ entry, reason: rank === 0 ? "newest-good" : "keep-newest-good" });
+        } else if (nowMs - entry.completedMs >= cfg.maxAgeDays * day) {
+          candidates.push({ entry, reason: "completed-good-age-and-rank" });
+        } else {
+          candidates.push({ entry, reason: "completed-good-rank" });
+        }
+        continue;
+      }
+      if (status === "failed-pre-mutation") {
+        const failures = group.filter((e) => e.manifest.status === status).sort(newestFirst);
+        const rank = failures.indexOf(entry);
+        const superseded = readyOrGood.some((other) => newestFirst(other, entry) < 0);
+        if (rank < cfg.keepFailedPreMutation || !superseded) protectedEntries.push({ entry, reason: !superseded ? "failed-pre-mutation-not-superseded" : "keep-failed-pre-mutation" });
+        else candidates.push({ entry, reason: "failed-pre-mutation-superseded" });
+        continue;
+      }
+      // A recovery-required copy is recovery evidence until a later known-good run.
+      if (!laterGood(entry)) {
+        protectedEntries.push({ entry, reason: "recovery-required-no-later-good" });
+      } else if (entry === newestRecovery && nowMs - entry.completedMs < cfg.maxAgeDays * day) {
+        protectedEntries.push({ entry, reason: "newest-recovery-required-grace" });
+      } else if (nowMs - entry.completedMs >= cfg.maxAgeDays * day || entry !== newestRecovery) {
+        candidates.push({ entry, reason: "recovery-required-superseded" });
+      } else {
+        protectedEntries.push({ entry, reason: "recovery-required-grace" });
+      }
+    }
+  }
+  return { candidates, protected: protectedEntries, unmanaged: [] };
+}
+
+function validManifest(value: unknown, canonicalRoot: string): value is SnapshotManifest {
+  const x = value as Partial<SnapshotManifest>;
+  return !!x && x.schemaVersion === SNAPSHOT_SCHEMA_VERSION && typeof x.canonicalHqRoot === "string" &&
+    x.canonicalHqRoot === canonicalRoot && x.rootHash === canonicalRootHash(canonicalRoot) &&
+    typeof x.runId === "string" && /^[A-Za-z0-9_-]+$/.test(x.runId) &&
+    ["copying", "ready", "completed-good", "failed-pre-mutation", "recovery-required"].includes(x.status ?? "") &&
+    typeof x.createdAt === "string" && Array.isArray(x.includedRoots) && typeof x.fileCount === "number" && typeof x.byteCount === "number";
+}
+
+export function inventoryManagedSnapshots(backupRoot: string, canonicalRoot: string, isCopyingOwnerLive: (m: SnapshotManifest) => boolean = () => false, retention: Partial<RetentionConfig> = {}): BackupPrunePlan & { entries: BackupEntry[] } {
+  const entries: BackupEntry[] = [];
+  const unmanaged: { name: string; reason: string }[] = [];
+  let names: string[] = [];
+  try { names = fs.readdirSync(backupRoot); } catch { return { entries, candidates: [], protected: [], unmanaged: [{ name: backupRoot, reason: "backup-root-unreadable" }] }; }
+  for (const name of names.sort()) {
+    // Never descend into categories such as mcp/; only direct, exact names qualify.
+    if (!MANAGED_SNAPSHOT_RE.test(name)) { unmanaged.push({ name, reason: "not-managed-snapshot-name" }); continue; }
+    const abs = path.join(backupRoot, name);
+    let st: fs.Stats;
+    try { st = fs.lstatSync(abs); } catch { unmanaged.push({ name, reason: "lstat-failed" }); continue; }
+    if (!st.isDirectory() || st.isSymbolicLink()) { unmanaged.push({ name, reason: "not-real-directory" }); continue; }
+    let manifest: unknown;
+    try { manifest = JSON.parse(fs.readFileSync(path.join(abs, SNAPSHOT_FILE), "utf8")); } catch { unmanaged.push({ name, reason: "missing-or-invalid-metadata" }); continue; }
+    if (!validManifest(manifest, canonicalRoot)) { unmanaged.push({ name, reason: "metadata-does-not-match-canonical-root" }); continue; }
+    const m = manifest;
+    const createdMs = Date.parse(m.createdAt);
+    const completedMs = Date.parse(m.completedAt ?? m.createdAt);
+    if (!Number.isFinite(createdMs) || !Number.isFinite(completedMs)) { unmanaged.push({ name, reason: "invalid-metadata-timestamp" }); continue; }
+    entries.push({ name, manifest: m, createdMs, completedMs, bytes: m.byteCount, identity: { dev: st.dev, ino: st.ino }, copyingOwnerLive: m.status === "copying" && isCopyingOwnerLive(m) });
+  }
+  const plan = planBackupPrune(entries, Date.now(), retention);
+  return { entries, ...plan, unmanaged: [...unmanaged, ...plan.unmanaged] };
+}
+
+/** Revalidates strict identity then renames before recursively removing it. */
+export function applyBackupPrune(backupRoot: string, canonicalRoot: string, plan: BackupPrunePlan, retention: Partial<RetentionConfig> = {}): { deleted: string[]; failures: string[] } {
+  const deleted: string[] = [], failures: string[] = [];
+  const lockPath = path.join(backupRoot, ".hq-backup-prune.lock");
+  let lockFd: number | undefined;
+  try { lockFd = fs.openSync(lockPath, "wx"); fs.writeSync(lockFd, `${process.pid}\n`); }
+  catch { return { deleted, failures: ["backup-root-lock-busy-or-unwritable"] }; }
+  try {
+    // This is deliberately after acquiring the backup-root lock and immediately
+    // before rename: a dry-run plan is never trusted across a filesystem race.
+    const fresh = inventoryManagedSnapshots(backupRoot, canonicalRoot, () => false, retention);
+    const freshByName = new Map(fresh.entries.map((e) => [e.name, e]));
+    const stillCandidates = new Set(fresh.candidates.map((e) => e.entry.name));
+    for (const candidate of plan.candidates) {
+      const current = freshByName.get(candidate.entry.name);
+      if (!current || !stillCandidates.has(candidate.entry.name) || current.manifest.runId !== candidate.entry.manifest.runId || current.identity?.dev !== candidate.entry.identity?.dev || current.identity?.ino !== candidate.entry.identity?.ino || current.manifest.status === "copying") { failures.push(`${candidate.entry.name}: changed-or-in-use`); continue; }
+      const from = path.join(backupRoot, current.name);
+      const tombstone = path.join(backupRoot, `.deleting-${current.manifest.runId}`);
+      try { fs.renameSync(from, tombstone); fs.rmSync(tombstone, { recursive: true, force: false }); deleted.push(current.name); }
+      catch (error) { failures.push(`${current.name}: ${error instanceof Error ? error.message : String(error)}`); }
+    }
+  } finally {
+    try { if (lockFd !== undefined) fs.closeSync(lockFd); fs.unlinkSync(lockPath); } catch { /* retained errors are safer than a delete race */ }
+  }
+  return { deleted, failures };
+}

package/src/bin/backup-prune-runner.ts

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+/** Explicit, local-only retention command. Defaults to dry-run. */
+import * as fs from "fs";
+import * as path from "path";
+import { applyBackupPrune, inventoryManagedSnapshots } from "../backup-prune.js";
+import { acquireOperationLock, OperationLockedError } from "../operation-lock.js";
+
+const args = process.argv.slice(2);
+const value = (flag: string) => { const i = args.indexOf(flag); return i >= 0 ? args[i + 1] : undefined; };
+const rootArg = value("--hq-root");
+const backupArg = value("--backup-dir");
+const mode = value("--mode") ?? "dry-run";
+if (!rootArg || !["dry-run", "apply"].includes(mode)) {
+  process.stderr.write("usage: hq-backup-prune --hq-root DIR [--backup-dir DIR] [--mode dry-run|apply]\n");
+  process.exit(2);
+}
+const root = fs.realpathSync(rootArg);
+const backupRoot = backupArg ? path.resolve(backupArg) : path.join(process.env.HOME ?? "", ".hq", "backups");
+let lock;
+try { lock = acquireOperationLock(root, "backup-prune", { timeoutSec: 0, onWaitStart: () => undefined }); }
+catch (error) {
+  if (error instanceof OperationLockedError) { process.stderr.write("hq-backup-prune: skipped-in-use\n"); process.exit(0); }
+  throw error;
+}
+try {
+  const inventory = inventoryManagedSnapshots(backupRoot, root, (m) => { try { process.kill(m.creatorPid, 0); return true; } catch { return false; } });
+  const plan = { candidates: inventory.candidates, protected: inventory.protected, unmanaged: inventory.unmanaged };
+  process.stdout.write(JSON.stringify({ mode, candidates: plan.candidates.map((x) => ({ name: x.entry.name, rootHash: x.entry.manifest.rootHash, status: x.entry.manifest.status, bytes: x.entry.bytes, reason: x.reason })), protected: plan.protected.map((x) => ({ name: x.entry.name, reason: x.reason })), unmanaged: plan.unmanaged }) + "\n");
+  if (mode === "apply") {
+    const result = applyBackupPrune(backupRoot, root, plan);
+    if (result.failures.length) { process.stderr.write(result.failures.join("\n") + "\n"); process.exitCode = 1; }
+  }
+} finally { lock.release(); }

package/src/bin/sync-runner-watch-loop.ts

@@ -1,4 +1,5 @@
 import * as path from "path";
+import { inventoryManagedSnapshots } from "../backup-prune.js";
 import { VaultClient } from "../index.js";
 import { pickCanonicalPersonEntity } from "../vault-client.js";
 import {
@@ -98,6 +99,15 @@ export async function runWatchLoop(
   const eventPush = argv.includes("--event-push");
   const companiesMode = argv.includes("--companies");
   const hqRoot = parsed.hqRoot;
+  // Delayed and daily: this must never be attached to the 15s poll cadence.
+  // Stage 0 remains dry-run only; the standalone hq-backup-prune command is
+  // the explicitly-gated apply surface.
+  let nextBackupPruneAt = Date.now() + 60_000;
+  const runBackupPrune = deps.runBackupPrune ?? (async (root: string) => {
+    const backupRoot = path.join(process.env.HOME ?? "", ".hq", "backups");
+    const plan = inventoryManagedSnapshots(backupRoot, root, (m) => { try { process.kill(m.creatorPid, 0); return true; } catch { return false; } });
+    process.stderr.write(`hq-sync-runner: backup retention dry-run — ${plan.candidates.length} candidate(s), ${plan.protected.length} protected\n`);
+  });
 
   const passArgv = argv.filter((a, i) => {
     if (a === "--watch") return false;
@@ -510,6 +520,14 @@ export async function runWatchLoop(
       } else if (result !== 0) {
         return result;
       }
+      if (Date.now() >= nextBackupPruneAt) {
+        // Advance before invoking: a failed/unavailable backstop cannot become
+        // an every-tick retry loop. It is diagnostic only and never restarts
+        // the sync daemon.
+        nextBackupPruneAt = Date.now() + 24 * 60 * 60 * 1000;
+        try { await runBackupPrune(hqRoot); }
+        catch (error) { process.stderr.write(`hq-sync-runner: backup retention dry-run failed — ${error instanceof Error ? error.message : String(error)}\n`); }
+      }
       await Promise.race([sleep(pollMs), stoppedSignal]);
     }
     return 0;

package/src/bin/sync-runner.ts

@@ -1649,6 +1649,8 @@ export interface RunnerLoopDeps {
    * `deps` and forwards just the argv to `runRunner`.
    */
   runPass?: (passArgv: string[]) => Promise<number>;
+  /** Stage-0 backup retention backstop: a dry-run only, never a sync-tick action. */
+  runBackupPrune?: (hqRoot: string) => Promise<void>;
   /**
    * Clock seam for the event-push watcher's debounce window. Defaults to
    * {@link systemClock}; tests inject a `FakeClock` to advance the window

package/src/cli/rescue-classify-ordering.test.ts

@@ -369,4 +369,125 @@ exec ${JSON.stringify(realGit)} "$@"
     expect(lexists(link)).toBe(true);
     expect(fs.existsSync(path.join(hqRoot, "core/a.md"))).toBe(true);
   });
+
+  it("fails with a typed state-change error when reindex replaces a classified symlink before apply", () => {
+    const hqRoot = makeHqRoot();
+    const target = path.join(hqRoot, "personal/skills/foreman/tests");
+    fs.mkdirSync(target, { recursive: true });
+    const link = path.join(hqRoot, ".claude/skills/personal:foreman/tests");
+    fs.mkdirSync(path.dirname(link), { recursive: true });
+    fs.symlinkSync("../../../personal/skills/foreman/tests", link);
+
+    const args = [
+      "--hq-root", hqRoot,
+      "--source", "test/repo",
+      "--ref", "main",
+      "--floor-sha", floorSha,
+      "--yes",
+      "--no-backup",
+    ];
+    const r = runRescueCapture(args, {
+      ...baseEnv,
+      HQ_RESCUE_FAULT_BEFORE_APPLY_REL: ".claude/skills/personal:foreman/tests",
+      HQ_RESCUE_FAULT_BEFORE_APPLY_KIND: "directory",
+    });
+    const out = `${r.stdout}\n${r.stderr}\n${String(r.threw ?? "")}`;
+
+    expect(r.threw, out).toBeInstanceOf(Error);
+    expect(out).toContain("changed after classification");
+    expect(out).toContain("expected symlink, found directory");
+    expect(out).not.toContain("EISDIR");
+    expect(fs.readFileSync(path.join(hqRoot, "core/a.md"), "utf-8")).toBe("v1\n");
+  });
+
+  it("keeps the full default wipe set out of worktrees and omits transient build state from the snapshot", () => {
+    const hqRoot = makeHqRoot();
+    const backupRoot = path.join(workDir, `backups-${caseSeq}`);
+    const writeTransient = (rel: string) => {
+      const dest = path.join(hqRoot, rel, "large.bin");
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      fs.writeFileSync(dest, "reproducible\n");
+    };
+    for (const rel of [
+      "worktrees/repo",
+      ".worktrees/repo",
+      ".sst-sandbox-home/runtime",
+      ".tmp-codex-asar/cache",
+      ".claude/worktrees/agent/repo",
+      ".claude/skills/demo/node_modules/pkg",
+      ".claude/skills/demo/.pnpm-store/v3",
+      ".claude/skills/demo/.sst/build",
+      ".claude/skills/demo/.next/cache",
+      ".claude/skills/demo/target/debug",
+    ]) {
+      writeTransient(rel);
+    }
+
+    const r = runRescueCapture(
+      [
+        "--hq-root", hqRoot,
+        "--source", "test/repo",
+        "--ref", "main",
+        "--floor-sha", floorSha,
+        "--backup-dir", backupRoot,
+        "--yes",
+      ],
+      baseEnv,
+    );
+    const out = `${r.stdout}\n${r.stderr}\n${String(r.threw ?? "")}`;
+
+    expect(r.threw, out).toBeUndefined();
+    expect(r.status, out).toBe(0);
+    for (const rel of ["worktrees", ".worktrees", ".sst-sandbox-home", ".tmp-codex-asar"]) {
+      expect(fs.existsSync(path.join(hqRoot, rel, "repo", "large.bin")) ||
+        fs.existsSync(path.join(hqRoot, rel, "runtime", "large.bin")) ||
+        fs.existsSync(path.join(hqRoot, rel, "cache", "large.bin")), rel).toBe(true);
+    }
+
+    const snapshots = fs.readdirSync(backupRoot).filter((name) => name.startsWith("pre-update-"));
+    expect(snapshots).toHaveLength(1);
+    const snapshot = path.join(backupRoot, snapshots[0]);
+    expect(fs.existsSync(path.join(snapshot, "core/a.md"))).toBe(true);
+    expect(fs.existsSync(path.join(snapshot, "RECOVERY.md"))).toBe(true);
+    for (const rel of [
+      "worktrees",
+      ".worktrees",
+      ".sst-sandbox-home",
+      ".tmp-codex-asar",
+      ".claude/worktrees",
+      ".claude/skills/demo/node_modules",
+      ".claude/skills/demo/.pnpm-store",
+      ".claude/skills/demo/.sst",
+      ".claude/skills/demo/.next",
+      ".claude/skills/demo/target",
+    ]) {
+      expect(lexists(path.join(snapshot, rel)), `snapshot unexpectedly contains ${rel}`).toBe(false);
+    }
+  });
+
+  it("dry-run never allocates or prunes snapshots", () => {
+    const hqRoot = makeHqRoot();
+    const backupRoot = path.join(workDir, `dry-backups-${caseSeq}`);
+    const existing = path.join(backupRoot, "pre-update-existing");
+    fs.mkdirSync(existing, { recursive: true });
+    fs.writeFileSync(path.join(existing, "keep.txt"), "do not prune\n");
+
+    const r = runRescueCapture(
+      [
+        "--hq-root", hqRoot,
+        "--source", "test/repo",
+        "--ref", "main",
+        "--floor-sha", floorSha,
+        "--backup-dir", backupRoot,
+        "--dry-run",
+      ],
+      baseEnv,
+    );
+    const out = `${r.stdout}\n${r.stderr}\n${String(r.threw ?? "")}`;
+
+    expect(r.threw, out).toBeUndefined();
+    expect(r.status, out).toBe(0);
+    expect(fs.readdirSync(backupRoot)).toEqual(["pre-update-existing"]);
+    expect(fs.readFileSync(path.join(existing, "keep.txt"), "utf-8")).toBe("do not prune\n");
+  });
 });