@indigoai-us/hq-cloud 6.15.0 → 6.15.2

package/src/cli/rescue-core.ts

@@ -1,3011 +0,0 @@
-/**
- * hq rescue — drift-preserving re-sync of a local HQ tree to an upstream
- * hq-core release (or staging branch). This is the native-TypeScript port of
- * the former scripts/replace-rescue.sh (removed). It is an *orchestration*
- * port: the control flow, three-way drift classification, routing, YAML
- * stamping, mtime restoration, backup snapshot and summary are implemented in
- * TypeScript, while the heavy primitives the bash itself delegated to —
- * `git` (clone/checkout/hash-object/cat-file/ls-tree/show/log), `rsync` (the
- * overlay), and the YAML editor (`yq`/`python3`) — are still invoked as
- * subprocesses. Reimplementing git's blob hashing or rsync's include/exclude
- * filter engine in pure JS would *increase* the risk of behavioural drift, so
- * the port reuses the exact same tools with the exact same argument vectors.
- *
- * Behaviour (classification outcomes, on-disk results, log lines, exit codes)
- * is preserved 1:1 with the legacy script. See the original script's header in
- * git history for the full algorithm narrative.
- *
- * Three-way classification per file under each wipe-set top-level entry:
- *   USER-ONLY  -> leave in place (overlay runs without --delete).
- *   UNCHANGED  -> delete (overlay re-lays from source) OR, when identical to
- *                 upstream HEAD, leave in place + protect from the overlay so
- *                 its mtime survives (Layer 1).
- *   USER-EDIT  -> rescue into personal/ (or diff-append for .claude/CLAUDE.md),
- *                 quarantine into .hq-conflicts/ (conflict class), or silently
- *                 overwrite (overwrite-safe class).
- */
-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;
-}
-
-// Paths always preserved across wipe+overlay (shuttled out, restored after).
-const CARVE_OUT_PATHS = [
-  "core/packages",
-  "packages",
-  ".claude/state",
-  "core/workers/registry.yaml",
-  ".claude/settings.local.json",
-];
-
-// Preserve set that is redundant to pass via --preserve (always preserved).
-const ALWAYS_PRESERVED_NAMES = [
-  ".git",
-  "companies",
-  "personal",
-  "workspace",
-  "repos",
-  ".github",
-  ".leak-scan",
-  ".hq-sync-journal.json",
-  ".hq",
-  ".hq-conflicts",
-  // Machine-local state. SSM/root invocations can leave credentials here
-  // unreadable to the HQ user; rescue must neither snapshot nor classify it.
-  ".local",
-  // Package-manager caches: never release-shipped, never drift-tracked, and
-  // huge (the pnpm content-addressed store alone is tens of thousands of
-  // files). Walking them just to classify everything user-only dominates the
-  // rescue on any machine that has run `pnpm install`. The sync engine ignores
-  // 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 {
-  ref: string;
-  sourceRepo: string;
-  dryRun: boolean;
-  assumeYes: boolean;
-  cloudUpdate: boolean;
-  extraPreserve: string[];
-  preserveSubpaths: string[];
-  narrowPaths: string[];
-  hqRootOverride: string;
-  historyCheck: boolean;
-  floorShaOverride: string;
-  doBackup: boolean;
-  backupRoot: string;
-  backupRetentionDays: string;
-  backupRetentionCount: string;
-}
-
-class ExitError extends Error {
-  constructor(public code: number) {
-    super(`exit ${code}`);
-  }
-}
-
-/** Run a subprocess synchronously, inheriting the parent environment by default. */
-function run(
-  cmd: string,
-  args: string[],
-  opts: { cwd?: string; env?: NodeJS.ProcessEnv; input?: string } = {},
-): { status: number; stdout: string; stderr: string } {
-  const res = spawnSync(cmd, args, {
-    cwd: opts.cwd,
-    env: opts.env ?? process.env,
-    input: opts.input,
-    encoding: "utf-8",
-  });
-  return {
-    status: res.status ?? (res.error ? 127 : 1),
-    stdout: res.stdout ?? "",
-    stderr: res.stderr ?? "",
-  };
-}
-
-/**
- * Cygwin's rsync is a POSIX program even when Node gave us a native Win32
- * path. Keep UNC paths in Cygwin's documented `//server/share` form and map
- * drive roots explicitly instead of relying on Cygwin's native-path fallback.
- */
-export function toCygwinRsyncPath(localPath: string): string {
-  const slashPath = localPath.replaceAll("\\", "/");
-  if (/^\/\/[^/]+\/[^/]+(?:\/|$)/.test(slashPath)) return slashPath;
-
-  const drivePath = /^([a-z]):\/(.*)$/i.exec(slashPath);
-  if (drivePath) {
-    return `/cygdrive/${drivePath[1]!.toLowerCase()}/${drivePath[2]}`;
-  }
-  return localPath;
-}
-
-function redactGitDiagnostic(output: string, ghToken: string): string {
-  let redacted = output;
-  if (ghToken) redacted = redacted.replaceAll(ghToken, "***");
-  return redacted
-    .replace(/\b([a-z][a-z0-9+.-]*:\/\/)[^\s/@]+(?::[^\s/@]*)?@/gi, "$1***@")
-    .replace(/(authorization\s*:\s*)[^\r\n]*/gi, "$1***");
-}
-
-/** `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 && 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.
-function isDir(p: string): boolean {
-  try {
-    return fs.statSync(p).isDirectory();
-  } catch {
-    return false;
-  }
-}
-function isFileFollow(p: string): boolean {
-  try {
-    return fs.statSync(p).isFile();
-  } catch {
-    return false;
-  }
-}
-function existsFollow(p: string): boolean {
-  try {
-    fs.statSync(p);
-    return true;
-  } catch {
-    return false;
-  }
-}
-function lstatOrNull(p: string): fs.Stats | null {
-  try {
-    return fs.lstatSync(p);
-  } catch {
-    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;
-}
-
-/** `cmp -s a b` — byte-identical regular-file comparison. */
-function bytesEqual(a: string, b: string): boolean {
-  try {
-    const sa = fs.statSync(a);
-    const sb = fs.statSync(b);
-    if (sa.size !== sb.size) return false;
-    return fs.readFileSync(a).equals(fs.readFileSync(b));
-  } catch {
-    return false;
-  }
-}
-
-function utcStamp(d: Date, sep: "colon" | "dash"): string {
-  const p = (n: number) => String(n).padStart(2, "0");
-  const date = `${d.getUTCFullYear()}-${p(d.getUTCMonth() + 1)}-${p(d.getUTCDate())}`;
-  const h = p(d.getUTCHours());
-  const m = p(d.getUTCMinutes());
-  const s = p(d.getUTCSeconds());
-  return sep === "colon" ? `${date}T${h}:${m}:${s}Z` : `${date}T${h}-${m}-${s}Z`;
-}
-
-/**
- * Parse the rescue argv exactly as the bash `while case` loop did, including
- * validation and the same exit codes (1 unknown/usage, 2 bad option). Throws
- * ExitError on any validation failure.
- */
-export function parseRescueArgs(argv: string[]): Config {
-  const cfg: Config = {
-    ref: "main",
-    sourceRepo: "indigoai-us/hq-core-staging",
-    dryRun: false,
-    assumeYes: false,
-    cloudUpdate: false,
-    extraPreserve: [],
-    preserveSubpaths: [],
-    narrowPaths: [],
-    hqRootOverride: "",
-    historyCheck: true,
-    floorShaOverride: "",
-    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 => {
-    // The legacy script printed its comment header here; we emit a concise
-    // equivalent. Exit code (1) is preserved.
-    process.stderr.write(
-      "usage: hq rescue [--ref REF] [--source OWNER/REPO] [--paths P1,P2,...]\n" +
-        "                 [--preserve PATH]... [--preserve-subpath REL]...\n" +
-        "                 [--hq-root DIR] [--no-history-check] [--floor-sha SHA]\n" +
-        "                 [--no-backup] [--backup-dir DIR] [--cloud-update]\n" +
-        "                 [--dry-run] [--yes]\n",
-    );
-    throw new ExitError(1);
-  };
-
-  let narrowCsv = "";
-  let i = 0;
-  const need = (_flag: string): string => {
-    // bash `shift 2` with a missing operand would expand to empty under set -u
-    // off for positional; here we treat a missing operand as empty string,
-    // matching `"$2"` when absent.
-    return i + 1 < argv.length ? argv[++i] : "";
-  };
-  for (; i < argv.length; i++) {
-    const a = argv[i];
-    switch (a) {
-      case "--ref":
-        cfg.ref = need(a);
-        break;
-      case "--source":
-        cfg.sourceRepo = need(a);
-        break;
-      case "--preserve":
-        cfg.extraPreserve.push(need(a));
-        break;
-      case "--preserve-subpath":
-        cfg.preserveSubpaths.push(need(a));
-        break;
-      case "--paths":
-        narrowCsv = need(a);
-        break;
-      case "--hq-root":
-        cfg.hqRootOverride = need(a);
-        break;
-      case "--no-history-check":
-        cfg.historyCheck = false;
-        break;
-      case "--floor-sha": {
-        cfg.floorShaOverride = need(a);
-        if (!/^[0-9a-f]{40}$/.test(cfg.floorShaOverride)) {
-          process.stderr.write(
-            `error: --floor-sha must be a 40-char lowercase hex SHA, got: ${cfg.floorShaOverride}\n`,
-          );
-          throw new ExitError(2);
-        }
-        break;
-      }
-      case "--no-backup":
-        cfg.doBackup = false;
-        break;
-      case "--backup-dir":
-        cfg.backupRoot = need(a);
-        break;
-      case "--dry-run":
-        cfg.dryRun = true;
-        break;
-      case "--cloud-update":
-        cfg.cloudUpdate = true;
-        break;
-      case "--yes":
-      case "-y":
-        cfg.assumeYes = true;
-        break;
-      case "-h":
-      case "--help":
-        usage();
-        break;
-      default:
-        process.stderr.write(`unknown arg: ${a}\n`);
-        usage();
-    }
-  }
-
-  // --preserve redundancy check.
-  for (const p of cfg.extraPreserve) {
-    const stripped = p.replace(/\/$/, "");
-    if (ALWAYS_PRESERVED_NAMES.includes(stripped)) {
-      process.stderr.write(
-        `error: --preserve ${p} is redundant ('${p}' is always preserved). Remove the flag.\n`,
-      );
-      throw new ExitError(2);
-    }
-  }
-
-  // --preserve-subpath traversal check.
-  for (const sp of cfg.preserveSubpaths) {
-    if (sp.startsWith("/") || sp.includes("..")) {
-      process.stderr.write(
-        `error: --preserve-subpath ${sp} must be a relative path with no '..' segments.\n`,
-      );
-      throw new ExitError(2);
-    }
-  }
-
-  // Append always-on carve-outs to preserveSubpaths (dedup).
-  for (const cp of CARVE_OUT_PATHS) {
-    if (!cfg.preserveSubpaths.includes(cp)) cfg.preserveSubpaths.push(cp);
-  }
-
-  // Narrow paths parsing + validation.
-  if (narrowCsv) {
-    for (const raw of narrowCsv.split(",")) {
-      const name = raw.trim();
-      if (name === "") continue;
-      if (name.includes("/") || name === ".." || name === ".") {
-        process.stderr.write(
-          `error: --paths entry '${name}' must be a single top-level name (no slashes, no '.' or '..').\n`,
-        );
-        throw new ExitError(2);
-      }
-      cfg.narrowPaths.push(name);
-    }
-    if (cfg.narrowPaths.length === 0) {
-      process.stderr.write("error: --paths was passed but resolved to an empty list.\n");
-      throw new ExitError(2);
-    }
-    if (cfg.extraPreserve.length !== 0) {
-      process.stderr.write(
-        "error: --paths and --preserve are mutually exclusive. Use --preserve-subpath for sub-paths inside the listed top-level entries.\n",
-      );
-      throw new ExitError(2);
-    }
-  }
-
-  return cfg;
-}
-
-/**
- * Execute a fully-parsed rescue. `argv` are the same flags the bash script
- * accepted; `env` defaults to process.env (GH_TOKEN is read from it). Returns
- * the process-equivalent exit status. Never throws for normal control-flow
- * exits — those are mapped to the returned status.
- */
-export function runRescue(
-  argv: string[],
-  opts: { env?: NodeJS.ProcessEnv } = {},
-): RunRescueResult {
-  const env = opts.env ?? process.env;
-  const out = (s: string) => process.stdout.write(s);
-  const err = (s: string) => process.stderr.write(s);
-
-  let cfg: Config;
-  try {
-    cfg = parseRescueArgs(argv);
-  } catch (e) {
-    if (e instanceof ExitError) return { status: e.code };
-    throw e;
-  }
-
-  let tmpdir: string | null = null;
-  const cleanup = () => {
-    if (tmpdir) {
-      try {
-        fs.rmSync(tmpdir, { recursive: true, force: true });
-      } catch {
-        /* best-effort */
-      }
-    }
-  };
-
-  try {
-    return doRescue(cfg, env, out, err, (d) => {
-      tmpdir = d;
-    });
-  } catch (e) {
-    if (e instanceof ExitError) return { status: e.code };
-    throw e;
-  } finally {
-    cleanup();
-  }
-}
-
-/**
- * True when `root` is usable as a rescue target: an absolute path that is not
- * a bare drive letter. Pure + exported for tests; `platformPath` defaults to
- * the host `path` module so Windows and POSIX runtimes each apply their own
- * absoluteness rules (tests pass `path.win32` / `path.posix` explicitly).
- *
- * Rejecting bare `C:` matters even though `path.win32.isAbsolute("C:")` is
- * already false — the explicit pattern documents the exact field failure and
- * guards against a future helper swap that treats drive-relative paths as
- * absolute.
- */
-export function isUsableRescueRoot(root: string, platformPath: path.PlatformPath = path): boolean {
-  if (/^[A-Za-z]:$/.test(root)) return false;
-  return platformPath.isAbsolute(root);
-}
-
-/**
- * `fs.realpathSync` that converts failure into the rescue's clean error path
- * (message + ExitError) instead of an uncaught exception. An uncaught throw
- * here is what turned one bad `--hq-root` into a daily crash-loop on Windows.
- */
-function realpathOrExit(p: string, err: (s: string) => void): string {
-  try {
-    return fs.realpathSync(p);
-  } catch (e) {
-    err(`error: cannot resolve --hq-root ${p}: ${e instanceof Error ? e.message : String(e)}\n`);
-    throw new ExitError(1);
-  }
-}
-
-function doRescue(
-  cfg: Config,
-  env: NodeJS.ProcessEnv,
-  out: (s: string) => void,
-  err: (s: string) => void,
-  setTmp: (d: string) => void,
-): RunRescueResult {
-  // --- Resolve HQ root ---
-  let hqRoot: string;
-  if (cfg.hqRootOverride) {
-    // Windows field failure (2026-08-02): the menubar app's daily background
-    // core update crash-looped for days because `--hq-root` arrived as the
-    // bare drive letter `C:`. `isDir("C:")` is true (drive-relative, resolves
-    // against the per-drive cwd) but `fs.realpathSync("C:")` throws EISDIR,
-    // so every retry died with an uncaught exception — console-window
-    // flicker, git.exe 0xc0000142 dialogs, and no core updates ever landing.
-    // Fail closed with a diagnosable message instead: a rescue root must be
-    // an absolute directory path, and the error echoes the exact argv this
-    // process received so the daily log identifies the caller that mangled
-    // the path (the split happens upstream of this process).
-    if (!isUsableRescueRoot(cfg.hqRootOverride)) {
-      err(
-        `error: --hq-root must be an absolute path, got ${JSON.stringify(cfg.hqRootOverride)}.\n` +
-          `       argv: ${JSON.stringify(process.argv.slice(2))}\n`,
-      );
-      throw new ExitError(1);
-    }
-    if (!isDir(cfg.hqRootOverride)) {
-      // bash `cd` failure under set -e would abort; mirror as a generic error.
-      err(`error: --hq-root ${cfg.hqRootOverride} is not a directory.\n`);
-      throw new ExitError(1);
-    }
-    hqRoot = realpathOrExit(cfg.hqRootOverride, err);
-  } else {
-    // Legacy default assumed the script lived at personal/skills/<skill>/.
-    // The package's programmatic callers always pass --hq-root; fall back to cwd.
-    hqRoot = realpathOrExit(process.cwd(), err);
-  }
-
-  // HQ-root sanity gate — guards against wiping a non-HQ directory. `companies/`
-  // is the stable anchor (present and preserved on every HQ install), confirmed
-  // by at least one core scaffold marker. We accept ANY of `.claude/`, `core/`,
-  // or `personal/` because the layout has drifted across releases: v14.0.0 ships
-  // NEITHER `personal/` (added v15) NOR `core/` (the v15 scaffold home) — it only
-  // has `.claude/`. Requiring `personal/` here left v14.0.0 users with no upgrade
-  // path (rescue aborted; DEV-1741). `.claude/` exists on every version v14→v15,
-  // so it admits the full upgrade range while still rejecting a bare directory.
-  const hasHqMarker =
-    isDir(path.join(hqRoot, ".claude")) ||
-    isDir(path.join(hqRoot, "core")) ||
-    isDir(path.join(hqRoot, "personal"));
-  if (!isDir(path.join(hqRoot, "companies")) || !hasHqMarker) {
-    err(
-      `error: ${hqRoot} does not look like an HQ root ` +
-        `(need companies/ plus one of .claude/, core/, or personal/). Aborting.\n`,
-    );
-    err("       pass --hq-root <dir> if the script is not at personal/skills/<skill>/.\n");
-    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);
-
-  // --- Capture the pre-rescue .claude/settings.json (BEFORE the wipe) ---
-  // This is `ours` for the post-overlay settings reconcile. It must be read now
-  // because the overlay-safe classification deletes/overwrites it before
-  // reconcileClaudeSettings runs. `null` when absent (fresh install / narrow
-  // mode that excludes .claude).
-  const claudeSettingsRel = ".claude/settings.json";
-  const claudeSettingsInScope =
-    cfg.narrowPaths.length === 0 || cfg.narrowPaths.includes(".claude");
-  let preRescueSettingsJson: string | null = null;
-  if (claudeSettingsInScope) {
-    const p = path.join(hqRoot, claudeSettingsRel);
-    if (isFileFollow(p)) {
-      try {
-        preRescueSettingsJson = fs.readFileSync(p, "utf-8");
-      } catch {
-        preRescueSettingsJson = null;
-      }
-    }
-  }
-
-  // --- Read prior sync-point metadata (BEFORE the wipe) ---
-  let prevSyncSha = "";
-  let prevSyncSource = "";
-  let prevSyncRef = "";
-  let prevSyncAt = "";
-  const coreYaml = path.join(hqRoot, "core", "core.yaml");
-  const yqAvailable = hasCmd("yq", env);
-  if (isFileFollow(coreYaml) && yqAvailable) {
-    const yq = (expr: string) =>
-      run("yq", ["-r", expr, coreYaml], { env }).stdout.trim();
-    prevSyncSha = yq(
-      ".replaced_from_source.last_sync_sha // .replaced_from_staging.last_sync_sha // \"\"",
-    );
-    prevSyncSource = yq(
-      ".replaced_from_source.source // .replaced_from_staging.source // \"\"",
-    );
-    prevSyncRef = yq(".replaced_from_source.ref // .replaced_from_staging.ref // \"\"");
-    prevSyncAt = yq(
-      ".replaced_from_source.last_sync_at // .replaced_from_staging.last_sync_at // \"\"",
-    );
-  }
-
-  // Caller override (--floor-sha) wins only when the on-disk stamp is empty.
-  if (!prevSyncSha && cfg.floorShaOverride) {
-    prevSyncSha = cfg.floorShaOverride;
-    prevSyncSource = cfg.sourceRepo;
-    prevSyncRef = "(caller-supplied floor)";
-    prevSyncAt = "(unstamped install)";
-  }
-
-  out(`==> HQ root:    ${hqRoot}\n`);
-  out(`==> Source:     https://github.com/${cfg.sourceRepo} @ ${cfg.ref}\n`);
-  if (prevSyncSha) {
-    if (prevSyncSource === cfg.sourceRepo) {
-      out(
-        `==> Prior sync: ${prevSyncSha} from ${prevSyncSource}@${prevSyncRef} (${prevSyncAt}) — will use as history floor\n`,
-      );
-    } else {
-      out(
-        `==> Prior sync: ${prevSyncSha} from ${prevSyncSource} (different source — ignoring as floor)\n`,
-      );
-    }
-  }
-  if (cfg.narrowPaths.length !== 0) {
-    out("==> Mode:       narrow (--paths)\n");
-    out(`==> Wipe set:   ${cfg.narrowPaths.join(" ")}\n`);
-  } 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, worktrees, .worktrees, .sst-sandbox-home, .tmp-codex-asar, .github, .leak-scan, .hq-sync-journal.json, .hq, .hq-conflicts, .local${extra}\n`,
-    );
-  }
-  if (cfg.preserveSubpaths.length !== 0) {
-    out("==> Preserved subpaths (backed up + restored across the overlay):\n");
-    for (const sp of cfg.preserveSubpaths) {
-      const isCarve = CARVE_OUT_PATHS.includes(sp);
-      out(isCarve ? `    - ${sp}  (always-on carve-out)\n` : `    - ${sp}\n`);
-    }
-  }
-  out(
-    `==> Drift policy: rescue user-edited files to personal/; route .agents|.codex|.obsidian|MIGRATION.md user-edits to .hq-conflicts/rescue-${RUN_TS}/; silently overwrite AGENTS.md|USER-GUIDE.md|core/policies/_digest.md (regenerable); leave user-only files untouched; drop reindex symlinks (regenerated by reindex.sh)\n`,
-  );
-  if (cfg.cloudUpdate) {
-    out(
-      "==> Cloud-update mode: ON  (recognize `hq-symlink:<target>` flat files as upstream-symlink-equivalent — reconciled as UNCHANGED)\n",
-    );
-  }
-  if (cfg.historyCheck) {
-    out("==> History gate: ON (skip drift if local matches any past staging blob at that path)\n");
-  } else {
-    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 / ${cfg.backupRetentionCount} completed)\n`,
-    );
-  } else {
-    out("==> Safety backup: OFF (--no-backup / HQ_RESCUE_NO_BACKUP=1)\n");
-  }
-  if (cfg.dryRun) out("==> DRY RUN     (no destructive operations will run)\n");
-
-  // --- Confirmation prompt ---
-  if (!cfg.assumeYes && !cfg.dryRun) {
-    let backupLine = "  * NO pre-op backup (--no-backup),";
-    if (cfg.doBackup)
-      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 =
-        "\n  * reconcile `hq-symlink:<target>` flat files against upstream symlinks (cloud-update mode),";
-    out(
-      `\nThis will:\n${backupLine}\n` +
-        "  * rescue user-edited files (vs the last sync) into personal/,\n" +
-        `  * route user-edited .agents/.codex/.obsidian/MIGRATION.md into .hq-conflicts/rescue-${RUN_TS}/ for review,\n` +
-        "  * silently overwrite AGENTS.md / USER-GUIDE.md / core/policies/_digest.md (regenerable from upstream or reindex — no copy preserved)," +
-        cloudLine +
-        "\n  * drop reindex-generated symlinks (regenerated by reindex.sh on next Stop hook),\n" +
-        "  * leave user-only files (not in upstream) untouched,\n" +
-        `  * delete upstream files unchanged since last sync, then unpack ${cfg.sourceRepo}@${cfg.ref} on top.\n` +
-        "Type 'yes' to proceed: ",
-    );
-    const confirm = readLineSync();
-    if (confirm !== "yes") {
-      out("Aborted.\n");
-      throw new ExitError(4);
-    }
-  }
-
-  const tmpdir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-replace-rescue-"));
-  setTmp(tmpdir);
-  const srcDir = path.join(tmpdir, "src");
-  const rescueLog = path.join(tmpdir, "rescue-actions.log");
-  fs.writeFileSync(rescueLog, "");
-  const unchangedList = path.join(tmpdir, "unchanged-paths.txt");
-  fs.writeFileSync(unchangedList, "");
-
-  const appendLog = (line: string) => {
-    try {
-      fs.appendFileSync(rescueLog, line);
-    } catch {
-      /* best-effort, matches `|| true` */
-    }
-  };
-
-  // --- Build clone URL (GH_TOKEN basic-auth injection) ---
-  const ghToken = env.GH_TOKEN || "";
-  let cloneUrl: string;
-  let cloneUrlDisplay: string;
-  if (ghToken) {
-    cloneUrl = `https://x-access-token:${ghToken}@github.com/${cfg.sourceRepo}.git`;
-    cloneUrlDisplay = `https://x-access-token:***@github.com/${cfg.sourceRepo}.git`;
-  } else {
-    cloneUrl = `https://github.com/${cfg.sourceRepo}.git`;
-    cloneUrlDisplay = cloneUrl;
-  }
-
-  const reportGitFailure = (result: ReturnType<typeof run>) => {
-    const diagnostic = result.stderr.trim() || result.stdout.trim();
-    if (diagnostic) err(`${redactGitDiagnostic(diagnostic, ghToken)}\n`);
-  };
-
-  out("\n");
-  if (cfg.historyCheck) {
-    out(`==> Cloning ${cloneUrlDisplay} @${cfg.ref} (full history, blob:none filter) ...\n`);
-    const cloneResult = run("git", ["clone", "--filter=blob:none", cloneUrl, srcDir], { env });
-    if (cloneResult.status !== 0) {
-      reportGitFailure(cloneResult);
-      err("error: clone failed\n");
-      throw new ExitError(5);
-    }
-    const checkoutResult = run("git", ["checkout", cfg.ref], { cwd: srcDir, env });
-    if (checkoutResult.status !== 0) {
-      reportGitFailure(checkoutResult);
-      err(`error: could not check out ref '${cfg.ref}' from ${cfg.sourceRepo}\n`);
-      throw new ExitError(5);
-    }
-  } else {
-    out(`==> Cloning ${cloneUrlDisplay} @${cfg.ref} (shallow) ...\n`);
-    const shallowCloneResult = run(
-      "git",
-      ["clone", "--depth", "1", "--branch", cfg.ref, cloneUrl, srcDir],
-      { env },
-    );
-    if (shallowCloneResult.status !== 0) {
-      reportGitFailure(shallowCloneResult);
-      out("    (shallow branch clone failed; trying full clone + checkout)\n");
-      const cloneResult = run("git", ["clone", cloneUrl, srcDir], { env });
-      if (cloneResult.status !== 0) {
-        reportGitFailure(cloneResult);
-        err("error: clone failed\n");
-        throw new ExitError(5);
-      }
-      const checkoutResult = run("git", ["checkout", cfg.ref], { cwd: srcDir, env });
-      if (checkoutResult.status !== 0) {
-        reportGitFailure(checkoutResult);
-        err(`error: could not check out ref '${cfg.ref}' from ${cfg.sourceRepo}\n`);
-        throw new ExitError(5);
-      }
-    }
-  }
-
-  const srcSha = run("git", ["rev-parse", "HEAD"], { cwd: srcDir, env }).stdout.trim();
-  // Committer timestamp of the source SHA — the DETERMINISTIC stamp value for
-  // core/core.yaml's `last_sync_at`. Stamping wall-clock "now" made every
-  // rescue run on every machine produce a byte-different core.yaml for the
-  // SAME release, which is exactly the genuine local≠remote divergence that
-  // minted `core.yaml.conflict-*` mirrors across machines. Same SHA in →
-  // identical bytes out, on any machine, any day.
-  const srcCommitIsoRaw = run("git", ["show", "-s", "--format=%cI", "HEAD"], {
-    cwd: srcDir,
-    env,
-  }).stdout.trim();
-  out(`==> Source SHA: ${srcSha}\n`);
-
-  // --- Restore file mtimes from git history ---
-  restoreMtimesFromGit(srcDir, env, out);
-
-  // --- Resolve history floor ---
-  let historyFloor = "";
-  let baselineMode: "history_floor" | "head_compare" = "head_compare";
-  if (cfg.historyCheck && prevSyncSha && prevSyncSource === cfg.sourceRepo) {
-    if (run("git", ["cat-file", "-e", prevSyncSha], { cwd: srcDir, env }).status === 0) {
-      historyFloor = prevSyncSha;
-      baselineMode = "history_floor";
-    } else {
-      out(
-        `    prior-sync SHA ${prevSyncSha} not reachable in clone (rebased/dropped?); falling back to head_compare\n`,
-      );
-    }
-  }
-  if (baselineMode === "history_floor") {
-    out(`==> Baseline: ${historyFloor} (last-sync floor reachable)\n`);
-  } else {
-    out("==> Baseline: HEAD compare (no usable last-sync stamp; first-ever run or stamp mismatch)\n");
-  }
-
-  // --- Build wipe/overlay arg sets per mode ---
-  const pruneNames: string[] = [];
-  let rsyncExcludes: string[] = [];
-  if (cfg.narrowPaths.length !== 0) {
-    for (const n of cfg.narrowPaths) {
-      rsyncExcludes.push(`--include=/${n}`);
-      rsyncExcludes.push(`--include=/${n}/***`);
-    }
-    rsyncExcludes.push("--exclude=/*");
-  } else {
-    pruneNames.push(...ALWAYS_PRESERVED_NAMES);
-    for (const p of cfg.extraPreserve) pruneNames.push(p);
-    rsyncExcludes = [
-      "--exclude=.git",
-      "--exclude=personal",
-      "--exclude=workspace",
-      "--exclude=repos",
-      "--exclude=.github",
-      "--exclude=.leak-scan",
-      "--exclude=.hq-sync-journal.json",
-      "--exclude=.hq",
-      "--exclude=.hq-conflicts",
-      "--exclude=/.local",
-      "--exclude=/worktrees",
-      "--exclude=/.worktrees",
-      "--exclude=/.sst-sandbox-home",
-      "--exclude=/.tmp-codex-asar",
-      "--include=/companies/",
-      "--include=/companies/_template/***",
-      "--exclude=/companies/*",
-    ];
-    for (const p of cfg.extraPreserve) rsyncExcludes.push(`--exclude=${p}`);
-  }
-
-  // --- Compute the wipe-set top-level roots ---
-  const wipeToplevel: string[] = [];
-  if (cfg.narrowPaths.length !== 0) {
-    for (const n of cfg.narrowPaths) {
-      if (lexists(path.join(hqRoot, n))) wipeToplevel.push(n);
-    }
-  } else {
-    const preserveSet = new Set(pruneNames);
-    let entries: string[] = [];
-    try {
-      entries = fs.readdirSync(hqRoot);
-    } catch {
-      entries = [];
-    }
-    entries.sort();
-    for (const name of entries) {
-      if (preserveSet.has(name)) continue;
-      wipeToplevel.push(name);
-    }
-    if (isDir(path.join(hqRoot, "companies", "_template"))) {
-      wipeToplevel.push("companies/_template");
-    }
-  }
-
-  // --- Classification state ---
-  const counts = {
-    userOnly: 0,
-    unchanged: 0,
-    userEdit: 0,
-    userConflict: 0,
-    userOverwrite: 0,
-    claudeDiffAppend: 0,
-    symlinkDropped: 0,
-    cloudSymlinkReconciled: 0,
-    driftReconciled: 0,
-  };
-
-  const ctx: WalkCtx = {
-    cfg,
-    env,
-    hqRoot,
-    srcDir,
-    historyFloor,
-    baselineMode,
-    runTs: RUN_TS,
-    srcSha,
-    counts,
-    unchangedList,
-    appendLog,
-    out,
-    decisions: [],
-    actions: [],
-  };
-
-  // --- Walk + classify (PHASE 1: read-only) ---
-  // Classification mutates nothing on disk: every outcome is recorded as a
-  // typed RescueDecision. Destructive ops (delete, rescue-move,
-  // conflict-quarantine, symlink-drop) are built from those decisions and
-  // executed later (PHASE 2). This is the
-  // ordering-safety invariant: if classification throws partway through the
-  // wipe set (e.g. an unreadable entry, a future unhandled file shape), it
-  // aborts HERE — before a single file has been touched or even queued as a
-  // filesystem closure — instead of leaving a half-applied wipe like the
-  // pre-port bash classifier did (DEV-1767:
-  // `Error: Path is a directory` on a nested dir-symlink, thrown after ~10 core
-  // files were already deleted). Dry-run renders each typed decision inline as
-  // the walk records it, preserving the legacy progress/fault timing while
-  // still sharing the same classify path as the live pass.
-  out("\n");
-  if (wipeToplevel.length === 0) {
-    out("==> Wipe set is empty; nothing to process or overlay.\n");
-  } else {
-    out(`==> Walking wipe set, classifying vs. ${cfg.sourceRepo}@${cfg.ref} ...\n`);
-    // Batch the per-file git facts (hashes + floor lookups) up front so the
-    // walk below is map lookups, not ~3 git spawns per file.
-    precomputeGitMaps(ctx, wipeToplevel);
-    for (const rootRel of wipeToplevel) {
-      walkAndProcess(ctx, rootRel);
-    }
-  }
-
-  // --- DRY RUN: report + exit ---
-  if (cfg.dryRun) {
-    out("\n");
-    out("==> DRY RUN classification summary:\n");
-    out(`  user-only (leave in place):       ${counts.userOnly} files\n`);
-    out(`  unchanged (preserved/re-laid):    ${counts.unchanged} files\n`);
-    out(`  user-edit (rescue / diff-append): ${counts.userEdit} files\n`);
-    out(`  user-edit (conflict quarantine):  ${counts.userConflict} files\n`);
-    out(`  user-edit (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 would diff-append to personal/CLAUDE.md\n");
-    }
-    if (counts.userConflict > 0) {
-      out(`    conflict bucket: .hq-conflicts/rescue-${RUN_TS}/\n`);
-    }
-    if (cfg.preserveSubpaths.length !== 0) {
-      out("\n");
-      out("==> DRY RUN: would back up + restore these sub-paths across the overlay:\n");
-      for (const sp of cfg.preserveSubpaths) {
-        if (lexists(path.join(hqRoot, sp))) {
-          out(`  ~ ./${sp}  (present — will survive)\n`);
-        } else {
-          out(`  ~ ./${sp}  (not present locally — no-op)\n`);
-        }
-      }
-    }
-    out("\n");
-    out("==> DRY RUN: would copy these top-level entries from source on overlay:\n");
-    if (cfg.narrowPaths.length !== 0) {
-      for (const n of cfg.narrowPaths) {
-        if (lexists(path.join(srcDir, n))) out(`  + ./${n}\n`);
-      }
-    } else {
-      const preserveSet = new Set(pruneNames);
-      let srcEntries: string[] = [];
-      try {
-        srcEntries = fs.readdirSync(srcDir);
-      } catch {
-        srcEntries = [];
-      }
-      srcEntries.sort();
-      for (const name of srcEntries) {
-        if (preserveSet.has(name)) continue;
-        out(`  + ${name}\n`);
-      }
-      if (isDir(path.join(srcDir, "companies", "_template"))) {
-        out(`  + ./companies/_template  (carve-out from ${cfg.sourceRepo}@${cfg.ref})\n`);
-      }
-    }
-    out("\n");
-    out("==> DRY RUN complete. No filesystem changes made.\n");
-    return { status: 0 };
-  }
-
-  // --- Apply classified actions (PHASE 2: destructive) ---
-  // The full wipe set classified without throwing, so it is now safe to mutate.
-  // Actions run in classification (walk) order — the same order the old
-  // interleaved walk mutated in — so per-file output and on-disk results are
-  // unchanged versus before the two-phase split.
-  const overlayProtect: string[] = [];
-  if (fs.statSync(unchangedList).size > 0) {
-    overlayProtect.push(`--exclude-from=${unchangedList}`);
-  }
-  const overlayArgs = [
-    "-a",
-    ...overlayProtect,
-    ...rsyncExcludes,
-    toCygwinRsyncPath(srcDir + "/"),
-    toCygwinRsyncPath(hqRoot + "/"),
-  ];
-  // Exercise the exact overlay command before any classified delete/move. A
-  // Cygwin path conversion or filter failure therefore leaves the root intact.
-  const overlayPreflight = run("rsync", ["--dry-run", ...overlayArgs], { env });
-  if (overlayPreflight.status !== 0) {
-    err(overlayPreflight.stderr);
-    throw new ExitError(overlayPreflight.status || 1);
-  }
-  ctx.actions = buildRescueActions(ctx);
-
-  // 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");
-  fs.mkdirSync(shuttle, { recursive: true });
-  const preserveMap: { id: number; rel: string }[] = [];
-  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`);
-    }
-  }
-
-  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`);
-    }
-  }
-
-  // --- Reconcile the generated .claude/settings.json ---
-  // Runs AFTER the overlay (which re-laid the release template, wiring in any
-  // newly-released hook registrations) and AFTER the preserve-subpath restore
-  // (which brought back the user's .claude/settings.local.json). Re-composes the
-  // machine env.PATH onto the release baseline and relocates genuine user drift
-  // (vs the last-sync floor) into settings.local.json so the effective merged
-  // settings are preserved. No-op in narrow mode that excludes .claude.
-  if (claudeSettingsInScope) {
-    reconcileClaudeSettings(
-      { hqRoot, srcDir, env, historyFloor, baselineMode, preserveSubpaths: cfg.preserveSubpaths },
-      preRescueSettingsJson,
-      out,
-      err,
-    );
-  }
-
-  // --- 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: NodeJS.ProcessEnv = {
-        ...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: NodeJS.ProcessEnv = {
-        ...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");
-    }
-  }
-
-  // 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`);
-    }
-  }
-  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 {
-    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: string[] = [];
-    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(`==> 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 };
-  } catch (error) {
-    if (backupDir && isDir(backupDir)) {
-      updateSnapshotStatus(backupDir, mutationStarted ? "recovery-required" : "failed-pre-mutation");
-      pruneManagedBackups(cfg, hqRoot, out, true);
-    }
-    throw error;
-  }
-}
-
-interface WalkCtx {
-  cfg: Config;
-  env: NodeJS.ProcessEnv;
-  hqRoot: string;
-  srcDir: string;
-  historyFloor: string;
-  baselineMode: "history_floor" | "head_compare";
-  // Batched git results, precomputed once before the classify walk so
-  // classifyOne does map lookups instead of spawning git ~3x per file. On a
-  // large wipe set, process-startup overhead dominates and this is the
-  // difference between minutes and seconds. A rel absent from a map falls back
-  // to a per-file spawn (safety for paths that can't be batched line-delimited,
-  // e.g. names containing a newline). See precomputeGitMaps.
-  //   localShas: rel -> local blob SHA (`git hash-object --stdin-paths`)
-  //   floorShas: rel -> floor blob SHA, or null when the path is not in the
-  //              floor (`git cat-file --batch-check`; replaces both the
-  //              per-file `cat-file -e` existence probe AND the `rev-parse`).
-  localShas?: Map<string, string>;
-  floorShas?: Map<string, string | null>;
-  runTs: string;
-  srcSha: string;
-  // Read-only classifier output, collected in walk order. Dry-run rendering is
-  // emitted inline as each decision is recorded; live filesystem action
-  // construction is derived from this same list only after the full classify
-  // walk completes.
-  decisions: RescueDecision[];
-  // Deferred destructive ops, built from RescueDecision only AFTER the entire
-  // wipe set has been classified without error (PHASE 2 in doRescue). This is
-  // what makes a classifier crash fail-safe — a throw mid-classify aborts before
-  // a single file is mutated, so the wipe is never left half-applied
-  // (DEV-1767). Dry-run never fills this (it returns after classification), so
-  // live + dry-run share one classify path.
-  actions: RescueAction[];
-  counts: {
-    userOnly: number;
-    unchanged: number;
-    userEdit: number;
-    userConflict: number;
-    userOverwrite: number;
-    claudeDiffAppend: number;
-    symlinkDropped: number;
-    cloudSymlinkReconciled: number;
-    driftReconciled: number;
-  };
-  unchangedList: string;
-  appendLog: (line: string) => void;
-  out: (s: string) => void;
-}
-
-interface RescueAction {
-  label: string;
-  affectedRels: string[];
-  expectedPaths: { rel: string; kind: RescuePathKind }[];
-  run: () => void;
-}
-
-export type RescueDecision =
-  | { kind: "skip"; rel: string }
-  | { kind: "drop-conflict-artifact"; rel: string }
-  | { kind: "drop-script-managed"; rel: string }
-  | { kind: "drop-reindex-symlink"; rel: string; target: string }
-  | { kind: "user-only"; rel: string }
-  | { kind: "cloud-symlink-reconciled"; rel: string }
-  | { kind: "drift-reconciled"; rel: string }
-  | { kind: "user-edit-diff-append"; rel: string }
-  | { kind: "user-edit-overwrite-safe"; rel: string }
-  | { kind: "user-edit-conflict"; rel: string }
-  | { kind: "user-edit-rescue"; rel: string; target: string }
-  | { kind: "unchanged-preserve"; rel: string }
-  | { kind: "unchanged-delete"; rel: string }
-  | { kind: "wholesale-replace-template"; rel: "companies/_template" };
-
-function recordDecision(ctx: WalkCtx, decision: RescueDecision): void {
-  ctx.decisions.push(decision);
-  if (ctx.cfg.dryRun) renderDryRunDecision(ctx, decision);
-  switch (decision.kind) {
-    case "drop-reindex-symlink":
-      ctx.counts.symlinkDropped += 1;
-      return;
-    case "user-only":
-      ctx.counts.userOnly += 1;
-      return;
-    case "cloud-symlink-reconciled":
-      ctx.counts.cloudSymlinkReconciled += 1;
-      return;
-    case "drift-reconciled":
-      ctx.counts.driftReconciled += 1;
-      return;
-    case "unchanged-preserve":
-    case "unchanged-delete":
-      ctx.counts.unchanged += 1;
-      return;
-    default:
-      return;
-  }
-}
-
-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) {
-      const restored = rollbackCompletedActions(ctx, completed, backupDir);
-      const manifest = writeApplyFailureManifest(
-        ctx,
-        backupDir,
-        action,
-        completed,
-        restored,
-        err,
-      );
-      ctx.out("\n");
-      ctx.out(`error: rescue apply failed during '${action.label}'.\n`);
-      if (restored.length > 0) {
-        ctx.out(`==> Rolled back ${restored.length} prior action path(s) from the safety snapshot.\n`);
-      }
-      if (manifest) {
-        ctx.out(`==> Recovery manifest: ${manifest}\n`);
-      }
-      throw err;
-    }
-  }
-}
-
-/** 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[],
-  backupDir: string,
-): string[] {
-  if (!backupDir || !isDir(backupDir)) return [];
-
-  const rels: string[] = [];
-  const seen = new Set<string>();
-  for (let i = completed.length - 1; i >= 0; i--) {
-    const action = completed[i];
-    for (let j = action.affectedRels.length - 1; j >= 0; j--) {
-      const rel = action.affectedRels[j];
-      if (rel && !seen.has(rel)) {
-        seen.add(rel);
-        rels.push(rel);
-      }
-    }
-  }
-
-  const restored: string[] = [];
-  for (const rel of rels) {
-    const snapshotPath = path.join(backupDir, rel);
-    if (!lexists(snapshotPath)) continue;
-    const dest = path.join(ctx.hqRoot, rel);
-    try {
-      fs.mkdirSync(path.dirname(dest), { recursive: true });
-      fs.rmSync(dest, { recursive: true, force: true });
-      cpATo(snapshotPath, dest);
-      restored.push(rel);
-    } catch {
-      // Recovery manifest below records any path that could not be restored.
-    }
-  }
-  return restored;
-}
-
-function writeApplyFailureManifest(
-  ctx: WalkCtx,
-  backupDir: string,
-  failedAction: RescueAction,
-  completed: RescueAction[],
-  restored: string[],
-  err: unknown,
-): string | null {
-  const message = err instanceof Error ? err.message : String(err);
-  const completedLines =
-    completed.length === 0
-      ? ["  (none)"]
-      : completed.map((action) => {
-          const paths = action.affectedRels.length > 0 ? action.affectedRels.join(", ") : "(no filesystem path)";
-          return `  - ${action.label}: ${paths}`;
-        });
-  const restoredSet = new Set(restored);
-  const unrestored = completed
-    .flatMap((action) => action.affectedRels)
-    .filter((rel, idx, arr) => rel && arr.indexOf(rel) === idx && !restoredSet.has(rel));
-
-  const lines: string[] = [];
-  lines.push("# HQ rescue apply recovery", "");
-  lines.push(`Created: ${ctx.runTs}`);
-  lines.push(`HQ root: ${ctx.hqRoot}`);
-  lines.push(`Source: ${ctx.cfg.sourceRepo}@${ctx.cfg.ref} (${ctx.srcSha})`);
-  lines.push(`Failed action: ${failedAction.label}`);
-  lines.push(`Error: ${message}`);
-  lines.push("");
-  lines.push("## Completed Before Failure");
-  for (const line of completedLines) {
-    lines.push(line);
-  }
-  lines.push("");
-  lines.push("## Failed Action Paths");
-  if (failedAction.affectedRels.length > 0) {
-    for (const rel of failedAction.affectedRels) lines.push(`  - ${rel}`);
-  } else {
-    lines.push("  (no filesystem path)");
-  }
-  lines.push("");
-  lines.push("## Rollback");
-  if (restored.length > 0) {
-    lines.push("Restored from the pre-op safety snapshot:");
-    for (const rel of restored) lines.push(`  - ${rel}`);
-  } else {
-    lines.push("No completed action paths were restored automatically.");
-  }
-  if (unrestored.length > 0) {
-    lines.push("", "Completed action paths still requiring review:");
-    for (const rel of unrestored) lines.push(`  - ${rel}`);
-  }
-  if (backupDir && isDir(backupDir)) {
-    lines.push("");
-    lines.push("Manual restore examples:");
-    lines.push(`  cp "${backupDir}/<relpath>" "${ctx.hqRoot}/<relpath>"`);
-    lines.push(`  rsync -a "${backupDir}/" "${ctx.hqRoot}/"`);
-  } else {
-    lines.push("", "No pre-op safety snapshot was available for automatic restore.");
-  }
-
-  const manifestDir = path.join(ctx.hqRoot, ".hq", "rescue-recovery");
-  const manifestPath = path.join(manifestDir, `rescue-apply-failure-${ctx.runTs}.md`);
-  try {
-    fs.mkdirSync(manifestDir, { recursive: true });
-    fs.writeFileSync(manifestPath, lines.join("\n") + "\n");
-    return manifestPath;
-  } catch {
-    return null;
-  }
-}
-
-// --- Rescue-target mapping ---
-function mapRescueTarget(rel: string): string {
-  if (rel === ".claude/CLAUDE.md") return "personal/CLAUDE.md";
-  let rest: string;
-  if (rel.startsWith(".claude/")) rest = rel.slice(".claude/".length);
-  else if (rel.startsWith("core/")) rest = rel.slice("core/".length);
-  else rest = rel;
-  return `personal/${rest}`;
-}
-
-function isConflictClass(rel: string): boolean {
-  return (
-    rel === ".agents" ||
-    rel.startsWith(".agents/") ||
-    rel === ".codex" ||
-    rel.startsWith(".codex/") ||
-    rel === ".obsidian" ||
-    rel.startsWith(".obsidian/") ||
-    rel === "MIGRATION.md"
-  );
-}
-
-function isOverwriteSafe(rel: string): boolean {
-  return (
-    rel === "AGENTS.md" ||
-    rel === "USER-GUIDE.md" ||
-    rel === "core/docs/hq/USER-GUIDE.md" ||
-    rel === "core/policies/_digest.md" ||
-    // `.claude/settings.json` is a machine-local *generated* file (setup.sh
-    // step 3b composes env.PATH into the release template). It always differs
-    // from every release blob because of that PATH, so the generic classifier
-    // would rescue it into personal/ and lay a PATH-less template on top —
-    // dropping the machine PATH and (depending on drift/history state) failing
-    // to wire in newly-released hook registrations. Instead let the overlay
-    // always re-lay the release template (no personal/ copy), then
-    // reconcileClaudeSettings() re-composes env.PATH and relocates genuine user
-    // drift into settings.local.json. See reconcileClaudeSettings.
-    rel === ".claude/settings.json"
-  );
-}
-
-function masterSyncSymlinkTarget(localPath: string): string | null {
-  const st = lstatOrNull(localPath);
-  if (!st || !st.isSymbolicLink()) return null;
-  let tgt = "";
-  try {
-    tgt = fs.readlinkSync(localPath);
-  } catch {
-    return null;
-  }
-  return tgt.includes("/personal/") || tgt.startsWith("personal/") ? tgt : null;
-}
-
-/**
- * Drop a reindex symlink with lstat + unlink semantics: treat the path as a
- * link and remove the link itself, never following or recursing into its
- * target.
- *
- * `fs.rmSync(p, { force: true })` stat-follows on some platforms (notably
- * macOS): a symlink whose target is a directory is seen as a directory, and
- * with `recursive` unset it throws `EISDIR` ("Path is a directory"). During a
- * rescue apply that abort rolls back the whole update — the exact failure this
- * guards against (a directory-target overlay symlink such as
- * core/knowledge/<name> -> personal/knowledge/<name>). `unlink(2)` removes the
- * link regardless of what it points at, so file- and directory-target reindex
- * symlinks are dropped identically. reindex.sh re-lays the link afterward.
- *
- * A missing path is a no-op (force-equivalent); a non-symlink is left untouched
- * so we can never recurse into or delete a real directory (the classifier only
- * ever routes real symlinks here — this stays defensive).
- */
-function dropReindexSymlink(localPath: string): void {
-  const st = lstatOrNull(localPath);
-  if (!st) return; // already gone — nothing to drop
-  if (!st.isSymbolicLink()) return; // never follow/recurse into a real target
-  fs.unlinkSync(localPath);
-}
-
-function isUnderPreserve(cfg: Config, rel: string): boolean {
-  for (const sp of cfg.preserveSubpaths) {
-    if (rel === sp || rel.startsWith(sp + "/")) return true;
-  }
-  return false;
-}
-
-/** Cloud-flattened `hq-symlink:<target>` equivalence check (--cloud-update). */
-function isCloudFlattenedSymlinkEquiv(ctx: WalkCtx, rel: string, localPath: string): boolean {
-  if (!ctx.cfg.cloudUpdate) return false;
-  if (!isFileFollow(localPath)) return false;
-  let buf: Buffer;
-  try {
-    buf = fs.readFileSync(localPath);
-  } catch {
-    return false;
-  }
-  const head = buf.subarray(0, 11).toString("utf-8");
-  if (head !== "hq-symlink:") return false;
-  // First line, strip prefix, strip newlines.
-  const firstLine = buf.toString("utf-8").split("\n")[0] ?? "";
-  const localTarget = firstLine.replace(/^hq-symlink:/, "").replace(/\n/g, "");
-  if (!localTarget) return false;
-
-  const ref = ctx.baselineMode === "history_floor" ? ctx.historyFloor : "HEAD";
-  const lsTree = run("git", ["ls-tree", ref, "--", rel], { cwd: ctx.srcDir, env: ctx.env }).stdout;
-  const mode = lsTree.trim().split(/\s+/)[0] ?? "";
-  if (mode !== "120000") return false;
-
-  const showRef = ctx.baselineMode === "history_floor" ? `${ctx.historyFloor}:${rel}` : `HEAD:${rel}`;
-  const upstreamTarget = run("git", ["show", showRef], { cwd: ctx.srcDir, env: ctx.env }).stdout;
-  if (!upstreamTarget) return false;
-  return localTarget === upstreamTarget;
-}
-
-// --- diff-append .claude/CLAUDE.md user additions into personal/CLAUDE.md ---
-function diffAppendClaudeMd(ctx: WalkCtx): void {
-  const localFile = path.join(ctx.hqRoot, ".claude/CLAUDE.md");
-  const personalFile = path.join(ctx.hqRoot, "personal/CLAUDE.md");
-  const baselineFile = path.join(
-    fs.mkdtempSync(path.join(os.tmpdir(), "claude-md-baseline-")),
-    "baseline",
-  );
-
-  let wroteBaseline = false;
-  if (ctx.baselineMode === "history_floor") {
-    const show = run("git", ["show", `${ctx.historyFloor}:.claude/CLAUDE.md`], {
-      cwd: ctx.srcDir,
-      env: ctx.env,
-    });
-    if (show.status === 0) {
-      fs.writeFileSync(baselineFile, show.stdout);
-      wroteBaseline = true;
-    }
-  }
-  const srcClaude = path.join(ctx.srcDir, ".claude/CLAUDE.md");
-  const baselineNonEmpty = () => {
-    try {
-      return fs.statSync(baselineFile).size > 0;
-    } catch {
-      return false;
-    }
-  };
-  if (!baselineNonEmpty() && isFileFollow(srcClaude)) {
-    fs.copyFileSync(srcClaude, baselineFile);
-    wroteBaseline = true;
-  }
-
-  fs.mkdirSync(path.join(ctx.hqRoot, "personal"), { recursive: true });
-
-  const personalNonEmpty = () => {
-    try {
-      return fs.statSync(personalFile).size > 0;
-    } catch {
-      return false;
-    }
-  };
-
-  if (!baselineNonEmpty()) {
-    // No baseline — record the whole local file under a marker.
-    try {
-      if (wroteBaseline) fs.rmSync(baselineFile, { force: true });
-    } catch {
-      /* ignore */
-    }
-    let block = "";
-    if (personalNonEmpty()) block += "\n";
-    block += `<!-- drift-append from .claude/CLAUDE.md @ ${ctx.runTs} (source ${ctx.srcSha}; no baseline available) -->\n`;
-    block += readFileOrEmpty(localFile);
-    fs.appendFileSync(personalFile, block);
-    ctx.out("    diff-appended (full local, no baseline): .claude/CLAUDE.md -> personal/CLAUDE.md\n");
-    ctx.counts.claudeDiffAppend += 1;
-    return;
-  }
-
-  // Extract additions via `diff -u` + the sed filter.
-  const diff = run("diff", ["-u", baselineFile, localFile], { env: ctx.env });
-  try {
-    fs.rmSync(baselineFile, { force: true });
-  } catch {
-    /* ignore */
-  }
-  const additions = diff.stdout
-    .split("\n")
-    .filter((l) => !l.startsWith("+++"))
-    .filter((l) => l.startsWith("+"))
-    .map((l) => l.slice(1));
-  // sed prints each matched line; reconstruct with trailing newline per line.
-  const additionsText = additions.length ? additions.join("\n") + "\n" : "";
-
-  if (!additionsText) {
-    ctx.out("    no user edits to .claude/CLAUDE.md (skipped diff-append)\n");
-    return;
-  }
-
-  let block = "";
-  if (personalNonEmpty()) block += "\n";
-  block += `<!-- drift-append from .claude/CLAUDE.md @ ${ctx.runTs} (source ${ctx.srcSha}) -->\n`;
-  block += additionsText;
-  fs.appendFileSync(personalFile, block);
-  ctx.out("    diff-appended: .claude/CLAUDE.md additions -> personal/CLAUDE.md\n");
-  ctx.counts.claudeDiffAppend += 1;
-}
-
-// --- .claude/settings.json reconcile (recompose env.PATH + relocate drift) ---
-
-type JsonValue =
-  | string
-  | number
-  | boolean
-  | null
-  | JsonValue[]
-  | { [k: string]: JsonValue };
-
-function isPlainObject(v: unknown): v is { [k: string]: JsonValue } {
-  return typeof v === "object" && v !== null && !Array.isArray(v);
-}
-
-/** Structural deep equality for JSON values (stable, order-sensitive for objects). */
-export function jsonDeepEqual(a: JsonValue, b: JsonValue): boolean {
-  if (a === b) return true;
-  if (Array.isArray(a) && Array.isArray(b)) {
-    if (a.length !== b.length) return false;
-    return a.every((x, i) => jsonDeepEqual(x, b[i]!));
-  }
-  if (isPlainObject(a) && isPlainObject(b)) {
-    const ak = Object.keys(a);
-    const bk = Object.keys(b);
-    if (ak.length !== bk.length) return false;
-    return ak.every((k) => k in b && jsonDeepEqual(a[k]!, b[k]!));
-  }
-  return false;
-}
-
-function jsonParseOrNull(text: string | null | undefined): JsonValue | null {
-  if (text == null) return null;
-  try {
-    return JSON.parse(text) as JsonValue;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Compute the drift of `ours` relative to `base` (the three-way "ours − base").
- * Returns a partial object holding only the values `ours` added or changed
- * versus `base`, suitable for merging into settings.local.json so Claude Code's
- * higher-precedence Local scope re-supplies them on top of the release baseline.
- *
- *  - object: recurse per key; a key absent from `base` is drift wholesale.
- *  - array: drift = the elements present in `ours` but not deep-contained in
- *    `base`. This matches Claude Code's union merge for permissions/hooks, so a
- *    relocated allow/deny entry unions back into the effective settings.
- *  - scalar / type-mismatch: drift = ours's value when not deep-equal.
- *
- * `excludePath` names dotted key paths that are NEVER drift (env.PATH — a
- * machine-local value re-composed onto the release baseline, not relocated).
- * Returns `undefined` when there is no drift at this node.
- */
-export function settingsDrift(
-  ours: JsonValue,
-  base: JsonValue | undefined,
-  excludePath: string[] = ["env.PATH"],
-  pathPrefix = "",
-): JsonValue | undefined {
-  const here = pathPrefix;
-  if (excludePath.includes(here)) return undefined;
-
-  if (base === undefined) {
-    // Whole subtree is new in ours — but still honor exclusions nested under it.
-    if (isPlainObject(ours)) {
-      const out: { [k: string]: JsonValue } = {};
-      let any = false;
-      for (const k of Object.keys(ours)) {
-        const child = settingsDrift(ours[k]!, undefined, excludePath, here ? `${here}.${k}` : k);
-        if (child !== undefined) {
-          out[k] = child;
-          any = true;
-        }
-      }
-      return any ? out : undefined;
-    }
-    return ours;
-  }
-
-  if (isPlainObject(ours) && isPlainObject(base)) {
-    const out: { [k: string]: JsonValue } = {};
-    let any = false;
-    for (const k of Object.keys(ours)) {
-      const child = settingsDrift(
-        ours[k]!,
-        k in base ? base[k]! : undefined,
-        excludePath,
-        here ? `${here}.${k}` : k,
-      );
-      if (child !== undefined) {
-        out[k] = child;
-        any = true;
-      }
-    }
-    return any ? out : undefined;
-  }
-
-  if (Array.isArray(ours) && Array.isArray(base)) {
-    const extra = ours.filter((el) => !base.some((b) => jsonDeepEqual(el, b)));
-    return extra.length > 0 ? extra : undefined;
-  }
-
-  return jsonDeepEqual(ours, base) ? undefined : ours;
-}
-
-/**
- * Deep-merge `patch` into `target` in place and return it. Objects merge
- * per-key; arrays union (append patch elements not already deep-present, so a
- * re-run is idempotent and no duplicate permission/hook entries accumulate);
- * scalars are added ONLY when the key is absent from `target`. A scalar the
- * user already set in Local is the higher-precedence value and MUST NOT be
- * clobbered by the lower-precedence Project drift (e.g. Project `model: opus` +
- * Local `model: sonnet` must stay `sonnet` after rescue). Mirrors how Claude
- * Code's Local scope overrides/unions over Project.
- */
-export function deepMergeSettings(
-  target: { [k: string]: JsonValue },
-  patch: { [k: string]: JsonValue },
-): { [k: string]: JsonValue } {
-  for (const k of Object.keys(patch)) {
-    const pv = patch[k]!;
-    const tv = target[k];
-    if (Array.isArray(pv) && Array.isArray(tv)) {
-      for (const el of pv) {
-        if (!tv.some((x) => jsonDeepEqual(x, el))) tv.push(el);
-      }
-    } else if (isPlainObject(pv) && isPlainObject(tv)) {
-      deepMergeSettings(tv, pv);
-    } else if (!(k in target)) {
-      // Key absent from Local — safe to introduce the relocated drift value.
-      target[k] = pv;
-    }
-    // else: Local already defines this scalar (or a differently-typed value);
-    // it is the higher-precedence override and is left untouched.
-  }
-  return target;
-}
-
-/**
- * Apply the user's array REMOVALS (elements present in `base` but absent from
- * `ours`) to the corresponding arrays in `theirs`, in place. A union-style Local
- * overlay cannot express a removal, so a permission/hook a user deliberately
- * deleted from the generated settings.json would otherwise be restored by the
- * release baseline and never removable. Filtering `theirs` — the Project file we
- * now own — is the only representation of that intent. Recurses through objects;
- * only acts when all three nodes are arrays (or objects to recurse). Requires a
- * REAL floor base: never call with base = theirs (HEAD), or release-only entries
- * would be mistaken for removals.
- */
-export function applyArrayRemovals(
-  theirs: { [k: string]: JsonValue },
-  ours: { [k: string]: JsonValue },
-  base: { [k: string]: JsonValue },
-): void {
-  for (const k of Object.keys(base)) {
-    const bv = base[k];
-    const ov = ours[k];
-    const tv = theirs[k];
-    if (Array.isArray(bv) && Array.isArray(ov) && Array.isArray(tv)) {
-      const removed = bv.filter((b) => !ov.some((o) => jsonDeepEqual(o, b)));
-      if (removed.length > 0) {
-        theirs[k] = tv.filter((t) => !removed.some((r) => jsonDeepEqual(r, t)));
-      }
-    } else if (isPlainObject(bv) && isPlainObject(ov) && isPlainObject(tv)) {
-      applyArrayRemovals(tv, ov, bv);
-    }
-  }
-}
-
-/**
- * Re-compose the machine env.PATH for the freshly-overlaid release template.
- * Runs the SAME composer setup.sh uses (core/scripts/compose-settings-path.sh)
- * with the machine's own PATH as the base — preferring the pre-rescue snapshot
- * so a working PATH is never degraded by a possibly-truncated rescue-process
- * PATH — so the value is always machine-specific and never a hardcoded release
- * PATH (the release template ships none). Prefers the release clone's composer,
- * falls back to the overlaid one; if neither runs, carries `basePath` verbatim.
- */
-function composeSettingsPath(
-  srcDir: string,
-  hqRoot: string,
-  basePath: string,
-  env: NodeJS.ProcessEnv,
-): string {
-  const candidates = [
-    path.join(srcDir, "core", "scripts", "compose-settings-path.sh"),
-    path.join(hqRoot, "core", "scripts", "compose-settings-path.sh"),
-  ];
-  for (const script of candidates) {
-    if (!isFileFollow(script)) continue;
-    const r = run("bash", [script, basePath], { env });
-    const composed = r.stdout.replace(/\n+$/, "");
-    if (r.status === 0 && composed) return composed;
-  }
-  return basePath;
-}
-
-interface ReconcileCtx {
-  hqRoot: string;
-  srcDir: string;
-  env: NodeJS.ProcessEnv;
-  historyFloor: string;
-  baselineMode: "history_floor" | "head_compare";
-  /** cfg.preserveSubpaths — used to honor an explicit `--preserve-subpath` of
-   *  settings.json (or the whole `.claude` tree). */
-  preserveSubpaths: string[];
-}
-
-/** True when `.claude/settings.json` is covered by an EXPLICIT preserve subpath
- *  (the caller asked rescue to keep it, so the reconcile must not rewrite it).
- *  The always-on carve-outs never cover settings.json, so any match here is a
- *  deliberate caller request. */
-function settingsExplicitlyPreserved(preserveSubpaths: string[]): boolean {
-  const rel = ".claude/settings.json";
-  for (const sp of preserveSubpaths) {
-    const s = sp.replace(/\/$/, "");
-    if (s === rel || s === ".claude" || rel.startsWith(s + "/")) return true;
-  }
-  return false;
-}
-
-/**
- * Post-overlay reconcile for the machine-local, generated `.claude/settings.json`.
- *
- * At entry the overlay has already re-laid the release template (theirs) over
- * settings.json, and the user's settings.local.json has been restored from the
- * preserve shuttle. This function:
- *   1. re-composes env.PATH onto theirs (machine-specific; deliverable 3), and
- *   2. extracts ours's drift versus the last-sync floor (base) — excluding
- *      env.PATH — and merges it into settings.local.json (deliverable 2),
- * so the EFFECTIVE merged settings (Project ⊕ Local, per Claude Code's rules)
- * are preserved while the Project base returns to the shipped composition with
- * any newly-released hook registrations wired in (deliverable 1).
- *
- * Best-effort and non-fatal: unreadable/invalid JSON degrades to a
- * PATH-recompose-only pass (never worse than the old behavior), matching
- * rescue's posture elsewhere.
- */
-export function reconcileClaudeSettings(
-  ctx: ReconcileCtx,
-  preRescueSettingsJson: string | null,
-  out: (s: string) => void,
-  err: (s: string) => void,
-): void {
-  const { hqRoot, srcDir, env, historyFloor, baselineMode, preserveSubpaths } = ctx;
-  const settingsPath = path.join(hqRoot, ".claude", "settings.json");
-  const localPath = path.join(hqRoot, ".claude", "settings.local.json");
-
-  // The caller explicitly asked to keep settings.json (via `--preserve-subpath
-  // .claude/settings.json` or `--preserve-subpath .claude`). The shuttle already
-  // restored their file; honor that and do not rewrite it (nor land new
-  // registrations — that is the point of an explicit preserve).
-  if (settingsExplicitlyPreserved(preserveSubpaths)) {
-    out("==> Skipped .claude/settings.json reconcile (explicitly preserved by --preserve-subpath)\n");
-    return;
-  }
-
-  const overlaidTemplateExists = isFileFollow(settingsPath);
-
-  if (!overlaidTemplateExists) {
-    // The release no longer ships .claude/settings.json, but the overwrite-safe
-    // classification already deleted the local file. Restore the pre-rescue copy
-    // so the machine PATH and every user customization survive (critical under
-    // --no-backup, where no snapshot exists to recover from).
-    if (preRescueSettingsJson !== null) {
-      try {
-        fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
-        fs.writeFileSync(settingsPath, preRescueSettingsJson);
-        out(
-          "==> Release no longer ships .claude/settings.json; restored your existing settings.json (no reconcile).\n",
-        );
-      } catch {
-        err("    WARN: could not restore pre-rescue .claude/settings.json after the release dropped the template\n");
-      }
-    }
-    return;
-  }
-
-  const theirsRaw = (() => {
-    try {
-      return fs.readFileSync(settingsPath, "utf-8");
-    } catch {
-      return null;
-    }
-  })();
-  const theirs = jsonParseOrNull(theirsRaw);
-  if (!isPlainObject(theirs)) {
-    err("    WARN: overlaid .claude/settings.json is not valid JSON; skipping settings reconcile\n");
-    return;
-  }
-
-  const ours = jsonParseOrNull(preRescueSettingsJson);
-  const oursIsValid = isPlainObject(ours);
-
-  // The pre-rescue settings.json existed but was not parseable, and the overlay
-  // already replaced it. Preserve the raw bytes under personal/ (the same place
-  // a user-edit rescue would have put them) so a temporarily-malformed file is
-  // never destroyed by a --no-backup run. Then continue with a PATH-recompose
-  // pass so the machine still works.
-  if (preRescueSettingsJson !== null && !oursIsValid) {
-    const backup = path.join(hqRoot, "personal", ".claude", "settings.json");
-    try {
-      fs.mkdirSync(path.dirname(backup), { recursive: true });
-      fs.writeFileSync(backup, preRescueSettingsJson);
-      err(
-        "    WARN: pre-rescue .claude/settings.json was not valid JSON; preserved a copy at personal/.claude/settings.json\n",
-      );
-    } catch {
-      err("    WARN: pre-rescue .claude/settings.json was not valid JSON and could not be backed up\n");
-    }
-  }
-
-  const oursEnvPath =
-    oursIsValid && isPlainObject(ours.env) && typeof ours.env.PATH === "string"
-      ? ours.env.PATH
-      : undefined;
-
-  // 1) Re-compose env.PATH onto the release baseline. Base = the machine's own
-  //    prior PATH snapshot when present, else this process's PATH.
-  const basePath = oursEnvPath ?? env.PATH ?? "";
-  const composedPath = composeSettingsPath(srcDir, hqRoot, basePath, env);
-  if (composedPath) {
-    const envObj = isPlainObject(theirs.env) ? theirs.env : (theirs.env = {});
-    envObj.PATH = composedPath;
-  }
-
-  // 2) Relocate genuine user drift (ours vs floor baseline) into settings.local,
-  //    and apply user array removals to the Project baseline.
-  let driftKeys = 0;
-  let relocationFailed = false;
-  if (oursIsValid) {
-    // realBase = settings.json at the last-sync floor (only trustworthy in
-    // history_floor mode). Removals require it; additions fall back to theirs.
-    let realBase: JsonValue | undefined;
-    if (baselineMode === "history_floor" && historyFloor) {
-      const show = run("git", ["show", `${historyFloor}:.claude/settings.json`], {
-        cwd: srcDir,
-        env,
-      });
-      if (show.status === 0) realBase = jsonParseOrNull(show.stdout);
-    }
-    // Removals: only with a REAL floor base (never theirs — release-only entries
-    // would look like removals).
-    if (isPlainObject(realBase)) {
-      applyArrayRemovals(theirs, ours, realBase);
-    }
-    // Additions drift: base = realBase when available, else theirs (conservative
-    // head_compare fallback — never loses a customization). See design note.
-    const additionsBase: JsonValue = isPlainObject(realBase) ? realBase : theirs;
-    const drift = settingsDrift(ours, additionsBase);
-    if (isPlainObject(drift) && Object.keys(drift).length > 0) {
-      const existingLocal = jsonParseOrNull((() => {
-        try {
-          return isFileFollow(localPath) ? fs.readFileSync(localPath, "utf-8") : null;
-        } catch {
-          return null;
-        }
-      })());
-      const localObj = isPlainObject(existingLocal) ? existingLocal : {};
-      deepMergeSettings(localObj, drift);
-      driftKeys = Object.keys(drift).length;
-      try {
-        fs.mkdirSync(path.dirname(localPath), { recursive: true });
-        fs.writeFileSync(localPath, JSON.stringify(localObj, null, 2) + "\n");
-      } catch {
-        relocationFailed = true;
-        err("    WARN: could not write .claude/settings.local.json during settings reconcile\n");
-      }
-    }
-  }
-
-  // If drift relocation into settings.local.json failed, DO NOT overwrite
-  // settings.json with the release baseline — that would drop the drift with no
-  // on-disk copy under --no-backup. Restore the pre-rescue file so nothing is
-  // lost; the update simply isn't applied to settings this run (the user can
-  // retry once settings.local.json is writable).
-  if (relocationFailed) {
-    if (preRescueSettingsJson !== null) {
-      try {
-        fs.writeFileSync(settingsPath, preRescueSettingsJson);
-      } catch {
-        err("    WARN: could not restore pre-rescue .claude/settings.json after a failed drift relocation\n");
-      }
-    }
-    err(
-      "    WARN: kept your original .claude/settings.json (settings update not applied — settings.local.json was unwritable)\n",
-    );
-    return;
-  }
-
-  // Write the re-composed release baseline back to settings.json.
-  try {
-    fs.writeFileSync(settingsPath, JSON.stringify(theirs, null, 2) + "\n");
-  } catch {
-    err("    WARN: could not write re-composed .claude/settings.json during reconcile\n");
-    return;
-  }
-
-  if (driftKeys > 0) {
-    out(
-      `==> Reconciled .claude/settings.json to release baseline (env.PATH re-composed; ` +
-        `relocated ${driftKeys} drift key(s) -> .claude/settings.local.json)\n`,
-    );
-  } else {
-    out(
-      "==> Reconciled .claude/settings.json to release baseline (env.PATH re-composed; no local drift to relocate)\n",
-    );
-  }
-}
-
-/**
- * Defense-in-depth for executable scaffold scripts. `rescue` rebuilds the tree
- * with `git clone` + `rsync -a`, faithfully propagating each file's git tree
- * mode (100755 vs 100644). So a script accidentally committed upstream WITHOUT
- * its executable bit (e.g. a `.claude/hooks/*.sh` checked in as 100644) is
- * delivered non-executable to every machine, and a hook the runtime exec's
- * directly then fails with EACCES ("Permission denied") and is silently
- * disabled.
- *
- * A `#!` shebang is an unambiguous "this file is meant to be run" marker, so
- * after the overlay we ensure every shipped shebang script is executable,
- * regardless of the (possibly wrong) upstream mode bit. Execute is added only
- * where read is already granted (0644 -> 0755, 0640 -> 0750), mirroring the
- * umask convention; files that already carry any exec bit, non-files, and
- * symlinks are left untouched. Paths are enumerated from the SOURCE repo's git
- * index, so this only ever touches release-shipped scaffold -- never user
- * content the rescue leaves in place.
- *
- * Best-effort and non-fatal: a failed `git ls-files` or chmod (read-only FS,
- * EPERM) is swallowed, matching the rest of rescue's posture. Returns the count
- * of files whose mode was changed, for the run summary.
- */
-function restoreShebangExecBits(
-  srcDir: string,
-  hqRoot: string,
-  env: NodeJS.ProcessEnv,
-): number {
-  let listing: string;
-  try {
-    const r = spawnSync("git", ["-C", srcDir, "ls-files", "-z"], {
-      encoding: "utf-8",
-      env,
-      maxBuffer: 128 * 1024 * 1024,
-    });
-    if (r.status !== 0 || typeof r.stdout !== "string") return 0;
-    listing = r.stdout;
-  } catch {
-    return 0;
-  }
-  let fixed = 0;
-  for (const rel of listing.split("\0")) {
-    if (!rel) continue;
-    const dest = path.join(hqRoot, rel);
-    let st: fs.Stats;
-    try {
-      st = fs.lstatSync(dest);
-    } catch {
-      continue; // not delivered here (preserve-excluded, ignored, narrowed out)
-    }
-    if (!st.isFile()) continue; // skip dirs and symlinks (lstat: a link is not a file)
-    if ((st.mode & 0o111) !== 0) continue; // already executable
-    // Sniff the first two bytes for a shebang.
-    let head = "";
-    try {
-      const fd = fs.openSync(dest, "r");
-      try {
-        const buf = Buffer.alloc(2);
-        const n = fs.readSync(fd, buf, 0, 2, 0);
-        head = buf.subarray(0, n).toString("latin1");
-      } finally {
-        fs.closeSync(fd);
-      }
-    } catch {
-      continue;
-    }
-    if (head !== "#!") continue;
-    const execBits = (st.mode & 0o444) >> 2; // copy r-bits into the x-bit slots
-    try {
-      fs.chmodSync(dest, st.mode | execBits);
-      fixed += 1;
-    } catch {
-      // read-only FS / EPERM -- non-fatal.
-    }
-  }
-  return fixed;
-}
-
-function readFileOrEmpty(p: string): string {
-  try {
-    return fs.readFileSync(p, "utf-8");
-  } catch {
-    return "";
-  }
-}
-
-// --- rescue a single USER-EDIT file into personal/ ---
-function rescueOne(ctx: WalkCtx, rel: string): void {
-  const localPath = path.join(ctx.hqRoot, rel);
-  ctx.counts.userEdit += 1;
-
-  if (rel === ".claude/CLAUDE.md") {
-    diffAppendClaudeMd(ctx);
-    fs.rmSync(localPath, { force: true });
-    ctx.appendLog(`rescued\t${rel}\t-> personal/CLAUDE.md (diff-append)\n`);
-    return;
-  }
-
-  const target = mapRescueTarget(rel);
-  let dest = path.join(ctx.hqRoot, target);
-  fs.mkdirSync(path.dirname(dest), { recursive: true });
-  if (lexists(dest)) {
-    dest = `${dest}.drift-${Math.floor(Date.now() / 1000)}-${process.pid}`;
-  }
-  fs.renameSync(localPath, dest);
-  const destRel = dest.startsWith(ctx.hqRoot + "/") ? dest.slice(ctx.hqRoot.length + 1) : dest;
-  ctx.out(`    rescued: ${rel}  ->  ${destRel}\n`);
-  ctx.appendLog(`rescued\t${rel}\t-> ${destRel}\n`);
-}
-
-// --- quarantine a single USER-EDIT file into .hq-conflicts/ ---
-function conflictOne(ctx: WalkCtx, rel: string): void {
-  const localPath = path.join(ctx.hqRoot, rel);
-  ctx.counts.userConflict += 1;
-
-  const target = `.hq-conflicts/rescue-${ctx.runTs}/${rel}`;
-  let dest = path.join(ctx.hqRoot, target);
-  fs.mkdirSync(path.dirname(dest), { recursive: true });
-  if (lexists(dest)) {
-    dest = `${dest}.drift-${Math.floor(Date.now() / 1000)}-${process.pid}`;
-  }
-  fs.renameSync(localPath, dest);
-  const destRel = dest.startsWith(ctx.hqRoot + "/") ? dest.slice(ctx.hqRoot.length + 1) : dest;
-  ctx.out(`    conflicted: ${rel}  ->  ${destRel}\n`);
-  ctx.appendLog(`conflicted\t${rel}\t-> ${destRel}\n`);
-}
-
-// --- classify one file (the per-file workhorse) ---
-//
-// Read-only by contract: this returns a RescueDecision only. It does not render
-// dry-run text, update action queues, or mutate the filesystem. Dry-run text is
-// rendered by recordDecision, and PHASE 2 action building happens only once the
-// whole wipe set has classified without throwing. Keep it that way.
-function classifyOne(ctx: WalkCtx, rel: string): RescueDecision {
-  const { cfg } = ctx;
-  const localPath = path.join(ctx.hqRoot, rel);
-  const srcPath = path.join(ctx.srcDir, rel);
-
-  // Test-only fault seam: prove the classify-before-delete ordering invariant
-  // by forcing a classifier throw at a chosen entry. Never set in production.
-  if (ctx.env.HQ_RESCUE_FAULT_AT_REL && rel === ctx.env.HQ_RESCUE_FAULT_AT_REL) {
-    throw new Error(`rescue classifier fault injected at ${rel} (HQ_RESCUE_FAULT_AT_REL)`);
-  }
-
-  if (isUnderPreserve(cfg, rel)) return { kind: "skip", rel };
-
-  // Conflict-resolution artifacts (`<name>.conflict-<ts>-<peer>.<ext>`).
-  const base = rel.includes("/") ? rel.slice(rel.lastIndexOf("/") + 1) : rel;
-  if (/\.conflict-/.test(base)) {
-    return { kind: "drop-conflict-artifact", rel };
-  }
-
-  // Script-managed files: core/core.yaml + legacy core.yaml.
-  if (rel === "core/core.yaml" || rel === "core.yaml") {
-    return { kind: "drop-script-managed", rel };
-  }
-
-  // Symlinks (mid-tree).
-  const lst = lstatOrNull(localPath);
-  if (lst && lst.isSymbolicLink()) {
-    const target = masterSyncSymlinkTarget(localPath);
-    if (target !== null) {
-      return { kind: "drop-reindex-symlink", rel, target };
-    }
-    return { kind: "skip", rel };
-  }
-
-  // Is path in upstream HEAD?
-  const inHead = existsFollow(srcPath) ? 1 : 0;
-
-  // Is path in last-sync floor? Read the batched precompute (floorShas); fall
-  // back to a per-file probe for any rel not represented there. A non-null
-  // entry both proves presence (inFloor=1) and carries the baseline blob SHA,
-  // reused below so the `rev-parse` never has to run.
-  let inFloor = 0;
-  let baselineSha: string | undefined;
-  if (ctx.baselineMode === "history_floor") {
-    const pre = ctx.floorShas?.get(rel);
-    if (pre !== undefined) {
-      if (pre) {
-        inFloor = 1;
-        baselineSha = pre;
-      }
-    } else if (
-      run("git", ["cat-file", "-e", `${ctx.historyFloor}:${rel}`], {
-        cwd: ctx.srcDir,
-        env: ctx.env,
-      }).status === 0
-    ) {
-      inFloor = 1;
-    }
-  }
-
-  // USER-ONLY: unknown to upstream (HEAD AND floor both lack it).
-  if (inHead === 0 && inFloor === 0) {
-    return { kind: "user-only", rel };
-  }
-
-  // Path is/was in upstream. Determine if user edited it.
-  let userEdited = 0;
-  if (ctx.baselineMode === "history_floor" && inFloor === 1) {
-    const localSha =
-      ctx.localShas?.get(rel) ??
-      run("git", ["hash-object", localPath], { env: ctx.env }).stdout.trim();
-    const floorSha =
-      baselineSha ??
-      run("git", ["rev-parse", `${ctx.historyFloor}:${rel}`], {
-        cwd: ctx.srcDir,
-        env: ctx.env,
-      }).stdout.trim();
-    if (!localSha || !floorSha || localSha !== floorSha) userEdited = 1;
-  } else if (inHead === 1) {
-    if (!bytesEqual(localPath, srcPath)) userEdited = 1;
-  } else {
-    // in_floor=1, in_head=0: upstream removed since last sync — rescue.
-    userEdited = 1;
-  }
-
-  // Cloud-update reclassification.
-  if (userEdited === 1 && isCloudFlattenedSymlinkEquiv(ctx, rel, localPath)) {
-    return { kind: "cloud-symlink-reconciled", rel };
-  }
-
-  // Convergence guard: drifted from floor but identical to upstream HEAD.
-  if (userEdited === 1 && inHead === 1 && bytesEqual(localPath, srcPath)) {
-    return { kind: "drift-reconciled", rel };
-  }
-
-  if (userEdited === 1) {
-    if (rel === ".claude/CLAUDE.md") {
-      return { kind: "user-edit-diff-append", rel };
-    }
-    if (isOverwriteSafe(rel)) {
-      return { kind: "user-edit-overwrite-safe", rel };
-    }
-    if (isConflictClass(rel)) {
-      return { kind: "user-edit-conflict", rel };
-    }
-    return { kind: "user-edit-rescue", rel, target: mapRescueTarget(rel) };
-  }
-
-  // user_edited=0: matches floor baseline. Split on byte-equality to HEAD.
-  if (bytesEqual(localPath, path.join(ctx.srcDir, rel))) {
-    return { kind: "unchanged-preserve", rel };
-  }
-  return { kind: "unchanged-delete", rel };
-}
-
-function renderDryRunDecision(ctx: WalkCtx, decision: RescueDecision): void {
-  switch (decision.kind) {
-    case "skip":
-      break;
-    case "drop-conflict-artifact":
-      ctx.out(`    drop conflict artifact: ${decision.rel}\n`);
-      break;
-    case "drop-script-managed":
-      ctx.out(`    skip script-managed (rewrites at stamp step): ${decision.rel}\n`);
-      break;
-    case "drop-reindex-symlink":
-      ctx.out(`    drop reindex symlink: ${decision.rel}  ->  ${decision.target}\n`);
-      break;
-    case "user-only":
-      ctx.out(`    user-only (leave in place): ${decision.rel}\n`);
-      break;
-    case "cloud-symlink-reconciled":
-      ctx.out(
-        `    cloud-symlink reconciled (unchanged): ${decision.rel}  (hq-symlink: marker matches upstream target)\n`,
-      );
-      break;
-    case "drift-reconciled":
-      ctx.out(`    drift reconciled (identical to upstream HEAD; no rescue): ${decision.rel}\n`);
-      break;
-    case "user-edit-diff-append":
-      ctx.out(`    user-edit (diff-append): ${decision.rel}  ->  personal/CLAUDE.md\n`);
-      ctx.counts.userEdit += 1;
-      break;
-    case "user-edit-overwrite-safe":
-      ctx.out(`    user-edit (overwrite-safe): ${decision.rel}  ->  upstream wins (no copy preserved)\n`);
-      ctx.counts.userOverwrite += 1;
-      break;
-    case "user-edit-conflict":
-      ctx.out(
-        `    user-edit (conflict): ${decision.rel}  ->  .hq-conflicts/rescue-${ctx.runTs}/${decision.rel}\n`,
-      );
-      ctx.counts.userConflict += 1;
-      break;
-    case "user-edit-rescue":
-      ctx.out(`    user-edit (rescue): ${decision.rel}  ->  ${decision.target}\n`);
-      ctx.counts.userEdit += 1;
-      break;
-    case "unchanged-preserve":
-      ctx.out(`    unchanged (preserved in place): ${decision.rel}\n`);
-      break;
-    case "unchanged-delete":
-      ctx.out(`    unchanged (delete + replace): ${decision.rel}\n`);
-      break;
-    case "wholesale-replace-template":
-      ctx.out("    wholesale-replace: companies/_template (template carve-out)\n");
-      break;
-  }
-}
-
-function buildRescueActions(ctx: WalkCtx): RescueAction[] {
-  const actions: RescueAction[] = [];
-  const add = (label: string, affectedRels: string[], runAction: () => void) => {
-    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);
-    switch (decision.kind) {
-      case "skip":
-      case "user-only":
-        break;
-      case "drop-conflict-artifact":
-        add(`drop conflict artifact: ${decision.rel}`, [decision.rel], () =>
-          fs.rmSync(localPath, { force: true }),
-        );
-        break;
-      case "drop-script-managed":
-        add(`drop script-managed: ${decision.rel}`, [decision.rel], () =>
-          fs.rmSync(localPath, { force: true }),
-        );
-        break;
-      case "drop-reindex-symlink":
-        add(`drop reindex symlink: ${decision.rel}`, [decision.rel], () => {
-          dropReindexSymlink(localPath);
-          ctx.appendLog(`symlink-dropped\t${decision.rel}\t(reindex regenerable)\n`);
-        });
-        break;
-      case "cloud-symlink-reconciled":
-        add(`cloud-symlink reconciled: ${decision.rel}`, [decision.rel], () => {
-          fs.rmSync(localPath, { force: true });
-          ctx.appendLog(
-            `cloud-symlink-reconciled\t${decision.rel}\t(hq-symlink: marker matches upstream target; overlay re-lays symlink)\n`,
-          );
-        });
-        break;
-      case "drift-reconciled":
-        add(`drift reconciled: ${decision.rel}`, [decision.rel], () => {
-          fs.rmSync(localPath, { force: true });
-          ctx.appendLog(
-            `drift-reconciled\t${decision.rel}\t(identical to upstream HEAD; drifted from floor only — no personal/ copy)\n`,
-          );
-        });
-        break;
-      case "user-edit-diff-append":
-        add(`rescue diff-append: ${decision.rel}`, [decision.rel], () =>
-          rescueOne(ctx, decision.rel),
-        );
-        break;
-      case "user-edit-overwrite-safe":
-        add(`overwrite-safe: ${decision.rel}`, [decision.rel], () => {
-          fs.rmSync(localPath, { force: true });
-          ctx.counts.userOverwrite += 1;
-          ctx.appendLog(
-            `overwritten\t${decision.rel}\t(overwrite-safe; upstream wins, no copy preserved)\n`,
-          );
-        });
-        break;
-      case "user-edit-conflict":
-        add(`conflict quarantine: ${decision.rel}`, [decision.rel], () =>
-          conflictOne(ctx, decision.rel),
-        );
-        break;
-      case "user-edit-rescue":
-        add(`rescue: ${decision.rel}`, [decision.rel], () => rescueOne(ctx, decision.rel));
-        break;
-      case "unchanged-preserve":
-        add(`preserve unchanged: ${decision.rel}`, [], () => {
-          fs.appendFileSync(ctx.unchangedList, `/${decision.rel}\n`);
-          ctx.appendLog(
-            `unchanged\t${decision.rel}\t(identical to upstream; left in place, mtime preserved)\n`,
-          );
-        });
-        break;
-      case "unchanged-delete":
-        add(`delete unchanged: ${decision.rel}`, [decision.rel], () => {
-          fs.rmSync(localPath, { force: true });
-          ctx.appendLog(
-            `deleted\t${decision.rel}\t(unchanged vs baseline; re-laid by overlay if still upstream)\n`,
-          );
-        });
-        break;
-      case "wholesale-replace-template":
-        add("wholesale-replace: companies/_template", [decision.rel], () =>
-          fs.rmSync(path.join(ctx.hqRoot, "companies", "_template"), {
-            recursive: true,
-            force: true,
-          }),
-        );
-        break;
-    }
-  }
-
-  return actions;
-}
-
-// --- walk a wipe-set root ---
-// Precompute the per-file git facts classifyOne needs, in two batched passes
-// instead of ~3 `git` spawns per file. Process-startup overhead (~15-20ms per
-// spawn) dominates the per-file path, so on a large wipe set this turns a
-// minutes-long classify into a seconds-long one. Behaviour is identical: the
-// SHAs produced here are exactly what the per-file commands returned, and any
-// rel not represented in a map falls back to its original per-file spawn.
-//
-// Mirrors walkAndProcess's enumeration so the batched set matches what actually
-// reaches classifyOne: it skips `companies/_template` (wholesale-replaced, never
-// classified per-file) and top-level symlinks (dropped, never classified).
-function precomputeGitMaps(ctx: WalkCtx, wipeToplevel: string[]): void {
-  const allRels: string[] = []; // every rel that reaches classifyOne (files + symlinks)
-  const fileRels: string[] = []; // subset that are regular files (hashable)
-  const fileAbs: string[] = []; // parallel to fileRels
-
-  for (const rootRel of wipeToplevel) {
-    if (rootRel === "companies/_template") continue;
-    const rootAbs = path.join(ctx.hqRoot, rootRel);
-    const lst = lstatOrNull(rootAbs);
-    if (!lst || lst.isSymbolicLink()) continue;
-    const rels = lst.isFile()
-      ? [rootRel]
-      : lst.isDirectory()
-        ? findFilesAndSymlinks(rootAbs, ctx.hqRoot)
-        : [];
-    for (const rel of rels) {
-      // A path containing a newline can't survive line-delimited batch stdin;
-      // leave it out of the maps and let classifyOne spawn per-file for it.
-      if (rel.includes("\n")) continue;
-      allRels.push(rel);
-      const st = lstatOrNull(path.join(ctx.hqRoot, rel));
-      if (st && st.isFile()) {
-        fileRels.push(rel);
-        fileAbs.push(path.join(ctx.hqRoot, rel));
-      }
-    }
-  }
-
-  // In head_compare mode classifyOne never consults these maps (it compares
-  // bytes against the upstream working tree directly), so skip both git passes.
-  if (ctx.baselineMode !== "history_floor") {
-    ctx.floorShas = new Map();
-    ctx.localShas = new Map();
-    return;
-  }
-
-  // Pass 1: floor existence + blob SHA for every rel, in one process.
-  // `cat-file --batch-check` prints "<sha> <type> <size>" for a present object
-  // or "<input> missing" otherwise, one line per input in order. This single
-  // pass replaces BOTH the per-file `cat-file -e` (existence) and `rev-parse`
-  // (sha). It reads only the git object DB — never local file contents — so it
-  // stays cheap even on a 100k-file wipe set.
-  const floorShas = new Map<string, string | null>();
-  if (allRels.length > 0) {
-    const res = run("git", ["cat-file", "--batch-check"], {
-      cwd: ctx.srcDir,
-      env: ctx.env,
-      input: allRels.map((rel) => `${ctx.historyFloor}:${rel}`).join("\n") + "\n",
-    });
-    if (res.status === 0) {
-      const lines = res.stdout.split("\n");
-      for (let i = 0; i < allRels.length; i++) {
-        const line = lines[i] ?? "";
-        if (line === "" || line.endsWith(" missing")) {
-          floorShas.set(allRels[i], null);
-        } else {
-          const sha = line.split(" ")[0];
-          floorShas.set(allRels[i], sha || null);
-        }
-      }
-    }
-  }
-  ctx.floorShas = floorShas;
-
-  // Pass 2: local blob SHA, but ONLY for regular files that are in the floor.
-  // classifyOne reads localShas exclusively in the `inFloor === 1` branch, so a
-  // file absent from the floor (e.g. the transient `.claude/worktrees/` trees,
-  // which classify as user-only) never needs a hash — and hashing it would mean
-  // reading its bytes for nothing. Restricting the hash set to floor members is
-  // what keeps a worktree-heavy tree fast: hundreds of reads instead of 100k.
-  const localShas = new Map<string, string>();
-  const hashAbs: string[] = [];
-  const hashRels: string[] = [];
-  for (let i = 0; i < fileRels.length; i++) {
-    if (floorShas.get(fileRels[i])) {
-      hashRels.push(fileRels[i]);
-      hashAbs.push(fileAbs[i]);
-    }
-  }
-  if (hashAbs.length > 0) {
-    const res = run("git", ["hash-object", "--stdin-paths"], {
-      env: ctx.env,
-      input: hashAbs.join("\n") + "\n",
-    });
-    if (res.status === 0) {
-      const lines = res.stdout.split("\n");
-      for (let i = 0; i < hashRels.length; i++) {
-        const sha = (lines[i] ?? "").trim();
-        if (sha) localShas.set(hashRels[i], sha);
-      }
-    }
-  }
-  ctx.localShas = localShas;
-}
-
-function walkAndProcess(ctx: WalkCtx, rootRel: string): void {
-  const rootAbs = path.join(ctx.hqRoot, rootRel);
-  if (!lexists(rootAbs)) return;
-
-  // companies/_template — wholesale-replace.
-  if (rootRel === "companies/_template") {
-    recordDecision(ctx, { kind: "wholesale-replace-template", rel: "companies/_template" });
-    return;
-  }
-
-  const lst = lstatOrNull(rootAbs);
-
-  // Top-level symlink.
-  if (lst && lst.isSymbolicLink()) {
-    const target = masterSyncSymlinkTarget(rootAbs);
-    if (target !== null) {
-      recordDecision(ctx, { kind: "drop-reindex-symlink", rel: rootRel, target });
-    }
-    return;
-  }
-
-  // Top-level regular file.
-  if (lst && lst.isFile()) {
-    recordDecision(ctx, classifyOne(ctx, rootRel));
-    return;
-  }
-
-  // Top-level directory: recursive walk, pruning canonical transient state.
-  for (const rel of findFilesAndSymlinks(rootAbs, ctx.hqRoot)) {
-    recordDecision(ctx, classifyOne(ctx, rel));
-  }
-}
-
-/**
- * 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[] = [];
-  const walk = (dir: string) => {
-    let entries: fs.Dirent[];
-    try {
-      entries = fs.readdirSync(dir, { withFileTypes: true });
-    } catch {
-      return;
-    }
-    entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
-    for (const ent of entries) {
-      const abs = path.join(dir, ent.name);
-      if (ent.isSymbolicLink()) {
-        // Surfaced as an entry (type l); never descended into.
-        found.push(abs.slice(hqRoot.length + 1));
-        continue;
-      }
-      if (ent.isDirectory()) {
-        // Prune dirs that are never release content and never worth walking:
-        //   - node_modules / .git: standard.
-        //   - .pnpm-store: pnpm cache (defense-in-depth; also preserved at the
-        //     top level), huge content-addressed tree.
-        //   - .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.
-        const rel = abs.slice(hqRoot.length + 1);
-        if (isRescueTransientDirectory(rel)) continue;
-        walk(abs);
-        continue;
-      }
-      if (ent.isFile()) {
-        found.push(abs.slice(hqRoot.length + 1));
-      }
-    }
-  };
-  walk(rootAbs);
-  return found;
-}
-
-// --- restore file mtimes from git commit history ---
-function restoreMtimesFromGit(
-  srcDir: string,
-  env: NodeJS.ProcessEnv,
-  out: (s: string) => void,
-): void {
-  // Deepen a shallow clone so per-file commit times are real.
-  const isShallow =
-    run("git", ["rev-parse", "--is-shallow-repository"], { cwd: srcDir, env }).stdout.trim() ===
-    "true";
-  if (isShallow) {
-    out("==> Deepening clone for per-file mtime history (blob:none) ...\n");
-    const r = run("git", ["fetch", "--unshallow", "--filter=blob:none"], { cwd: srcDir, env });
-    if (r.status !== 0) {
-      out("    (unshallow failed; mtimes fall back to release tip-commit time)\n");
-    }
-  }
-
-  out("==> Restoring file mtimes from git commit history ...\n");
-  const log = run(
-    "git",
-    ["log", "--no-renames", "--pretty=format:C:%ct", "--name-only", "--diff-filter=ACMR"],
-    { cwd: srcDir, env },
-  );
-  if (log.status !== 0) return;
-
-  let ts = "";
-  const seen = new Set<string>();
-  for (const line of log.stdout.split("\n")) {
-    if (line.startsWith("C:")) {
-      ts = line.slice(2);
-      continue;
-    }
-    if (line.length === 0) continue;
-    if (seen.has(line)) continue;
-    seen.add(line);
-    const f = path.join(srcDir, line);
-    const st = lstatOrNull(f);
-    if (!st || st.isSymbolicLink() || !st.isFile()) continue;
-    const epoch = Number(ts);
-    if (!Number.isFinite(epoch)) continue;
-    try {
-      fs.utimesSync(f, epoch, epoch);
-    } catch {
-      /* best-effort, matches perl `|| true` */
-    }
-  }
-}
-
-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 {
-    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: string): number {
-  let n = 0;
-  const st = lstatOrNull(dir);
-  if (!st) return 0;
-  if (st.isFile()) return 1;
-  if (!st.isDirectory() || st.isSymbolicLink()) return 0;
-  const walk = (d: string) => {
-    let entries: fs.Dirent[];
-    try {
-      entries = fs.readdirSync(d, { withFileTypes: true });
-    } catch {
-      return;
-    }
-    for (const ent of entries) {
-      const abs = path.join(d, ent.name);
-      if (ent.isDirectory()) walk(abs);
-      else if (ent.isFile()) n += 1;
-    }
-  };
-  walk(dir);
-  return n;
-}
-
-/**
- * `cp -a <src> <destDir>/[<asName>]` — recursive copy preserving symlinks,
- * mtimes and modes. Mirrors the bash `cp -a "$src" "$destDir/"` (copies the
- * source basename into destDir) and the shuttle form (`cp -a "$src"
- * "$SHUTTLE/$id"`, an explicit destination name).
- */
-function cpA(src: string, destDir: string, asName?: string): void {
-  const dest = asName ? path.join(destDir, asName) : path.join(destDir, path.basename(src));
-  cpATo(src, dest);
-}
-
-/** `cp -a <src> <dest>` with an explicit destination path. */
-function cpATo(src: string, dest: string): void {
-  const st = lstatOrNull(src);
-  if (!st) return;
-  if (st.isSymbolicLink()) {
-    const link = fs.readlinkSync(src);
-    try {
-      fs.rmSync(dest, { force: true });
-    } catch {
-      /* ignore */
-    }
-    fs.symlinkSync(link, dest);
-    return;
-  }
-  if (st.isDirectory()) {
-    fs.mkdirSync(dest, { recursive: true });
-    for (const name of fs.readdirSync(src)) {
-      cpATo(path.join(src, name), path.join(dest, name));
-    }
-    try {
-      fs.utimesSync(dest, st.atime, st.mtime);
-    } catch {
-      /* ignore */
-    }
-    return;
-  }
-  // Regular file.
-  fs.copyFileSync(src, dest);
-  try {
-    fs.chmodSync(dest, st.mode);
-    fs.utimesSync(dest, st.atime, st.mtime);
-  } catch {
-    /* ignore */
-  }
-}
-
-/** 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;
-  const buf = Buffer.alloc(1);
-  let line = "";
-  for (;;) {
-    let bytes = 0;
-    try {
-      bytes = fs.readSync(fd, buf, 0, 1, null);
-    } catch {
-      break; // EOF / not readable
-    }
-    if (bytes === 0) break;
-    const ch = buf.toString("utf-8");
-    if (ch === "\n") break;
-    line += ch;
-  }
-  return line.replace(/\r$/, "");
-}