@indigoai-us/hq-cloud 6.18.15 → 6.18.16-alpha.1

package/dist/qmd-reindex.test.js

@@ -10,11 +10,12 @@
  * 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 { describe, it, expect, vi } 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, } from "./qmd-reindex.js";
+import { clearTimeout as clearRealTimeout, setTimeout as setRealTimeout } from "node:timers";
+import { reindexAfterSync, createQmdExec, looksCorrupt, resolveExecTimeoutMs, DEFAULT_QMD_EXEC_TIMEOUT_MS, parseIndexDirFromStatus, parseCollectionPathFromShow, pathsEquivalent, repairPathDriftEnabled, acquireDualReindexLocks, } from "./qmd-reindex.js";
 /** A lock acquirer that always succeeds — keeps command-sequence tests pure. */
 const noLock = () => ({ release() { } });
 /** Identity realpath so path-drift comparisons stay deterministic in fakes. */
@@ -22,7 +23,7 @@ const identityRealpath = (p) => path.resolve(p);
 /** Build a fake exec that returns status 0 for everything and logs calls. */
 function fakeExec(opts) {
     const calls = [];
-    const exec = (args) => {
+    const exec = async (args) => {
         calls.push(args);
         const override = opts?.resultFor?.(args);
         if (override)
@@ -48,9 +49,9 @@ function fakeExec(opts) {
     return { exec, calls };
 }
 describe("reindexAfterSync", () => {
-    it("no-ops when the path is not an HQ root", () => {
+    it("no-ops when the path is not an HQ root", async () => {
         const { exec, calls } = fakeExec();
-        const r = reindexAfterSync("/tmp/not-hq", {
+        const r = await reindexAfterSync("/tmp/not-hq", {
             exec,
             acquireReindexLock: noLock,
             existsSync: () => false, // core/core.yaml absent
@@ -58,9 +59,9 @@ describe("reindexAfterSync", () => {
         expect(r.qmdAvailable).toBe(false);
         expect(calls).toHaveLength(0);
     });
-    it("no-ops when qmd is unavailable (collection list errors)", () => {
+    it("no-ops when qmd is unavailable (collection list errors)", async () => {
         const { exec, calls } = fakeExec({ failOn: "collection" });
-        const r = reindexAfterSync("/hq", {
+        const r = await reindexAfterSync("/hq", {
             exec,
             acquireReindexLock: noLock,
             existsSync: () => true, // core.yaml present
@@ -69,9 +70,9 @@ describe("reindexAfterSync", () => {
         expect(r.updated).toBe(false);
         expect(calls).toEqual([["status"], ["collection", "list"]]);
     });
-    it("registers a missing company collection then runs an incremental update", () => {
+    it("registers a missing company collection then runs an incremental update", async () => {
         const { exec, calls } = fakeExec({ listStdout: "Collections (1):\n\nHQ (qmd://HQ/)\n" });
-        const r = reindexAfterSync("/hq", {
+        const r = await reindexAfterSync("/hq", {
             exec,
             acquireReindexLock: noLock,
             existsSync: () => true,
@@ -90,9 +91,9 @@ describe("reindexAfterSync", () => {
             ["update"],
         ]);
     });
-    it("skips collections that already exist at the desired path", () => {
+    it("skips collections that already exist at the desired path", async () => {
         const { exec, calls } = fakeExec({ listStdout: "acme (qmd://acme/)\n" });
-        const r = reindexAfterSync("/hq", {
+        const r = await reindexAfterSync("/hq", {
             exec,
             acquireReindexLock: noLock,
             existsSync: () => true,
@@ -109,7 +110,7 @@ describe("reindexAfterSync", () => {
             ["update"],
         ]);
     });
-    it("detects path drift without repairing when HQ_QMD_REPAIR_PATH_DRIFT is off", () => {
+    it("detects path drift without repairing when HQ_QMD_REPAIR_PATH_DRIFT is off", async () => {
         const drifted = path.join("/mirror", "knowledge-acme");
         const { exec, calls } = fakeExec({
             listStdout: "acme (qmd://acme/)\n",
@@ -120,7 +121,7 @@ describe("reindexAfterSync", () => {
                 }
                 : undefined,
         });
-        const r = reindexAfterSync("/hq", {
+        const r = await reindexAfterSync("/hq", {
             exec,
             acquireReindexLock: noLock,
             existsSync: () => true,
@@ -136,7 +137,7 @@ describe("reindexAfterSync", () => {
         // 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", () => {
+    it("repairs path drift when HQ_QMD_REPAIR_PATH_DRIFT=1 and skips embed", async () => {
         const drifted = path.join("/mirror", "knowledge-acme");
         const desired = path.join("/hq", "companies", "acme", "knowledge");
         const { exec, calls } = fakeExec({
@@ -145,7 +146,7 @@ describe("reindexAfterSync", () => {
                 ? { status: 0, stdout: `Collection: acme\n  Path: ${drifted}\n` }
                 : undefined,
         });
-        const r = reindexAfterSync("/hq", {
+        const r = await reindexAfterSync("/hq", {
             exec,
             acquireReindexLock: noLock,
             existsSync: () => true,
@@ -168,7 +169,7 @@ describe("reindexAfterSync", () => {
             ["update"],
         ]);
     });
-    it("does not remove a drifted collection when desired path has no indexable markdown", () => {
+    it("does not remove a drifted collection when desired path has no indexable markdown", async () => {
         const drifted = path.join("/mirror", "knowledge-acme");
         const { exec, calls } = fakeExec({
             listStdout: "acme (qmd://acme/)\n",
@@ -177,7 +178,7 @@ describe("reindexAfterSync", () => {
                 : undefined,
         });
         // hasIndexableMarkdown false → skipped before show/repair (desired empty).
-        const r = reindexAfterSync("/hq", {
+        const r = await reindexAfterSync("/hq", {
             exec,
             acquireReindexLock: noLock,
             existsSync: () => true,
@@ -189,9 +190,9 @@ describe("reindexAfterSync", () => {
         expect(r.collectionsRepaired).toEqual([]);
         expect(calls.some((c) => c[1] === "remove")).toBe(false);
     });
-    it("skips company dirs with no indexable markdown", () => {
+    it("skips company dirs with no indexable markdown", async () => {
         const { exec, calls } = fakeExec({ listStdout: "" });
-        const r = reindexAfterSync("/hq", {
+        const r = await reindexAfterSync("/hq", {
             exec,
             acquireReindexLock: noLock,
             existsSync: () => true,
@@ -201,9 +202,9 @@ describe("reindexAfterSync", () => {
         expect(r.collectionsAdded).toEqual([]);
         expect(calls).toEqual([["status"], ["collection", "list"], ["update"]]);
     });
-    it("registers populated company projects with the shell name and mask", () => {
+    it("registers populated company projects with the shell name and mask", async () => {
         const { exec, calls } = fakeExec({ listStdout: "" });
-        const r = reindexAfterSync("/hq", {
+        const r = await reindexAfterSync("/hq", {
             exec,
             acquireReindexLock: noLock,
             existsSync: () => true,
@@ -228,10 +229,10 @@ describe("reindexAfterSync", () => {
             ["update"],
         ]);
     });
-    it("skips missing and empty company projects dirs", () => {
+    it("skips missing and empty company projects dirs", async () => {
         const { exec, calls } = fakeExec({ listStdout: "" });
         const emptyProjects = path.join("/hq", "companies", "empty", "projects");
-        const r = reindexAfterSync("/hq", {
+        const r = await reindexAfterSync("/hq", {
             exec,
             acquireReindexLock: noLock,
             existsSync: (p) => p !== path.join("/hq", "companies", "missing", "projects"),
@@ -242,10 +243,10 @@ describe("reindexAfterSync", () => {
         expect(r.collectionsAdded).toEqual([]);
         expect(calls).toEqual([["status"], ["collection", "list"], ["update"]]);
     });
-    it("registers populated personal knowledge with the shell name and mask", () => {
+    it("registers populated personal knowledge with the shell name and mask", async () => {
         const { exec, calls } = fakeExec({ listStdout: "" });
         const personalKnowledge = path.join("/hq", "personal", "knowledge");
-        const r = reindexAfterSync("/hq", {
+        const r = await reindexAfterSync("/hq", {
             exec,
             acquireReindexLock: noLock,
             existsSync: () => true,
@@ -269,9 +270,9 @@ describe("reindexAfterSync", () => {
             ["update"],
         ]);
     });
-    it("skips absent and empty personal knowledge", () => {
+    it("skips absent and empty personal knowledge", async () => {
         const absent = fakeExec({ listStdout: "" });
-        const absentResult = reindexAfterSync("/hq", {
+        const absentResult = await reindexAfterSync("/hq", {
             exec: absent.exec,
             acquireReindexLock: noLock,
             existsSync: (p) => p !== path.join("/hq", "personal", "knowledge"),
@@ -280,7 +281,7 @@ describe("reindexAfterSync", () => {
         expect(absentResult.collectionsAdded).toEqual([]);
         expect(absent.calls).toEqual([["status"], ["collection", "list"], ["update"]]);
         const empty = fakeExec({ listStdout: "" });
-        const emptyResult = reindexAfterSync("/hq", {
+        const emptyResult = await reindexAfterSync("/hq", {
             exec: empty.exec,
             acquireReindexLock: noLock,
             existsSync: () => true,
@@ -290,7 +291,7 @@ describe("reindexAfterSync", () => {
         expect(emptyResult.collectionsAdded).toEqual([]);
         expect(empty.calls).toEqual([["status"], ["collection", "list"], ["update"]]);
     });
-    it("does not add projects or personal knowledge a second time", () => {
+    it("does not add projects or personal knowledge a second time", async () => {
         let listCount = 0;
         const { exec, calls } = fakeExec({
             resultFor: (args) => {
@@ -314,15 +315,15 @@ describe("reindexAfterSync", () => {
             hasIndexableProjectContent: () => true,
             realpathSync: identityRealpath,
         };
-        expect(reindexAfterSync("/hq", options).collectionsAdded).toEqual([
+        expect((await reindexAfterSync("/hq", options)).collectionsAdded).toEqual([
             "acme",
             "acme-projects",
             "personal-knowledge",
         ]);
-        expect(reindexAfterSync("/hq", options).collectionsAdded).toEqual([]);
+        expect((await 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", () => {
+    it("emits the same collection-add commands as the shell for a fixture tree", async () => {
         const dir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-qmd-parity-"));
         try {
             const hq = path.join(dir, "hq");
@@ -340,7 +341,7 @@ describe("reindexAfterSync", () => {
             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 });
+            await reindexAfterSync(hq, { exec, acquireReindexLock: noLock });
             expect(calls.filter((c) => c[0] === "collection" && c[1] === "add")).toEqual([
                 ["collection", "add", acmeKnowledge, "--name", "acme", "--mask", "**/*.md"],
                 [
@@ -367,9 +368,9 @@ describe("reindexAfterSync", () => {
             fs.rmSync(dir, { recursive: true, force: true });
         }
     });
-    it("skips qmd entirely when provided changed paths do not touch knowledge markdown", () => {
+    it("skips qmd entirely when provided changed paths do not touch knowledge markdown", async () => {
         const { exec, calls } = fakeExec({ listStdout: "" });
-        const r = reindexAfterSync("/hq", {
+        const r = await reindexAfterSync("/hq", {
             exec,
             acquireReindexLock: noLock,
             existsSync: () => true,
@@ -379,12 +380,12 @@ describe("reindexAfterSync", () => {
         expect(r.updated).toBe(false);
         expect(calls).toEqual([]);
     });
-    it("debounces dirty updates with a pending marker and flushes the final update later", () => {
+    it("debounces dirty updates with a pending marker and flushes the final update later", async () => {
         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", {
+            const first = await reindexAfterSync("/hq", {
                 exec,
                 acquireReindexLock: noLock,
                 existsSync: () => true,
@@ -403,7 +404,7 @@ describe("reindexAfterSync", () => {
                 ["collection", "list"],
                 ["collection", "show", "acme"],
             ]);
-            const second = reindexAfterSync("/hq", {
+            const second = await reindexAfterSync("/hq", {
                 exec,
                 acquireReindexLock: noLock,
                 existsSync: () => true,
@@ -427,9 +428,9 @@ describe("reindexAfterSync", () => {
             fs.rmSync(dir, { recursive: true, force: true });
         }
     });
-    it("runs embed only when embed:true", () => {
+    it("runs embed only when embed:true", async () => {
         const { exec, calls } = fakeExec({ listStdout: "" });
-        const r = reindexAfterSync("/hq", {
+        const r = await reindexAfterSync("/hq", {
             exec,
             acquireReindexLock: noLock,
             existsSync: () => true,
@@ -439,13 +440,13 @@ describe("reindexAfterSync", () => {
         expect(r.embedded).toBe(true);
         expect(calls).toEqual([["status"], ["collection", "list"], ["update"], ["embed"]]);
     });
-    it("never throws even if exec misbehaves", () => {
-        const exec = () => {
+    it("never throws even if exec misbehaves", async () => {
+        const exec = async () => {
             throw new Error("boom");
         };
-        expect(() => reindexAfterSync("/hq", { exec, acquireReindexLock: noLock, existsSync: () => true })).not.toThrow();
+        await expect(reindexAfterSync("/hq", { exec, acquireReindexLock: noLock, existsSync: () => true })).resolves.toMatchObject({ qmdAvailable: false });
     });
-    it("hasIndexableMarkdown finds a real .md and ignores INDEX.md", () => {
+    it("hasIndexableMarkdown finds a real .md and ignores INDEX.md", async () => {
         const dir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-qmd-test-"));
         try {
             const hq = path.join(dir, "hq");
@@ -456,7 +457,7 @@ describe("reindexAfterSync", () => {
             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
+            const r = await 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);
         }
@@ -465,12 +466,12 @@ describe("reindexAfterSync", () => {
         }
     });
     // ── Corruption safety: lock serialization (feedback_b9a369ff) ──────────────
-    it("skips the cycle after status when another writer holds the lock", () => {
+    it("skips the cycle after status when another writer holds the lock", async () => {
         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", {
+            const r = await reindexAfterSync("/hq", {
                 exec,
                 existsSync: () => true,
                 statePath,
@@ -489,14 +490,14 @@ describe("reindexAfterSync", () => {
             fs.rmSync(dir, { recursive: true, force: true });
         }
     });
-    it("always releases the lock, even when a qmd command throws after status", () => {
+    it("always releases the lock, even when a qmd command throws after status", async () => {
         let released = false;
-        const exec = (args) => {
+        const exec = async (args) => {
             if (args[0] === "status")
                 return { status: 0, stdout: "" };
             throw new Error("boom");
         };
-        reindexAfterSync("/hq", {
+        await reindexAfterSync("/hq", {
             exec,
             existsSync: () => true,
             acquireReindexLock: () => ({
@@ -508,7 +509,7 @@ describe("reindexAfterSync", () => {
         expect(released).toBe(true);
     });
     // ── Corruption safety: timeout-kill handling ───────────────────────────────
-    it("treats a timed-out update as not-done, marks dirty, and does NOT embed", () => {
+    it("treats a timed-out update as not-done, marks dirty, and does NOT embed", async () => {
         const dir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-qmd-timeout-"));
         try {
             const statePath = path.join(dir, "qmd-state.json");
@@ -516,7 +517,7 @@ describe("reindexAfterSync", () => {
                 listStdout: "",
                 resultFor: (args) => args[0] === "update" ? { status: null, timedOut: true } : undefined,
             });
-            const r = reindexAfterSync("/hq", {
+            const r = await reindexAfterSync("/hq", {
                 exec,
                 acquireReindexLock: noLock,
                 existsSync: () => true,
@@ -536,12 +537,12 @@ describe("reindexAfterSync", () => {
             fs.rmSync(dir, { recursive: true, force: true });
         }
     });
-    it("treats a timed-out embed as not-embedded and marks dirty", () => {
+    it("treats a timed-out embed as not-embedded and marks dirty", async () => {
         const { exec } = fakeExec({
             listStdout: "",
             resultFor: (args) => args[0] === "embed" ? { status: null, timedOut: true } : undefined,
         });
-        const r = reindexAfterSync("/hq", {
+        const r = await reindexAfterSync("/hq", {
             exec,
             acquireReindexLock: noLock,
             existsSync: () => true,
@@ -554,7 +555,7 @@ describe("reindexAfterSync", () => {
         expect(r.pendingDirty).toBe(true);
     });
     // ── Corruption safety: SQLITE_CORRUPT detection + quarantine ────────────────
-    it("quarantines the resolved index dir when update reports SQLITE_CORRUPT", () => {
+    it("quarantines the resolved index dir when update reports SQLITE_CORRUPT", async () => {
         const dir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-qmd-corrupt-"));
         try {
             const statePath = path.join(dir, "qmd-state.json");
@@ -571,7 +572,7 @@ describe("reindexAfterSync", () => {
                     ? { status: 1, stderr: "SqliteError: database disk image is malformed (SQLITE_CORRUPT)" }
                     : undefined,
             });
-            const r = reindexAfterSync("/hq", {
+            const r = await reindexAfterSync("/hq", {
                 exec,
                 acquireReindexLock: noLock,
                 existsSync: () => true,
@@ -593,14 +594,14 @@ describe("reindexAfterSync", () => {
             fs.rmSync(dir, { recursive: true, force: true });
         }
     });
-    it("reports quarantine failure when corruption is detected but nothing moves", () => {
+    it("reports quarantine failure when corruption is detected but nothing moves", async () => {
         const quarantined = [];
         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", {
+        const r = await reindexAfterSync("/hq", {
             exec,
             acquireReindexLock: noLock,
             existsSync: () => true,
@@ -615,7 +616,7 @@ describe("reindexAfterSync", () => {
         expect(calls).toEqual([["status"], ["collection", "list"]]);
         expect(quarantined).toEqual([path.join("/hq", ".qmd")]);
     });
-    it("quarantines when embed reports SQLITE_CORRUPT", () => {
+    it("quarantines when embed reports SQLITE_CORRUPT", async () => {
         const quarantined = [];
         const { exec, calls } = fakeExec({
             listStdout: "",
@@ -623,7 +624,7 @@ describe("reindexAfterSync", () => {
                 ? { status: 1, stderr: "code SQLITE_CORRUPT at store.js:1546" }
                 : undefined,
         });
-        const r = reindexAfterSync("/hq", {
+        const r = await reindexAfterSync("/hq", {
             exec,
             acquireReindexLock: noLock,
             existsSync: () => true,
@@ -642,7 +643,7 @@ describe("reindexAfterSync", () => {
 });
 // ── The default reindex lock (real filesystem) ───────────────────────────────
 describe("default reindex lock", () => {
-    it("holds the lock for the duration of the cycle and releases it after", () => {
+    it("holds the lock for the duration of the cycle and releases it after", async () => {
         const dir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-qmd-lock-"));
         try {
             const hq = path.join(dir, "hq");
@@ -654,7 +655,7 @@ describe("default reindex lock", () => {
             const lockPath = path.join(hq, ".qmd", ".reindex.lock");
             let reAcquireBlockedWhileHeld = false;
             const { exec } = fakeExec({ listStdout: "" });
-            const observingExec = (args) => {
+            const observingExec = async (args) => {
                 if (args[0] === "update") {
                     try {
                         fs.closeSync(fs.openSync(lockPath, "wx"));
@@ -665,9 +666,9 @@ describe("default reindex lock", () => {
                             err.code === "EEXIST";
                     }
                 }
-                return exec(args);
+                return await exec(args);
             };
-            const r = reindexAfterSync(hq, { exec: observingExec });
+            const r = await reindexAfterSync(hq, { exec: observingExec });
             expect(r.updated).toBe(true);
             expect(reAcquireBlockedWhileHeld).toBe(true);
             expect(fs.existsSync(lockPath)).toBe(false);
@@ -676,7 +677,7 @@ describe("default reindex lock", () => {
             fs.rmSync(dir, { recursive: true, force: true });
         }
     });
-    it("reclaims a lock held by a dead PID (stale takeover)", () => {
+    it("reclaims a lock held by a dead PID (stale takeover)", async () => {
         const dir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-qmd-lock-stale-"));
         try {
             const hq = path.join(dir, "hq");
@@ -689,7 +690,7 @@ describe("default 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 });
+            const r = await reindexAfterSync(hq, { exec });
             expect(r.updated).toBe(true);
             expect(r.lockBusy).toBe(false);
             expect(calls.some((c) => c[0] === "update")).toBe(true);
@@ -700,7 +701,7 @@ describe("default reindex lock", () => {
     });
 });
 describe("acquireDualReindexLocks", () => {
-    it("dedupes identical paths so a process cannot lock itself out", () => {
+    it("dedupes identical paths so a process cannot lock itself out", async () => {
         let acquires = 0;
         const acquire = () => {
             acquires++;
@@ -712,7 +713,7 @@ describe("acquireDualReindexLocks", () => {
         expect(locks).toHaveLength(1);
         expect(acquires).toBe(1);
     });
-    it("releases the first lock when the second is busy", () => {
+    it("releases the first lock when the second is busy", async () => {
         const released = [];
         let n = 0;
         const acquire = (lockPath) => {
@@ -736,46 +737,158 @@ describe("acquireDualReindexLocks", () => {
 });
 // ── Pure helpers ─────────────────────────────────────────────────────────────
 describe("resolveExecTimeoutMs", () => {
-    it("defaults to a generous bound, not the old 120s that killed writes", () => {
+    it("defaults to a generous bound, not the old 120s that killed writes", async () => {
         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", () => {
+    it("honors a valid HQ_QMD_EXEC_TIMEOUT_MS override", async () => {
         expect(resolveExecTimeoutMs({ HQ_QMD_EXEC_TIMEOUT_MS: "300000" })).toBe(300_000);
     });
-    it("ignores an invalid override", () => {
+    it("ignores an invalid override", async () => {
         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("createQmdExec", () => {
+    function waitForReadyMarker(markerPath) {
+        if (fs.existsSync(markerPath))
+            return Promise.resolve();
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const watcher = fs.watch(path.dirname(markerPath));
+            const timeout = setRealTimeout(() => {
+                if (settled)
+                    return;
+                settled = true;
+                watcher.close();
+                reject(new Error(`qmd child did not become ready: ${markerPath}`));
+            }, 10_000);
+            timeout.unref();
+            const finish = (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                watcher.close();
+                clearRealTimeout(timeout);
+                if (error)
+                    reject(error);
+                else
+                    resolve();
+            };
+            watcher.on("change", (_event, filename) => {
+                if ((filename === null || filename.toString() === path.basename(markerPath)) &&
+                    fs.existsSync(markerPath)) {
+                    finish();
+                }
+            });
+            watcher.once("error", finish);
+            if (fs.existsSync(markerPath))
+                finish();
+        });
+    }
+    function readyChildScript(markerPath, sigintHandler) {
+        return [
+            "const fs = require('node:fs');",
+            `process.on('SIGINT', ${sigintHandler});`,
+            `fs.writeFileSync(${JSON.stringify(markerPath)}, 'ready');`,
+            "setInterval(() => {}, 1000);",
+        ].join(" ");
+    }
+    it("captures output and sends SIGINT when the configured timeout expires", async () => {
+        const markerDir = fs.mkdtempSync(path.join(os.tmpdir(), "qmd-exec-timeout-"));
+        const markerPath = path.join(markerDir, "ready");
+        const controller = new AbortController();
+        const exec = createQmdExec({
+            command: process.execPath,
+            timeoutMs: 250,
+            // Keep the escalation outside the 250ms timeout-clock advance.
+            sigintGraceMs: 1_000,
+        });
+        const ready = waitForReadyMarker(markerPath);
+        let resultPromise;
+        vi.useFakeTimers();
+        try {
+            resultPromise = exec([
+                "-e",
+                readyChildScript(markerPath, "() => { process.stdout.write('sigint'); process.exit(0); }"),
+            ], { signal: controller.signal });
+            await Promise.race([
+                ready,
+                resultPromise.then(() => {
+                    throw new Error("qmd child exited before installing its SIGINT handler");
+                }),
+            ]);
+            await vi.advanceTimersByTimeAsync(250);
+            const result = await resultPromise;
+            expect(result).toMatchObject({ status: 0, timedOut: true });
+            expect(result.stdout).toContain("sigint");
+        }
+        finally {
+            vi.useRealTimers();
+            controller.abort();
+            if (resultPromise)
+                await resultPromise;
+            fs.rmSync(markerDir, { recursive: true, force: true });
+        }
+    });
+    it("sends SIGINT to an in-flight child on shutdown and escalates after the grace period", async () => {
+        const markerDir = fs.mkdtempSync(path.join(os.tmpdir(), "qmd-exec-abort-"));
+        const markerPath = path.join(markerDir, "ready");
+        const controller = new AbortController();
+        const exec = createQmdExec({
+            command: process.execPath,
+            timeoutMs: 10_000,
+            sigintGraceMs: 50,
+        });
+        let resultPromise;
+        try {
+            resultPromise = exec([
+                "-e",
+                readyChildScript(markerPath, "() => process.stdout.write('sigint')"),
+            ], { signal: controller.signal });
+            await waitForReadyMarker(markerPath);
+            controller.abort();
+            const result = await resultPromise;
+            expect(result.timedOut).toBe(false);
+            expect(result.stdout).toContain("sigint");
+            expect(result.status).toBeNull();
+        }
+        finally {
+            controller.abort();
+            if (resultPromise)
+                await resultPromise;
+            fs.rmSync(markerDir, { recursive: true, force: true });
+        }
+    });
+});
 describe("looksCorrupt", () => {
-    it("matches the SQLITE_CORRUPT signature on stdout or stderr", () => {
+    it("matches the SQLITE_CORRUPT signature on stdout or stderr", async () => {
         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", () => {
+    it("does not match clean output", async () => {
         expect(looksCorrupt({ stdout: "Updated 688 documents", stderr: "" })).toBe(false);
         expect(looksCorrupt({})).toBe(false);
     });
 });
 describe("parseIndexDirFromStatus / parseCollectionPathFromShow", () => {
-    it("parses Index file path into its directory", () => {
+    it("parses Index file path into its directory", async () => {
         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", () => {
+    it("returns null when Index line is missing", async () => {
         expect(parseIndexDirFromStatus("Collections: 2\n")).toBeNull();
     });
-    it("parses Path from collection show", () => {
+    it("parses Path from collection show", async () => {
         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", () => {
+    it("treats case and trailing separators as equal", async () => {
         expect(pathsEquivalent("/HQ/Companies/Acme/knowledge/", "/hq/companies/acme/knowledge", (p) => p)).toBe(true);
     });
-    it("enables repair only for 1/true/yes", () => {
+    it("enables repair only for 1/true/yes", async () => {
         expect(repairPathDriftEnabled({})).toBe(false);
         expect(repairPathDriftEnabled({ HQ_QMD_REPAIR_PATH_DRIFT: "1" })).toBe(true);
         expect(repairPathDriftEnabled({ HQ_QMD_REPAIR_PATH_DRIFT: "true" })).toBe(true);