@indigoai-us/hq-cloud 6.1.0 → 6.2.0

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-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;
+}

package/src/lib/conflict.test.ts

@@ -16,6 +16,7 @@ import {
 import {
   appendConflictEntry,
   getConflictIndexPath,
+  pruneConflictIndex,
   readConflictIndex,
   removeConflictEntry,
   writeConflictIndex,
@@ -142,3 +143,173 @@ describe("conflict index", () => {
     expect(idx.conflicts).toEqual([]);
   });
 });
+
+describe("pruneConflictIndex", () => {
+  let tmpHq: string;
+
+  beforeEach(() => {
+    tmpHq = fs.mkdtempSync(path.join(os.tmpdir(), "hq-cprune-"));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpHq, { recursive: true, force: true });
+  });
+
+  /** Write a file at a hq-relative path, creating parent dirs. */
+  function put(rel: string, content: string): void {
+    const abs = path.join(tmpHq, rel);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, content);
+  }
+
+  /** Write a symlink at a hq-relative path pointing at `target` (verbatim). */
+  function putLink(rel: string, target: string): void {
+    const abs = path.join(tmpHq, rel);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.symlinkSync(target, abs);
+  }
+
+  /**
+   * Build an entry whose original/conflict paths are derived from `id` so each
+   * row addresses distinct files on disk (the shared `entry()` helper above
+   * reuses one fixed path pair, which would collide across rows here).
+   */
+  function rowFor(id: string): ConflictIndexEntry {
+    return {
+      id,
+      originalPath: `dir/${id}.md`,
+      conflictPath: `dir/${id}.md.conflict-2026-04-27T22-05-14Z-abc123.md`,
+      detectedAt: "2026-04-27T22:05:14Z",
+      side: "pull",
+      machineId: "abc123",
+      localHash: "local",
+      remoteHash: "remote",
+    };
+  }
+
+  it("returns a zeroed result and writes nothing for an empty/absent index", () => {
+    const res = pruneConflictIndex(tmpHq);
+    expect(res).toEqual({
+      prunedOrphans: 0,
+      prunedIdentical: 0,
+      removedMirrors: 0,
+      kept: 0,
+    });
+    expect(fs.existsSync(getConflictIndexPath(tmpHq))).toBe(false);
+  });
+
+  it("drops a row whose .conflict-* mirror no longer exists (orphan)", () => {
+    const row = rowFor("orphan");
+    put(row.originalPath, "still here");
+    // No mirror file on disk.
+    writeConflictIndex(tmpHq, { version: 1, conflicts: [row] });
+
+    const res = pruneConflictIndex(tmpHq);
+    expect(res.prunedOrphans).toBe(1);
+    expect(res.kept).toBe(0);
+    expect(readConflictIndex(tmpHq).conflicts).toHaveLength(0);
+  });
+
+  it("drops a byte-identical row and deletes its mirror file", () => {
+    const row = rowFor("identical");
+    put(row.originalPath, "same bytes");
+    put(row.conflictPath, "same bytes");
+    writeConflictIndex(tmpHq, { version: 1, conflicts: [row] });
+
+    const res = pruneConflictIndex(tmpHq);
+    expect(res.prunedIdentical).toBe(1);
+    expect(res.removedMirrors).toBe(1);
+    expect(readConflictIndex(tmpHq).conflicts).toHaveLength(0);
+    expect(fs.existsSync(path.join(tmpHq, row.conflictPath))).toBe(false);
+    // The user's original is never touched.
+    expect(fs.existsSync(path.join(tmpHq, row.originalPath))).toBe(true);
+  });
+
+  it("keeps a genuinely divergent row and leaves both files in place", () => {
+    const row = rowFor("real");
+    put(row.originalPath, "local edit");
+    put(row.conflictPath, "remote edit");
+    writeConflictIndex(tmpHq, { version: 1, conflicts: [row] });
+
+    const res = pruneConflictIndex(tmpHq);
+    expect(res.kept).toBe(1);
+    expect(res.prunedIdentical).toBe(0);
+    expect(res.prunedOrphans).toBe(0);
+    expect(readConflictIndex(tmpHq).conflicts.map((c) => c.id)).toEqual(["real"]);
+    expect(fs.existsSync(path.join(tmpHq, row.conflictPath))).toBe(true);
+  });
+
+  it("keeps a row whose original is missing (local-delete divergence)", () => {
+    const row = rowFor("deleted-local");
+    // No original; mirror present.
+    put(row.conflictPath, "remote bytes");
+    writeConflictIndex(tmpHq, { version: 1, conflicts: [row] });
+
+    const res = pruneConflictIndex(tmpHq);
+    expect(res.kept).toBe(1);
+    expect(readConflictIndex(tmpHq).conflicts).toHaveLength(1);
+  });
+
+  it("treats two symlinks with the same target as identical, differing targets as a conflict", () => {
+    const same = rowFor("link-same");
+    putLink(same.originalPath, "../target/a");
+    putLink(same.conflictPath, "../target/a");
+
+    const diff = rowFor("link-diff");
+    putLink(diff.originalPath, "../target/a");
+    putLink(diff.conflictPath, "../target/b");
+
+    writeConflictIndex(tmpHq, { version: 1, conflicts: [same, diff] });
+
+    const res = pruneConflictIndex(tmpHq);
+    expect(res.prunedIdentical).toBe(1);
+    expect(res.kept).toBe(1);
+    expect(readConflictIndex(tmpHq).conflicts.map((c) => c.id)).toEqual([
+      "link-diff",
+    ]);
+  });
+
+  it("partitions a mixed batch and preserves only the real conflicts", () => {
+    const orphan = rowFor("orphan");
+    put(orphan.originalPath, "x"); // mirror missing
+
+    const identical = rowFor("identical");
+    put(identical.originalPath, "dup");
+    put(identical.conflictPath, "dup");
+
+    const real = rowFor("real");
+    put(real.originalPath, "L");
+    put(real.conflictPath, "R");
+
+    writeConflictIndex(tmpHq, {
+      version: 1,
+      conflicts: [orphan, identical, real],
+    });
+
+    const res = pruneConflictIndex(tmpHq);
+    expect(res).toEqual({
+      prunedOrphans: 1,
+      prunedIdentical: 1,
+      removedMirrors: 1,
+      kept: 1,
+    });
+    expect(readConflictIndex(tmpHq).conflicts.map((c) => c.id)).toEqual(["real"]);
+  });
+
+  it("does not rewrite the index file when nothing is pruned", () => {
+    const real = rowFor("real");
+    put(real.originalPath, "L");
+    put(real.conflictPath, "R");
+    writeConflictIndex(tmpHq, { version: 1, conflicts: [real] });
+
+    const indexPath = getConflictIndexPath(tmpHq);
+    const before = fs.statSync(indexPath).mtimeMs;
+    // Advance the clock past filesystem mtime granularity, then prune.
+    const spin = Date.now() + 20;
+    while (Date.now() < spin) {
+      /* busy-wait ~20ms so a rewrite would move mtime */
+    }
+    pruneConflictIndex(tmpHq);
+    expect(fs.statSync(indexPath).mtimeMs).toBe(before);
+  });
+});