@indigoai-us/hq-cloud 5.48.3 → 6.0.0

package/scripts/{master-sync.sh → reindex.sh}

@@ -1,16 +1,16 @@
 #!/bin/bash
-# master-sync.sh — surfaces namespace skills as Claude Code skills under
+# reindex.sh — surfaces namespace skills as Claude Code skills under
 # .claude/skills/<ns>:<skill>/ with every file in the source skill folder
 # mirrored as a symlink. Also mirrors personal/{knowledge,policies,workers,
 # settings}/* into core/<type>/<name>.
 #
 # This script ships inside the @indigoai-us/hq-cloud package and is invoked via
-# `hq master-sync` (which passes the HQ root as $1). It is idempotent and cheap
+# `hq reindex` (which passes the HQ root as $1). It is idempotent and cheap
 # to re-run, so it doesn't gate on whether personal/ was actually touched. Real
 # files/dirs already at the link path are left untouched.
 #
 # REPO_ROOT resolution (in priority order):
-#   1. $1                — passed by `hq master-sync` (the HQ root)
+#   1. $1                — passed by `hq reindex` (the HQ root)
 #   2. $HQ_REPO_ROOT     — env override
 #   3. $PWD              — fallback when invoked directly
 #
@@ -40,7 +40,7 @@ set -uo pipefail
 
 REPO_ROOT="${1:-${HQ_REPO_ROOT:-$PWD}}"
 if [ ! -d "$REPO_ROOT" ]; then
-  echo "master-sync: REPO_ROOT '$REPO_ROOT' is not a directory" >&2
+  echo "reindex: REPO_ROOT '$REPO_ROOT' is not a directory" >&2
   exit 1
 fi
 REPO_ROOT="$(cd "$REPO_ROOT" && pwd)"
@@ -128,7 +128,7 @@ while [ "$i" -lt "${#namespaces[@]}" ]; do
     fi
   done
   if [ "$already" -eq 1 ]; then
-    echo "master-sync: namespace '$ns' already claimed by an earlier source; skipping $src_rel" >&2
+    echo "reindex: namespace '$ns' already claimed by an earlier source; skipping $src_rel" >&2
     continue
   fi
   seen+=("$ns")
@@ -147,7 +147,7 @@ while [ "$i" -lt "${#namespaces[@]}" ]; do
 
     # If something non-directory occupies the slot, bail.
     if [ -e "$wrapper" ] && [ ! -L "$wrapper" ] && [ ! -d "$wrapper" ]; then
-      echo "master-sync: $wrapper exists and is not a directory; skipping" >&2
+      echo "reindex: $wrapper exists and is not a directory; skipping" >&2
       continue
     fi
     # If it's a symlink (e.g. legacy directory-symlink form from earlier
@@ -171,10 +171,10 @@ while [ "$i" -lt "${#namespaces[@]}" ]; do
         if [ "$current" = "$relative_target" ]; then
           continue
         fi
-        echo "master-sync: .claude/skills/$wrapper_name/$entry already points to '$current' (expected '$relative_target'); leaving alone" >&2
+        echo "reindex: .claude/skills/$wrapper_name/$entry already points to '$current' (expected '$relative_target'); leaving alone" >&2
         continue
       elif [ -e "$link_path" ]; then
-        echo "master-sync: $link_path already exists and is not a symlink; skipping" >&2
+        echo "reindex: $link_path already exists and is not a symlink; skipping" >&2
         continue
       fi
 
@@ -298,10 +298,10 @@ for type in knowledge policies workers settings; do
       if [ "$current" = "$relative_target" ]; then
         continue
       fi
-      echo "master-sync: core/$type/$entry already points to '$current' (expected '$relative_target'); leaving alone" >&2
+      echo "reindex: core/$type/$entry already points to '$current' (expected '$relative_target'); leaving alone" >&2
       continue
     elif [ -e "$link_path" ]; then
-      echo "master-sync: core/$type/$entry already exists and is not a symlink; skipping" >&2
+      echo "reindex: core/$type/$entry already exists and is not a symlink; skipping" >&2
       continue
     fi
 

package/scripts/replace-rescue.sh

@@ -77,7 +77,7 @@
 #   not a customization — saving it under personal/ or .hq-conflicts/ just
 #   accumulates noise.
 #
-# Symlinks generated by `master-sync.sh` (targets resolving into
+# 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
@@ -245,7 +245,7 @@ BACKUP_DIR=""   # resolved at snapshot time (BACKUP_ROOT/pre-update-<RUN_TS>)
 # 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).
+# (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
@@ -436,7 +436,7 @@ if [ "${#PRESERVE_SUBPATHS[@]}" -ne 0 ]; then
     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)"
+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
@@ -459,7 +459,7 @@ if [ "$ASSUME_YES" != "1" ] && [ "$DRY_RUN" != "1" ]; then
   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"
+  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
@@ -617,6 +617,7 @@ 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
@@ -766,7 +767,7 @@ rescue_one() {
 #
 # 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
+# polluting the personal/ overlay tree (where reindex would then try
 # to re-mirror them into core/).
 is_conflict_class() {
   local rel="$1"
@@ -813,7 +814,7 @@ conflict_one() {
 #   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.
+#                                   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).
@@ -893,11 +894,11 @@ is_cloud_flattened_symlink_equiv() {
   [ "$local_target" = "$upstream_target" ]
 }
 
-# True when $local_path is a symlink generated by master-sync.sh — those
+# 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 master-sync.sh run, so the
+# 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() {
@@ -957,20 +958,20 @@ process_one() {
       ;;
   esac
 
-  # Symlinks (mid-tree). master-sync.sh deterministically rebuilds the
+  # 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-master-sync symlinks (user-created,
+  # 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 master-sync symlink: $rel  ->  $(readlink "$local_path" 2>/dev/null || true)"
+        echo "    drop reindex 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
+        printf 'symlink-dropped\t%s\t(reindex regenerable)\n' "$rel" >> "$RESCUE_LOG" 2>/dev/null || true
       fi
     fi
     return 0
@@ -1035,6 +1036,31 @@ process_one() {
     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
@@ -1097,16 +1123,16 @@ walk_and_process() {
   # 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
+  # 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 master-sync symlink: $root_rel  ->  $(readlink "$root_abs" 2>/dev/null || true)"
+        echo "    drop reindex 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
+        printf 'symlink-dropped\t%s\t(reindex regenerable)\n' "$root_rel" >> "$RESCUE_LOG" 2>/dev/null || true
       fi
     fi
     return 0
@@ -1120,7 +1146,7 @@ walk_and_process() {
 
   # 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
+  # `-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.
@@ -1190,7 +1216,8 @@ if [ "$DRY_RUN" = "1" ]; then
   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"
+  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
@@ -1333,7 +1360,8 @@ 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"
+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
@@ -1367,7 +1395,8 @@ if [ "$DO_BACKUP" = "1" ] && [ -n "$BACKUP_DIR" ] && [ -d "$BACKUP_DIR" ]; then
     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"
+    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

package/src/cli/index.ts

@@ -25,9 +25,9 @@ export { promote } from "./promote.js";
 export type { PromoteOptions, PromoteResult } from "./promote.js";
 
 // Skill/personal-overlay mirroring + workers-registry regen (formerly the
-// hq-core master-sync.sh hook).
-export { masterSync, masterSyncScriptPath } from "./master-sync.js";
-export type { MasterSyncOptions, MasterSyncResult } from "./master-sync.js";
+// hq-core master-sync.sh hook; `hq reindex`).
+export { reindex, reindexScriptPath } from "./reindex.js";
+export type { ReindexOptions, ReindexResult } from "./reindex.js";
 
 // Drift-preserving HQ-core re-sync (formerly bundled only inside the HQ Sync
 // menubar app). Now shared between the app and `hq rescue`.

package/src/cli/{master-sync.test.ts → reindex.test.ts}

@@ -1,9 +1,9 @@
 /**
- * Unit tests for `hq master-sync` (the formerly-bash hq-core hook, now shipped
+ * Unit tests for `hq reindex` (the formerly-bash hq-core hook, now shipped
  * in this package and invoked via the CLI).
  *
- * The logic itself lives in scripts/master-sync.sh; these tests exercise it via
- * the masterSync() wrapper against a temp HQ tree, asserting the observable
+ * The logic itself lives in scripts/reindex.sh; these tests exercise it via
+ * the reindex() wrapper against a temp HQ tree, asserting the observable
  * filesystem outcomes (skill wrappers, personal-overlay mirroring) rather than
  * re-deriving the bash internals.
  */
@@ -12,17 +12,17 @@ import { describe, it, expect, beforeEach, afterEach } from "vitest";
 import * as fs from "fs";
 import * as path from "path";
 import * as os from "os";
-import { masterSync, masterSyncScriptPath } from "./master-sync.js";
+import { reindex, reindexScriptPath } from "./reindex.js";
 
-describe("masterSyncScriptPath", () => {
+describe("reindexScriptPath", () => {
   it("resolves to the bundled script and the file exists", () => {
-    const p = masterSyncScriptPath();
-    expect(p.endsWith(path.join("scripts", "master-sync.sh"))).toBe(true);
+    const p = reindexScriptPath();
+    expect(p.endsWith(path.join("scripts", "reindex.sh"))).toBe(true);
     expect(fs.existsSync(p)).toBe(true);
   });
 });
 
-describe("masterSync", () => {
+describe("reindex", () => {
   let root: string;
 
   beforeEach(() => {
@@ -44,7 +44,7 @@ describe("masterSync", () => {
     fs.writeFileSync(path.join(root, "core/skills/demo/helper.md"), "h\n");
     writeSkill("companies/acme/skills/widget");
 
-    const { status } = masterSync({ repoRoot: root });
+    const { status } = reindex({ repoRoot: root });
     expect(status).toBe(0);
 
     const coreWrapper = path.join(root, ".claude/skills/core:demo");
@@ -65,7 +65,7 @@ describe("masterSync", () => {
     fs.mkdirSync(path.join(root, "personal/policies"), { recursive: true });
     fs.writeFileSync(path.join(root, "personal/policies/myrule.md"), "rule\n");
 
-    const { status } = masterSync({ repoRoot: root });
+    const { status } = reindex({ repoRoot: root });
     expect(status).toBe(0);
 
     const link = path.join(root, "core/policies/myrule.md");
@@ -75,18 +75,18 @@ describe("masterSync", () => {
 
   it("prunes orphan managed wrappers when the source skill disappears", () => {
     writeSkill("core/skills/demo");
-    masterSync({ repoRoot: root });
+    reindex({ repoRoot: root });
     expect(fs.existsSync(path.join(root, ".claude/skills/core:demo"))).toBe(true);
 
     fs.rmSync(path.join(root, "core/skills/demo"), { recursive: true, force: true });
-    masterSync({ repoRoot: root });
+    reindex({ repoRoot: root });
     expect(fs.existsSync(path.join(root, ".claude/skills/core:demo"))).toBe(false);
   });
 
   it("is idempotent — a second run is a no-op", () => {
     writeSkill("core/skills/demo");
-    expect(masterSync({ repoRoot: root }).status).toBe(0);
-    expect(masterSync({ repoRoot: root }).status).toBe(0);
+    expect(reindex({ repoRoot: root }).status).toBe(0);
+    expect(reindex({ repoRoot: root }).status).toBe(0);
     expect(
       fs.readlinkSync(path.join(root, ".claude/skills/core:demo/SKILL.md")),
     ).toBe("../../../core/skills/demo/SKILL.md");

package/src/cli/reindex.ts

@@ -0,0 +1,57 @@
+/**
+ * hq reindex — surfaces namespaced skills as Claude Code skill wrappers,
+ * mirrors personal/{knowledge,policies,workers,settings} into core/, prunes
+ * orphan wrappers, and regenerates the workers registry.
+ *
+ * The implementation lives in scripts/reindex.sh, shipped with this package.
+ * This module resolves that script relative to the package (dist/cli → package
+ * root) and execs it against the caller's HQ root. Historically the script ran
+ * directly as a Claude Code hook inside hq-core (named "master-sync"); it now
+ * lives here so a single copy is maintained, and the hq-core hook is a thin
+ * shim over `hq reindex`.
+ */
+import { spawnSync } from "child_process";
+import { fileURLToPath } from "url";
+import path from "path";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/**
+ * Absolute path to the bundled reindex.sh. From the compiled module at
+ * dist/cli/reindex.js, the package root is two levels up; the script lives
+ * at <package-root>/scripts/reindex.sh.
+ */
+export function reindexScriptPath(): string {
+  return path.resolve(__dirname, "..", "..", "scripts", "reindex.sh");
+}
+
+export interface ReindexOptions {
+  /** HQ root to operate on. Defaults to process.cwd(). */
+  repoRoot?: string;
+}
+
+export interface ReindexResult {
+  /** Exit status of the underlying script (0 = success). */
+  status: number;
+}
+
+/**
+ * Run reindex against an HQ root. Synchronous — the script is cheap and
+ * idempotent, and callers (the hook shim, sync/rescue, tests) want the exit
+ * status. stdout/stderr from the script are forwarded to stderr so the
+ * caller's stdout stays clean (hooks must not emit stdout that the agent
+ * interprets).
+ */
+export function reindex(opts: ReindexOptions = {}): ReindexResult {
+  const repoRoot = opts.repoRoot ?? process.cwd();
+  const script = reindexScriptPath();
+  const res = spawnSync("bash", [script, repoRoot], {
+    stdio: ["ignore", "inherit", "inherit"],
+  });
+  if (res.error) {
+    process.stderr.write(`reindex: failed to run ${script}: ${res.error.message}\n`);
+    return { status: 1 };
+  }
+  return { status: res.status ?? 1 };
+}

package/src/cli/rescue-drift-reconcile.test.ts

@@ -0,0 +1,158 @@
+/**
+ * Integration test for the rescue convergence guard in scripts/replace-rescue.sh.
+ *
+ * Regression for the false `.drift-*` litter: in `history_floor` mode the
+ * rescue overlay flags a scaffold file as USER-EDIT whenever its blob differs
+ * from the *old* baseline (floor). HQ's own Stop hooks rewrite scaffold files
+ * every session, so a file routinely drifts from the floor yet lands
+ * byte-for-byte identical to the *new* upstream HEAD the overlay is about to
+ * write — and the old code rescued it into personal/ with a redundant
+ * `.drift-<ts>-<pid>` copy. The guard reclassifies "drifted from floor but
+ * identical to upstream HEAD" as UNCHANGED (no rescue).
+ *
+ * The script clones its source from GitHub, so we shim `git clone` to clone a
+ * local fixture repo instead. Everything runs under --dry-run (no destructive
+ * ops, no backup) and we assert the classification the script reports.
+ */
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { execFileSync, spawnSync } from "child_process";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+
+const RESCUE_SCRIPT = path.resolve(process.cwd(), "scripts/replace-rescue.sh");
+
+function hasGit(): boolean {
+  try {
+    execFileSync("git", ["--version"], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const gitAvailable = hasGit();
+
+describe.skipIf(!gitAvailable)("rescue drift convergence guard", () => {
+  let workDir: string;
+  let upstream: string;
+  let hqRoot: string;
+  let shimDir: string;
+  let floorSha: string;
+  let env: NodeJS.ProcessEnv;
+
+  const git = (cwd: string, ...args: string[]) =>
+    execFileSync("git", args, {
+      cwd,
+      stdio: ["ignore", "pipe", "pipe"],
+      env: {
+        ...process.env,
+        GIT_AUTHOR_NAME: "t",
+        GIT_AUTHOR_EMAIL: "t@t",
+        GIT_COMMITTER_NAME: "t",
+        GIT_COMMITTER_EMAIL: "t@t",
+      },
+    })
+      .toString()
+      .trim();
+
+  beforeAll(() => {
+    workDir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-rescue-drift-"));
+
+    // --- Build a local "upstream" repo: floor commit, then a HEAD commit
+    //     where core/x.md changed (v1 -> v2) and the others stayed put. ---
+    upstream = path.join(workDir, "upstream");
+    fs.mkdirSync(path.join(upstream, "core"), { recursive: true });
+    git(workDir, "init", "-b", "main", "upstream");
+    fs.writeFileSync(path.join(upstream, "core/x.md"), "v1\n");
+    fs.writeFileSync(path.join(upstream, "core/edited.md"), "base\n");
+    fs.writeFileSync(path.join(upstream, "core/keep.md"), "same\n");
+    git(upstream, "add", "-A");
+    git(upstream, "commit", "-m", "floor");
+    floorSha = git(upstream, "rev-parse", "HEAD");
+    // HEAD: only x.md advances.
+    fs.writeFileSync(path.join(upstream, "core/x.md"), "v2\n");
+    git(upstream, "add", "-A");
+    git(upstream, "commit", "-m", "head");
+
+    // --- Build the local HQ root being rescued. ---
+    hqRoot = path.join(workDir, "hq");
+    fs.mkdirSync(path.join(hqRoot, "core"), { recursive: true });
+    // `companies/` + `personal/` make it "look like" an HQ root (script guard);
+    // both are preserved (never walked).
+    fs.mkdirSync(path.join(hqRoot, "personal"), { recursive: true });
+    fs.mkdirSync(path.join(hqRoot, "companies"), { recursive: true });
+    // Drifted from floor ("v1") but byte-identical to upstream HEAD ("v2").
+    // OLD behavior: rescued to personal/x.md (+ .drift on collision).
+    // NEW behavior: reconciled as UNCHANGED — no rescue.
+    fs.writeFileSync(path.join(hqRoot, "core/x.md"), "v2\n");
+    // Genuinely user-edited: differs from both floor and HEAD -> still rescued.
+    fs.writeFileSync(path.join(hqRoot, "core/edited.md"), "MINE\n");
+    // Untouched vs floor -> UNCHANGED.
+    fs.writeFileSync(path.join(hqRoot, "core/keep.md"), "same\n");
+
+    // --- git shim: rewrite `git clone <github-url> dest` to the local fixture. ---
+    // Resolve the real git BEFORE the shim is on PATH so we don't recurse.
+    const realGit = execFileSync("bash", ["-lc", "command -v git"]).toString().trim() || "/usr/bin/git";
+    shimDir = path.join(workDir, "shim");
+    fs.mkdirSync(shimDir, { recursive: true });
+    const shim = `#!/usr/bin/env bash
+if [ "$1" = "clone" ]; then
+  args=()
+  for a in "$@"; do
+    case "$a" in
+      https://github.com/*) a=${JSON.stringify(upstream)} ;;
+    esac
+    args+=("$a")
+  done
+  exec ${JSON.stringify(realGit)} "\${args[@]}"
+fi
+exec ${JSON.stringify(realGit)} "$@"
+`;
+    fs.writeFileSync(path.join(shimDir, "git"), shim, { mode: 0o755 });
+
+    env = { ...process.env, PATH: `${shimDir}:${process.env.PATH ?? ""}` };
+  });
+
+  afterAll(() => {
+    if (workDir) fs.rmSync(workDir, { recursive: true, force: true });
+  });
+
+  function runRescue() {
+    return spawnSync(
+      "bash",
+      [
+        RESCUE_SCRIPT,
+        "--hq-root", hqRoot,
+        "--source", "test/repo",
+        "--ref", "main",
+        "--floor-sha", floorSha,
+        "--dry-run",
+        "--yes",
+        "--no-backup",
+      ],
+      { env, encoding: "utf-8" },
+    );
+  }
+
+  it("reconciles a floor-drifted file that is identical to upstream HEAD (no rescue)", () => {
+    const r = runRescue();
+    const out = `${r.stdout}\n${r.stderr}`;
+    // Sanity: ran in history_floor mode against our floor.
+    expect(r.status, out).toBe(0);
+    expect(out).toContain(`Baseline: ${floorSha}`);
+
+    // The drifted-but-identical-to-HEAD file is reconciled, NOT rescued.
+    expect(out).toContain("drift reconciled (identical to upstream HEAD; no rescue): core/x.md");
+    expect(out).not.toMatch(/user-edit \(rescue\): core\/x\.md/);
+
+    // The genuinely-edited file is still rescued into personal/.
+    expect(out).toContain("user-edit (rescue): core/edited.md  ->  personal/edited.md");
+
+    // Untouched file classified UNCHANGED.
+    expect(out).toContain("unchanged (delete + replace): core/keep.md");
+
+    // Summary reflects exactly one reconcile.
+    expect(out).toMatch(/drift reconciled \(== upstream\):\s+1 files/);
+  });
+});

package/src/cli/rescue.reindex.test.ts

@@ -0,0 +1,46 @@
+/**
+ * Wiring tests: `rescue()` runs `reindex()` after a successful, non-dry-run
+ * rescue so the generated skill wrappers / personal mirrors / workers registry
+ * are refreshed once core/ has been re-laid-down.
+ *
+ * child_process is mocked so the real replace-rescue.sh never runs, and
+ * ./reindex.js is mocked to a spy so we assert the call without spawning.
+ */
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+vi.mock("child_process", () => ({
+  spawnSync: vi.fn(() => ({ status: 0 })),
+}));
+vi.mock("./reindex.js", () => ({
+  reindex: vi.fn(() => ({ status: 0 })),
+}));
+
+import { spawnSync } from "child_process";
+import { reindex } from "./reindex.js";
+import { rescue } from "./rescue.js";
+
+describe("rescue → reindex", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    (spawnSync as unknown as ReturnType<typeof vi.fn>).mockReturnValue({ status: 0 });
+  });
+
+  it("refreshes via reindex after a successful rescue", () => {
+    const r = rescue({ hqRoot: "/tmp/hq", assumeYes: true });
+    expect(r.status).toBe(0);
+    expect(reindex).toHaveBeenCalledTimes(1);
+    expect(reindex).toHaveBeenCalledWith({ repoRoot: "/tmp/hq" });
+  });
+
+  it("does NOT run reindex on a dry-run", () => {
+    rescue({ hqRoot: "/tmp/hq", dryRun: true });
+    expect(reindex).not.toHaveBeenCalled();
+  });
+
+  it("does NOT run reindex when the rescue script fails", () => {
+    (spawnSync as unknown as ReturnType<typeof vi.fn>).mockReturnValueOnce({ status: 1 });
+    const r = rescue({ hqRoot: "/tmp/hq", assumeYes: true });
+    expect(r.status).toBe(1);
+    expect(reindex).not.toHaveBeenCalled();
+  });
+});

package/src/cli/rescue.ts

@@ -17,6 +17,7 @@
 import { spawnSync } from "child_process";
 import { fileURLToPath } from "url";
 import path from "path";
+import { reindex } from "./reindex.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -118,5 +119,18 @@ export function rescue(opts: RescueOptions = {}): RescueResult {
     process.stderr.write(`rescue: failed to run ${script}: ${res.error.message}\n`);
     return { status: 1 };
   }
-  return { status: res.status ?? 1 };
+  const status = res.status ?? 1;
+  // A successful, non-dry-run rescue re-lays-down core/, so refresh the
+  // generated skill wrappers, personal-overlay mirrors, and workers registry.
+  // Best-effort + idempotent — never overrides the rescue's own exit status.
+  // repoRoot falls back to process.cwd() (reindex's default) when hqRoot is
+  // omitted, matching the rescue script's own cwd-based default.
+  if (status === 0 && !opts.dryRun) {
+    try {
+      reindex({ repoRoot: opts.hqRoot });
+    } catch {
+      // best-effort
+    }
+  }
+  return { status };
 }