@indigoai-us/hq-cloud 6.15.0 → 6.15.2

package/src/qmd-reindex.test.ts

@@ -1,877 +0,0 @@
-/**
- * Unit tests for reindexAfterSync.
- *
- * The function shells out to the global `qmd` binary, so every test injects a
- * fake `exec` that records the calls and returns canned results — no real qmd
- * is invoked. We assert on the *sequence of qmd commands* the function would
- * run, which is the contract that keeps a teammate's index fresh after sync.
- *
- * Corruption-safety tests pin feedback_b9a369ff + feedback_332c7ccc (resolved
- * index path, dual-lock, honest quarantine). Path-drift tests pin
- * feedback_f8e233c6 (detect-only by default; opt-in repair).
- */
-
-import { describe, it, expect } from "vitest";
-import * as fs from "fs";
-import * as os from "os";
-import * as path from "path";
-import {
-  reindexAfterSync,
-  looksCorrupt,
-  resolveExecTimeoutMs,
-  DEFAULT_QMD_EXEC_TIMEOUT_MS,
-  parseIndexDirFromStatus,
-  parseCollectionPathFromShow,
-  pathsEquivalent,
-  repairPathDriftEnabled,
-  acquireDualReindexLocks,
-  type QmdExec,
-  type QmdExecResult,
-  type AcquireReindexLock,
-  type QuarantineCorruptIndex,
-} from "./qmd-reindex.js";
-
-/** A lock acquirer that always succeeds — keeps command-sequence tests pure. */
-const noLock: AcquireReindexLock = () => ({ release() {} });
-
-/** Identity realpath so path-drift comparisons stay deterministic in fakes. */
-const identityRealpath = (p: string) => path.resolve(p);
-
-/** Build a fake exec that returns status 0 for everything and logs calls. */
-function fakeExec(opts?: {
-  listStdout?: string;
-  statusStdout?: string;
-  failOn?: string;
-  resultFor?: (args: string[]) => Partial<QmdExecResult> | undefined;
-}): {
-  exec: QmdExec;
-  calls: string[][];
-} {
-  const calls: string[][] = [];
-  const exec: QmdExec = (args) => {
-    calls.push(args);
-    const override = opts?.resultFor?.(args);
-    if (override) return { status: 0, stdout: "", ...override };
-    if (opts?.failOn && args[0] === opts.failOn) return { status: 1, stdout: "" };
-    if (args[0] === "status") {
-      return { status: 0, stdout: opts?.statusStdout ?? "" };
-    }
-    if (args[0] === "collection" && args[1] === "list") {
-      return { status: 0, stdout: opts?.listStdout ?? "" };
-    }
-    if (args[0] === "collection" && args[1] === "show") {
-      const name = args[2] ?? "unknown";
-      const registered = path.join("/hq", "companies", name, "knowledge");
-      return {
-        status: 0,
-        stdout: `Collection: ${name}\n  Path: ${registered}\n  Pattern: **/*.md\n`,
-      };
-    }
-    return { status: 0, stdout: "" };
-  };
-  return { exec, calls };
-}
-
-describe("reindexAfterSync", () => {
-  it("no-ops when the path is not an HQ root", () => {
-    const { exec, calls } = fakeExec();
-    const r = reindexAfterSync("/tmp/not-hq", {
-      exec,
-      acquireReindexLock: noLock,
-      existsSync: () => false, // core/core.yaml absent
-    });
-    expect(r.qmdAvailable).toBe(false);
-    expect(calls).toHaveLength(0);
-  });
-
-  it("no-ops when qmd is unavailable (collection list errors)", () => {
-    const { exec, calls } = fakeExec({ failOn: "collection" });
-    const r = reindexAfterSync("/hq", {
-      exec,
-      acquireReindexLock: noLock,
-      existsSync: () => true, // core.yaml present
-    });
-    expect(r.qmdAvailable).toBe(false);
-    expect(r.updated).toBe(false);
-    expect(calls).toEqual([["status"], ["collection", "list"]]);
-  });
-
-  it("registers a missing company collection then runs an incremental update", () => {
-    const { exec, calls } = fakeExec({ listStdout: "Collections (1):\n\nHQ (qmd://HQ/)\n" });
-    const r = reindexAfterSync("/hq", {
-      exec,
-      acquireReindexLock: noLock,
-      existsSync: () => true,
-      readCompanies: () => ["acme"],
-      hasIndexableMarkdown: (p) => p === path.join("/hq", "companies", "acme", "knowledge"),
-    });
-    expect(r.qmdAvailable).toBe(true);
-    expect(r.collectionsAdded).toEqual(["acme"]);
-    expect(r.updated).toBe(true);
-    expect(r.embedded).toBe(false);
-
-    expect(calls).toEqual([
-      ["status"],
-      ["collection", "list"],
-      ["collection", "add", path.join("/hq", "companies", "acme", "knowledge"), "--name", "acme", "--mask", "**/*.md"],
-      ["context", "add", "qmd://acme", "Knowledge base for acme."],
-      ["update"],
-    ]);
-  });
-
-  it("skips collections that already exist at the desired path", () => {
-    const { exec, calls } = fakeExec({ listStdout: "acme (qmd://acme/)\n" });
-    const r = reindexAfterSync("/hq", {
-      exec,
-      acquireReindexLock: noLock,
-      existsSync: () => true,
-      readCompanies: () => ["acme"],
-      hasIndexableMarkdown: (p) => p === path.join("/hq", "companies", "acme", "knowledge"),
-      realpathSync: identityRealpath,
-    });
-    expect(r.collectionsAdded).toEqual([]);
-    expect(r.pathDriftDetected).toEqual([]);
-    expect(calls).toEqual([
-      ["status"],
-      ["collection", "list"],
-      ["collection", "show", "acme"],
-      ["update"],
-    ]);
-  });
-
-  it("detects path drift without repairing when HQ_QMD_REPAIR_PATH_DRIFT is off", () => {
-    const drifted = path.join("/mirror", "knowledge-acme");
-    const { exec, calls } = fakeExec({
-      listStdout: "acme (qmd://acme/)\n",
-      resultFor: (args) =>
-        args[0] === "collection" && args[1] === "show"
-          ? {
-              status: 0,
-              stdout: `Collection: acme\n  Path: ${drifted}\n`,
-            }
-          : undefined,
-    });
-    const r = reindexAfterSync("/hq", {
-      exec,
-      acquireReindexLock: noLock,
-      existsSync: () => true,
-      readCompanies: () => ["acme"],
-      hasIndexableMarkdown: (p) => p === path.join("/hq", "companies", "acme", "knowledge"),
-      realpathSync: identityRealpath,
-      env: {},
-      embed: true,
-    });
-    expect(r.pathDriftDetected).toEqual(["acme"]);
-    expect(r.collectionsRepaired).toEqual([]);
-    expect(calls.some((c) => c[0] === "collection" && c[1] === "remove")).toBe(false);
-    // Detect-only must still allow embed (no repair this cycle).
-    expect(r.embedded).toBe(true);
-  });
-
-  it("repairs path drift when HQ_QMD_REPAIR_PATH_DRIFT=1 and skips embed", () => {
-    const drifted = path.join("/mirror", "knowledge-acme");
-    const desired = path.join("/hq", "companies", "acme", "knowledge");
-    const { exec, calls } = fakeExec({
-      listStdout: "acme (qmd://acme/)\n",
-      resultFor: (args) =>
-        args[0] === "collection" && args[1] === "show"
-          ? { status: 0, stdout: `Collection: acme\n  Path: ${drifted}\n` }
-          : undefined,
-    });
-    const r = reindexAfterSync("/hq", {
-      exec,
-      acquireReindexLock: noLock,
-      existsSync: () => true,
-      readCompanies: () => ["acme"],
-      hasIndexableMarkdown: (p) => p === path.join("/hq", "companies", "acme", "knowledge"),
-      realpathSync: identityRealpath,
-      env: { HQ_QMD_REPAIR_PATH_DRIFT: "1" },
-      embed: true,
-    });
-    expect(r.pathDriftDetected).toEqual(["acme"]);
-    expect(r.collectionsRepaired).toEqual(["acme"]);
-    expect(r.embedded).toBe(false);
-    expect(calls).toEqual([
-      ["status"],
-      ["collection", "list"],
-      ["collection", "show", "acme"],
-      ["collection", "remove", "acme"],
-      ["collection", "add", desired, "--name", "acme", "--mask", "**/*.md"],
-      ["context", "add", "qmd://acme", "Knowledge base for acme."],
-      ["update"],
-    ]);
-  });
-
-  it("does not remove a drifted collection when desired path has no indexable markdown", () => {
-    const drifted = path.join("/mirror", "knowledge-acme");
-    const { exec, calls } = fakeExec({
-      listStdout: "acme (qmd://acme/)\n",
-      resultFor: (args) =>
-        args[0] === "collection" && args[1] === "show"
-          ? { status: 0, stdout: `Collection: acme\n  Path: ${drifted}\n` }
-          : undefined,
-    });
-    // hasIndexableMarkdown false → skipped before show/repair (desired empty).
-    const r = reindexAfterSync("/hq", {
-      exec,
-      acquireReindexLock: noLock,
-      existsSync: () => true,
-      readCompanies: () => ["acme"],
-      hasIndexableMarkdown: () => false,
-      env: { HQ_QMD_REPAIR_PATH_DRIFT: "1" },
-    });
-    expect(r.pathDriftDetected).toEqual([]);
-    expect(r.collectionsRepaired).toEqual([]);
-    expect(calls.some((c) => c[1] === "remove")).toBe(false);
-  });
-
-  it("skips company dirs with no indexable markdown", () => {
-    const { exec, calls } = fakeExec({ listStdout: "" });
-    const r = reindexAfterSync("/hq", {
-      exec,
-      acquireReindexLock: noLock,
-      existsSync: () => true,
-      readCompanies: () => ["empty"],
-      hasIndexableMarkdown: () => false,
-    });
-    expect(r.collectionsAdded).toEqual([]);
-    expect(calls).toEqual([["status"], ["collection", "list"], ["update"]]);
-  });
-
-  it("registers populated company projects with the shell name and mask", () => {
-    const { exec, calls } = fakeExec({ listStdout: "" });
-    const r = reindexAfterSync("/hq", {
-      exec,
-      acquireReindexLock: noLock,
-      existsSync: () => true,
-      readCompanies: () => ["acme"],
-      hasIndexableMarkdown: () => false,
-      hasIndexableProjectContent: () => true,
-    });
-
-    expect(r.collectionsAdded).toEqual(["acme-projects"]);
-    expect(calls).toEqual([
-      ["status"],
-      ["collection", "list"],
-      [
-        "collection",
-        "add",
-        path.join("/hq", "companies", "acme", "projects"),
-        "--name",
-        "acme-projects",
-        "--mask",
-        "**/*.{md,json}",
-      ],
-      ["context", "add", "qmd://acme-projects", "Project PRDs and documentation for acme."],
-      ["update"],
-    ]);
-  });
-
-  it("skips missing and empty company projects dirs", () => {
-    const { exec, calls } = fakeExec({ listStdout: "" });
-    const emptyProjects = path.join("/hq", "companies", "empty", "projects");
-    const r = reindexAfterSync("/hq", {
-      exec,
-      acquireReindexLock: noLock,
-      existsSync: (p) => p !== path.join("/hq", "companies", "missing", "projects"),
-      readCompanies: () => ["missing", "empty"],
-      hasIndexableMarkdown: () => false,
-      hasIndexableProjectContent: (p) => p !== emptyProjects,
-    });
-
-    expect(r.collectionsAdded).toEqual([]);
-    expect(calls).toEqual([["status"], ["collection", "list"], ["update"]]);
-  });
-
-  it("registers populated personal knowledge with the shell name and mask", () => {
-    const { exec, calls } = fakeExec({ listStdout: "" });
-    const personalKnowledge = path.join("/hq", "personal", "knowledge");
-    const r = reindexAfterSync("/hq", {
-      exec,
-      acquireReindexLock: noLock,
-      existsSync: () => true,
-      readCompanies: () => [],
-      hasIndexableMarkdown: (p) => p === personalKnowledge,
-    });
-
-    expect(r.collectionsAdded).toEqual(["personal-knowledge"]);
-    expect(calls).toEqual([
-      ["status"],
-      ["collection", "list"],
-      [
-        "collection",
-        "add",
-        personalKnowledge,
-        "--name",
-        "personal-knowledge",
-        "--mask",
-        "**/*.md",
-      ],
-      ["context", "add", "qmd://personal-knowledge", "Personal knowledge base (owner overlay)."],
-      ["update"],
-    ]);
-  });
-
-  it("skips absent and empty personal knowledge", () => {
-    const absent = fakeExec({ listStdout: "" });
-    const absentResult = reindexAfterSync("/hq", {
-      exec: absent.exec,
-      acquireReindexLock: noLock,
-      existsSync: (p) => p !== path.join("/hq", "personal", "knowledge"),
-      readCompanies: () => [],
-    });
-    expect(absentResult.collectionsAdded).toEqual([]);
-    expect(absent.calls).toEqual([["status"], ["collection", "list"], ["update"]]);
-
-    const empty = fakeExec({ listStdout: "" });
-    const emptyResult = reindexAfterSync("/hq", {
-      exec: empty.exec,
-      acquireReindexLock: noLock,
-      existsSync: () => true,
-      readCompanies: () => [],
-      hasIndexableMarkdown: () => false,
-    });
-    expect(emptyResult.collectionsAdded).toEqual([]);
-    expect(empty.calls).toEqual([["status"], ["collection", "list"], ["update"]]);
-  });
-
-  it("does not add projects or personal knowledge a second time", () => {
-    let listCount = 0;
-    const { exec, calls } = fakeExec({
-      resultFor: (args) => {
-        if (args[0] !== "collection" || args[1] !== "list") return undefined;
-        listCount++;
-        return {
-          status: 0,
-          stdout:
-            listCount === 1
-              ? ""
-              : "acme (qmd://acme/)\nacme-projects (qmd://acme-projects/)\npersonal-knowledge (qmd://personal-knowledge/)\n",
-        };
-      },
-    });
-    const options = {
-      exec,
-      acquireReindexLock: noLock,
-      existsSync: () => true,
-      readCompanies: () => ["acme"],
-      hasIndexableMarkdown: () => true,
-      hasIndexableProjectContent: () => true,
-      realpathSync: identityRealpath,
-    };
-
-    expect(reindexAfterSync("/hq", options).collectionsAdded).toEqual([
-      "acme",
-      "acme-projects",
-      "personal-knowledge",
-    ]);
-    expect(reindexAfterSync("/hq", options).collectionsAdded).toEqual([]);
-    expect(calls.filter((c) => c[0] === "collection" && c[1] === "add")).toHaveLength(3);
-  });
-
-  it("emits the same collection-add commands as the shell for a fixture tree", () => {
-    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-qmd-parity-"));
-    try {
-      const hq = path.join(dir, "hq");
-      const acmeKnowledge = path.join(hq, "companies", "acme", "knowledge");
-      const acmeProjects = path.join(hq, "companies", "acme", "projects");
-      const emptyProjects = path.join(hq, "companies", "empty", "projects");
-      const personalKnowledge = path.join(hq, "personal", "knowledge");
-      fs.mkdirSync(path.join(hq, "core"), { recursive: true });
-      fs.mkdirSync(acmeKnowledge, { recursive: true });
-      fs.mkdirSync(acmeProjects, { recursive: true });
-      fs.mkdirSync(emptyProjects, { recursive: true });
-      fs.mkdirSync(personalKnowledge, { recursive: true });
-      fs.writeFileSync(path.join(hq, "core", "core.yaml"), "hqVersion: 1\n");
-      fs.writeFileSync(path.join(acmeKnowledge, "note.md"), "# knowledge\n");
-      fs.writeFileSync(path.join(acmeProjects, "prd.json"), "{}\n");
-      fs.writeFileSync(path.join(personalKnowledge, "note.md"), "# personal\n");
-
-      const { exec, calls } = fakeExec({ listStdout: "" });
-      reindexAfterSync(hq, { exec, acquireReindexLock: noLock });
-
-      expect(calls.filter((c) => c[0] === "collection" && c[1] === "add")).toEqual([
-        ["collection", "add", acmeKnowledge, "--name", "acme", "--mask", "**/*.md"],
-        [
-          "collection",
-          "add",
-          acmeProjects,
-          "--name",
-          "acme-projects",
-          "--mask",
-          "**/*.{md,json}",
-        ],
-        [
-          "collection",
-          "add",
-          personalKnowledge,
-          "--name",
-          "personal-knowledge",
-          "--mask",
-          "**/*.md",
-        ],
-      ]);
-    } finally {
-      fs.rmSync(dir, { recursive: true, force: true });
-    }
-  });
-
-  it("skips qmd entirely when provided changed paths do not touch knowledge markdown", () => {
-    const { exec, calls } = fakeExec({ listStdout: "" });
-    const r = reindexAfterSync("/hq", {
-      exec,
-      acquireReindexLock: noLock,
-      existsSync: () => true,
-      changedPaths: ["companies/acme/docs/readme.txt"],
-    });
-    expect(r.qmdAvailable).toBe(false);
-    expect(r.updated).toBe(false);
-    expect(calls).toEqual([]);
-  });
-
-  it("debounces dirty updates with a pending marker and flushes the final update later", () => {
-    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-qmd-debounce-"));
-    try {
-      const statePath = path.join(dir, "qmd-state.json");
-      const { exec, calls } = fakeExec({ listStdout: "acme (qmd://acme/)\n" });
-
-      const first = reindexAfterSync("/hq", {
-        exec,
-        acquireReindexLock: noLock,
-        existsSync: () => true,
-        readCompanies: () => ["acme"],
-        hasIndexableMarkdown: (p) => p === path.join("/hq", "companies", "acme", "knowledge"),
-        changedPaths: ["companies/acme/knowledge/note.md"],
-        debounceMs: 60_000,
-        nowMs: 100_000,
-        statePath,
-        realpathSync: identityRealpath,
-      });
-      expect(first.updated).toBe(false);
-      expect(first.pendingDirty).toBe(true);
-      expect(calls).toEqual([
-        ["status"],
-        ["collection", "list"],
-        ["collection", "show", "acme"],
-      ]);
-
-      const second = reindexAfterSync("/hq", {
-        exec,
-        acquireReindexLock: noLock,
-        existsSync: () => true,
-        changedPaths: [],
-        debounceMs: 60_000,
-        nowMs: 161_000,
-        statePath,
-      });
-      expect(second.updated).toBe(true);
-      expect(second.pendingDirty).toBe(false);
-      expect(calls).toEqual([
-        ["status"],
-        ["collection", "list"],
-        ["collection", "show", "acme"],
-        ["status"],
-        ["collection", "list"],
-        ["update"],
-      ]);
-    } finally {
-      fs.rmSync(dir, { recursive: true, force: true });
-    }
-  });
-
-  it("runs embed only when embed:true", () => {
-    const { exec, calls } = fakeExec({ listStdout: "" });
-    const r = reindexAfterSync("/hq", {
-      exec,
-      acquireReindexLock: noLock,
-      existsSync: () => true,
-      readCompanies: () => [],
-      embed: true,
-    });
-    expect(r.embedded).toBe(true);
-    expect(calls).toEqual([["status"], ["collection", "list"], ["update"], ["embed"]]);
-  });
-
-  it("never throws even if exec misbehaves", () => {
-    const exec: QmdExec = () => {
-      throw new Error("boom");
-    };
-    expect(() =>
-      reindexAfterSync("/hq", { exec, acquireReindexLock: noLock, existsSync: () => true }),
-    ).not.toThrow();
-  });
-
-  it("hasIndexableMarkdown finds a real .md and ignores INDEX.md", () => {
-    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-qmd-test-"));
-    try {
-      const hq = path.join(dir, "hq");
-      const kdir = path.join(hq, "companies", "acme", "knowledge");
-      fs.mkdirSync(kdir, { recursive: true });
-      fs.mkdirSync(path.join(hq, "core"), { recursive: true });
-      fs.writeFileSync(path.join(hq, "core", "core.yaml"), "hqVersion: 1\n");
-      fs.writeFileSync(path.join(kdir, "INDEX.md"), "# index\n");
-      fs.writeFileSync(path.join(kdir, "note.md"), "# real\n");
-
-      const { exec, calls } = fakeExec({ listStdout: "" });
-      const r = reindexAfterSync(hq, { exec, acquireReindexLock: noLock }); // real fs walk
-      expect(r.collectionsAdded).toEqual(["acme"]);
-      expect(calls.some((c) => c[0] === "collection" && c[1] === "add")).toBe(true);
-    } finally {
-      fs.rmSync(dir, { recursive: true, force: true });
-    }
-  });
-
-  // ── Corruption safety: lock serialization (feedback_b9a369ff) ──────────────
-
-  it("skips the cycle after status when another writer holds the lock", () => {
-    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-qmd-lockbusy-"));
-    try {
-      const statePath = path.join(dir, "qmd-state.json");
-      const { exec, calls } = fakeExec({ listStdout: "" });
-      const r = reindexAfterSync("/hq", {
-        exec,
-        existsSync: () => true,
-        statePath,
-        // Simulate a concurrent qmd writer already holding the lock.
-        acquireReindexLock: () => null,
-      });
-      // status is read-only and runs before lock; no write commands follow.
-      expect(calls).toEqual([["status"]]);
-      expect(r.lockBusy).toBe(true);
-      expect(r.pendingDirty).toBe(true);
-      expect(r.updated).toBe(false);
-      const persisted = JSON.parse(fs.readFileSync(statePath, "utf8"));
-      expect(persisted.pendingDirty).toBe(true);
-    } finally {
-      fs.rmSync(dir, { recursive: true, force: true });
-    }
-  });
-
-  it("always releases the lock, even when a qmd command throws after status", () => {
-    let released = false;
-    const exec: QmdExec = (args) => {
-      if (args[0] === "status") return { status: 0, stdout: "" };
-      throw new Error("boom");
-    };
-    reindexAfterSync("/hq", {
-      exec,
-      existsSync: () => true,
-      acquireReindexLock: () => ({
-        release() {
-          released = true;
-        },
-      }),
-    });
-    expect(released).toBe(true);
-  });
-
-  // ── Corruption safety: timeout-kill handling ───────────────────────────────
-
-  it("treats a timed-out update as not-done, marks dirty, and does NOT embed", () => {
-    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-qmd-timeout-"));
-    try {
-      const statePath = path.join(dir, "qmd-state.json");
-      const { exec, calls } = fakeExec({
-        listStdout: "",
-        resultFor: (args) =>
-          args[0] === "update" ? { status: null, timedOut: true } : undefined,
-      });
-      const r = reindexAfterSync("/hq", {
-        exec,
-        acquireReindexLock: noLock,
-        existsSync: () => true,
-        readCompanies: () => [],
-        embed: true,
-        statePath,
-      });
-      expect(r.timedOut).toBe(true);
-      expect(r.updated).toBe(false);
-      expect(r.embedded).toBe(false);
-      expect(r.pendingDirty).toBe(true);
-      expect(calls).toEqual([["status"], ["collection", "list"], ["update"]]);
-      const persisted = JSON.parse(fs.readFileSync(statePath, "utf8"));
-      expect(persisted.pendingDirty).toBe(true);
-    } finally {
-      fs.rmSync(dir, { recursive: true, force: true });
-    }
-  });
-
-  it("treats a timed-out embed as not-embedded and marks dirty", () => {
-    const { exec } = fakeExec({
-      listStdout: "",
-      resultFor: (args) =>
-        args[0] === "embed" ? { status: null, timedOut: true } : undefined,
-    });
-    const r = reindexAfterSync("/hq", {
-      exec,
-      acquireReindexLock: noLock,
-      existsSync: () => true,
-      readCompanies: () => [],
-      embed: true,
-    });
-    expect(r.updated).toBe(true);
-    expect(r.embedded).toBe(false);
-    expect(r.timedOut).toBe(true);
-    expect(r.pendingDirty).toBe(true);
-  });
-
-  // ── Corruption safety: SQLITE_CORRUPT detection + quarantine ────────────────
-
-  it("quarantines the resolved index dir when update reports SQLITE_CORRUPT", () => {
-    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-qmd-corrupt-"));
-    try {
-      const statePath = path.join(dir, "qmd-state.json");
-      const cacheDir = path.join(dir, "cache-qmd");
-      const quarantined: Array<{ qmdDir: string; suffix: string }> = [];
-      const quarantine: QuarantineCorruptIndex = (qmdDir, suffix) => {
-        quarantined.push({ qmdDir, suffix });
-        return path.join(qmdDir, `index.sqlite.corrupt-${suffix}`);
-      };
-      const { exec, calls } = fakeExec({
-        listStdout: "",
-        statusStdout: `Index: ${path.join(cacheDir, "index.sqlite")}\nSize: 1 GB\n`,
-        resultFor: (args) =>
-          args[0] === "update"
-            ? { status: 1, stderr: "SqliteError: database disk image is malformed (SQLITE_CORRUPT)" }
-            : undefined,
-      });
-      const r = reindexAfterSync("/hq", {
-        exec,
-        acquireReindexLock: noLock,
-        existsSync: () => true,
-        readCompanies: () => [],
-        embed: true,
-        statePath,
-        quarantineCorruptIndex: quarantine,
-      });
-      expect(r.corruptionQuarantined).toBe(true);
-      expect(r.corruptionQuarantineFailed).toBe(false);
-      expect(r.embedded).toBe(false);
-      expect(r.pendingDirty).toBe(true);
-      expect(calls).toEqual([["status"], ["collection", "list"], ["update"]]);
-      expect(quarantined).toHaveLength(1);
-      expect(quarantined[0].qmdDir).toBe(cacheDir);
-      expect(r.indexDir).toBe(cacheDir);
-    } finally {
-      fs.rmSync(dir, { recursive: true, force: true });
-    }
-  });
-
-  it("reports quarantine failure when corruption is detected but nothing moves", () => {
-    const quarantined: string[] = [];
-    const { exec, calls } = fakeExec({
-      resultFor: (args) =>
-        args[0] === "collection" && args[1] === "list"
-          ? { status: 0, stdout: "database disk image is malformed" }
-          : undefined,
-    });
-    const r = reindexAfterSync("/hq", {
-      exec,
-      acquireReindexLock: noLock,
-      existsSync: () => true,
-      quarantineCorruptIndex: (qmdDir) => {
-        quarantined.push(qmdDir);
-        return null;
-      },
-    });
-    expect(r.corruptionQuarantined).toBe(false);
-    expect(r.corruptionQuarantineFailed).toBe(true);
-    expect(r.updated).toBe(false);
-    expect(calls).toEqual([["status"], ["collection", "list"]]);
-    expect(quarantined).toEqual([path.join("/hq", ".qmd")]);
-  });
-
-  it("quarantines when embed reports SQLITE_CORRUPT", () => {
-    const quarantined: string[] = [];
-    const { exec, calls } = fakeExec({
-      listStdout: "",
-      resultFor: (args) =>
-        args[0] === "embed"
-          ? { status: 1, stderr: "code SQLITE_CORRUPT at store.js:1546" }
-          : undefined,
-    });
-    const r = reindexAfterSync("/hq", {
-      exec,
-      acquireReindexLock: noLock,
-      existsSync: () => true,
-      readCompanies: () => [],
-      embed: true,
-      quarantineCorruptIndex: (qmdDir) => {
-        quarantined.push(qmdDir);
-        return path.join(qmdDir, "index.sqlite.corrupt-x");
-      },
-    });
-    expect(r.corruptionQuarantined).toBe(true);
-    expect(r.embedded).toBe(false);
-    expect(calls).toEqual([["status"], ["collection", "list"], ["update"], ["embed"]]);
-    expect(quarantined).toEqual([path.join("/hq", ".qmd")]);
-  });
-});
-
-// ── The default reindex lock (real filesystem) ───────────────────────────────
-
-describe("default reindex lock", () => {
-  it("holds the lock for the duration of the cycle and releases it after", () => {
-    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-qmd-lock-"));
-    try {
-      const hq = path.join(dir, "hq");
-      const kdir = path.join(hq, "companies", "acme", "knowledge");
-      fs.mkdirSync(kdir, { recursive: true });
-      fs.mkdirSync(path.join(hq, "core"), { recursive: true });
-      fs.writeFileSync(path.join(hq, "core", "core.yaml"), "v: 1\n");
-      fs.writeFileSync(path.join(kdir, "note.md"), "# real\n");
-
-      const lockPath = path.join(hq, ".qmd", ".reindex.lock");
-      let reAcquireBlockedWhileHeld = false;
-      const { exec } = fakeExec({ listStdout: "" });
-      const observingExec: QmdExec = (args) => {
-        if (args[0] === "update") {
-          try {
-            fs.closeSync(fs.openSync(lockPath, "wx"));
-            fs.unlinkSync(lockPath);
-          } catch (err) {
-            reAcquireBlockedWhileHeld =
-              (err as NodeJS.ErrnoException).code === "EEXIST";
-          }
-        }
-        return exec(args);
-      };
-
-      const r = reindexAfterSync(hq, { exec: observingExec });
-      expect(r.updated).toBe(true);
-      expect(reAcquireBlockedWhileHeld).toBe(true);
-      expect(fs.existsSync(lockPath)).toBe(false);
-    } finally {
-      fs.rmSync(dir, { recursive: true, force: true });
-    }
-  });
-
-  it("reclaims a lock held by a dead PID (stale takeover)", () => {
-    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-qmd-lock-stale-"));
-    try {
-      const hq = path.join(dir, "hq");
-      const kdir = path.join(hq, "companies", "acme", "knowledge");
-      fs.mkdirSync(kdir, { recursive: true });
-      fs.mkdirSync(path.join(hq, "core"), { recursive: true });
-      fs.writeFileSync(path.join(hq, "core", "core.yaml"), "v: 1\n");
-      fs.writeFileSync(path.join(kdir, "note.md"), "# real\n");
-
-      const lockPath = path.join(hq, ".qmd", ".reindex.lock");
-      fs.mkdirSync(path.dirname(lockPath), { recursive: true });
-      fs.writeFileSync(
-        lockPath,
-        JSON.stringify({ pid: 2147483646, startedAt: "2000-01-01T00:00:00.000Z", command: "dead" }),
-      );
-
-      const { exec, calls } = fakeExec({ listStdout: "" });
-      const r = reindexAfterSync(hq, { exec });
-      expect(r.updated).toBe(true);
-      expect(r.lockBusy).toBe(false);
-      expect(calls.some((c) => c[0] === "update")).toBe(true);
-    } finally {
-      fs.rmSync(dir, { recursive: true, force: true });
-    }
-  });
-});
-
-describe("acquireDualReindexLocks", () => {
-  it("dedupes identical paths so a process cannot lock itself out", () => {
-    let acquires = 0;
-    const acquire: AcquireReindexLock = () => {
-      acquires++;
-      return { release() {} };
-    };
-    const same = path.join("/hq", ".qmd", ".reindex.lock");
-    const { locks, busy } = acquireDualReindexLocks(acquire, [same, same]);
-    expect(busy).toBe(false);
-    expect(locks).toHaveLength(1);
-    expect(acquires).toBe(1);
-  });
-
-  it("releases the first lock when the second is busy", () => {
-    const released: string[] = [];
-    let n = 0;
-    const acquire: AcquireReindexLock = (lockPath) => {
-      n++;
-      if (n === 2) return null;
-      return {
-        release() {
-          released.push(lockPath);
-        },
-      };
-    };
-    const { locks, busy } = acquireDualReindexLocks(acquire, [
-      "/a/.reindex.lock",
-      "/b/.reindex.lock",
-    ]);
-    expect(busy).toBe(true);
-    expect(locks).toHaveLength(0);
-    expect(released).toEqual(["/a/.reindex.lock"]);
-  });
-});
-
-// ── Pure helpers ─────────────────────────────────────────────────────────────
-
-describe("resolveExecTimeoutMs", () => {
-  it("defaults to a generous bound, not the old 120s that killed writes", () => {
-    expect(resolveExecTimeoutMs({})).toBe(DEFAULT_QMD_EXEC_TIMEOUT_MS);
-    expect(DEFAULT_QMD_EXEC_TIMEOUT_MS).toBeGreaterThan(120_000);
-  });
-
-  it("honors a valid HQ_QMD_EXEC_TIMEOUT_MS override", () => {
-    expect(resolveExecTimeoutMs({ HQ_QMD_EXEC_TIMEOUT_MS: "300000" })).toBe(300_000);
-  });
-
-  it("ignores an invalid override", () => {
-    expect(resolveExecTimeoutMs({ HQ_QMD_EXEC_TIMEOUT_MS: "nope" })).toBe(DEFAULT_QMD_EXEC_TIMEOUT_MS);
-    expect(resolveExecTimeoutMs({ HQ_QMD_EXEC_TIMEOUT_MS: "-5" })).toBe(DEFAULT_QMD_EXEC_TIMEOUT_MS);
-    expect(resolveExecTimeoutMs({ HQ_QMD_EXEC_TIMEOUT_MS: "0" })).toBe(DEFAULT_QMD_EXEC_TIMEOUT_MS);
-  });
-});
-
-describe("looksCorrupt", () => {
-  it("matches the SQLITE_CORRUPT signature on stdout or stderr", () => {
-    expect(looksCorrupt({ stderr: "SqliteError: ... code SQLITE_CORRUPT" })).toBe(true);
-    expect(looksCorrupt({ stdout: "database disk image is malformed" })).toBe(true);
-    expect(looksCorrupt({ stdout: "Database disk image IS MALFORMED" })).toBe(true);
-  });
-
-  it("does not match clean output", () => {
-    expect(looksCorrupt({ stdout: "Updated 688 documents", stderr: "" })).toBe(false);
-    expect(looksCorrupt({})).toBe(false);
-  });
-});
-
-describe("parseIndexDirFromStatus / parseCollectionPathFromShow", () => {
-  it("parses Index file path into its directory", () => {
-    expect(
-      parseIndexDirFromStatus("Index: C:/Users/me/.cache/qmd/index.sqlite\nSize: 1.3 GB\n"),
-    ).toBe(path.dirname("C:/Users/me/.cache/qmd/index.sqlite"));
-  });
-
-  it("returns null when Index line is missing", () => {
-    expect(parseIndexDirFromStatus("Collections: 2\n")).toBeNull();
-  });
-
-  it("parses Path from collection show", () => {
-    expect(
-      parseCollectionPathFromShow("Collection: indigo\n  Path: /hq/companies/indigo/knowledge\n"),
-    ).toBe("/hq/companies/indigo/knowledge");
-  });
-});
-
-describe("pathsEquivalent / repairPathDriftEnabled", () => {
-  it("treats case and trailing separators as equal", () => {
-    expect(
-      pathsEquivalent("/HQ/Companies/Acme/knowledge/", "/hq/companies/acme/knowledge", (p) => p),
-    ).toBe(true);
-  });
-
-  it("enables repair only for 1/true/yes", () => {
-    expect(repairPathDriftEnabled({})).toBe(false);
-    expect(repairPathDriftEnabled({ HQ_QMD_REPAIR_PATH_DRIFT: "1" })).toBe(true);
-    expect(repairPathDriftEnabled({ HQ_QMD_REPAIR_PATH_DRIFT: "true" })).toBe(true);
-    expect(repairPathDriftEnabled({ HQ_QMD_REPAIR_PATH_DRIFT: "yes" })).toBe(true);
-    expect(repairPathDriftEnabled({ HQ_QMD_REPAIR_PATH_DRIFT: "0" })).toBe(false);
-  });
-});