@indigoai-us/hq-cloud 6.1.0 → 6.2.0

package/scripts/replace-rescue.sh

@@ -1,1522 +0,0 @@
-#!/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 `reindex.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 `reindex` 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 reindex symlinks (regenerated by reindex.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 reindex — no copy preserved),%b\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 %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 LEAVES in place
-# (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"
-
-# Paths the walk classified UNCHANGED (left in place). Fed to the overlay as an
-# --exclude-from so rsync never touches them — preserving their on-disk mtime
-# exactly (Layer 1). rsync's -t re-stamps even a checksum-skipped file to the
-# source's time, so excluding is the only way to leave the local mtime truly
-# untouched.
-UNCHANGED_LIST="$TMPDIR/unchanged-paths.txt"
-: > "$UNCHANGED_LIST"
-
-# 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"
-
-# --- Restore file mtimes from git history (mtime-preservation fix) -----------
-#
-# A bare `git clone`/checkout stamps every working-tree file with clone-time
-# (git stores no per-file mtimes), so the `rsync -a` overlay below would reset
-# every rescued file's mtime to "whenever rescue ran" — collapsing all history
-# onto one instant and breaking "newer-than" comparisons, mtime-keyed caches,
-# and reproducible state across machines. This is the rescue-path analogue of
-# the 5.37.0 `hq-mtime` fix on the sync/S3 path, sourced from git commit times
-# because the rescue source is a clone, not the vault.
-#
-# Single history walk, newest-first: the first commit a path appears in is its
-# last-modifying commit, and that commit's committer-date becomes the file's
-# mtime. Applied via perl's utime() — portable across macOS/Linux, unlike
-# `touch -d @epoch` (GNU-only). Symlinks are skipped (utime follows the link
-# to its target). Deleted-then-readded paths resolve correctly: newest wins.
-restore_mtimes_from_git() {
-  local src="$1"
-  if ! command -v perl >/dev/null 2>&1; then
-    echo "    (perl unavailable; skipping mtime restore — overlay mtimes stay clone-time)"
-    return 0
-  fi
-
-  # Correct per-file granularity needs full history. A shallow clone knows
-  # only the tip commit, so every file would collapse to the release time;
-  # deepen (blob:none keeps it to cheap commit/tree metadata) when shallow.
-  if [ "$(git -C "$src" rev-parse --is-shallow-repository 2>/dev/null)" = "true" ]; then
-    echo "==> Deepening clone for per-file mtime history (blob:none) ..."
-    git -C "$src" fetch --unshallow --filter=blob:none >/dev/null 2>&1 \
-      || echo "    (unshallow failed; mtimes fall back to release tip-commit time)"
-  fi
-
-  echo "==> Restoring file mtimes from git commit history ..."
-  git -C "$src" log --no-renames --pretty=format:'C:%ct' --name-only --diff-filter=ACMR 2>/dev/null \
-    | awk '/^C:/ { ts = substr($0, 3); next } NF { if (!seen[$0]++) print ts "\t" $0 }' \
-    | SRC="$src" perl -ne '
-        chomp;
-        my ($ts, $rel) = split(/\t/, $_, 2);
-        next unless defined $rel and length $rel;
-        my $f = "$ENV{SRC}/$rel";
-        next if -l $f or not -f $f;
-        utime $ts, $ts, $f;
-      ' || true
-}
-restore_mtimes_from_git "$TMPDIR/src"
-
-# --- 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
-COUNT_DRIFT_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 reindex 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 reindex 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 reindex.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 reindex.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). reindex.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-reindex 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 reindex symlink: $rel  ->  $(readlink "$local_path" 2>/dev/null || true)"
-      else
-        rm -f "$local_path"
-        printf 'symlink-dropped\t%s\t(reindex 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
-
-  # Convergence guard: in history_floor mode a file is flagged USER-EDIT when
-  # its blob differs from the *old* baseline (the floor). But HQ's own Stop
-  # hooks (reindex symlinking personal/->core/, autocommit, registry/
-  # _digest/core.yaml regeneration) rewrite scaffold files every session, so a
-  # file routinely drifts from the floor yet lands byte-for-byte identical to
-  # the *new* upstream HEAD this overlay is about to write. Rescuing it into
-  # personal/ then just deposits a redundant `.drift-<ts>-<pid>` copy of bytes
-  # the overlay would have written anyway (this is what produced the 32-file
-  # `.drift-*` litter on a live tree). If local already equals upstream HEAD
-  # there is nothing to preserve, so reclassify as UNCHANGED (delete; the
-  # overlay re-writes the identical bytes). Parallels the cloud-symlink
-  # reconcile above and the sync-side convergence guard. Gated on in_head so an
-  # upstream-removed file (in_head=0) is still rescued; a no-op in head_compare
-  # mode, where `cmp` already settled user_edited against upstream HEAD.
-  if [ "$user_edited" = "1" ] && [ "$in_head" = "1" ] && cmp -s "$local_path" "$src_path"; then
-    COUNT_DRIFT_RECONCILED=$((COUNT_DRIFT_RECONCILED + 1))
-    if [ "$DRY_RUN" = "1" ]; then
-      echo "    drift reconciled (identical to upstream HEAD; no rescue): $rel"
-    else
-      rm -f "$local_path"
-      printf 'drift-reconciled\t%s\t(identical to upstream HEAD; drifted from floor only — no personal/ copy)\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
-    # user_edited=0: local matches the floor baseline (user didn't touch it).
-    # That does NOT mean it matches upstream HEAD — upstream may have advanced
-    # or removed it. Split on byte-equality to the HEAD version the overlay
-    # would write ($TMPDIR/src is checked out at HEAD):
-    #   identical to HEAD -> overlay is a content no-op; leave it untouched and
-    #     protect it from the overlay so its mtime is preserved (Layer 1).
-    #   differs from HEAD  -> keep the original delete semantics: rm now; the
-    #     no-delete overlay re-lays it from source (with a git-commit mtime)
-    #     when still upstream, or leaves it gone when upstream removed it.
-    COUNT_UNCHANGED=$((COUNT_UNCHANGED + 1))
-    if cmp -s "$local_path" "$TMPDIR/src/$rel" 2>/dev/null; then
-      if [ "$DRY_RUN" = "1" ]; then
-        echo "    unchanged (preserved in place): $rel"
-      else
-        printf '/%s\n' "$rel" >> "$UNCHANGED_LIST"
-        printf 'unchanged\t%s\t(identical to upstream; left in place, mtime preserved)\n' "$rel" >> "$RESCUE_LOG" 2>/dev/null || true
-      fi
-    else
-      if [ "$DRY_RUN" = "1" ]; then
-        echo "    unchanged (delete + replace): $rel"
-      else
-        rm -f "$local_path"
-        printf 'deleted\t%s\t(unchanged vs baseline; re-laid by overlay if still upstream)\n' "$rel" >> "$RESCUE_LOG" 2>/dev/null || true
-      fi
-    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; reindex
-  # 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 reindex symlink: $root_rel  ->  $(readlink "$root_abs" 2>/dev/null || true)"
-      else
-        rm -f "$root_abs"
-        printf 'symlink-dropped\t%s\t(reindex 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 reindex-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 (preserved/re-laid):    $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 "  drift reconciled (== upstream):   $COUNT_DRIFT_RECONCILED files"
-  echo "  reindex 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: $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 ..."
-# Protect UNCHANGED (identical-to-HEAD) files: feed their paths as an
-# --exclude-from (FIRST in the filter chain, so it wins) so rsync never touches
-# them — -a's -t would otherwise re-stamp their mtime to the source's time, and
-# excluding is the only way to leave the local mtime truly untouched (Layer 1).
-# Every other file under the wipe set was already rm'd by the walk, so the
-# overlay writes into an absent slot and -a carries the git-commit mtimes
-# restore_mtimes_from_git stamped onto the source.
-OVERLAY_PROTECT=()
-[ -s "$UNCHANGED_LIST" ] && OVERLAY_PROTECT=( --exclude-from="$UNCHANGED_LIST" )
-rsync -a "${OVERLAY_PROTECT[@]+"${OVERLAY_PROTECT[@]}"}" "${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 (preserved/re-laid):    $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 "    drift reconciled (== upstream):   $COUNT_DRIFT_RECONCILED files"
-echo "    reindex 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  (preserved/re-laid):          $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 "  drift reconciled (== upstream HEAD):     $COUNT_DRIFT_RECONCILED"
-    echo "  reindex 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."
-# Snapshot path footer: emit only when a backup was actually taken AND its
-# resolved dir is non-empty. Wrapped in `if/then/fi` (not a `[...] && [...]
-# && echo` chain) so the script's final exit status is independent of the
-# branch taken — a `[ DO_BACKUP = 1 ]` test returning false in a `&&` chain
-# became this script's exit code under `set -e`, which kills any parent
-# wrapper script (e.g. `apps/hq-cloud/scripts/vault-rescue.sh`) that runs
-# us under `set -euo pipefail`.
-if [ "$DO_BACKUP" = "1" ] && [ -n "$BACKUP_DIR" ]; then
-  echo "    A full pre-update snapshot is at $BACKUP_DIR (RECOVERY.md explains restore)."
-fi
-
-# Always succeed if we reached the end. Without this, a future maintainer
-# could add another conditional trailing line and silently regress the
-# wrapper-script-kill bug. Explicit > implicit for the script's contract.
-exit 0