@indigoai-us/hq-cloud 5.47.2 → 5.48.0

package/scripts/replace-rescue.sh

@@ -0,0 +1,1400 @@
+#!/usr/bin/env bash
+# replace-rescue.sh
+#
+# Renamed from `replace-from-staging-rescue.sh` in v0.1.104 once the script
+# became channel-agnostic (`--source` + `--ref` drive both the @indigo
+# "Update to Staging" flow and the prod "Update to vX.Y.Z" flow). Old name
+# kept as a backup search path in `hq_core_staging::resolve_rescue_script`
+# so a stale resource dir mid-rebuild doesn't break dev. The persisted
+# `core/core.yaml` stamp key also got renamed (`replaced_from_staging` ->
+# `replaced_from_source`); reads honour both, writes use the new key and
+# `del` the old.
+#
+# Variant of replace-from-staging.sh (the original clobbering version,
+# kept upstream for non-HQ-Sync callers) that:
+#
+#   1. Does NOT require the destination to be a git repo. The `.git/` check is
+#      dropped and git status reporting at the end is replaced with a plain
+#      file-count summary. (git is still required to fetch the source repo.)
+#
+#   2. Rescues drifts instead of clobbering them. Before the wipe, every file
+#      in the wipe set that DIFFERS from staging (or exists only locally) is
+#      MOVED into `personal/` so it survives as a layered override.
+#
+# Drift detection — three-way classification (v0.1.104+):
+#
+#   For every regular file under each wipe-set top-level entry, the walk
+#   classifies it as one of:
+#
+#     A. USER-ONLY  — path not in upstream HEAD AND not in the last-sync
+#                     tree (per `replaced_from_source.last_sync_sha`). The
+#                     user created this file and upstream has no opinion
+#                     about it. ACTION: leave in place. The rsync overlay
+#                     is run without --delete so user-only files survive.
+#
+#     B. UNCHANGED  — local file is byte-identical to the version at the
+#                     last-sync SHA (or, when no stamp is available, to
+#                     the current upstream HEAD). User didn't touch it
+#                     since last sync. ACTION: delete locally; the overlay
+#                     writes the fresh upstream version on top.
+#
+#     C. USER-EDIT  — local file differs from the last-sync version (or
+#                     from HEAD in head-compare fallback mode). The user
+#                     authored a change after the last sync. ACTION:
+#                     rescue per the mapping below.
+#
+# Rescue mapping for USER-EDIT files:
+#
+#   a. `.claude/CLAUDE.md`  ->  DIFF-APPEND additions to `personal/CLAUDE.md`
+#                              (whole-file move was too disruptive — most
+#                              users only add sections, so we extract the
+#                              lines present locally but not in baseline
+#                              and append them under a timestamped marker.)
+#   b. `.claude/<rest>`     ->  `personal/<rest>`  (mkdir -p personal/<top-of-rest>/)
+#   c. `core/<rest>`        ->  `personal/<rest>`  (mkdir -p personal/<top-of-rest>/)
+#   d. `<rest>` (root file) ->  `personal/<rest>`  (mkdir -p personal/<top-of-rest>/)
+#
+# Conflict-class USER-EDITs (bypass the personal/ rescue and quarantine in
+# `.hq-conflicts/rescue-<RUN_TS>/<rel>` instead — see is_conflict_class):
+#
+#   - `.agents/`   — agent runtime state, not a portable overlay
+#   - `.codex/`    — codex per-machine cache/state
+#   - `.obsidian/` — vault UI state (workspace.json, graph.json)
+#   - `MIGRATION.md` (root) — always re-shipped by overlay; a divergent local
+#                              copy means an upgrade snag worth reviewing,
+#                              not a customization to preserve in personal/.
+#
+# Overwrite-safe USER-EDITs (silently overwritten by the overlay — no
+# rescue, no conflict, no copy preserved — see is_overwrite_safe):
+#
+#   - `AGENTS.md` (root)
+#   - `USER-GUIDE.md` (root, pre-v15 layout)
+#   - `core/docs/hq/USER-GUIDE.md`
+#   - `core/policies/_digest.md` (rebuilt by `build-policy-digest.sh`)
+#
+#   These paths are either always re-shipped by upstream or auto-regenerated
+#   by a script on the next Stop hook. A drifted local copy is just stale,
+#   not a customization — saving it under personal/ or .hq-conflicts/ just
+#   accumulates noise.
+#
+# Symlinks generated by `master-sync.sh` (targets resolving into
+# `personal/`) are DELETED during the walk rather than preserved. They
+# rebuild deterministically on the next Stop-hook pass — keeping the old
+# link risks shadowing the upstream file the overlay writes at the same
+# path.
+#
+# --cloud-update flag (off by default): the rescue walk recognizes files
+# whose content is `hq-symlink:<target>` as the cloud-flattened
+# serialization of an upstream symlink. hq-sync stores symlinks in S3
+# as small text files with this magic prefix because S3 has no symlink
+# semantics; a vault snapshot pulled via `aws s3 sync` has these in
+# place of symlinks. When the local marker's target matches the upstream
+# symlink's target, the file is reclassified UNCHANGED (deleted; the
+# overlay re-lays the real symlink). Targets that disagree fall through
+# to normal user-edit routing. ONLY enable when --hq-root points at a
+# vault mirror, not a real local HQ tree.
+#
+# If the rescue destination already exists, the moved file is suffixed
+# with `.drift-<unix-ts>` so we never silently overwrite a prior override.
+#
+# Two operating modes (same as the parent script):
+#
+#   - Default ("preserve-list"): wipes every top-level entry except a hardcoded
+#     preserve set (`.git`, `companies/` except `companies/_template/`,
+#     `personal/`, `workspace/`, `repos/`, `.github/`, `.leak-scan/`,
+#     `.hq-sync-journal.json`, `.hq/`, `.hq-conflicts/`),
+#     plus any paths passed via --preserve.
+#
+#     `repos/` is always preserved: it holds user-owned git checkouts
+#     (`repos/public/` + `repos/private/`) whose `.git/` directories would
+#     shatter under a file-by-file rescue. hq-core never ships a `repos/`
+#     tree, so the overlay can't restore it — the only safe handling is
+#     to leave it alone entirely.
+#
+#   - `--paths`: wipes ONLY the explicit comma-separated list of top-level
+#     entries and overlays only those.
+#
+# `--preserve-subpath <rel>` (repeatable) carves out individual files INSIDE
+# the wipe set, copied to a mktemp shuttle pre-wipe and restored post-overlay.
+#
+# Baseline mode — what counts as "user edit":
+#
+#   * `history_floor` (default, used when `replaced_from_source.last_sync_sha`
+#     is stamped AND reachable in the clone): a file is a USER-EDIT iff its
+#     `git hash-object` SHA differs from the blob SHA at that path at the
+#     stamped commit. One `git rev-parse <floor>:<rel>` per file — cheap.
+#     This is strictly more accurate than the v0.1.103 history-walk index:
+#     the floor is the exact point the user diverged from, so no spurious
+#     "matches some past staging blob" coincidences mask real edits.
+#
+#   * `head_compare` (fallback when no stamp is set OR `--no-history-check`
+#     is passed): a file is a USER-EDIT iff `cmp -s` against the upstream
+#     HEAD copy disagrees. Loses the ability to distinguish
+#     "upstream-removed since last sync" from "user-added new file" — both
+#     look like "in local, not in HEAD". Safe default for first-ever runs.
+#
+# Cost: full-history clone with `--filter=blob:none` (~15 MB for
+# hq-core-staging vs. ~5 MB shallow). Per-file blob SHA comparisons are
+# microseconds each. The big v0.1.103 perf footgun (391k-file node_modules
+# walks) is dead now that `repos/` is preserved and node_modules + nested
+# .git are pruned from the walk.
+#
+# Sync-point provenance — `core/core.yaml`:
+#
+#   On a successful default-mode (full-replace) run, the script records the
+#   source commit it synced to under `core/core.yaml`'s
+#   `replaced_from_source:` key (source / ref / last_sync_sha / last_sync_at).
+#   On the NEXT run, this is read before the clone and — if the source repo
+#   matches and the SHA is reachable in the new clone — used as the
+#   **history floor**: the index walks `git log <last_sync_sha>` instead of
+#   `git log --all`, scoping it to "blobs the source knew about at our last
+#   sync point". A local file whose content matches one of those blobs is
+#   provably lag (user had it via prior sync). A local file whose content
+#   only matches blobs from AFTER the last sync — i.e. blobs the user
+#   couldn't have copied from a sync — is treated as user-authored even if
+#   it happens to coincide with a recent source commit.
+#
+#   Backwards compat: pre-v0.1.104 runs stamped under the old key
+#   `replaced_from_staging`. The read block tries the new key first and
+#   falls back to the old one so a user's history-floor benefit survives
+#   the rename. The write block stamps the new key AND deletes the old
+#   one in the same yq pass so post-migration only one stamp exists.
+#
+# Usage:
+#   replace-rescue.sh [--ref REF] [--source OWNER/REPO]
+#                     [--paths PATH1,PATH2,...]
+#                     [--preserve PATH]...
+#                     [--preserve-subpath REL]...
+#                     [--hq-root DIR]
+#                     [--no-history-check]
+#                     [--no-backup] [--backup-dir DIR]
+#                     [--cloud-update]
+#                     [--dry-run] [--yes]
+#
+# Defaults:
+#   --ref     main
+#   --source  indigoai-us/hq-core-staging
+#   --hq-root <script>/../../..    (assumes script lives at personal/skills/<skill>/)
+#
+# Requires: git (for source clone + hash-object), rsync, cmp, awk, grep, sort.
+
+set -euo pipefail
+
+REF="main"
+SOURCE_REPO="indigoai-us/hq-core-staging"
+DRY_RUN=0
+ASSUME_YES=0
+# Cloud-update mode (--cloud-update). When ON, the rescue walk recognizes
+# files whose content is `hq-symlink:<target>` as the cloud-flattened
+# serialization of an upstream symlink — hq-sync stores symlinks in S3
+# as small text files with this magic prefix because S3 has no symlink
+# semantics. If upstream at this path is a symlink whose target matches
+# the local file's payload, the file is reclassified as UNCHANGED (just
+# deleted; the overlay re-lays the real symlink). Mismatches fall through
+# to normal user-edit routing. OFF by default for safety — only meaningful
+# when --hq-root points at a vault snapshot (e.g. an `aws s3 sync` mirror),
+# not a real local HQ tree where symlinks are real.
+CLOUD_UPDATE=0
+EXTRA_PRESERVE=()
+PRESERVE_SUBPATHS=()
+NARROW_PATHS_CSV=""
+HQ_ROOT_OVERRIDE=""
+HISTORY_CHECK=1
+# Caller-supplied history-floor SHA. When set (40-char hex), overrides
+# the value read from `core/core.yaml`'s `replaced_from_source.last_sync_sha`
+# stamp. Use case: a user whose `core/core.yaml` is unstamped (pre-rescue
+# install — e.g. existing v14.0.0 → v14.2.1 prod upgrade) should still
+# get `history_floor` mode rather than the `head_compare` fallback, which
+# misclassifies every upstream change since their installed version as a
+# USER-EDIT and shoves it into `personal/`. The hq-sync caller resolves
+# `v<installed-hqVersion>` against `--source` via the GitHub API and
+# passes it here so the rescue baselines against the user's actual
+# installed tree, not "any blob in main's history."
+FLOOR_SHA_OVERRIDE=""
+
+# Pre-operation safety snapshot (v0.4.1+). The rescue walk MOVES USER-EDIT
+# files into personal/ and DELETES UNCHANGED ones before the overlay. A
+# misclassification (head_compare fallback on an unstamped install, a binary
+# USER-EDIT, an interrupted run) would otherwise be unrecoverable — there was
+# previously NO backup taken by the destructive code itself, only a manual
+# step documented in MIGRATION.md that users skipped. We now snapshot the
+# wipe set to ~/.hq/backups/pre-update-<ts>/ + write a RECOVERY.md manifest
+# BEFORE any destructive op. Default ON; opt out with --no-backup or
+# HQ_RESCUE_NO_BACKUP=1. Override location with --backup-dir / HQ_BACKUP_DIR.
+# Old snapshots older than HQ_BACKUP_RETENTION_DAYS (default 7) are pruned
+# after a successful run — this is the auto-cleanup MIGRATION.md promised.
+DO_BACKUP=1
+[ "${HQ_RESCUE_NO_BACKUP:-0}" = "1" ] && DO_BACKUP=0
+BACKUP_ROOT="${HQ_BACKUP_DIR:-$HOME/.hq/backups}"
+BACKUP_RETENTION_DAYS="${HQ_BACKUP_RETENTION_DAYS:-7}"
+BACKUP_DIR=""   # resolved at snapshot time (BACKUP_ROOT/pre-update-<RUN_TS>)
+
+# Paths that are ALWAYS preserved across the wipe+overlay, regardless of
+# mode or user flags. Each entry is shuttled to a mktemp area pre-wipe and
+# restored post-overlay (same mechanism as --preserve-subpath), AND skipped
+# by drift detection so the rescue scan never touches them.
+#
+# Why core/packages and packages: both hold user-curated packs (hq-pack-*)
+# resolved through the npm/hq-cli install path; staging may also ship under
+# `core/packages` with different content. Without this carve-out a
+# full-replace would clobber the local pack tree.
+# Why .claude/state: runtime session state — `.claude/state/active-session-*`
+# changes every session; shuttling preserves it across the overlay.
+# Why core/workers/registry.yaml: generated locally by
+# `core/scripts/generate-workers-registry.sh` from the union of core +
+# personal + installed-pack workers. Its content is a function of the
+# user's install state, not the upstream tree, so an overlay that
+# replaces it produces a registry that doesn't match what's on disk
+# (and `master-sync` regenerates it on the next Stop hook anyway).
+# Shuttling preserves the up-to-date local version across the rescue.
+# Why .claude/settings.local.json: per-user local settings (denied paths,
+# env vars, allow-listed tool patterns) authored by the user via the CLI
+# or hand-edits. Never shipped from upstream — it has no upstream version
+# at all. Subjecting it to drift detection would just rescue it into
+# personal/ every run, which is busywork. Shuttle preserves the local
+# version across the overlay so the rescue is a no-op for this file.
+CARVE_OUT_PATHS=( "core/packages" "packages" ".claude/state" "core/workers/registry.yaml" ".claude/settings.local.json" )
+
+usage() {
+  sed -n '2,55p' "$0"
+  exit 1
+}
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --ref) REF="$2"; shift 2 ;;
+    --source) SOURCE_REPO="$2"; shift 2 ;;
+    --preserve) EXTRA_PRESERVE+=("$2"); shift 2 ;;
+    --preserve-subpath) PRESERVE_SUBPATHS+=("$2"); shift 2 ;;
+    --paths) NARROW_PATHS_CSV="$2"; shift 2 ;;
+    --hq-root) HQ_ROOT_OVERRIDE="$2"; shift 2 ;;
+    --no-history-check) HISTORY_CHECK=0; shift ;;
+    --floor-sha)
+      FLOOR_SHA_OVERRIDE="$2"
+      # Fail fast on obviously bad input (the rescue is destructive — better
+      # to abort here than silently fall through to head_compare halfway in).
+      if ! printf '%s' "$FLOOR_SHA_OVERRIDE" | grep -qE '^[0-9a-f]{40}$'; then
+        echo "error: --floor-sha must be a 40-char lowercase hex SHA, got: $FLOOR_SHA_OVERRIDE" >&2
+        exit 2
+      fi
+      shift 2 ;;
+    --no-backup) DO_BACKUP=0; shift ;;
+    --backup-dir) BACKUP_ROOT="$2"; shift 2 ;;
+    --dry-run) DRY_RUN=1; shift ;;
+    --cloud-update) CLOUD_UPDATE=1; shift ;;
+    --yes|-y) ASSUME_YES=1; shift ;;
+    -h|--help) usage ;;
+    *) echo "unknown arg: $1" >&2; usage ;;
+  esac
+done
+
+for p in "${EXTRA_PRESERVE[@]+"${EXTRA_PRESERVE[@]}"}"; do
+  case "$p" in
+    .git|companies|personal|workspace|repos|.github|.leak-scan|.hq-sync-journal.json|.hq|.hq-conflicts|.git/|companies/|personal/|workspace/|repos/|.github/|.leak-scan/|.hq/|.hq-conflicts/)
+      echo "error: --preserve $p is redundant ('$p' is always preserved). Remove the flag." >&2
+      exit 2
+      ;;
+  esac
+done
+
+for sp in "${PRESERVE_SUBPATHS[@]+"${PRESERVE_SUBPATHS[@]}"}"; do
+  case "$sp" in
+    /*|*..*)
+      echo "error: --preserve-subpath $sp must be a relative path with no '..' segments." >&2
+      exit 2
+      ;;
+  esac
+done
+
+# Append the always-preserved carve-outs to PRESERVE_SUBPATHS so the same
+# backup/restore code path handles them. Dedup against any user-supplied
+# entries (defensive — user may also have passed them explicitly).
+for cp in "${CARVE_OUT_PATHS[@]}"; do
+  already=0
+  for sp in "${PRESERVE_SUBPATHS[@]+"${PRESERVE_SUBPATHS[@]}"}"; do
+    if [ "$sp" = "$cp" ]; then already=1; break; fi
+  done
+  [ "$already" = "1" ] || PRESERVE_SUBPATHS+=("$cp")
+done
+
+NARROW_PATHS=()
+if [ -n "$NARROW_PATHS_CSV" ]; then
+  IFS=',' read -r -a _NARROW_RAW <<< "$NARROW_PATHS_CSV"
+  for raw in "${_NARROW_RAW[@]}"; do
+    name="${raw#"${raw%%[![:space:]]*}"}"
+    name="${name%"${name##*[![:space:]]}"}"
+    if [ -z "$name" ]; then continue; fi
+    case "$name" in
+      */*|..|.)
+        echo "error: --paths entry '$name' must be a single top-level name (no slashes, no '.' or '..')." >&2
+        exit 2
+        ;;
+    esac
+    NARROW_PATHS+=("$name")
+  done
+  if [ "${#NARROW_PATHS[@]}" -eq 0 ]; then
+    echo "error: --paths was passed but resolved to an empty list." >&2
+    exit 2
+  fi
+  if [ "${#EXTRA_PRESERVE[@]}" -ne 0 ]; then
+    echo "error: --paths and --preserve are mutually exclusive. Use --preserve-subpath for sub-paths inside the listed top-level entries." >&2
+    exit 2
+  fi
+fi
+
+# --- Resolve HQ root (no .git requirement) -----------------------------------
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+if [ -n "$HQ_ROOT_OVERRIDE" ]; then
+  HQ_ROOT="$(cd "$HQ_ROOT_OVERRIDE" && pwd)"
+else
+  HQ_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
+fi
+
+# Sanity: look for `companies/` and `personal/` (not `.git/`). Drift rescue
+# needs personal/ to exist as the override target.
+if [ ! -d "$HQ_ROOT/companies" ] || [ ! -d "$HQ_ROOT/personal" ]; then
+  echo "error: $HQ_ROOT does not look like an HQ root (missing companies/ or personal/). Aborting." >&2
+  echo "       pass --hq-root <dir> if the script is not at personal/skills/<skill>/." >&2
+  exit 3
+fi
+
+# Per-run timestamp marker. Used in the CLAUDE.md diff-append header and
+# as the suffix on collision-renamed rescue destinations. The v0.1.103
+# `.hq-conflicts/rescue-<ts>/` fallback bucket is gone — every rescue
+# now lands under `personal/`, mkdir-ing the parent dir if missing.
+RUN_TS="$(date -u +%Y-%m-%dT%H-%M-%SZ)"
+
+# --- Read prior sync-point metadata (must happen BEFORE the wipe) -----------
+# If the user has run this script before in default mode, core/core.yaml
+# carries the source SHA we last synced to. We use that SHA later (after
+# the clone) as the history-floor: scope the index walk to commits reachable
+# from <last_sync_sha> instead of all branches. Only honored when the
+# previously-recorded source matches the current --source.
+#
+# Try the new key (`replaced_from_source`) first, fall back to the old
+# (`replaced_from_staging`) so a user whose last sync ran on v0.1.103-or-
+# earlier still gets the history-floor benefit on the next run. The yq
+# `//` alternative operator returns the left side when non-null, else the
+# right; the trailing `// ""` collapses null to empty string so the bash
+# checks below stay simple.
+PREV_SYNC_SHA=""
+PREV_SYNC_SOURCE=""
+PREV_SYNC_REF=""
+PREV_SYNC_AT=""
+if [ -f "$HQ_ROOT/core/core.yaml" ] && command -v yq >/dev/null 2>&1; then
+  PREV_SYNC_SHA="$(yq -r '.replaced_from_source.last_sync_sha // .replaced_from_staging.last_sync_sha // ""' "$HQ_ROOT/core/core.yaml" 2>/dev/null || true)"
+  PREV_SYNC_SOURCE="$(yq -r '.replaced_from_source.source // .replaced_from_staging.source // ""' "$HQ_ROOT/core/core.yaml" 2>/dev/null || true)"
+  PREV_SYNC_REF="$(yq -r '.replaced_from_source.ref // .replaced_from_staging.ref // ""' "$HQ_ROOT/core/core.yaml" 2>/dev/null || true)"
+  PREV_SYNC_AT="$(yq -r '.replaced_from_source.last_sync_at // .replaced_from_staging.last_sync_at // ""' "$HQ_ROOT/core/core.yaml" 2>/dev/null || true)"
+fi
+
+# Caller override (--floor-sha) wins when the on-disk stamp is empty.
+# Set PREV_SYNC_SOURCE to the current --source so the source-match check
+# below ("only honor the floor when the previously-recorded source
+# matches the current --source") trivially passes — the caller has
+# already verified the SHA resolves to a commit in `--source`.
+#
+# We intentionally do NOT overwrite a non-empty stamp: a real prior-sync
+# SHA is strictly more accurate than a caller's "best guess" floor
+# derived from the installed `hqVersion` tag (the user may have run a
+# rescue since the version stamp was written, advancing the floor).
+if [ -z "$PREV_SYNC_SHA" ] && [ -n "$FLOOR_SHA_OVERRIDE" ]; then
+  PREV_SYNC_SHA="$FLOOR_SHA_OVERRIDE"
+  PREV_SYNC_SOURCE="$SOURCE_REPO"
+  PREV_SYNC_REF="(caller-supplied floor)"
+  PREV_SYNC_AT="(unstamped install)"
+fi
+
+echo "==> HQ root:    $HQ_ROOT"
+echo "==> Source:     https://github.com/$SOURCE_REPO @ $REF"
+if [ -n "$PREV_SYNC_SHA" ]; then
+  if [ "$PREV_SYNC_SOURCE" = "$SOURCE_REPO" ]; then
+    echo "==> Prior sync: $PREV_SYNC_SHA from $PREV_SYNC_SOURCE@$PREV_SYNC_REF ($PREV_SYNC_AT) — will use as history floor"
+  else
+    echo "==> Prior sync: $PREV_SYNC_SHA from $PREV_SYNC_SOURCE (different source — ignoring as floor)"
+  fi
+fi
+if [ "${#NARROW_PATHS[@]}" -ne 0 ]; then
+  echo "==> Mode:       narrow (--paths)"
+  echo "==> Wipe set:   ${NARROW_PATHS[*]}"
+else
+  echo "==> Mode:       preserve-list (default)"
+  echo "==> Preserved:  .git, companies (except companies/_template), personal, workspace, repos, .github, .leak-scan, .hq-sync-journal.json, .hq, .hq-conflicts${EXTRA_PRESERVE[*]+, ${EXTRA_PRESERVE[*]}}"
+fi
+if [ "${#PRESERVE_SUBPATHS[@]}" -ne 0 ]; then
+  echo "==> Preserved subpaths (backed up + restored across the overlay):"
+  for sp in "${PRESERVE_SUBPATHS[@]}"; do
+    # Mark the always-on carve-outs so it's obvious they're not from --preserve-subpath.
+    is_carve=0
+    for cp in "${CARVE_OUT_PATHS[@]}"; do
+      if [ "$cp" = "$sp" ]; then is_carve=1; break; fi
+    done
+    if [ "$is_carve" = "1" ]; then
+      echo "    - $sp  (always-on carve-out)"
+    else
+      echo "    - $sp"
+    fi
+  done
+fi
+echo "==> 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 master-sync symlinks (regenerated by master-sync.sh)"
+if [ "$CLOUD_UPDATE" = "1" ]; then
+  echo "==> Cloud-update mode: ON  (recognize \`hq-symlink:<target>\` flat files as upstream-symlink-equivalent — reconciled as UNCHANGED)"
+fi
+if [ "$HISTORY_CHECK" = "1" ]; then
+  echo "==> History gate: ON (skip drift if local matches any past staging blob at that path)"
+else
+  echo "==> History gate: OFF (--no-history-check; every diff rescued)"
+fi
+if [ "$DO_BACKUP" = "1" ]; then
+  echo "==> Safety backup: ON  -> $BACKUP_ROOT/pre-update-$RUN_TS (retention ${BACKUP_RETENTION_DAYS}d)"
+else
+  echo "==> Safety backup: OFF (--no-backup / HQ_RESCUE_NO_BACKUP=1)"
+fi
+[ "$DRY_RUN" = "1" ] && echo "==> DRY RUN     (no destructive operations will run)"
+
+if [ "$ASSUME_YES" != "1" ] && [ "$DRY_RUN" != "1" ]; then
+  _backup_line="  * NO pre-op backup (--no-backup),"
+  [ "$DO_BACKUP" = "1" ] && _backup_line="  * snapshot the wipe set to $BACKUP_ROOT/pre-update-$RUN_TS first,"
+  _cloud_line=""
+  if [ "$CLOUD_UPDATE" = "1" ]; then
+    _cloud_line="\n  * reconcile \`hq-symlink:<target>\` flat files against upstream symlinks (cloud-update mode),"
+  fi
+  printf "\nThis will:\n%s\n  * rescue user-edited files (vs the last sync) into personal/,\n  * route user-edited .agents/.codex/.obsidian/MIGRATION.md into .hq-conflicts/rescue-%s/ for review,\n  * silently overwrite AGENTS.md / USER-GUIDE.md / core/policies/_digest.md (regenerable from upstream or master-sync — no copy preserved),%b\n  * drop master-sync-generated symlinks (regenerated by master-sync.sh on next Stop hook),\n  * leave user-only files (not in upstream) untouched,\n  * delete upstream files unchanged since last sync, then unpack %s@%s on top.\nType 'yes' to proceed: " "$_backup_line" "$RUN_TS" "$_cloud_line" "$SOURCE_REPO" "$REF"
+  read -r confirm
+  [ "$confirm" = "yes" ] || { echo "Aborted."; exit 4; }
+fi
+
+TMPDIR="$(mktemp -d -t hq-replace-rescue-XXXXXX)"
+trap 'rm -rf "$TMPDIR"' EXIT
+
+# Append-only record of every file the walk MOVES (rescue) or DELETES
+# (unchanged). Folded into the snapshot's RECOVERY.md manifest after the run
+# so a user can see exactly what changed and restore any single file.
+RESCUE_LOG="$TMPDIR/rescue-actions.log"
+: > "$RESCUE_LOG"
+
+# Build the clone URL. If GH_TOKEN is set in the environment, inject it as
+# the basic-auth user so `git clone` can access private staging repos
+# without an interactive credential prompt. This is the form the GitHub
+# docs recommend for token-based git over HTTPS:
+#   https://x-access-token:<token>@github.com/<owner>/<repo>.git
+# The hq-sync Tauri caller resolves GH_TOKEN via `gh auth token` (same
+# path the existing drift-classifier uses) before spawning this script.
+if [ -n "${GH_TOKEN:-}" ]; then
+  CLONE_URL="https://x-access-token:${GH_TOKEN}@github.com/$SOURCE_REPO.git"
+  CLONE_URL_DISPLAY="https://x-access-token:***@github.com/$SOURCE_REPO.git"
+else
+  CLONE_URL="https://github.com/$SOURCE_REPO.git"
+  CLONE_URL_DISPLAY="$CLONE_URL"
+fi
+
+echo ""
+if [ "$HISTORY_CHECK" = "1" ]; then
+  # Full commit/tree history (needed for the path → all-time-SHA index) but
+  # lazy blob fetching. We never need blob contents for the index — only
+  # blob SHAs from `git log --raw` — so blobs are never lazy-fetched in
+  # practice. Checkout of HEAD does fetch HEAD-tree blobs, which we need
+  # anyway for the cmp-based current-state comparison.
+  echo "==> Cloning $CLONE_URL_DISPLAY @$REF (full history, blob:none filter) ..."
+  git clone --filter=blob:none "$CLONE_URL" "$TMPDIR/src" >/dev/null 2>&1 || {
+    echo "error: clone failed" >&2; exit 5
+  }
+  (cd "$TMPDIR/src" && git checkout "$REF" >/dev/null 2>&1) || {
+    echo "error: could not check out ref '$REF' from $SOURCE_REPO" >&2
+    exit 5
+  }
+else
+  echo "==> Cloning $CLONE_URL_DISPLAY @$REF (shallow) ..."
+  git clone --depth 1 --branch "$REF" "$CLONE_URL" "$TMPDIR/src" >/dev/null 2>&1 || {
+    echo "    (shallow branch clone failed; trying full clone + checkout)"
+    git clone "$CLONE_URL" "$TMPDIR/src" >/dev/null
+    (cd "$TMPDIR/src" && git checkout "$REF" >/dev/null 2>&1) || {
+      echo "error: could not check out ref '$REF' from $SOURCE_REPO" >&2
+      exit 5
+    }
+  }
+fi
+
+SRC_SHA="$(cd "$TMPDIR/src" && git rev-parse HEAD)"
+echo "==> Source SHA: $SRC_SHA"
+
+# --- Resolve the history floor (last-sync SHA reachable in clone?) ----------
+#
+# The v0.1.104 algorithm drops the path → all-time-SHA index in favour of
+# per-file `git rev-parse <floor>:<rel>` comparisons. The floor is just the
+# stamped `replaced_from_source.last_sync_sha`, validated to be reachable
+# in this clone. When reachable, BASELINE_MODE=history_floor; otherwise
+# BASELINE_MODE=head_compare (cmp local vs upstream HEAD).
+#
+# Reachability check uses `git cat-file -e` because commits + trees are
+# always fully fetched even under --filter=blob:none. The floor SHA's
+# tree is what we'll consult per file; blobs at that tree may be lazy
+# but `git rev-parse <floor>:<rel>` only needs the tree, not the blob
+# contents.
+HISTORY_FLOOR=""
+BASELINE_MODE="head_compare"
+if [ "$HISTORY_CHECK" = "1" ] && [ -n "$PREV_SYNC_SHA" ] && [ "$PREV_SYNC_SOURCE" = "$SOURCE_REPO" ]; then
+  if (cd "$TMPDIR/src" && git cat-file -e "$PREV_SYNC_SHA" 2>/dev/null); then
+    HISTORY_FLOOR="$PREV_SYNC_SHA"
+    BASELINE_MODE="history_floor"
+  else
+    echo "    prior-sync SHA $PREV_SYNC_SHA not reachable in clone (rebased/dropped?); falling back to head_compare"
+  fi
+fi
+if [ "$BASELINE_MODE" = "history_floor" ]; then
+  echo "==> Baseline: $HISTORY_FLOOR (last-sync floor reachable)"
+else
+  echo "==> Baseline: HEAD compare (no usable last-sync stamp; first-ever run or stamp mismatch)"
+fi
+
+# --- Build wipe/overlay arg sets per mode ------------------------------------
+PRUNE_ARGS=()
+RSYNC_EXCLUDES=()
+
+if [ "${#NARROW_PATHS[@]}" -ne 0 ]; then
+  for n in "${NARROW_PATHS[@]}"; do
+    RSYNC_EXCLUDES+=( --include="/$n" )
+    RSYNC_EXCLUDES+=( --include="/$n/***" )
+  done
+  RSYNC_EXCLUDES+=( --exclude='/*' )
+else
+  PRUNE_ARGS=( -not -name .git -not -name companies -not -name personal -not -name workspace -not -name repos -not -name .github -not -name .leak-scan -not -name .hq-sync-journal.json -not -name .hq -not -name .hq-conflicts )
+  for p in "${EXTRA_PRESERVE[@]+"${EXTRA_PRESERVE[@]}"}"; do
+    PRUNE_ARGS+=( -not -name "$p" )
+  done
+  RSYNC_EXCLUDES=(
+    --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 p in "${EXTRA_PRESERVE[@]+"${EXTRA_PRESERVE[@]}"}"; do
+    RSYNC_EXCLUDES+=( --exclude="$p" )
+  done
+fi
+
+# --- Compute the wipe-set roots (top-level entries that will be deleted) -----
+WIPE_TOPLEVEL=()
+if [ "${#NARROW_PATHS[@]}" -ne 0 ]; then
+  for n in "${NARROW_PATHS[@]}"; do
+    [ -e "$HQ_ROOT/$n" ] && WIPE_TOPLEVEL+=("$n")
+  done
+else
+  while IFS= read -r line; do
+    rel="${line#./}"
+    WIPE_TOPLEVEL+=("$rel")
+  done < <( cd "$HQ_ROOT" && find . -mindepth 1 -maxdepth 1 "${PRUNE_ARGS[@]}" -print )
+  # companies/_template carve-out (wiped in default mode)
+  [ -d "$HQ_ROOT/companies/_template" ] && WIPE_TOPLEVEL+=("companies/_template")
+fi
+
+# --- Drift detection + rescue (v0.1.104 algorithm) --------------------------
+#
+# For each file under each wipe-set top-level entry, three-way classify
+# as USER-ONLY / UNCHANGED / USER-EDIT and act:
+#
+#   USER-ONLY  -> leave in place (skip — neither rescued nor deleted).
+#                 The rsync overlay below runs WITHOUT --delete, so any
+#                 file we leave alone survives the operation cleanly.
+#   UNCHANGED  -> rm -f the local copy. Overlay re-creates from source.
+#   USER-EDIT  -> rescue (mv to personal/, or diff-append for CLAUDE.md),
+#                 then the rm is implicit (rescue_one mv'd it).
+#
+# Counters surfaced in the post-run summary.
+COUNT_USER_ONLY=0
+COUNT_UNCHANGED=0
+COUNT_USER_EDIT=0
+COUNT_USER_CONFLICT=0
+COUNT_USER_OVERWRITE=0
+COUNT_CLAUDE_DIFF_APPEND=0
+COUNT_SYMLINK_DROPPED=0
+COUNT_CLOUD_SYMLINK_RECONCILED=0
+
+# True if $rel is under any always-preserved subpath. Drift detection
+# skips these — they're shuttled out, the wipe+overlay runs, then they're
+# restored unchanged. Detecting them as drifts would just move them to
+# personal/ and then leave a phantom-restored copy back at their original
+# location.
+is_under_preserve() {
+  local rel="$1" sp
+  for sp in "${PRESERVE_SUBPATHS[@]+"${PRESERVE_SUBPATHS[@]}"}"; do
+    case "$rel" in
+      "$sp"|"$sp"/*) return 0 ;;
+    esac
+  done
+  return 1
+}
+
+# Map a USER-EDIT path to its personal/ rescue target. Always lands under
+# personal/ — no fallback bucket. Strips `.claude/` or `core/` prefix so
+# `.claude/policies/foo.md` -> `personal/policies/foo.md`, etc. Caller
+# `mkdir -p "$(dirname dest)"` to ensure the parent exists.
+map_rescue_target() {
+  local rel="$1"
+  if [ "$rel" = ".claude/CLAUDE.md" ]; then
+    echo "personal/CLAUDE.md"
+    return
+  fi
+  local rest=""
+  case "$rel" in
+    .claude/*) rest="${rel#.claude/}" ;;
+    core/*)    rest="${rel#core/}" ;;
+    *)         rest="$rel" ;;
+  esac
+  echo "personal/$rest"
+}
+
+# Diff-append the user's additions in .claude/CLAUDE.md to personal/CLAUDE.md.
+# "Additions" are lines present locally but not in baseline (the last-sync
+# version, or current HEAD when no floor). Removed/modified lines are NOT
+# preserved by this algorithm — users rarely delete from CLAUDE.md and the
+# complexity of a true three-way merge isn't worth it in v1. If the user
+# did delete or modify lines they'll need to manually reconcile against
+# the new upstream version.
+#
+# Header marker (`<!-- drift-append ... -->`) timestamps the run + records
+# the source SHA so a user reading personal/CLAUDE.md can audit when each
+# block landed.
+diff_append_claude_md() {
+  local local_file="$HQ_ROOT/.claude/CLAUDE.md"
+  local personal_file="$HQ_ROOT/personal/CLAUDE.md"
+  local baseline_file
+  baseline_file="$(mktemp -t claude-md-baseline.XXXXXX)"
+
+  # Try the floor first, then HEAD. Either provides a "what the user
+  # started from" snapshot.
+  if [ "$BASELINE_MODE" = "history_floor" ]; then
+    (cd "$TMPDIR/src" && git show "$HISTORY_FLOOR:.claude/CLAUDE.md" > "$baseline_file" 2>/dev/null) || :
+  fi
+  if [ ! -s "$baseline_file" ] && [ -f "$TMPDIR/src/.claude/CLAUDE.md" ]; then
+    cp "$TMPDIR/src/.claude/CLAUDE.md" "$baseline_file"
+  fi
+
+  mkdir -p "$HQ_ROOT/personal"
+
+  if [ ! -s "$baseline_file" ]; then
+    # No baseline at all — record the whole local file as a drift block
+    # under a marker noting the absence of a baseline.
+    rm -f "$baseline_file"
+    {
+      [ -s "$personal_file" ] && printf '\n'
+      printf '<!-- drift-append from .claude/CLAUDE.md @ %s (source %s; no baseline available) -->\n' \
+        "$RUN_TS" "$SRC_SHA"
+      cat "$local_file"
+    } >> "$personal_file"
+    echo "    diff-appended (full local, no baseline): .claude/CLAUDE.md -> personal/CLAUDE.md"
+    COUNT_CLAUDE_DIFF_APPEND=$((COUNT_CLAUDE_DIFF_APPEND + 1))
+    return
+  fi
+
+  # Extract additions via `diff -u`. The sed strips the `+`/`+++` prefixes
+  # and preserves blank-line additions. Lost: file-header (`+++ local`)
+  # which we filter explicitly.
+  local additions_file
+  additions_file="$(mktemp -t claude-md-additions.XXXXXX)"
+  diff -u "$baseline_file" "$local_file" 2>/dev/null \
+    | sed -n '/^+++/!{ /^+/{ s/^+//; p } }' \
+    > "$additions_file" || :
+  rm -f "$baseline_file"
+
+  if [ ! -s "$additions_file" ]; then
+    rm -f "$additions_file"
+    echo "    no user edits to .claude/CLAUDE.md (skipped diff-append)"
+    return
+  fi
+
+  {
+    [ -s "$personal_file" ] && printf '\n'
+    printf '<!-- drift-append from .claude/CLAUDE.md @ %s (source %s) -->\n' \
+      "$RUN_TS" "$SRC_SHA"
+    cat "$additions_file"
+  } >> "$personal_file"
+  rm -f "$additions_file"
+  echo "    diff-appended: .claude/CLAUDE.md additions -> personal/CLAUDE.md"
+  COUNT_CLAUDE_DIFF_APPEND=$((COUNT_CLAUDE_DIFF_APPEND + 1))
+}
+
+# Rescue a single USER-EDIT file. Special-cases .claude/CLAUDE.md to
+# diff-append. All other paths land under personal/<rest>, mkdir-ing the
+# parent dir as needed. Collision suffix: .drift-<unix-ts>-<pid>.
+# Implicitly removes the original local path (CLAUDE.md is rm'd after
+# the diff-append; others are mv'd off).
+rescue_one() {
+  local rel="$1"
+  local local_path="$HQ_ROOT/$rel"
+  COUNT_USER_EDIT=$((COUNT_USER_EDIT + 1))
+
+  if [ "$rel" = ".claude/CLAUDE.md" ]; then
+    diff_append_claude_md
+    rm -f "$local_path"
+    printf 'rescued\t%s\t-> personal/CLAUDE.md (diff-append)\n' "$rel" >> "$RESCUE_LOG" 2>/dev/null || true
+    return
+  fi
+
+  local target
+  target="$(map_rescue_target "$rel")"
+  local dest="$HQ_ROOT/$target"
+  mkdir -p "$(dirname "$dest")"
+  if [ -e "$dest" ]; then
+    dest="${dest}.drift-$(date +%s)-$$"
+  fi
+  mv "$local_path" "$dest"
+  echo "    rescued: $rel  ->  ${dest#"$HQ_ROOT/"}"
+  printf 'rescued\t%s\t-> %s\n' "$rel" "${dest#"$HQ_ROOT/"}" >> "$RESCUE_LOG" 2>/dev/null || true
+}
+
+# Paths whose USER-EDIT outcome lands in .hq-conflicts/ rather than
+# personal/. These are runtime-managed dirs (IDE/agent state) and the
+# legacy root MIGRATION.md — they aren't user-overlay material the way
+# personal/ files are:
+#
+#   .agents/   — agent runtime artifacts (regenerated; not a customization)
+#   .codex/    — codex runtime/cache (per-machine; not portable as overlay)
+#   .obsidian/ — vault UI state (workspace.json, graph.json — local-only)
+#   MIGRATION.md — release migration doc; always re-shipped by overlay,
+#                  a divergent local copy means an upgrade snag worth
+#                  reviewing, not a customization to preserve under
+#                  personal/.
+#
+# Routing them to .hq-conflicts/rescue-<RUN_TS>/<rel> keeps them quarantined
+# under a timestamped bucket the user can inspect and discard, without
+# polluting the personal/ overlay tree (where master-sync would then try
+# to re-mirror them into core/).
+is_conflict_class() {
+  local rel="$1"
+  case "$rel" in
+    .agents|.agents/*)     return 0 ;;
+    .codex|.codex/*)       return 0 ;;
+    .obsidian|.obsidian/*) return 0 ;;
+    MIGRATION.md)          return 0 ;;
+  esac
+  return 1
+}
+
+# Move a USER-EDIT file into the .hq-conflicts/rescue-<RUN_TS>/ quarantine
+# bucket. Parallel to rescue_one() but never touches personal/.
+conflict_one() {
+  local rel="$1"
+  local local_path="$HQ_ROOT/$rel"
+  COUNT_USER_CONFLICT=$((COUNT_USER_CONFLICT + 1))
+
+  local target=".hq-conflicts/rescue-$RUN_TS/$rel"
+  local dest="$HQ_ROOT/$target"
+  mkdir -p "$(dirname "$dest")"
+  if [ -e "$dest" ]; then
+    dest="${dest}.drift-$(date +%s)-$$"
+  fi
+  mv "$local_path" "$dest"
+  echo "    conflicted: $rel  ->  ${dest#"$HQ_ROOT/"}"
+  printf 'conflicted\t%s\t-> %s\n' "$rel" "${dest#"$HQ_ROOT/"}" >> "$RESCUE_LOG" 2>/dev/null || true
+}
+
+# Paths whose USER-EDIT is SILENTLY OVERWRITTEN by the overlay — no rescue
+# to personal/, no quarantine to .hq-conflicts/. The local copy is either
+# auto-regenerated by another script or always re-shipped by upstream, so a
+# divergent local version is just stale and the upstream version should
+# land cleanly. This is the third user-edit outcome (alongside rescue +
+# conflict) — semantically equivalent to UNCHANGED, but reached even when
+# the bytes differ.
+#
+#   AGENTS.md                     — root alias; always re-shipped by upstream.
+#                                   Locally a symlink to .claude/CLAUDE.md in
+#                                   a healthy HQ; vault snapshots that flatten
+#                                   to a file always read as drifted.
+#   USER-GUIDE.md                 — pre-v15 root copy; always re-shipped.
+#   core/docs/hq/USER-GUIDE.md   — current release doc; always re-shipped.
+#   core/policies/_digest.md     — generated by `core/scripts/build-policy-digest.sh`
+#                                   from the union of policy files; rebuilt on
+#                                   the next Stop-hook master-sync pass.
+#                                   Same rationale as core/workers/registry.yaml,
+#                                   minus the carve-out (digest is small + cheap
+#                                   to regenerate, so just let the overlay win).
+is_overwrite_safe() {
+  local rel="$1"
+  case "$rel" in
+    AGENTS.md)                  return 0 ;;
+    USER-GUIDE.md)              return 0 ;;
+    core/docs/hq/USER-GUIDE.md) return 0 ;;
+    core/policies/_digest.md)   return 0 ;;
+  esac
+  return 1
+}
+
+# Cloud-flattened symlink detection (only meaningful with --cloud-update).
+# hq-sync serializes symlinks to S3 as small text files whose entire content
+# is `hq-symlink:<target>` (no newline; <target> is the same string the
+# symlink would resolve to). A vault snapshot pulled via `aws s3 sync` has
+# these in place of symlinks. When --cloud-update is on AND the upstream
+# blob at $rel is a symlink AND the local file is an `hq-symlink:<target>`
+# marker AND <target> matches the upstream symlink's target, the file is
+# semantically equivalent to upstream — not a user edit — so we route it
+# through the UNCHANGED branch (delete; the overlay re-lays the real
+# symlink). Returns 0 (reconciled / equivalent), 1 (not equivalent / not
+# a marker / upstream is not a symlink).
+#
+# Tradeoffs:
+#   - Read of local file's first line; cheap for tiny markers.
+#   - Two git calls per candidate (ls-tree mode check + symlink-target
+#     fetch); only triggered for files already flagged user-edited under
+#     --cloud-update, so the hot path is unaffected.
+#   - Strict: target must match exactly. A drifted marker (`hq-symlink:`
+#     pointing somewhere the upstream symlink no longer points) is still
+#     treated as a user-edit and routed normally — never silently
+#     overwritten.
+is_cloud_flattened_symlink_equiv() {
+  local rel="$1"
+  local local_path="$2"
+  [ "$CLOUD_UPDATE" = "1" ] || return 1
+  [ -f "$local_path" ] || return 1
+
+  # File must START with the magic marker. `hq-symlink:` is 11 bytes; we
+  # read exactly 11 to compare. Anything else (binary blob, longer doc,
+  # different prefix) bails out cheaply.
+  local head_bytes
+  head_bytes="$(head -c 11 "$local_path" 2>/dev/null || true)"
+  [ "$head_bytes" = "hq-symlink:" ] || return 1
+
+  # Extract the target the marker points to. Strip the prefix; tolerate
+  # an optional trailing newline (some serializers add one, some don't).
+  local local_target
+  local_target="$(sed -n '1p' "$local_path" 2>/dev/null | sed 's/^hq-symlink://' | tr -d '\n')"
+  [ -n "$local_target" ] || return 1
+
+  # Upstream blob at $rel must be a symlink (mode 120000). Look up the
+  # tree entry mode at the floor commit (history_floor mode) or via the
+  # checked-out source tree (head_compare fallback).
+  local mode
+  if [ "$BASELINE_MODE" = "history_floor" ]; then
+    mode="$(cd "$TMPDIR/src" && git ls-tree "$HISTORY_FLOOR" -- "$rel" 2>/dev/null | awk '{print $1}')"
+  else
+    mode="$(cd "$TMPDIR/src" && git ls-tree HEAD -- "$rel" 2>/dev/null | awk '{print $1}')"
+  fi
+  [ "$mode" = "120000" ] || return 1
+
+  # Read upstream symlink's target. For a symlink blob, `git show` returns
+  # the target path as plain text (no newline).
+  local upstream_target
+  if [ "$BASELINE_MODE" = "history_floor" ]; then
+    upstream_target="$(cd "$TMPDIR/src" && git show "$HISTORY_FLOOR:$rel" 2>/dev/null)"
+  else
+    upstream_target="$(cd "$TMPDIR/src" && git show "HEAD:$rel" 2>/dev/null)"
+  fi
+  [ -n "$upstream_target" ] || return 1
+
+  # Equivalent iff the targets match byte-for-byte.
+  [ "$local_target" = "$upstream_target" ]
+}
+
+# True when $local_path is a symlink generated by master-sync.sh — those
+# point into personal/ (e.g. `core/<type>/<entry>` -> `../../personal/...`,
+# `.claude/skills/<ns>:<entry>` -> `../../../personal/skills/<entry>/...`,
+# `.claude/commands/<ns>/<entry>.md` -> `../../../personal/skills/<entry>/SKILL.md`).
+# They are deterministically rebuilt on the next master-sync.sh run, so the
+# safe move during rescue is to delete rather than preserve — a leftover
+# symlink can shadow an overlaid-from-upstream real file at the same path.
+is_master_sync_symlink() {
+  local local_path="$1"
+  [ -L "$local_path" ] || return 1
+  local tgt
+  tgt="$(readlink "$local_path" 2>/dev/null || true)"
+  case "$tgt" in
+    */personal/*|personal/*) return 0 ;;
+  esac
+  return 1
+}
+
+# Classify + act on one file. The per-file workhorse of the new algorithm.
+process_one() {
+  local rel="$1"
+  local local_path="$HQ_ROOT/$rel"
+  local src_path="$TMPDIR/src/$rel"
+
+  # Always-preserved paths bypass drift detection entirely (shuttle owns
+  # them across the overlay).
+  if is_under_preserve "$rel"; then
+    return 0
+  fi
+
+  # Conflict-resolution artifacts (HQ-Sync renames divergent local files
+  # to `<name>.conflict-<ts>-<peer>.<ext>`). Never authored, never in
+  # upstream — rm them so the wipe consumes them rather than dragging
+  # them to personal/.
+  case "${rel##*/}" in
+    *.conflict-*)
+      if [ "$DRY_RUN" = "1" ]; then
+        echo "    drop conflict artifact: $rel"
+      else
+        rm -f "$local_path"
+      fi
+      return 0
+      ;;
+  esac
+
+  # Script-managed files: core/core.yaml (v14+) and core.yaml (pre-v14
+  # legacy layout). The script reads the prior stamp at the start of the
+  # run and rewrites a fresh stamp at the end (see the yq/python block
+  # below). Subjecting these to drift detection just creates noise: the
+  # local file always differs from the floor because we wrote a new
+  # stamp last run, but that's not a user edit — it's our own output.
+  # Skip rescue, just delete; the overlay restores the fresh upstream
+  # version, then the stamp step updates it with the new sync point.
+  case "$rel" in
+    core/core.yaml|core.yaml)
+      if [ "$DRY_RUN" = "1" ]; then
+        echo "    skip script-managed (rewrites at stamp step): $rel"
+      else
+        rm -f "$local_path"
+      fi
+      return 0
+      ;;
+  esac
+
+  # Symlinks (mid-tree). master-sync.sh deterministically rebuilds the
+  # personal/-targeted ones on its next Stop-hook pass, so the safe move
+  # here is to delete them — a leftover symlink at a path the overlay
+  # also writes to creates an ambiguous "is this the symlink or the
+  # overlaid file?" state on disk. Non-master-sync symlinks (user-created,
+  # absolute targets, or targets outside personal/) are left alone.
+  if [ -L "$local_path" ]; then
+    if is_master_sync_symlink "$local_path"; then
+      COUNT_SYMLINK_DROPPED=$((COUNT_SYMLINK_DROPPED + 1))
+      if [ "$DRY_RUN" = "1" ]; then
+        echo "    drop master-sync symlink: $rel  ->  $(readlink "$local_path" 2>/dev/null || true)"
+      else
+        rm -f "$local_path"
+        printf 'symlink-dropped\t%s\t(master-sync regenerable)\n' "$rel" >> "$RESCUE_LOG" 2>/dev/null || true
+      fi
+    fi
+    return 0
+  fi
+
+  # Is path in upstream HEAD?
+  local in_head=0
+  [ -e "$src_path" ] && in_head=1
+
+  # Is path in last-sync floor (if we have one)?
+  local in_floor=0
+  if [ "$BASELINE_MODE" = "history_floor" ]; then
+    if (cd "$TMPDIR/src" && git cat-file -e "$HISTORY_FLOOR:$rel" 2>/dev/null); then
+      in_floor=1
+    fi
+  fi
+
+  # USER-ONLY: path is unknown to upstream (HEAD AND floor both lack it).
+  # The user created this — leave it alone. The overlay (no --delete)
+  # doesn't touch files outside its source manifest, so the file survives.
+  if [ "$in_head" = "0" ] && [ "$in_floor" = "0" ]; then
+    COUNT_USER_ONLY=$((COUNT_USER_ONLY + 1))
+    if [ "$DRY_RUN" = "1" ]; then
+      echo "    user-only (leave in place): $rel"
+    fi
+    return 0
+  fi
+
+  # Path is/was in upstream. Determine if user edited it.
+  local user_edited=0
+  if [ "$BASELINE_MODE" = "history_floor" ] && [ "$in_floor" = "1" ]; then
+    # Compare local blob SHA against the blob at floor:rel.
+    local local_sha baseline_sha
+    local_sha="$(git hash-object "$local_path" 2>/dev/null || true)"
+    baseline_sha="$(cd "$TMPDIR/src" && git rev-parse "$HISTORY_FLOOR:$rel" 2>/dev/null || true)"
+    if [ -z "$local_sha" ] || [ -z "$baseline_sha" ] || [ "$local_sha" != "$baseline_sha" ]; then
+      user_edited=1
+    fi
+  elif [ "$in_head" = "1" ]; then
+    # head_compare fallback: cmp against current upstream copy.
+    cmp -s "$local_path" "$src_path" || user_edited=1
+  else
+    # in_floor=1 but in_head=0: upstream removed the file since last
+    # sync. Without a floor compare we can't tell if the user touched
+    # it; conservative default is to treat as USER-EDIT and rescue.
+    user_edited=1
+  fi
+
+  # Cloud-update mode: before routing as a user-edit, check if the local
+  # bytes are actually the cloud-flattened serialization of the same
+  # upstream symlink. If so, this isn't an edit — it's a transport
+  # artifact. Reclassify as UNCHANGED so the overlay rewrites the real
+  # symlink without polluting personal/ or .hq-conflicts/.
+  if [ "$user_edited" = "1" ] && is_cloud_flattened_symlink_equiv "$rel" "$local_path"; then
+    COUNT_CLOUD_SYMLINK_RECONCILED=$((COUNT_CLOUD_SYMLINK_RECONCILED + 1))
+    if [ "$DRY_RUN" = "1" ]; then
+      echo "    cloud-symlink reconciled (unchanged): $rel  (hq-symlink: marker matches upstream target)"
+    else
+      rm -f "$local_path"
+      printf 'cloud-symlink-reconciled\t%s\t(hq-symlink: marker matches upstream target; overlay re-lays symlink)\n' "$rel" >> "$RESCUE_LOG" 2>/dev/null || true
+    fi
+    return 0
+  fi
+
+  if [ "$user_edited" = "1" ]; then
+    if [ "$DRY_RUN" = "1" ]; then
+      if [ "$rel" = ".claude/CLAUDE.md" ]; then
+        echo "    user-edit (diff-append): $rel  ->  personal/CLAUDE.md"
+        COUNT_USER_EDIT=$((COUNT_USER_EDIT + 1))
+      elif is_overwrite_safe "$rel"; then
+        echo "    user-edit (overwrite-safe): $rel  ->  upstream wins (no copy preserved)"
+        COUNT_USER_OVERWRITE=$((COUNT_USER_OVERWRITE + 1))
+      elif is_conflict_class "$rel"; then
+        echo "    user-edit (conflict): $rel  ->  .hq-conflicts/rescue-$RUN_TS/$rel"
+        COUNT_USER_CONFLICT=$((COUNT_USER_CONFLICT + 1))
+      else
+        echo "    user-edit (rescue): $rel  ->  $(map_rescue_target "$rel")"
+        COUNT_USER_EDIT=$((COUNT_USER_EDIT + 1))
+      fi
+    else
+      if [ "$rel" = ".claude/CLAUDE.md" ]; then
+        rescue_one "$rel"
+      elif is_overwrite_safe "$rel"; then
+        rm -f "$local_path"
+        COUNT_USER_OVERWRITE=$((COUNT_USER_OVERWRITE + 1))
+        printf 'overwritten\t%s\t(overwrite-safe; upstream wins, no copy preserved)\n' "$rel" >> "$RESCUE_LOG" 2>/dev/null || true
+      elif is_conflict_class "$rel"; then
+        conflict_one "$rel"
+      else
+        rescue_one "$rel"
+      fi
+    fi
+  else
+    # UNCHANGED — overlay will replace cleanly.
+    COUNT_UNCHANGED=$((COUNT_UNCHANGED + 1))
+    if [ "$DRY_RUN" = "1" ]; then
+      echo "    unchanged (delete + replace): $rel"
+    else
+      rm -f "$local_path"
+      printf 'deleted\t%s\t(unchanged vs baseline; re-created by overlay)\n' "$rel" >> "$RESCUE_LOG" 2>/dev/null || true
+    fi
+  fi
+}
+
+# Walk a wipe-set root, processing each file. companies/_template is
+# special-cased: always wholesale-replace (it's a template, never
+# user-authored), so we just rm it here and let the overlay re-create.
+walk_and_process() {
+  local root_rel="$1"
+  local root_abs="$HQ_ROOT/$root_rel"
+  [ -e "$root_abs" ] || [ -L "$root_abs" ] || return 0
+
+  # companies/_template — wholesale-replace.
+  if [ "$root_rel" = "companies/_template" ]; then
+    if [ "$DRY_RUN" = "1" ]; then
+      echo "    wholesale-replace: companies/_template (template carve-out)"
+    else
+      rm -rf "$HQ_ROOT/companies/_template"
+    fi
+    return 0
+  fi
+
+  # Top-level symlinks (AGENTS.md, MIGRATION.md, etc.). Most are static
+  # convenience aliases the overlay overwrites cleanly (rsync -a preserves
+  # link semantics from source). Master-sync personal-overlay symlinks at
+  # the top level — rare but possible — are dropped here so the overlay
+  # can land a real file at the same path without ambiguity; master-sync
+  # regenerates the link on its next Stop-hook pass.
+  if [ -L "$root_abs" ]; then
+    if is_master_sync_symlink "$root_abs"; then
+      COUNT_SYMLINK_DROPPED=$((COUNT_SYMLINK_DROPPED + 1))
+      if [ "$DRY_RUN" = "1" ]; then
+        echo "    drop master-sync symlink: $root_rel  ->  $(readlink "$root_abs" 2>/dev/null || true)"
+      else
+        rm -f "$root_abs"
+        printf 'symlink-dropped\t%s\t(master-sync regenerable)\n' "$root_rel" >> "$RESCUE_LOG" 2>/dev/null || true
+      fi
+    fi
+    return 0
+  fi
+
+  # Top-level regular file.
+  if [ -f "$root_abs" ]; then
+    process_one "$root_rel"
+    return
+  fi
+
+  # Top-level directory: walk recursively, pruning node_modules + nested
+  # .git (v0.1.103 perf + correctness guard). Symlinks are surfaced via
+  # `-type l` so master-sync-generated links (targets resolving into
+  # personal/) can be dropped — see process_one + is_master_sync_symlink.
+  # Under -P (the default), find does not descend INTO directory symlinks,
+  # which keeps the walk bounded even when those links exist.
+  while IFS= read -r -d '' f; do
+    local rel="${f#"$HQ_ROOT/"}"
+    process_one "$rel"
+  done < <(find "$root_abs" \( -type d \( -name node_modules -o -name .git \) -prune \) -o \( \( -type f -o -type l \) -print0 \))
+}
+
+# Prune pre-update-* snapshots older than the retention window. Best-effort:
+# a failure here never aborts the run (the snapshot we just took is what
+# matters). This is the auto-cleanup MIGRATION.md promised but never shipped.
+prune_old_backups() {
+  [ -d "$BACKUP_ROOT" ] || return 0
+  case "$BACKUP_RETENTION_DAYS" in ''|*[!0-9]*) return 0 ;; esac
+  [ "$BACKUP_RETENTION_DAYS" -gt 0 ] || return 0
+  find "$BACKUP_ROOT" -maxdepth 1 -type d -name 'pre-update-*' -mtime +"$BACKUP_RETENTION_DAYS" -print 2>/dev/null \
+    | while IFS= read -r old; do
+        echo "    pruned old snapshot (> ${BACKUP_RETENTION_DAYS}d): ${old##*/}"
+        rm -rf "$old" 2>/dev/null || true
+      done
+}
+
+# --- Pre-operation safety snapshot (BEFORE any destructive op) --------------
+# Copy every wipe-set top-level entry to ~/.hq/backups/pre-update-<ts>/ so a
+# misclassification or interrupted rescue is fully recoverable. Only the wipe
+# set is snapshotted — repos/ (often ~GBs), personal/, companies/, workspace/
+# are preserved by the overlay and never at risk, so copying them would be
+# wasteful and slow. node_modules/ + nested .git/ are excluded for the same
+# reason. Skipped in dry-run (nothing gets destroyed) and when --no-backup.
+if [ "$DO_BACKUP" = "1" ] && [ "$DRY_RUN" != "1" ] && [ "${#WIPE_TOPLEVEL[@]}" -ne 0 ]; then
+  BACKUP_DIR="$BACKUP_ROOT/pre-update-$RUN_TS"
+  echo ""
+  echo "==> Safety snapshot -> $BACKUP_DIR"
+  mkdir -p "$BACKUP_DIR"
+  for root_rel in "${WIPE_TOPLEVEL[@]}"; do
+    src_abs="$HQ_ROOT/$root_rel"
+    [ -e "$src_abs" ] || continue
+    parent_rel="$(dirname "$root_rel")"
+    mkdir -p "$BACKUP_DIR/$parent_rel"
+    if command -v rsync >/dev/null 2>&1; then
+      rsync -a --exclude='node_modules/' --exclude='.git/' "$src_abs" "$BACKUP_DIR/$parent_rel/" 2>/dev/null \
+        || cp -a "$src_abs" "$BACKUP_DIR/$parent_rel/" 2>/dev/null || true
+    else
+      cp -a "$src_abs" "$BACKUP_DIR/$parent_rel/" 2>/dev/null || true
+    fi
+  done
+  echo "    snapshot complete (restore any file: cp \"$BACKUP_DIR/<relpath>\" \"$HQ_ROOT/<relpath>\")"
+fi
+
+echo ""
+if [ "${#WIPE_TOPLEVEL[@]}" -eq 0 ]; then
+  echo "==> Wipe set is empty; nothing to process or overlay."
+else
+  echo "==> Walking wipe set, classifying vs. $SOURCE_REPO@$REF ..."
+  for root_rel in "${WIPE_TOPLEVEL[@]}"; do
+    walk_and_process "$root_rel"
+  done
+fi
+
+if [ "$DRY_RUN" = "1" ]; then
+  echo ""
+  echo "==> DRY RUN classification summary:"
+  echo "  user-only (leave in place):       $COUNT_USER_ONLY files"
+  echo "  unchanged (delete + replace):     $COUNT_UNCHANGED files"
+  echo "  user-edit (rescue / diff-append): $COUNT_USER_EDIT files"
+  echo "  user-edit (conflict quarantine):  $COUNT_USER_CONFLICT files"
+  echo "  user-edit (overwrite-safe):       $COUNT_USER_OVERWRITE files"
+  echo "  cloud-symlink reconciled:         $COUNT_CLOUD_SYMLINK_RECONCILED files"
+  echo "  master-sync symlinks dropped:     $COUNT_SYMLINK_DROPPED entries"
+  if [ "$COUNT_CLAUDE_DIFF_APPEND" -gt 0 ]; then
+    echo "    of which .claude/CLAUDE.md would diff-append to personal/CLAUDE.md"
+  fi
+  if [ "$COUNT_USER_CONFLICT" -gt 0 ]; then
+    echo "    conflict bucket: .hq-conflicts/rescue-$RUN_TS/"
+  fi
+  if [ "${#PRESERVE_SUBPATHS[@]}" -ne 0 ]; then
+    echo ""
+    echo "==> DRY RUN: would back up + restore these sub-paths across the overlay:"
+    for sp in "${PRESERVE_SUBPATHS[@]}"; do
+      if [ -e "$HQ_ROOT/$sp" ]; then
+        echo "  ~ ./$sp  (present — will survive)"
+      else
+        echo "  ~ ./$sp  (not present locally — no-op)"
+      fi
+    done
+  fi
+  echo ""
+  echo "==> DRY RUN: would copy these top-level entries from source on overlay:"
+  if [ "${#NARROW_PATHS[@]}" -ne 0 ]; then
+    for n in "${NARROW_PATHS[@]}"; do
+      if [ -e "$TMPDIR/src/$n" ]; then
+        echo "  + ./$n"
+      fi
+    done
+  else
+    ( cd "$TMPDIR/src" && find . -mindepth 1 -maxdepth 1 "${PRUNE_ARGS[@]}" | sed 's|^\./|  + |' )
+    if [ -d "$TMPDIR/src/companies/_template" ]; then
+      echo "  + ./companies/_template  (carve-out from $SOURCE_REPO@$REF)"
+    fi
+  fi
+  echo ""
+  echo "==> DRY RUN complete. No filesystem changes made."
+  exit 0
+fi
+
+# --- Back up preserve-subpaths to a mktemp shuttle ---------------------------
+SHUTTLE="$TMPDIR/preserve"
+mkdir -p "$SHUTTLE"
+: > "$TMPDIR/preserve.map"
+shuttle_id=0
+for sp in "${PRESERVE_SUBPATHS[@]+"${PRESERVE_SUBPATHS[@]}"}"; do
+  src="$HQ_ROOT/$sp"
+  if [ -e "$src" ]; then
+    shuttle_id=$((shuttle_id + 1))
+    cp -a "$src" "$SHUTTLE/$shuttle_id"
+    printf '%s\t%s\n' "$shuttle_id" "$sp" >> "$TMPDIR/preserve.map"
+    echo "==> Backed up $sp -> shuttle/$shuttle_id"
+  fi
+done
+
+echo ""
+echo "==> Walk complete (user-only: $COUNT_USER_ONLY, unchanged-deleted: $COUNT_UNCHANGED, user-edit-rescued: $COUNT_USER_EDIT, conflict-quarantined: $COUNT_USER_CONFLICT, overwrite-safe: $COUNT_USER_OVERWRITE, cloud-symlink-reconciled: $COUNT_CLOUD_SYMLINK_RECONCILED, symlinks-dropped: $COUNT_SYMLINK_DROPPED)"
+# Note: v0.1.103-and-earlier did a wholesale `rm -rf` of every wipe-set
+# top-level entry here. The new walk_and_process does per-file deletion
+# (only files that exist in upstream + are unchanged are deleted; user-only
+# files survive). The wholesale wipe step is intentionally gone — keep
+# the no-delete semantics of the rsync overlay below to preserve files
+# the walk left alone.
+
+echo "==> Overlaying source onto HQ root ..."
+rsync -a "${RSYNC_EXCLUDES[@]}" "$TMPDIR/src/" "$HQ_ROOT/"
+
+if [ -s "$TMPDIR/preserve.map" ]; then
+  echo "==> Restoring preserved sub-paths ..."
+  while IFS=$'\t' read -r id relpath; do
+    dest="$HQ_ROOT/$relpath"
+    mkdir -p "$(dirname "$dest")"
+    if [ -d "$SHUTTLE/$id" ]; then
+      rm -rf "$dest"
+      cp -a "$SHUTTLE/$id" "$dest"
+    else
+      cp -a "$SHUTTLE/$id" "$dest"
+    fi
+    echo "    restored $relpath"
+  done < "$TMPDIR/preserve.map"
+fi
+
+# --- Stamp sync-point provenance into core/core.yaml ------------------------
+# Default mode only — in narrow mode we only overlaid a subset of top-level
+# entries, so claiming "the HQ root is at <sha>" would be misleading. yq
+# is preferred (clean in-place edit, preserves comments mediocrely but well
+# enough). Falls back to a python3+PyYAML one-liner if yq is missing.
+if [ "${#NARROW_PATHS[@]}" -eq 0 ] && [ -f "$HQ_ROOT/core/core.yaml" ]; then
+  NOW_UTC="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+  if command -v yq >/dev/null 2>&1; then
+    # Write the new key AND delete the old (pre-v0.1.104) one in the same
+    # pass so post-migration the file holds only the new stamp. `del(...)`
+    # is a no-op when the key is absent, so this is safe for fresh installs.
+    SHA="$SRC_SHA" SOURCE="$SOURCE_REPO" THE_REF="$REF" AT="$NOW_UTC" \
+      yq -i '
+        .replaced_from_source.source       = strenv(SOURCE) |
+        .replaced_from_source.ref          = strenv(THE_REF) |
+        .replaced_from_source.last_sync_sha = strenv(SHA) |
+        .replaced_from_source.last_sync_at  = strenv(AT) |
+        del(.replaced_from_staging)
+      ' "$HQ_ROOT/core/core.yaml"
+    echo "==> Stamped core/core.yaml: replaced_from_source.last_sync_sha=$SRC_SHA"
+  elif command -v python3 >/dev/null 2>&1 && python3 -c 'import yaml' >/dev/null 2>&1; then
+    SHA="$SRC_SHA" SOURCE="$SOURCE_REPO" THE_REF="$REF" AT="$NOW_UTC" CORE="$HQ_ROOT/core/core.yaml" \
+      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"],
+}
+# Drop the pre-v0.1.104 key on migration. .pop with a default is a no-op
+# when the key is absent.
+d.pop("replaced_from_staging", None)
+with open(path, "w") as f:
+    yaml.safe_dump(d, f, default_flow_style=False, sort_keys=False)
+'
+    echo "==> Stamped core/core.yaml: replaced_from_source.last_sync_sha=$SRC_SHA"
+  else
+    echo "    WARN: neither yq nor python3+PyYAML available — skipping core/core.yaml stamp" >&2
+  fi
+fi
+
+echo ""
+echo "==> File count summary:"
+for root_rel in "${WIPE_TOPLEVEL[@]}"; do
+  if [ -e "$HQ_ROOT/$root_rel" ]; then
+    n_files="$(find "$HQ_ROOT/$root_rel" -type f 2>/dev/null | wc -l | tr -d ' ')"
+    echo "    $root_rel: $n_files files"
+  fi
+done
+echo ""
+echo "==> Classification:"
+echo "    user-only (left in place):        $COUNT_USER_ONLY files"
+echo "    unchanged (deleted + overlaid):   $COUNT_UNCHANGED files"
+echo "    user-edits (rescued):             $COUNT_USER_EDIT files"
+echo "    user-edits (conflict quarantine): $COUNT_USER_CONFLICT files"
+echo "    user-edits (overwrite-safe):      $COUNT_USER_OVERWRITE files"
+echo "    cloud-symlink reconciled:         $COUNT_CLOUD_SYMLINK_RECONCILED files"
+echo "    master-sync symlinks dropped:     $COUNT_SYMLINK_DROPPED entries"
+if [ "$COUNT_CLAUDE_DIFF_APPEND" -gt 0 ]; then
+  echo "      of which .claude/CLAUDE.md diff-appended to personal/CLAUDE.md"
+fi
+if [ "$COUNT_USER_CONFLICT" -gt 0 ]; then
+  echo "      conflict bucket: .hq-conflicts/rescue-$RUN_TS/"
+fi
+if [ "$BASELINE_MODE" = "history_floor" ]; then
+  echo "    baseline:                          last-sync floor $HISTORY_FLOOR"
+else
+  echo "    baseline:                          upstream HEAD (no stamp; first run / floor unreachable)"
+fi
+
+# --- Write recovery manifest into the snapshot + prune old snapshots --------
+if [ "$DO_BACKUP" = "1" ] && [ -n "$BACKUP_DIR" ] && [ -d "$BACKUP_DIR" ]; then
+  {
+    echo "# HQ pre-update safety snapshot"
+    echo ""
+    echo "Created:   $RUN_TS"
+    echo "HQ root:   $HQ_ROOT"
+    echo "Source:    $SOURCE_REPO@$REF ($SRC_SHA)"
+    if [ "$BASELINE_MODE" = "history_floor" ]; then
+      echo "Baseline:  history_floor ($HISTORY_FLOOR)"
+    else
+      echo "Baseline:  head_compare (no last-sync stamp; first run or floor unreachable)"
+    fi
+    echo ""
+    echo "## What the rescue did"
+    echo "  user-only  (left in place):              $COUNT_USER_ONLY"
+    echo "  unchanged  (deleted + re-overlaid):      $COUNT_UNCHANGED"
+    echo "  user-edit  (rescued into personal/):     $COUNT_USER_EDIT"
+    echo "  user-edit  (conflict quarantine):        $COUNT_USER_CONFLICT"
+    echo "  user-edit  (overwrite-safe):             $COUNT_USER_OVERWRITE"
+    echo "  cloud-symlink reconciled:                $COUNT_CLOUD_SYMLINK_RECONCILED"
+    echo "  master-sync symlinks dropped:            $COUNT_SYMLINK_DROPPED"
+    if [ "$COUNT_USER_CONFLICT" -gt 0 ]; then
+      echo "  conflict bucket: .hq-conflicts/rescue-$RUN_TS/"
+    fi
+    echo ""
+    echo "## Moved / deleted files (tab-separated: action, path, detail)"
+    if [ -s "$RESCUE_LOG" ]; then
+      cat "$RESCUE_LOG"
+    else
+      echo "  (no files were moved or deleted)"
+    fi
+    echo ""
+    echo "## Restore"
+    echo "This directory holds the wipe set exactly as it was before the update."
+    echo "Restore a single file:"
+    echo "  cp \"$BACKUP_DIR/<relpath>\" \"$HQ_ROOT/<relpath>\""
+    echo "Restore everything (overwrites current scaffold — use with care):"
+    echo "  rsync -a \"$BACKUP_DIR/\" \"$HQ_ROOT/\""
+    echo ""
+    echo "Auto-pruned after $BACKUP_RETENTION_DAYS days (HQ_BACKUP_RETENTION_DAYS)."
+  } > "$BACKUP_DIR/RECOVERY.md" 2>/dev/null || true
+  echo ""
+  echo "==> Pre-update snapshot + recovery manifest: $BACKUP_DIR"
+  prune_old_backups
+fi
+
+echo ""
+echo "==> Done. Source: $SOURCE_REPO@$REF ($SRC_SHA)"
+echo "    User-edited files were rescued under personal/ (see scan output above)."
+echo "    User-only files (created by you, unknown to upstream) were left untouched."
+[ "$DO_BACKUP" = "1" ] && [ -n "$BACKUP_DIR" ] && echo "    A full pre-update snapshot is at $BACKUP_DIR (RECOVERY.md explains restore)."