@indigoai-us/hq-cloud 6.1.0 → 6.2.1

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

@@ -1,5 +1,5 @@
 /**
- * Integration test for the rescue convergence guard in scripts/replace-rescue.sh.
+ * Integration test for the rescue convergence guard in src/cli/rescue-core.ts.
  *
  * Regression for the false `.drift-*` litter: in `history_floor` mode the
  * rescue overlay flags a scaffold file as USER-EDIT whenever its blob differs
@@ -10,17 +10,16 @@
  * `.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
+ * The rescue 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.
+ * ops, no backup) and we assert the classification the rescue reports.
  */
 import { describe, it, expect, beforeAll, afterAll } from "vitest";
-import { execFileSync, spawnSync } from "child_process";
+import { execFileSync } 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");
+import { runRescue } from "./rescue-core.js";
 
 function hasGit(): boolean {
   try {
@@ -33,6 +32,30 @@ function hasGit(): boolean {
 
 const gitAvailable = hasGit();
 
+/** Run the rescue in-process, capturing its stdout/stderr. */
+function runRescueCapture(argv: string[], env: NodeJS.ProcessEnv) {
+  let stdout = "";
+  let stderr = "";
+  const origOut = process.stdout.write.bind(process.stdout);
+  const origErr = process.stderr.write.bind(process.stderr);
+  process.stdout.write = ((chunk: unknown) => {
+    stdout += String(chunk);
+    return true;
+  }) as typeof process.stdout.write;
+  process.stderr.write = ((chunk: unknown) => {
+    stderr += String(chunk);
+    return true;
+  }) as typeof process.stderr.write;
+  let status: number;
+  try {
+    status = runRescue(argv, { env }).status;
+  } finally {
+    process.stdout.write = origOut;
+    process.stderr.write = origErr;
+  }
+  return { status, stdout, stderr };
+}
+
 describe.skipIf(!gitAvailable)("rescue drift convergence guard", () => {
   let workDir: string;
   let upstream: string;
@@ -118,11 +141,9 @@ exec ${JSON.stringify(realGit)} "$@"
     if (workDir) fs.rmSync(workDir, { recursive: true, force: true });
   });
 
-  function runRescue() {
-    return spawnSync(
-      "bash",
+  function runRescueDry() {
+    return runRescueCapture(
       [
-        RESCUE_SCRIPT,
         "--hq-root", hqRoot,
         "--source", "test/repo",
         "--ref", "main",
@@ -131,12 +152,12 @@ exec ${JSON.stringify(realGit)} "$@"
         "--yes",
         "--no-backup",
       ],
-      { env, encoding: "utf-8" },
+      env,
     );
   }
 
   it("reconciles a floor-drifted file that is identical to upstream HEAD (no rescue)", () => {
-    const r = runRescue();
+    const r = runRescueDry();
     const out = `${r.stdout}\n${r.stderr}`;
     // Sanity: ran in history_floor mode against our floor.
     expect(r.status, out).toBe(0);

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

@@ -0,0 +1,156 @@
+/**
+ * Regression for the rescue → sync-journal stale-baseline bug.
+ *
+ * Root cause: the rescue overlay rewrites scaffold files from upstream but
+ * never re-stamps the personal-vault sync journal. The journal keeps the
+ * PRE-rescue hash, so the next sync reads localHash != journal.hash ("local
+ * changed") and — when the vault also moved — mints a false `.conflict-*`
+ * mirror. `runRescue` now re-stamps the journal baseline for the files the
+ * overlay actually re-laid (scoped to rsync `-i` itemize output, so a user's
+ * pending edit is never touched).
+ *
+ * This test seeds a journal whose entry for an overlaid file carries the OLD
+ * hash, runs a real (non-dry-run) rescue, and asserts the entry was re-stamped
+ * to the freshly laid-down content — i.e. `localChanged` would now be false.
+ */
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { execFileSync } from "child_process";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { runRescue } from "./rescue-core.js";
+import {
+  hashFile,
+  readJournal,
+  writeJournal,
+  PERSONAL_VAULT_JOURNAL_SLUG,
+} from "../journal.js";
+
+function hasGit(): boolean {
+  try {
+    execFileSync("git", ["--version"], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+const gitAvailable = hasGit();
+
+function runRescueCapture(argv: string[], env: NodeJS.ProcessEnv) {
+  let stdout = "";
+  const origOut = process.stdout.write.bind(process.stdout);
+  const origErr = process.stderr.write.bind(process.stderr);
+  process.stdout.write = ((c: unknown) => ((stdout += String(c)), true)) as typeof process.stdout.write;
+  process.stderr.write = (() => true) as typeof process.stderr.write;
+  let status: number;
+  try {
+    status = runRescue(argv, { env }).status;
+  } finally {
+    process.stdout.write = origOut;
+    process.stderr.write = origErr;
+  }
+  return { status, stdout };
+}
+
+describe.skipIf(!gitAvailable)("rescue re-stamps sync-journal baseline for re-laid files", () => {
+  let workDir: string, upstream: string, hqRoot: string, stateDir: string, floorSha: string;
+  let env: NodeJS.ProcessEnv;
+  let savedStateDir: string | undefined;
+
+  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-journal-"));
+
+    // upstream: floor (doc.md=v1), then HEAD advances doc.md -> v2.
+    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/doc.md"), "v1\n");
+    git(upstream, "add", "-A");
+    git(upstream, "commit", "-m", "floor");
+    floorSha = git(upstream, "rev-parse", "HEAD");
+    fs.writeFileSync(path.join(upstream, "core/doc.md"), "v2\n");
+    git(upstream, "add", "-A");
+    git(upstream, "commit", "-m", "head");
+
+    // local HQ root: doc.md == floor (v1) -> rescue overlays it to HEAD (v2).
+    hqRoot = path.join(workDir, "hq");
+    fs.mkdirSync(path.join(hqRoot, "core"), { recursive: true });
+    fs.mkdirSync(path.join(hqRoot, "personal"), { recursive: true });
+    fs.mkdirSync(path.join(hqRoot, "companies"), { recursive: true });
+    const docAbs = path.join(hqRoot, "core/doc.md");
+    fs.writeFileSync(docAbs, "v1\n");
+
+    // state dir + seeded personal-vault journal carrying the STALE (v1) hash.
+    stateDir = path.join(workDir, "state");
+    fs.mkdirSync(stateDir, { recursive: true });
+    savedStateDir = process.env.HQ_STATE_DIR;
+    process.env.HQ_STATE_DIR = stateDir; // getStateDir() reads process.env
+    const staleHash = hashFile(docAbs); // hash of v1
+    writeJournal(PERSONAL_VAULT_JOURNAL_SLUG, {
+      version: "2",
+      lastSync: new Date(0).toISOString(),
+      files: {
+        "core/doc.md": {
+          hash: staleHash,
+          size: fs.statSync(docAbs).size,
+          syncedAt: new Date(0).toISOString(),
+          direction: "down",
+          remoteEtag: "seed-etag",
+          mtimeMs: fs.statSync(docAbs).mtimeMs,
+        },
+      },
+      pulls: [],
+    } as never);
+
+    // git shim: redirect `git clone <github-url>` to the local fixture.
+    const realGit = execFileSync("bash", ["-lc", "command -v git"]).toString().trim() || "/usr/bin/git";
+    const shimDir = path.join(workDir, "shim");
+    fs.mkdirSync(shimDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(shimDir, "git"),
+      `#!/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)} "$@"
+`,
+      { mode: 0o755 },
+    );
+    env = { ...process.env, PATH: `${shimDir}:${process.env.PATH ?? ""}`, HQ_STATE_DIR: stateDir };
+  });
+
+  afterAll(() => {
+    if (savedStateDir === undefined) delete process.env.HQ_STATE_DIR;
+    else process.env.HQ_STATE_DIR = savedStateDir;
+    if (workDir) fs.rmSync(workDir, { recursive: true, force: true });
+  });
+
+  it("re-stamps the journal so the overlaid file is no longer seen as locally changed", () => {
+    const docAbs = path.join(hqRoot, "core/doc.md");
+    const staleHash = readJournal(PERSONAL_VAULT_JOURNAL_SLUG).files["core/doc.md"].hash;
+
+    const r = runRescueCapture(
+      ["--hq-root", hqRoot, "--source", "test/repo", "--ref", "main", "--floor-sha", floorSha, "--yes", "--no-backup"],
+      env,
+    );
+    expect(r.status, r.stdout).toBe(0);
+
+    // overlay actually re-laid the file (v1 -> v2)
+    expect(fs.readFileSync(docAbs, "utf-8")).toBe("v2\n");
+
+    // journal entry was re-stamped to the NEW content's hash
+    const entry = readJournal(PERSONAL_VAULT_JOURNAL_SLUG).files["core/doc.md"];
+    expect(entry.hash).toBe(hashFile(docAbs)); // == hash(v2): localChanged would be FALSE
+    expect(entry.hash).not.toBe(staleHash); // proves it changed from the stale v1 baseline
+    expect(entry.remoteEtag).toBe("seed-etag"); // remote side untouched -> clean push/converge, not conflict
+    expect(r.stdout).toContain("Reconciled sync-journal baseline");
+  });
+});

package/src/cli/rescue-mtime-preserve.test.ts

@@ -1,6 +1,6 @@
 /**
  * Integration regression for the rescue mtime-preservation fix in
- * scripts/replace-rescue.sh.
+ * src/cli/rescue-core.ts.
  *
  * The bug: rescue rebuilds the tree by `git clone` + `rsync -a`. A git
  * checkout stamps every file with clone-time (git stores no per-file mtimes),
@@ -9,24 +9,23 @@
  * this: hundreds of files sharing one mtime, mtime == ctime == birth).
  *
  * The fix has three parts, all asserted below:
- *   - Layer 1: UNCHANGED files are left in place; the --checksum overlay skips
- *     them, so their existing mtime survives.
+ *   - Layer 1: UNCHANGED files are left in place; the overlay excludes them, so
+ *     their existing mtime survives.
  *   - Layer 2: files the overlay DOES write (upstream-changed, brand-new) get
  *     the git committer-date of their last-modifying commit, not wall-clock.
  *   - Layer 3: full history is used (history_floor mode clones full history;
  *     the shallow path unshallows) so per-file commit times are real.
  *
- * The script clones from GitHub, so we shim `git clone` to a local fixture
+ * The rescue clones from GitHub, so we shim `git clone` to a local fixture
  * (same technique as rescue-drift-reconcile.test.ts) and run for real
  * (non-dry-run, --no-backup) so the overlay actually lays files down.
  */
 import { describe, it, expect, beforeAll, afterAll } from "vitest";
-import { execFileSync, spawnSync } from "child_process";
+import { execFileSync } 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");
+import { runRescue } from "./rescue-core.js";
 
 function has(bin: string, ...args: string[]): boolean {
   try {
@@ -37,15 +36,39 @@ function has(bin: string, ...args: string[]): boolean {
   }
 }
 
-// Needs git (fixture + clone), rsync (overlay), and perl (the utime pass).
-const toolsAvailable =
-  has("git", "--version") && has("rsync", "--version") && has("perl", "-e", "1");
+// Needs git (fixture + clone) and rsync (overlay). The mtime restore is now
+// native (fs.utimesSync), so perl is no longer required.
+const toolsAvailable = has("git", "--version") && has("rsync", "--version");
 
 // Fixed commit epochs so assertions are exact and machine-independent.
 const FLOOR_EPOCH = 1577836800; // 2020-01-01T00:00:00Z
 const HEAD_EPOCH = 1609459200; // 2021-01-01T00:00:00Z
 const KEEP_PRESET_EPOCH = 1546300800; // 2019-01-01T00:00:00Z (local, pre-rescue)
 
+/** Run the rescue in-process, capturing its stdout/stderr. */
+function runRescueCapture(argv: string[], env: NodeJS.ProcessEnv) {
+  let stdout = "";
+  let stderr = "";
+  const origOut = process.stdout.write.bind(process.stdout);
+  const origErr = process.stderr.write.bind(process.stderr);
+  process.stdout.write = ((chunk: unknown) => {
+    stdout += String(chunk);
+    return true;
+  }) as typeof process.stdout.write;
+  process.stderr.write = ((chunk: unknown) => {
+    stderr += String(chunk);
+    return true;
+  }) as typeof process.stderr.write;
+  let status: number;
+  try {
+    status = runRescue(argv, { env }).status;
+  } finally {
+    process.stdout.write = origOut;
+    process.stderr.write = origErr;
+  }
+  return { status, stdout, stderr };
+}
+
 describe.skipIf(!toolsAvailable)("rescue preserves mtimes (no clone-time flattening)", () => {
   let workDir: string;
   let upstream: string;
@@ -129,10 +152,8 @@ exec ${JSON.stringify(realGit)} "$@"
     env = { ...process.env, PATH: `${shimDir}:${process.env.PATH ?? ""}` };
 
     // --- run the real rescue (non-dry-run) ----------------------------------
-    const r = spawnSync(
-      "bash",
+    const r = runRescueCapture(
       [
-        RESCUE_SCRIPT,
         "--hq-root", hqRoot,
         "--source", "test/repo",
         "--ref", "main",
@@ -140,9 +161,9 @@ exec ${JSON.stringify(realGit)} "$@"
         "--yes",
         "--no-backup",
       ],
-      { env, encoding: "utf-8" },
+      env,
     );
-    // Surface script output on failure for debuggability.
+    // Surface output on failure for debuggability.
     if (r.status !== 0) {
       throw new Error(`rescue failed (${r.status}):\n${r.stdout}\n${r.stderr}`);
     }

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

@@ -3,26 +3,27 @@
  * 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.
+ * The rescue algorithm (./rescue-core.js) is mocked so no real clone/overlay
+ * runs, and ./reindex.js is mocked to a spy so we assert the call without
+ * touching disk.
  */
 import { describe, it, expect, vi, beforeEach } from "vitest";
 
-vi.mock("child_process", () => ({
-  spawnSync: vi.fn(() => ({ status: 0 })),
+vi.mock("./rescue-core.js", () => ({
+  runRescue: vi.fn(() => ({ status: 0 })),
 }));
 vi.mock("./reindex.js", () => ({
   reindex: vi.fn(() => ({ status: 0 })),
 }));
 
-import { spawnSync } from "child_process";
+import { runRescue } from "./rescue-core.js";
 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 });
+    (runRescue as unknown as ReturnType<typeof vi.fn>).mockReturnValue({ status: 0 });
   });
 
   it("refreshes via reindex after a successful rescue", () => {
@@ -37,8 +38,8 @@ describe("rescue → reindex", () => {
     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 });
+  it("does NOT run reindex when the rescue fails", () => {
+    (runRescue 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.test.ts

@@ -1,15 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { buildRescueArgs, rescueScriptPath } from "./rescue.js";
-
-describe("rescueScriptPath", () => {
-  it("resolves to the bundled script at the package root", () => {
-    const p = rescueScriptPath();
-    expect(p.endsWith("scripts/replace-rescue.sh")).toBe(true);
-    // From dist/cli/rescue.js the package root is two levels up; ensure we
-    // don't accidentally point inside dist/.
-    expect(p).not.toContain("/dist/scripts/");
-  });
-});
+import { buildRescueArgs } from "./rescue.js";
 
 describe("buildRescueArgs", () => {
   it("emits no args for an empty option set (script defaults apply)", () => {

package/src/cli/rescue.ts

@@ -2,34 +2,18 @@
  * hq rescue — re-sync a local HQ tree to an upstream hq-core release (or a
  * staging branch) WITHOUT destroying the user's local edits ("drift").
  *
- * The implementation lives in scripts/replace-rescue.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. The script was
- * historically bundled inside the HQ Sync menubar app; it now lives here so a
- * single copy is maintained and BOTH consumers — the menubar app (which
- * bundles this package's copy) and `@indigoai-us/hq-cli`'s `hq rescue`
- * command — drive the exact same rescue logic.
+ * The implementation is native TypeScript in ./rescue-core.ts (the former
+ * scripts/replace-rescue.sh, ported and removed). This module owns the public
+ * option surface + flag mapping and the post-rescue reindex wiring; the heavy
+ * classify/overlay/stamp algorithm lives in rescue-core. BOTH consumers — the
+ * HQ Sync menubar app (which spawns `hq-rescue` from this package) and
+ * `@indigoai-us/hq-cli`'s `hq rescue` command — drive the exact same logic.
  *
- * The script is channel-agnostic: `--source <repo>` + `--ref <tag|branch>`
- * select prod vs staging, and `--floor-sha` pins the three-way history floor.
- * See scripts/replace-rescue.sh for the full classify/overlay/stamp algorithm.
+ * Channel-agnostic: `--source <repo>` + `--ref <tag|branch>` select prod vs
+ * staging, and `--floor-sha` pins the three-way history floor.
  */
-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);
-
-/**
- * Absolute path to the bundled replace-rescue.sh. From the compiled module at
- * dist/cli/rescue.js, the package root is two levels up; the script lives at
- * <package-root>/scripts/replace-rescue.sh.
- */
-export function rescueScriptPath(): string {
-  return path.resolve(__dirname, "..", "..", "scripts", "replace-rescue.sh");
-}
+import { runRescue } from "./rescue-core.js";
 
 export interface RescueOptions {
   /** HQ root to operate on. Passed as `--hq-root`. Defaults to the script's
@@ -101,25 +85,16 @@ export function buildRescueArgs(opts: RescueOptions = {}): string[] {
 }
 
 /**
- * Run the rescue script against an HQ root. Synchronous — the script is
- * long-running (clone + scan) and callers want the exit status + live output.
- * stdout/stderr from the script are inherited so the user sees the scan log
- * and the confirmation prompt (unless `assumeYes` is set).
+ * Run the rescue against an HQ root. Synchronous — the work is long-running
+ * (clone + scan + overlay) and callers want the exit status + live output.
+ * stdout/stderr are written directly so the user sees the scan log and the
+ * confirmation prompt (unless `assumeYes` is set).
  */
 export function rescue(opts: RescueOptions = {}): RescueResult {
-  const script = rescueScriptPath();
   const args = buildRescueArgs(opts);
-  const env = { ...process.env };
+  const env: NodeJS.ProcessEnv = { ...process.env };
   if (opts.ghToken) env.GH_TOKEN = opts.ghToken;
-  const res = spawnSync("bash", [script, ...args], {
-    stdio: "inherit",
-    env,
-  });
-  if (res.error) {
-    process.stderr.write(`rescue: failed to run ${script}: ${res.error.message}\n`);
-    return { status: 1 };
-  }
-  const status = res.status ?? 1;
+  const { status } = runRescue(args, { env });
   // 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.

package/src/index.ts

@@ -213,11 +213,11 @@ export { promote } from "./cli/index.js";
 export type { PromoteOptions, PromoteResult } from "./cli/index.js";
 
 // Skill/personal-overlay mirroring + workers-registry regen (`hq reindex`).
-export { reindex, reindexScriptPath } from "./cli/index.js";
+export { reindex } from "./cli/index.js";
 export type { ReindexOptions, ReindexResult } from "./cli/index.js";
 
 // Drift-preserving HQ-core re-sync — shared by the HQ Sync app and `hq rescue`.
-export { rescue, rescueScriptPath, buildRescueArgs } from "./cli/index.js";
+export { rescue, buildRescueArgs } from "./cli/index.js";
 export type { RescueOptions, RescueResult } from "./cli/index.js";
 
 export type {

package/src/lib/conflict-index.ts

@@ -125,3 +125,149 @@ export function removeConflictEntry(hqRoot: string, id: string): void {
   if (filtered.length === index.conflicts.length) return;
   writeConflictIndex(hqRoot, { version: index.version, conflicts: filtered });
 }
+
+/** Summary of what a {@link pruneConflictIndex} pass reclaimed. */
+export interface PruneConflictIndexResult {
+  /** Rows dropped because their `.conflict-*` mirror no longer exists. */
+  prunedOrphans: number;
+  /** Rows dropped because the original file and its mirror are byte-identical. */
+  prunedIdentical: number;
+  /** Byte-identical mirror files deleted from disk during the pass. */
+  removedMirrors: number;
+  /** Rows kept (genuine divergence, or unprovable — fail-safe retained). */
+  kept: number;
+}
+
+/**
+ * Byte-identity check used by the prune pass. Symlink-aware: two symlinks are
+ * identical iff their link targets match (mirroring how the detector hashes a
+ * symlink record — `hashSymlinkTarget`, not the followed content). A symlink
+ * compared against a regular file is never identical. Regular files reject on a
+ * size mismatch first (cheap), then compare full bytes.
+ *
+ * Throws if either side can't be read — callers treat that as "unprovable" and
+ * keep the entry rather than risk dropping a real conflict.
+ */
+function entryFilesAreIdentical(
+  aPath: string,
+  aStat: fs.Stats,
+  bPath: string,
+  bStat: fs.Stats,
+): boolean {
+  const aLink = aStat.isSymbolicLink();
+  const bLink = bStat.isSymbolicLink();
+  if (aLink || bLink) {
+    if (aLink !== bLink) return false;
+    return fs.readlinkSync(aPath) === fs.readlinkSync(bPath);
+  }
+  if (aStat.size !== bStat.size) return false;
+  return fs.readFileSync(aPath).equals(fs.readFileSync(bPath));
+}
+
+/**
+ * Garbage-collect the conflict index so it self-heals instead of growing
+ * without bound. Before this pass existed the ledger only ever shrank when a
+ * human resolved a conflict via `/resolve-conflicts`; every false positive and
+ * every orphaned row lingered forever, so the index over-reported the real
+ * pending-conflict count (the menubar's journal-derived count stayed correct,
+ * but `.hq-conflicts/index.json` did not).
+ *
+ * Two classes of entry are dropped — both provably not a pending conflict:
+ *
+ *   1. **Orphaned** — the `.conflict-*` mirror file is gone from disk. The
+ *      mirror is the only artifact a human resolves against; once it's missing
+ *      the row can never be acted on, so it's pure litter (the "missing-cloud"
+ *      rows operators reported climbing into the dozens).
+ *
+ *   2. **Byte-identical false positives** — the original file and its conflict
+ *      mirror both still exist and are byte-for-byte identical. The mirror
+ *      holds the remote bytes captured at detection time, so identical bytes
+ *      mean there was never a real divergence (this is exactly the manual
+ *      safe-purge operators have been doing by hand). The stale mirror file is
+ *      deleted and the row dropped.
+ *
+ * Conservative by construction — an entry is kept whenever it might be a real
+ * conflict: the original file is missing (a genuine local-delete-vs-remote
+ * divergence), the bytes differ, or either side can't be read. The index file
+ * is only rewritten when at least one row is actually dropped, so a clean
+ * ledger keeps its mtime untouched.
+ */
+export function pruneConflictIndex(hqRoot: string): PruneConflictIndexResult {
+  const result: PruneConflictIndexResult = {
+    prunedOrphans: 0,
+    prunedIdentical: 0,
+    removedMirrors: 0,
+    kept: 0,
+  };
+
+  const index = readConflictIndex(hqRoot);
+  if (index.conflicts.length === 0) return result;
+
+  const kept: ConflictIndexEntry[] = [];
+  const mirrorsToRemove: string[] = [];
+
+  for (const entry of index.conflicts) {
+    const mirrorAbs = path.join(hqRoot, entry.conflictPath);
+    const originalAbs = path.join(hqRoot, entry.originalPath);
+
+    let mirrorStat: fs.Stats;
+    try {
+      mirrorStat = fs.lstatSync(mirrorAbs);
+    } catch {
+      // Mirror is gone — orphaned row, drop it. Nothing on disk to clean up.
+      result.prunedOrphans++;
+      continue;
+    }
+
+    // Both sides must exist to compare. A missing original is a real
+    // local-delete divergence — keep it for the human to resolve.
+    let originalStat: fs.Stats;
+    try {
+      originalStat = fs.lstatSync(originalAbs);
+    } catch {
+      kept.push(entry);
+      result.kept++;
+      continue;
+    }
+
+    let identical: boolean;
+    try {
+      identical = entryFilesAreIdentical(
+        originalAbs,
+        originalStat,
+        mirrorAbs,
+        mirrorStat,
+      );
+    } catch {
+      // Couldn't read one side — fail safe, keep the row.
+      kept.push(entry);
+      result.kept++;
+      continue;
+    }
+
+    if (identical) {
+      result.prunedIdentical++;
+      mirrorsToRemove.push(mirrorAbs);
+    } else {
+      kept.push(entry);
+      result.kept++;
+    }
+  }
+
+  // No row dropped → leave the file (and its mtime) untouched.
+  if (kept.length === index.conflicts.length) return result;
+
+  // Delete the byte-identical mirror litter. Best-effort: a leftover identical
+  // mirror is cosmetic, never corrupting, so a failed unlink doesn't abort.
+  for (const mirrorAbs of mirrorsToRemove) {
+    try {
+      fs.rmSync(mirrorAbs, { force: true });
+      result.removedMirrors++;
+    } catch {
+      /* best-effort cleanup */
+    }
+  }
+
+  writeConflictIndex(hqRoot, { version: index.version, conflicts: kept });
+  return result;
+}