@indigoai-us/hq-cloud 6.1.0 → 6.2.1

package/src/cli/rescue-core.ts

@@ -0,0 +1,1719 @@
+/**
+ * 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 {
+  readJournal,
+  writeJournal,
+  hashFile,
+  updateEntry,
+  PERSONAL_VAULT_JOURNAL_SLUG,
+} from "../journal.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",
+];
+
+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;
+}
+
+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 ?? "",
+  };
+}
+
+/** `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;
+}
+
+// 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 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",
+  };
+
+  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();
+  }
+}
+
+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) {
+    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 = fs.realpathSync(cfg.hqRootOverride);
+  } 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 = fs.realpathSync(process.cwd());
+  }
+
+  if (!isDir(path.join(hqRoot, "companies")) || !isDir(path.join(hqRoot, "personal"))) {
+    err(
+      `error: ${hqRoot} does not look like an HQ root (missing companies/ 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");
+
+  // --- 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, .github, .leak-scan, .hq-sync-journal.json, .hq, .hq-conflicts${extra}\n`,
+    );
+  }
+  if (cfg.preserveSubpaths.length !== 0) {
+    out("==> Preserved subpaths (backed up + restored across the overlay):\n");
+    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)\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 wipe set 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;
+  }
+
+  out("\n");
+  if (cfg.historyCheck) {
+    out(`==> Cloning ${cloneUrlDisplay} @${cfg.ref} (full history, blob:none filter) ...\n`);
+    if (run("git", ["clone", "--filter=blob:none", cloneUrl, srcDir], { env }).status !== 0) {
+      err("error: clone failed\n");
+      throw new ExitError(5);
+    }
+    if (run("git", ["checkout", cfg.ref], { cwd: srcDir, env }).status !== 0) {
+      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`);
+    if (
+      run("git", ["clone", "--depth", "1", "--branch", cfg.ref, cloneUrl, srcDir], { env })
+        .status !== 0
+    ) {
+      out("    (shallow branch clone failed; trying full clone + checkout)\n");
+      if (run("git", ["clone", cloneUrl, srcDir], { env }).status !== 0) {
+        err("error: clone failed\n");
+        throw new ExitError(5);
+      }
+      if (run("git", ["checkout", cfg.ref], { cwd: srcDir, env }).status !== 0) {
+        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();
+  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",
+      "--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,
+  };
+
+  // --- Pre-operation safety snapshot (BEFORE any destructive op) ---
+  let backupDir = "";
+  if (cfg.doBackup && !cfg.dryRun && wipeToplevel.length !== 0) {
+    backupDir = path.join(cfg.backupRoot, `pre-update-${RUN_TS}`);
+    out("\n");
+    out(`==> Safety snapshot -> ${backupDir}\n`);
+    fs.mkdirSync(backupDir, { recursive: true });
+    const rsyncAvailable = hasCmd("rsync", env);
+    for (const rootRel of wipeToplevel) {
+      const srcAbs = path.join(hqRoot, rootRel);
+      if (!lexists(srcAbs)) continue;
+      const parentRel = path.dirname(rootRel);
+      const destParent = path.join(backupDir, parentRel);
+      fs.mkdirSync(destParent, { recursive: true });
+      if (rsyncAvailable) {
+        const r = run(
+          "rsync",
+          ["-a", "--exclude=node_modules/", "--exclude=.git/", srcAbs, destParent + "/"],
+          { env },
+        );
+        if (r.status !== 0) cpA(srcAbs, destParent);
+      } else {
+        cpA(srcAbs, destParent);
+      }
+    }
+    out(
+      `    snapshot complete (restore any file: cp "${backupDir}/<relpath>" "${hqRoot}/<relpath>")\n`,
+    );
+  }
+
+  // --- Walk + classify ---
+  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`);
+    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 };
+  }
+
+  // --- 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");
+  const overlayProtect: string[] = [];
+  if (fs.statSync(unchangedList).size > 0) {
+    overlayProtect.push(`--exclude-from=${unchangedList}`);
+  }
+  const overlay = run(
+    "rsync",
+    ["-ai", ...overlayProtect, ...rsyncExcludes, srcDir + "/", hqRoot + "/"],
+    { 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 sync-journal baseline for re-laid files ---
+  // The overlay rewrote scaffold files from upstream, but their personal-vault
+  // sync-journal entries still carry the PRE-rescue hash. The next sync would
+  // then read localHash != journal.hash ("local changed") and — when the vault
+  // also moved — mint a false `.conflict-*` mirror (the root cause of the
+  // conflict-file litter). Re-stamp the baseline to the freshly laid-down
+  // content so `localChanged` is false: the common single-machine case
+  // converges silently, and a genuinely-divergent vault degrades to a clean
+  // pull instead of a conflict mirror.
+  //
+  // Scoped STRICTLY to the paths rsync reported transferring (`-i` itemize) —
+  // never a blanket journal rewrite — so a user's unsynced pending edit (which
+  // the walk already rescued to personal/ rather than overlaying) is never
+  // silently marked as synced. Best-effort: a reconcile failure must never
+  // fail the rescue.
+  try {
+    const relaid: string[] = [];
+    for (const line of overlay.stdout.split("\n")) {
+      // itemize line: 11-char change code, space, path. 2nd col `f` = file.
+      const m = /^[<>ch.]f\S{9} (.+)$/.exec(line);
+      if (m) relaid.push(m[1]);
+    }
+    if (relaid.length > 0) {
+      const journal = readJournal(PERSONAL_VAULT_JOURNAL_SLUG);
+      let restamped = 0;
+      for (const rel of relaid) {
+        const prev = journal.files[rel];
+        if (!prev) continue; // only re-stamp paths already in the synced baseline
+        const abs = path.join(hqRoot, rel);
+        let st: fs.Stats;
+        try {
+          st = fs.lstatSync(abs);
+        } catch {
+          continue;
+        }
+        if (st.isSymbolicLink() || !st.isFile()) continue;
+        updateEntry(
+          journal,
+          rel,
+          hashFile(abs),
+          st.size,
+          prev.direction,
+          prev.remoteEtag,
+          st.mtimeMs,
+        );
+        restamped++;
+      }
+      if (restamped > 0) {
+        writeJournal(PERSONAL_VAULT_JOURNAL_SLUG, journal);
+        out(
+          `==> Reconciled sync-journal baseline for ${restamped} re-laid file(s)\n`,
+        );
+      }
+    }
+  } catch (e) {
+    out(
+      `    (sync-journal reconcile skipped: ${
+        e instanceof Error ? e.message : String(e)
+      })\n`,
+    );
+  }
+
+  // --- Stamp sync-point provenance into core/core.yaml ---
+  if (cfg.narrowPaths.length === 0 && isFileFollow(coreYaml)) {
+    const nowUtc = utcStamp(new Date(), "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");
+    }
+  }
+
+  // --- 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 wipe set exactly as it was before the update.");
+    lines.push("Restore a single file:");
+    lines.push(`  cp "${backupDir}/<relpath>" "${hqRoot}/<relpath>"`);
+    lines.push("Restore everything (overwrites current scaffold — use with care):");
+    lines.push(`  rsync -a "${backupDir}/" "${hqRoot}/"`);
+    lines.push("", `Auto-pruned after ${cfg.backupRetentionDays} days (HQ_BACKUP_RETENTION_DAYS).`);
+    try {
+      fs.writeFileSync(path.join(backupDir, "RECOVERY.md"), lines.join("\n") + "\n");
+    } catch {
+      /* best-effort, matches `|| true` */
+    }
+    out("\n");
+    out(`==> Pre-update snapshot + recovery manifest: ${backupDir}\n`);
+    pruneOldBackups(cfg, out);
+  }
+
+  out("\n");
+  out(`==> Done. Source: ${cfg.sourceRepo}@${cfg.ref} (${srcSha})\n`);
+  out("    User-edited files were rescued under personal/ (see scan output above).\n");
+  out("    User-only files (created by you, unknown to upstream) were left untouched.\n");
+  if (cfg.doBackup && backupDir) {
+    out(`    A full pre-update snapshot is at ${backupDir} (RECOVERY.md explains restore).\n`);
+  }
+
+  return { status: 0 };
+}
+
+interface WalkCtx {
+  cfg: Config;
+  env: NodeJS.ProcessEnv;
+  hqRoot: string;
+  srcDir: string;
+  historyFloor: string;
+  baselineMode: "history_floor" | "head_compare";
+  runTs: string;
+  srcSha: string;
+  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;
+}
+
+// --- 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"
+  );
+}
+
+function isMasterSyncSymlink(localPath: string): boolean {
+  const st = lstatOrNull(localPath);
+  if (!st || !st.isSymbolicLink()) return false;
+  let tgt = "";
+  try {
+    tgt = fs.readlinkSync(localPath);
+  } catch {
+    return false;
+  }
+  return tgt.includes("/personal/") || tgt.startsWith("personal/");
+}
+
+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;
+}
+
+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 + act on one file (the per-file workhorse) ---
+function processOne(ctx: WalkCtx, rel: string): void {
+  const { cfg } = ctx;
+  const localPath = path.join(ctx.hqRoot, rel);
+  const srcPath = path.join(ctx.srcDir, rel);
+
+  if (isUnderPreserve(cfg, rel)) return;
+
+  // Conflict-resolution artifacts (`<name>.conflict-<ts>-<peer>.<ext>`).
+  const base = rel.includes("/") ? rel.slice(rel.lastIndexOf("/") + 1) : rel;
+  if (/\.conflict-/.test(base)) {
+    if (cfg.dryRun) {
+      ctx.out(`    drop conflict artifact: ${rel}\n`);
+    } else {
+      fs.rmSync(localPath, { force: true });
+    }
+    return;
+  }
+
+  // Script-managed files: core/core.yaml + legacy core.yaml.
+  if (rel === "core/core.yaml" || rel === "core.yaml") {
+    if (cfg.dryRun) {
+      ctx.out(`    skip script-managed (rewrites at stamp step): ${rel}\n`);
+    } else {
+      fs.rmSync(localPath, { force: true });
+    }
+    return;
+  }
+
+  // Symlinks (mid-tree).
+  const lst = lstatOrNull(localPath);
+  if (lst && lst.isSymbolicLink()) {
+    if (isMasterSyncSymlink(localPath)) {
+      ctx.counts.symlinkDropped += 1;
+      if (cfg.dryRun) {
+        let tgt = "";
+        try {
+          tgt = fs.readlinkSync(localPath);
+        } catch {
+          /* ignore */
+        }
+        ctx.out(`    drop reindex symlink: ${rel}  ->  ${tgt}\n`);
+      } else {
+        fs.rmSync(localPath, { force: true });
+        ctx.appendLog(`symlink-dropped\t${rel}\t(reindex regenerable)\n`);
+      }
+    }
+    return;
+  }
+
+  // Is path in upstream HEAD?
+  const inHead = existsFollow(srcPath) ? 1 : 0;
+
+  // Is path in last-sync floor?
+  let inFloor = 0;
+  if (ctx.baselineMode === "history_floor") {
+    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) {
+    ctx.counts.userOnly += 1;
+    if (cfg.dryRun) ctx.out(`    user-only (leave in place): ${rel}\n`);
+    return;
+  }
+
+  // Path is/was in upstream. Determine if user edited it.
+  let userEdited = 0;
+  if (ctx.baselineMode === "history_floor" && inFloor === 1) {
+    const localSha = run("git", ["hash-object", localPath], { env: ctx.env }).stdout.trim();
+    const baselineSha = run("git", ["rev-parse", `${ctx.historyFloor}:${rel}`], {
+      cwd: ctx.srcDir,
+      env: ctx.env,
+    }).stdout.trim();
+    if (!localSha || !baselineSha || localSha !== baselineSha) 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)) {
+    ctx.counts.cloudSymlinkReconciled += 1;
+    if (cfg.dryRun) {
+      ctx.out(
+        `    cloud-symlink reconciled (unchanged): ${rel}  (hq-symlink: marker matches upstream target)\n`,
+      );
+    } else {
+      fs.rmSync(localPath, { force: true });
+      ctx.appendLog(
+        `cloud-symlink-reconciled\t${rel}\t(hq-symlink: marker matches upstream target; overlay re-lays symlink)\n`,
+      );
+    }
+    return;
+  }
+
+  // Convergence guard: drifted from floor but identical to upstream HEAD.
+  if (userEdited === 1 && inHead === 1 && bytesEqual(localPath, srcPath)) {
+    ctx.counts.driftReconciled += 1;
+    if (cfg.dryRun) {
+      ctx.out(`    drift reconciled (identical to upstream HEAD; no rescue): ${rel}\n`);
+    } else {
+      fs.rmSync(localPath, { force: true });
+      ctx.appendLog(
+        `drift-reconciled\t${rel}\t(identical to upstream HEAD; drifted from floor only — no personal/ copy)\n`,
+      );
+    }
+    return;
+  }
+
+  if (userEdited === 1) {
+    if (cfg.dryRun) {
+      if (rel === ".claude/CLAUDE.md") {
+        ctx.out(`    user-edit (diff-append): ${rel}  ->  personal/CLAUDE.md\n`);
+        ctx.counts.userEdit += 1;
+      } else if (isOverwriteSafe(rel)) {
+        ctx.out(`    user-edit (overwrite-safe): ${rel}  ->  upstream wins (no copy preserved)\n`);
+        ctx.counts.userOverwrite += 1;
+      } else if (isConflictClass(rel)) {
+        ctx.out(`    user-edit (conflict): ${rel}  ->  .hq-conflicts/rescue-${ctx.runTs}/${rel}\n`);
+        ctx.counts.userConflict += 1;
+      } else {
+        ctx.out(`    user-edit (rescue): ${rel}  ->  ${mapRescueTarget(rel)}\n`);
+        ctx.counts.userEdit += 1;
+      }
+    } else {
+      if (rel === ".claude/CLAUDE.md") {
+        rescueOne(ctx, rel);
+      } else if (isOverwriteSafe(rel)) {
+        fs.rmSync(localPath, { force: true });
+        ctx.counts.userOverwrite += 1;
+        ctx.appendLog(`overwritten\t${rel}\t(overwrite-safe; upstream wins, no copy preserved)\n`);
+      } else if (isConflictClass(rel)) {
+        conflictOne(ctx, rel);
+      } else {
+        rescueOne(ctx, rel);
+      }
+    }
+  } else {
+    // user_edited=0: matches floor baseline. Split on byte-equality to HEAD.
+    ctx.counts.unchanged += 1;
+    if (bytesEqual(localPath, path.join(ctx.srcDir, rel))) {
+      if (cfg.dryRun) {
+        ctx.out(`    unchanged (preserved in place): ${rel}\n`);
+      } else {
+        fs.appendFileSync(ctx.unchangedList, `/${rel}\n`);
+        ctx.appendLog(`unchanged\t${rel}\t(identical to upstream; left in place, mtime preserved)\n`);
+      }
+    } else {
+      if (cfg.dryRun) {
+        ctx.out(`    unchanged (delete + replace): ${rel}\n`);
+      } else {
+        fs.rmSync(localPath, { force: true });
+        ctx.appendLog(`deleted\t${rel}\t(unchanged vs baseline; re-laid by overlay if still upstream)\n`);
+      }
+    }
+  }
+}
+
+// --- walk a wipe-set root ---
+function walkAndProcess(ctx: WalkCtx, rootRel: string): void {
+  const { cfg } = ctx;
+  const rootAbs = path.join(ctx.hqRoot, rootRel);
+  if (!lexists(rootAbs)) return;
+
+  // companies/_template — wholesale-replace.
+  if (rootRel === "companies/_template") {
+    if (cfg.dryRun) {
+      ctx.out("    wholesale-replace: companies/_template (template carve-out)\n");
+    } else {
+      fs.rmSync(path.join(ctx.hqRoot, "companies", "_template"), { recursive: true, force: true });
+    }
+    return;
+  }
+
+  const lst = lstatOrNull(rootAbs);
+
+  // Top-level symlink.
+  if (lst && lst.isSymbolicLink()) {
+    if (isMasterSyncSymlink(rootAbs)) {
+      ctx.counts.symlinkDropped += 1;
+      if (cfg.dryRun) {
+        let tgt = "";
+        try {
+          tgt = fs.readlinkSync(rootAbs);
+        } catch {
+          /* ignore */
+        }
+        ctx.out(`    drop reindex symlink: ${rootRel}  ->  ${tgt}\n`);
+      } else {
+        fs.rmSync(rootAbs, { force: true });
+        ctx.appendLog(`symlink-dropped\t${rootRel}\t(reindex regenerable)\n`);
+      }
+    }
+    return;
+  }
+
+  // Top-level regular file.
+  if (lst && lst.isFile()) {
+    processOne(ctx, rootRel);
+    return;
+  }
+
+  // Top-level directory: recursive walk, pruning node_modules + nested .git.
+  for (const rel of findFilesAndSymlinks(rootAbs, ctx.hqRoot)) {
+    processOne(ctx, rel);
+  }
+}
+
+/**
+ * Mirror of `find "$root" \( -type d \( -name node_modules -o -name .git \)
+ * -prune \) -o \( \( -type f -o -type l \) -print0 \)`: yield repo-relative
+ * paths of regular files and symlinks, pruning node_modules/.git dirs and not
+ * descending into directory symlinks (find -P default). Deterministic order.
+ */
+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()) {
+        if (ent.name === "node_modules" || ent.name === ".git") continue; // prune
+        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` */
+    }
+  }
+}
+
+// --- prune old pre-update-* snapshots past retention ---
+function pruneOldBackups(cfg: Config, out: (s: string) => void): void {
+  if (!isDir(cfg.backupRoot)) return;
+  if (!/^[0-9]+$/.test(cfg.backupRetentionDays)) return;
+  const days = Number(cfg.backupRetentionDays);
+  if (!(days > 0)) return;
+  // `find -mtime +N`: strictly older than (N+1)*24h by mtime.
+  const cutoffMs = Date.now() - (days + 1) * 24 * 60 * 60 * 1000;
+  let entries: string[] = [];
+  try {
+    entries = fs.readdirSync(cfg.backupRoot);
+  } catch {
+    return;
+  }
+  for (const name of entries) {
+    if (!name.startsWith("pre-update-")) continue;
+    const abs = path.join(cfg.backupRoot, name);
+    const st = lstatOrNull(abs);
+    if (!st || !st.isDirectory()) continue;
+    if (st.mtimeMs < cutoffMs) {
+      out(`    pruned old snapshot (> ${cfg.backupRetentionDays}d): ${name}\n`);
+      try {
+        fs.rmSync(abs, { recursive: true, force: true });
+      } catch {
+        /* best-effort */
+      }
+    }
+  }
+}
+
+// --- 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 */
+  }
+}
+
+/** 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$/, "");
+}