@indigoai-us/hq-cloud 6.15.0 → 6.15.2

package/src/qmd-reindex.ts

@@ -1,842 +0,0 @@
-/**
- * Post-sync qmd reindex.
- *
- * Why this lives in the runner (not just an HQ-core script): the qmd search
- * index is a per-machine local store, and nothing re-indexed it after a sync
- * pulled new files in — so teammates saw divergent search results depending
- * on who ran `qmd update` most recently, and newly-synced knowledge folders
- * weren't searchable until someone manually registered them as a collection.
- *
- * The runner ships via `npx @indigoai-us/hq-cloud@latest` (both the AppBar
- * menubar and the `/hq-sync` CLI pull it at runtime), so putting the fix here
- * reaches every teammate on their next sync WITHOUT requiring them to update
- * their HQ core. It is therefore intentionally self-contained: it shells out
- * to the globally-installed `qmd` binary directly and does NOT depend on any
- * script inside the synced HQ tree (which may be stale).
- *
- * What it does, best-effort and idempotent:
- *   1. Auto-registers populated company knowledge, company project, and
- *      personal knowledge dirs that aren't yet qmd collections (kills the
- *      manual "map" step). Company knowledge detects path drift when the name
- *      exists but points elsewhere; repairs only when
- *      `HQ_QMD_REPAIR_PATH_DRIFT=1` (non-breaking default: detect-only).
- *   2. Runs an incremental lexical `qmd update` (fast — qmd skips unchanged
- *      files by mtime).
- *   3. Rebuilds embeddings only when `embed: true` (slow on a multi-GB
- *      index; meant for an idle pass, not every sync). Never embeds in the
- *      same cycle as a path-drift repair (repair drops that collection's
- *      vectors).
- *
- * The index itself is never synced — it is large, binary, and embeds absolute
- * local paths. Only its *freshness* is automated here.
- *
- * ## Corruption safety (feedback_b9a369ff + feedback_332c7ccc)
- *
- * The qmd store (sqlite-vec) was being corrupted on the vector side because
- * TWO uncoordinated writers raced on it. Mitigations:
- *   - Raised exec timeout so legitimate long passes are not killed mid-write.
- *   - Dual advisory lock: legacy `<hqRoot>/.qmd/.reindex.lock` AND
- *     `<resolvedIndexDir>/.reindex.lock` (deduped when equal). Default index
- *     is often `~/.cache/qmd/index.sqlite`, not `<hqRoot>/.qmd`.
- *   - Corruption quarantine targets the resolved index dir; reports success
- *     only when files were actually moved.
- */
-
-import * as fs from "fs";
-import * as path from "path";
-import { spawnSync } from "child_process";
-
-/** Result of a single `qmd` invocation. */
-export interface QmdExecResult {
-  status: number | null;
-  stdout: string;
-  /** Captured stderr (qmd prints SQLITE_CORRUPT errors here). Optional for fakes. */
-  stderr?: string;
-  /** True when the process was killed because it exceeded the exec timeout. */
-  timedOut?: boolean;
-}
-
-/** Injectable command runner — real `spawnSync` in prod, a fake in tests. */
-export interface QmdExec {
-  (args: string[]): QmdExecResult;
-}
-
-/**
- * Default exec timeout for a single `qmd` invocation. The historical 120s bound
- * routinely killed `qmd update`/`qmd embed` mid-write on a large index (the HQ
- * root's `hq` collection alone spans the whole tree), which corrupted the vector
- * store. 15 minutes comfortably covers a cold or embed-heavy pass, so the bound
- * effectively stops firing on legitimate work; a genuinely wedged process is
- * still bounded, and a timed-out pass is treated as not-done (never written
- * further onto) — see {@link defaultExec} and {@link reindexAfterSync}.
- */
-export const DEFAULT_QMD_EXEC_TIMEOUT_MS = 900_000;
-
-/** Resolve the exec timeout, honoring `HQ_QMD_EXEC_TIMEOUT_MS` (ms) if valid. */
-export function resolveExecTimeoutMs(env: NodeJS.ProcessEnv = process.env): number {
-  const raw = env.HQ_QMD_EXEC_TIMEOUT_MS;
-  if (raw !== undefined && raw !== "") {
-    const n = Number(raw);
-    if (Number.isFinite(n) && n > 0) return Math.round(n);
-  }
-  return DEFAULT_QMD_EXEC_TIMEOUT_MS;
-}
-
-/** Opt-in destructive path-drift repair (remove + re-add). Default off. */
-export function repairPathDriftEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
-  const raw = (env.HQ_QMD_REPAIR_PATH_DRIFT ?? "").trim().toLowerCase();
-  return raw === "1" || raw === "true" || raw === "yes";
-}
-
-/**
- * Parse the directory that holds `index.sqlite` from `qmd status` output.
- * Returns null when the Index line is missing/unparseable.
- */
-export function parseIndexDirFromStatus(stdout: string): string | null {
-  const m = stdout.match(/^\s*Index:\s*(.+?)\s*$/m);
-  if (!m) return null;
-  const indexFile = m[1].trim();
-  if (!indexFile) return null;
-  return path.dirname(indexFile);
-}
-
-/** Parse `Path:` from `qmd collection show` human output. */
-export function parseCollectionPathFromShow(stdout: string): string | null {
-  const m = stdout.match(/^\s*Path:\s*(.+?)\s*$/m);
-  if (!m) return null;
-  const p = m[1].trim();
-  return p || null;
-}
-
-/** Case-insensitive, trailing-separator-tolerant path equality after realpath. */
-export function pathsEquivalent(
-  a: string,
-  b: string,
-  realpathSync: (p: string) => string = safeRealpathSync,
-): boolean {
-  return normalizePathKey(realpathSync(a)) === normalizePathKey(realpathSync(b));
-}
-
-function normalizePathKey(p: string): string {
-  return path.resolve(p).replace(/[/\\]+$/, "").toLowerCase();
-}
-
-function safeRealpathSync(p: string): string {
-  try {
-    return fs.realpathSync(p);
-  } catch {
-    return path.resolve(p);
-  }
-}
-
-const defaultExec: QmdExec = (args) => {
-  const res = spawnSync("qmd", args, {
-    encoding: "utf8",
-    // Bound so a wedged index never hangs the runner forever, but generously —
-    // see DEFAULT_QMD_EXEC_TIMEOUT_MS.
-    timeout: resolveExecTimeoutMs(),
-    // On timeout send SIGINT instead of the default SIGTERM. NOTE: qmd 2.5.3
-    // traps BOTH identically — each handler only restores the cursor and calls
-    // process.exit() — so SIGINT is NOT inherently a graceful transaction
-    // unwind; it is simply the same exit path qmd takes on Ctrl-C. The real
-    // write-safety guarantee is the raised bound above (a kill is now rare) plus
-    // treating a timed-out pass as not-done and never embedding after it (see
-    // reindexAfterSync). SIGINT is kept only so a killed pass exits qmd's normal
-    // way rather than via an unhandled default signal.
-    killSignal: "SIGINT",
-  });
-  const timedOut =
-    res.error != null &&
-    (res.error as NodeJS.ErrnoException).code === "ETIMEDOUT";
-  return {
-    status: res.status,
-    stdout: res.stdout ?? "",
-    stderr: res.stderr ?? "",
-    timedOut,
-  };
-};
-
-/** SQLite corruption signature qmd surfaces when the vector store is damaged. */
-const CORRUPTION_SIGNATURE = /SQLITE_CORRUPT|database disk image is malformed/i;
-
-/** True if a qmd result reports SQLite corruption on stdout or stderr. */
-export function looksCorrupt(r: Partial<Pick<QmdExecResult, "stdout" | "stderr">>): boolean {
-  return CORRUPTION_SIGNATURE.test(`${r.stdout ?? ""}\n${r.stderr ?? ""}`);
-}
-
-/** Handle returned by an acquired reindex lock. `release()` is idempotent. */
-export interface ReindexLockHandle {
-  release(): void;
-}
-
-/**
- * Acquire the shared reindex lock at `lockPath`. Returns a handle when acquired,
- * or `null` when another live writer already holds it (caller should skip the
- * cycle). Must never throw — coordination is advisory and must not fail a sync.
- */
-export type AcquireReindexLock = (lockPath: string) => ReindexLockHandle | null;
-
-/**
- * How long a lock file may sit before a new acquirer treats it as abandoned and
- * reclaims it, even if its recorded PID can't be probed (e.g. a different user,
- * or a torn/empty file). Backstops the PID-liveness check for the crash case.
- */
-const DEFAULT_LOCK_STALE_MS = 30 * 60_000;
-
-function reindexLockStaleMs(env: NodeJS.ProcessEnv = process.env): number {
-  const raw = env.HQ_QMD_LOCK_STALE_MS;
-  if (raw !== undefined && raw !== "") {
-    const n = Number(raw);
-    if (Number.isFinite(n) && n >= 0) return Math.round(n);
-  }
-  return DEFAULT_LOCK_STALE_MS;
-}
-
-const NOOP_LOCK: ReindexLockHandle = { release() {} };
-
-// Track locks this process holds so a clean exit/signal removes them; a crash is
-// covered by the stale/PID reclaim path in the acquirer.
-const heldReindexLocks = new Set<string>();
-let reindexExitHookInstalled = false;
-
-function installReindexExitHookOnce(): void {
-  if (reindexExitHookInstalled) return;
-  reindexExitHookInstalled = true;
-  process.on("exit", () => {
-    for (const p of heldReindexLocks) unlinkIfOwned(p);
-  });
-}
-
-/** Is `pid` a live process? ESRCH → dead; EPERM/other → conservatively alive. */
-function pidAlive(pid: number): boolean {
-  if (!Number.isInteger(pid) || pid <= 0) return false;
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (err) {
-    return (err as NodeJS.ErrnoException)?.code !== "ESRCH";
-  }
-}
-
-/** Unlink `lockPath` only if it still records THIS process as the holder. */
-function unlinkIfOwned(lockPath: string): void {
-  try {
-    const info = JSON.parse(fs.readFileSync(lockPath, "utf8")) as { pid?: number };
-    if (info?.pid !== process.pid) return;
-  } catch {
-    // Unreadable/torn/already-gone — don't risk clobbering another holder.
-    return;
-  }
-  try {
-    fs.unlinkSync(lockPath);
-  } catch {
-    /* already gone — fine */
-  }
-}
-
-/**
- * If the lock at `lockPath` is held by a dead PID or is older than the stale
- * bound, unlink it so the caller can retry. Returns true when it reclaimed (or
- * the lock vanished mid-check), false when a live, fresh holder still owns it.
- */
-function reclaimReindexLockIfStale(lockPath: string): boolean {
-  let st: fs.Stats;
-  try {
-    st = fs.statSync(lockPath);
-  } catch {
-    // Vanished between EEXIST and stat → the holder released; let caller retry.
-    return true;
-  }
-  let holderPid = 0;
-  try {
-    const info = JSON.parse(fs.readFileSync(lockPath, "utf8")) as { pid?: number };
-    if (typeof info?.pid === "number") holderPid = info.pid;
-  } catch {
-    /* torn/empty lock — fall through to the staleness check */
-  }
-  const dead = holderPid > 0 && !pidAlive(holderPid);
-  const stale = Date.now() - st.mtimeMs > reindexLockStaleMs();
-  if (dead || stale) {
-    try {
-      fs.unlinkSync(lockPath);
-    } catch {
-      // Someone else reclaimed it first; the next create attempt re-evaluates.
-    }
-    return true;
-  }
-  return false;
-}
-
-const defaultAcquireReindexLock: AcquireReindexLock = (lockPath) => {
-  // Escape hatch: a caller that manages exclusion itself can disable the lock.
-  if (process.env.HQ_QMD_REINDEX_LOCK === "0") return NOOP_LOCK;
-
-  const payload = JSON.stringify({
-    pid: process.pid,
-    startedAt: new Date().toISOString(),
-    command: "hq-cloud qmd-reindex",
-  });
-
-  // At most one reclaim + one retry: acquire, or (if stale) reclaim then retry.
-  for (let attempt = 0; attempt < 2; attempt++) {
-    try {
-      fs.mkdirSync(path.dirname(lockPath), { recursive: true });
-      const fd = fs.openSync(lockPath, "wx", 0o600);
-      try {
-        fs.writeSync(fd, payload);
-      } finally {
-        fs.closeSync(fd);
-      }
-      heldReindexLocks.add(lockPath);
-      installReindexExitHookOnce();
-      return {
-        release() {
-          heldReindexLocks.delete(lockPath);
-          unlinkIfOwned(lockPath);
-        },
-      };
-    } catch (err) {
-      if ((err as NodeJS.ErrnoException)?.code !== "EEXIST") {
-        // The lock dir isn't writable. Fail OPEN rather than block the reindex
-        // on an infra problem: proceed without the advisory lock. The corruption
-        // guard below is the remaining backstop.
-        return NOOP_LOCK;
-      }
-      // Held. Reclaim iff the holder is dead/stale, then retry once.
-      if (reclaimReindexLockIfStale(lockPath)) continue;
-      return null; // live, fresh holder → skip this cycle
-    }
-  }
-  return null;
-};
-
-/**
- * Acquire unique lock paths (legacy + resolved index). If any is busy, release
- * what was acquired and return busy. Dedupes when both paths are the same so a
- * process never O_EXCL-locks itself out.
- */
-export function acquireDualReindexLocks(
-  acquireLock: AcquireReindexLock,
-  lockPaths: string[],
-): { locks: ReindexLockHandle[]; busy: boolean } {
-  const unique: string[] = [];
-  const seen = new Set<string>();
-  for (const p of lockPaths) {
-    const key = normalizePathKey(p);
-    if (seen.has(key)) continue;
-    seen.add(key);
-    unique.push(p);
-  }
-  const locks: ReindexLockHandle[] = [];
-  for (const p of unique) {
-    const handle = acquireLock(p);
-    if (!handle) {
-      for (const acquired of locks) acquired.release();
-      return { locks: [], busy: true };
-    }
-    locks.push(handle);
-  }
-  return { locks, busy: false };
-}
-
-/** Move corrupt DB files aside (never delete) so a clean rebuild can follow. */
-export type QuarantineCorruptIndex = (
-  qmdDir: string,
-  timestampSuffix: string,
-) => string | null;
-
-const CORRUPTIBLE_DB_FILES = ["index.sqlite", "index.sqlite-wal", "index.sqlite-shm"];
-
-const defaultQuarantineCorruptIndex: QuarantineCorruptIndex = (qmdDir, tsSuffix) => {
-  let movedBase: string | null = null;
-  for (const name of CORRUPTIBLE_DB_FILES) {
-    const src = path.join(qmdDir, name);
-    try {
-      if (!fs.existsSync(src)) continue;
-      const dest = `${src}.corrupt-${tsSuffix}`;
-      fs.renameSync(src, dest);
-      if (name === "index.sqlite") movedBase = dest;
-      else if (movedBase === null) movedBase = dest;
-    } catch {
-      // Best-effort: move what we can. A file we can't move is left in place;
-      // the corruption guard still prevents further writes this cycle.
-    }
-  }
-  return movedBase;
-};
-
-/** Filesystem-safe timestamp suffix for a quarantined DB file. */
-function quarantineSuffix(nowMs: number): string {
-  return new Date(nowMs).toISOString().replace(/[:.]/g, "-");
-}
-
-const DEFAULT_CHANGED_PATH_DEBOUNCE_MS = 60_000;
-
-export interface ReindexOptions {
-  /** Rebuild embeddings too (slow). Default false — lexical-only. */
-  embed?: boolean;
-  /**
-   * HQ-relative paths changed by sync. When omitted, preserves the historical
-   * behavior and runs QMD for any sync caller that invokes this function.
-   */
-  changedPaths?: string[];
-  /** Force a collection registration refresh even when content is not dirty. */
-  forceCollectionRefresh?: boolean;
-  /** Delay dirty updates by this many ms while keeping a persistent marker. */
-  debounceMs?: number;
-  /** Clock override for deterministic debounce tests. */
-  nowMs?: number;
-  /** State file override for tests. */
-  statePath?: string;
-  /** Command runner override for tests. */
-  exec?: QmdExec;
-  /** `existsSync` override for tests. */
-  existsSync?: (p: string) => boolean;
-  /** `readdirSync` override for tests (returns subdir names of companies/). */
-  readCompanies?: (companiesDir: string) => string[];
-  /** Returns true if the knowledge dir has at least one indexable .md file. */
-  hasIndexableMarkdown?: (knowledgeDir: string) => boolean;
-  /** Returns true if the projects dir has at least one indexable .md or .json file. */
-  hasIndexableProjectContent?: (projectsDir: string) => boolean;
-  /** Reindex-lock acquirer override for tests. */
-  acquireReindexLock?: AcquireReindexLock;
-  /** Corrupt-index quarantine override for tests. */
-  quarantineCorruptIndex?: QuarantineCorruptIndex;
-  /** realpath override for path-drift comparison in tests. */
-  realpathSync?: (p: string) => string;
-  /** Env override for tests (repair flag, etc.). */
-  env?: NodeJS.ProcessEnv;
-  /** Optional diagnostic sink for unexpected swallowed failures. */
-  log?: (diagnostic: {
-    event: string;
-    message: string;
-    err: unknown;
-    context?: Record<string, unknown>;
-  }) => void;
-}
-
-export interface ReindexResult {
-  qmdAvailable: boolean;
-  collectionsAdded: string[];
-  /** HQ-convention collections whose registered path differs from desired. */
-  pathDriftDetected: string[];
-  /** Collections successfully remove+re-added when repair was enabled. */
-  collectionsRepaired: string[];
-  updated: boolean;
-  embedded: boolean;
-  pendingDirty: boolean;
-  /** True when the cycle was skipped because another writer held the lock. */
-  lockBusy: boolean;
-  /** True when a qmd command exceeded the exec timeout and was aborted. */
-  timedOut: boolean;
-  /** True when a corrupt index was detected and files were quarantined. */
-  corruptionQuarantined: boolean;
-  /** True when corruption was detected but quarantine moved nothing. */
-  corruptionQuarantineFailed: boolean;
-  /** Directory used for quarantine / index-side lock (resolved or fallback). */
-  indexDir: string | null;
-}
-
-/**
- * Reindex qmd for an HQ tree after a sync. Never throws — all failures are
- * swallowed so a reindex problem can never mask or fail the sync result.
- *
- * @returns a small summary for logging/telemetry (collectionsAdded, updated).
- */
-export function reindexAfterSync(
-  hqRoot: string,
-  opts: ReindexOptions = {},
-): ReindexResult {
-  const exec = opts.exec ?? defaultExec;
-  const existsSync = opts.existsSync ?? fs.existsSync;
-  const acquireLock = opts.acquireReindexLock ?? defaultAcquireReindexLock;
-  const quarantine = opts.quarantineCorruptIndex ?? defaultQuarantineCorruptIndex;
-  const realpathSync = opts.realpathSync ?? safeRealpathSync;
-  const env = opts.env ?? process.env;
-  const result: ReindexResult = {
-    qmdAvailable: false,
-    collectionsAdded: [],
-    pathDriftDetected: [],
-    collectionsRepaired: [],
-    updated: false,
-    embedded: false,
-    pendingDirty: false,
-    lockBusy: false,
-    timedOut: false,
-    corruptionQuarantined: false,
-    corruptionQuarantineFailed: false,
-    indexDir: null,
-  };
-
-  try {
-    // Guard: only operate on a real HQ tree.
-    if (!existsSync(path.join(hqRoot, "core", "core.yaml"))) return result;
-
-    const statePath = opts.statePath ?? path.join(hqRoot, ".hq", "qmd-reindex-state.json");
-    const state = readState(statePath);
-    const changedPaths = opts.changedPaths;
-    const dirtyFromChanges =
-      changedPaths === undefined ||
-      changedPaths.some(isQmdIndexableContentPath);
-    const registrationMayBeStale =
-      opts.forceCollectionRefresh === true ||
-      changedPaths === undefined ||
-      dirtyFromChanges;
-    const pendingDirty = state.pendingDirty === true;
-    if (!dirtyFromChanges && !registrationMayBeStale && !pendingDirty) {
-      return result;
-    }
-
-    const nowMs = opts.nowMs ?? Date.now();
-    const pendingSinceMs =
-      pendingDirty && typeof state.pendingSinceMs === "number"
-        ? state.pendingSinceMs
-        : nowMs;
-
-    // Resolve the real index directory before locking. Default qmd layout is
-    // ~/.cache/qmd, not <hqRoot>/.qmd — status is read-only.
-    const legacyQmdDir = path.join(hqRoot, ".qmd");
-    const status = exec(["status"]);
-    const parsedIndexDir = parseIndexDirFromStatus(status.stdout ?? "");
-    const indexDir = parsedIndexDir ?? legacyQmdDir;
-    result.indexDir = indexDir;
-
-    // Serialize qmd writers across legacy + resolved layouts (feedback_332c7ccc).
-    const { locks, busy } = acquireDualReindexLocks(acquireLock, [
-      path.join(legacyQmdDir, ".reindex.lock"),
-      path.join(indexDir, ".reindex.lock"),
-    ]);
-    if (busy) {
-      writeState(statePath, { ...state, pendingDirty: true, pendingSinceMs });
-      result.lockBusy = true;
-      result.pendingDirty = true;
-      return result;
-    }
-
-    try {
-      if (looksCorrupt(status)) {
-        handleCorruption(indexDir, statePath, state, pendingSinceMs, nowMs, quarantine, result);
-        return result;
-      }
-
-      // Guard: qmd must be installed. `qmd collection list` doubles as the
-      // availability probe AND the source for which collections already exist.
-      const list = exec(["collection", "list"]);
-      if (list.status !== 0) return result; // qmd absent or errored — no-op
-      // An already-corrupt store can surface here even on the lexical side.
-      if (looksCorrupt(list)) {
-        handleCorruption(indexDir, statePath, state, pendingSinceMs, nowMs, quarantine, result);
-        return result;
-      }
-      result.qmdAvailable = true;
-      const existingCollections = list.stdout;
-      let repairedThisCycle = false;
-      const hasIndexableMarkdown = opts.hasIndexableMarkdown ?? defaultHasIndexableMarkdown;
-      const hasIndexableProjectContent =
-        opts.hasIndexableProjectContent ?? defaultHasIndexableProjectContent;
-
-      // 1. Auto-register missing / reconcile drifted company knowledge collections.
-      if (registrationMayBeStale) {
-        const companiesDir = path.join(hqRoot, "companies");
-        const slugs = (opts.readCompanies ?? defaultReadCompanies)(companiesDir);
-        const allowRepair = repairPathDriftEnabled(env);
-        for (const slug of slugs) {
-          const knowledgeDir = path.join(companiesDir, slug, "knowledge");
-          if (!existsSync(knowledgeDir)) continue;
-          const hasMd = hasIndexableMarkdown(knowledgeDir);
-          if (!hasMd) continue;
-
-          const namePresent = existingCollections.includes(`qmd://${slug}/`);
-          if (!namePresent) {
-            const add = exec(["collection", "add", knowledgeDir, "--name", slug, "--mask", "**/*.md"]);
-            if (add.status === 0) {
-              exec(["context", "add", `qmd://${slug}`, `Knowledge base for ${slug}.`]);
-              result.collectionsAdded.push(slug);
-            }
-            continue;
-          }
-
-          // Name exists — check path (feedback_f8e233c6). Paths only on `show`.
-          const show = exec(["collection", "show", slug]);
-          if (show.status !== 0) continue;
-          const registeredPath = parseCollectionPathFromShow(show.stdout ?? "");
-          if (!registeredPath) continue;
-          if (pathsEquivalent(registeredPath, knowledgeDir, realpathSync)) continue;
-
-          result.pathDriftDetected.push(slug);
-          opts.log?.({
-            event: "runner.qmd_reindex.path_drift",
-            message: `qmd collection ${slug} path drifted`,
-            err: null,
-            context: {
-              slug,
-              registeredPath,
-              desiredPath: knowledgeDir,
-              repairEnabled: allowRepair,
-            },
-          });
-
-          if (!allowRepair) continue;
-
-          // Guaranteed hasMd + exists above. Remove + re-add; never embed inline.
-          const removed = exec(["collection", "remove", slug]);
-          if (removed.status !== 0) {
-            writeState(statePath, { ...state, pendingDirty: true, pendingSinceMs });
-            result.pendingDirty = true;
-            opts.log?.({
-              event: "runner.qmd_reindex.path_drift_repair_failed",
-              message: `failed to remove drifted collection ${slug}`,
-              err: removed.stderr ?? removed.stdout,
-              context: { slug },
-            });
-            continue;
-          }
-          const add = exec(["collection", "add", knowledgeDir, "--name", slug, "--mask", "**/*.md"]);
-          if (add.status !== 0) {
-            writeState(statePath, { ...state, pendingDirty: true, pendingSinceMs });
-            result.pendingDirty = true;
-            opts.log?.({
-              event: "runner.qmd_reindex.path_drift_repair_failed",
-              message: `removed ${slug} but failed to re-add at desired path`,
-              err: add.stderr ?? add.stdout,
-              context: { slug, knowledgeDir },
-            });
-            continue;
-          }
-          exec(["context", "add", `qmd://${slug}`, `Knowledge base for ${slug}.`]);
-          result.collectionsRepaired.push(slug);
-          repairedThisCycle = true;
-        }
-
-        // 1b. Auto-register company projects collections. Match the shell
-        // post-sync convention exactly so prd.json and project docs are searchable.
-        for (const slug of slugs) {
-          const projectsDir = path.join(companiesDir, slug, "projects");
-          if (!existsSync(projectsDir)) continue;
-          if (!hasIndexableProjectContent(projectsDir)) continue;
-
-          const name = `${slug}-projects`;
-          if (existingCollections.includes(`qmd://${name}/`)) continue;
-          const add = exec([
-            "collection",
-            "add",
-            projectsDir,
-            "--name",
-            name,
-            "--mask",
-            "**/*.{md,json}",
-          ]);
-          if (add.status === 0) {
-            exec(["context", "add", `qmd://${name}`, `Project PRDs and documentation for ${slug}.`]);
-            result.collectionsAdded.push(name);
-          }
-        }
-
-        // 1c. Auto-register the owner overlay's personal knowledge collection.
-        const personalKnowledgeDir = path.join(hqRoot, "personal", "knowledge");
-        const personalKnowledgeName = "personal-knowledge";
-        if (
-          existsSync(personalKnowledgeDir) &&
-          hasIndexableMarkdown(personalKnowledgeDir) &&
-          !existingCollections.includes(`qmd://${personalKnowledgeName}/`)
-        ) {
-          const add = exec([
-            "collection",
-            "add",
-            personalKnowledgeDir,
-            "--name",
-            personalKnowledgeName,
-            "--mask",
-            "**/*.md",
-          ]);
-          if (add.status === 0) {
-            exec([
-              "context",
-              "add",
-              `qmd://${personalKnowledgeName}`,
-              "Personal knowledge base (owner overlay).",
-            ]);
-            result.collectionsAdded.push(personalKnowledgeName);
-          }
-        }
-      }
-
-      // 2. Incremental lexical reindex.
-      const shouldUpdate = dirtyFromChanges || pendingDirty;
-      if (shouldUpdate) {
-        const debounceMs =
-          opts.debounceMs ??
-          (changedPaths === undefined ? 0 : DEFAULT_CHANGED_PATH_DEBOUNCE_MS);
-        if (debounceMs > 0 && nowMs - pendingSinceMs < debounceMs) {
-          writeState(statePath, { ...state, pendingDirty: true, pendingSinceMs });
-          result.pendingDirty = true;
-          return result;
-        }
-
-        const update = exec(["update"]);
-        if (looksCorrupt(update)) {
-          handleCorruption(indexDir, statePath, state, pendingSinceMs, nowMs, quarantine, result);
-          return result;
-        }
-        if (update.timedOut) {
-          // Aborted mid-pass by the timeout. Do NOT treat as done and do NOT
-          // proceed to embed — mark dirty and retry cleanly next cycle.
-          writeState(statePath, { ...state, pendingDirty: true, pendingSinceMs });
-          result.timedOut = true;
-          result.pendingDirty = true;
-          return result;
-        }
-        result.updated = update.status === 0;
-        if (result.updated) {
-          writeState(statePath, { pendingDirty: false, lastSuccessMs: nowMs });
-        } else {
-          writeState(statePath, { ...state, pendingDirty: true, pendingSinceMs });
-          result.pendingDirty = true;
-        }
-      }
-
-      // 3. Embeddings only on explicit request — never after a path-drift repair
-      // in the same cycle (repair destroys that collection's vectors).
-      if (opts.embed && !repairedThisCycle) {
-        const embed = exec(["embed"]);
-        if (looksCorrupt(embed)) {
-          handleCorruption(indexDir, statePath, state, pendingSinceMs, nowMs, quarantine, result);
-          return result;
-        }
-        if (embed.timedOut) {
-          writeState(statePath, { ...state, pendingDirty: true, pendingSinceMs });
-          result.timedOut = true;
-          result.pendingDirty = true;
-          return result;
-        }
-        result.embedded = embed.status === 0;
-      }
-    } finally {
-      for (const lock of locks) lock.release();
-    }
-  } catch (err) {
-    try {
-      opts.log?.({
-        event: "runner.qmd_reindex.internal_failed",
-        message: "post-sync qmd reindex failed",
-        err,
-        context: { hqRoot },
-      });
-    } catch {
-      /* diagnostics must never affect sync */
-    }
-    // Reindex is best-effort; the sync result is authoritative. Swallow.
-  }
-
-  return result;
-}
-
-/**
- * Quarantine the corrupt DB aside and mark the tree dirty so the NEXT cycle
- * rebuilds from scratch under the lock, instead of writing further onto an
- * already-damaged vector store. Mutates `result` in place.
- * `corruptionQuarantined` is true only when files were actually moved.
- */
-function handleCorruption(
-  indexDir: string,
-  statePath: string,
-  state: QmdReindexState,
-  pendingSinceMs: number,
-  nowMs: number,
-  quarantine: QuarantineCorruptIndex,
-  result: ReindexResult,
-): void {
-  const moved = quarantine(indexDir, quarantineSuffix(nowMs));
-  writeState(statePath, { ...state, pendingDirty: true, pendingSinceMs });
-  if (moved != null) {
-    result.corruptionQuarantined = true;
-  } else {
-    result.corruptionQuarantineFailed = true;
-  }
-  result.pendingDirty = true;
-}
-
-interface QmdReindexState {
-  pendingDirty?: boolean;
-  pendingSinceMs?: number;
-  lastSuccessMs?: number;
-}
-
-function readState(statePath: string): QmdReindexState {
-  try {
-    return JSON.parse(fs.readFileSync(statePath, "utf8")) as QmdReindexState;
-  } catch {
-    return {};
-  }
-}
-
-function writeState(statePath: string, state: QmdReindexState): void {
-  try {
-    fs.mkdirSync(path.dirname(statePath), { recursive: true });
-    fs.writeFileSync(statePath, JSON.stringify(state, null, 2) + "\n");
-  } catch {
-    // State is an optimization/guarantee aid; QMD failures must not fail sync.
-  }
-}
-
-function isQmdIndexableContentPath(relPath: string): boolean {
-  const normalized = relPath.split(path.sep).join("/");
-  return (
-    /^companies\/[^/]+\/knowledge\/.+\.md$/i.test(normalized) ||
-    /^companies\/[^/]+\/projects\/.+\.(?:md|json)$/i.test(normalized) ||
-    /^personal\/knowledge\/.+\.md$/i.test(normalized)
-  );
-}
-
-function defaultReadCompanies(companiesDir: string): string[] {
-  try {
-    return fs
-      .readdirSync(companiesDir, { withFileTypes: true })
-      .filter((e) => e.isDirectory() && !e.name.startsWith("_") && !e.name.startsWith("."))
-      .map((e) => e.name);
-  } catch {
-    return [];
-  }
-}
-
-function defaultHasIndexableMarkdown(knowledgeDir: string): boolean {
-  // Shallow check is enough to decide "is this collection worth registering":
-  // walk a bounded depth looking for any .md that isn't INDEX.md.
-  const stack: Array<{ dir: string; depth: number }> = [{ dir: knowledgeDir, depth: 0 }];
-  while (stack.length) {
-    const { dir, depth } = stack.pop()!;
-    let entries: fs.Dirent[];
-    try {
-      entries = fs.readdirSync(dir, { withFileTypes: true });
-    } catch {
-      continue;
-    }
-    for (const e of entries) {
-      if (e.isFile() && e.name.endsWith(".md") && e.name !== "INDEX.md") return true;
-      if (e.isDirectory() && depth < 4 && !e.name.startsWith(".")) {
-        stack.push({ dir: path.join(dir, e.name), depth: depth + 1 });
-      }
-    }
-  }
-  return false;
-}
-
-function defaultHasIndexableProjectContent(projectsDir: string): boolean {
-  // Match the shell's `find -type f \( -name '*.md' -o -name '*.json' \)`
-  // guard: project documentation and PRD JSON both make the collection useful.
-  const stack = [projectsDir];
-  while (stack.length) {
-    const dir = stack.pop()!;
-    let entries: fs.Dirent[];
-    try {
-      entries = fs.readdirSync(dir, { withFileTypes: true });
-    } catch {
-      continue;
-    }
-    for (const e of entries) {
-      if (e.isFile() && (e.name.endsWith(".md") || e.name.endsWith(".json"))) return true;
-      if (e.isDirectory()) stack.push(path.join(dir, e.name));
-    }
-  }
-  return false;
-}