@indigoai-us/hq-cli 5.97.0 → 5.97.1

package/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 ## [Unreleased]
 
+## [5.97.1]
+
+### Fixed
+
+- Search commands no longer crash — or file a Sentry report — when the bundled
+  qmd's native module was never built. pnpm 10 skips dependency build scripts by
+  default, so `pnpm add @indigoai-us/hq-cli` lands with better-sqlite3
+  uncompiled; the bundled `@tobilu/qmd` then died with "Could not locate the
+  bindings file" the moment it opened its SQLite store, and `hq index status`
+  reported that as an hq-cli crash (HQ-CLI-J, Sentry 7656662146). Three things
+  changed. The qmd usability probe now actually opens a store (a throwaway one,
+  so the real index is never touched) instead of running `qmd --version`, which
+  exited 0 even on a bindings-broken install — the false positive that let this
+  ship in 5.94.2. That probe now runs on every resolution, including when there
+  is no qmd on PATH to fall back to, so a broken bundled binary is caught rather
+  than blindly preferred. And a broken bundled qmd now self-heals: hq runs
+  better-sqlite3's own install step (`prebuild-install`, then
+  `node-gyp rebuild --release`) once, inside its own dependency tree, under a
+  hard timeout, before giving up — set `HQ_QMD_NO_REPAIR=1` to opt out. When the
+  module still cannot load, hq prints an actionable remedy (approve the build and
+  reinstall — `pnpm approve-builds -g better-sqlite3` for a global install, or
+  without `-g` for a local project, or reinstall with npm), exits 1, and skips
+  Sentry; `hq index status` degrades to a status block that
+  names the problem rather than throwing. Any other qmd failure, and any genuine
+  hq-cli defect, still reports as before. Note: hq-cli's own pnpm build approval
+  only applies when hq-cli is the root project, never on a consumer install, so
+  the runtime probe and self-heal are what make a pnpm-installed host recover.
+  (#349)
+
 ## [5.97.0]
 
 ### Added

package/dist/commands/index-cmd.js

@@ -1,7 +1,8 @@
 import { Option } from 'commander';
-import { deriveCollections, listRegisteredCollections, reconcileCollections, resolveQmdBin, resolveQmdVersion, runQmd, } from '../lib/search-index/index.js';
+import { deriveCollections, listRegisteredCollections, packageLocalBin, reconcileCollections, resolveQmdBin, resolveQmdVersion, runQmd, } from '../lib/search-index/index.js';
 import { backgroundStatus, defaultBackgroundDependencies, runBackgroundLauncher, runBackgroundWorker, } from '../lib/search-index/background.js';
 import { findHqRoot } from '../utils/manifest.js';
+import { QMD_NATIVE_BINDING_REMEDY, isQmdNativeBindingError, } from '../utils/qmd-native-binding-error.js';
 const defaults = {
     reconcileCollections,
     deriveCollections,
@@ -93,17 +94,42 @@ export function registerIndexCommand(program, dependencies = defaults) {
         .action((options) => {
         const hqRoot = resolveRoot(options.hqRoot);
         const bin = dependencies.resolveQmdBin();
-        const registered = dependencies.listRegisteredCollections(hqRoot, { bin, cwd: hqRoot });
+        // resolveQmdVersion() reads the BUNDLED @tobilu/qmd manifest, so it is
+        // only accurate for the bundled binary. When the store-opening probe
+        // rejects the bundled qmd and a PATH (or HQ_QMD_BIN) qmd wins, pairing its
+        // path with the bundled version would misreport it — omit it instead.
+        const qmdVersion = bin === packageLocalBin() ? dependencies.resolveQmdVersion() : undefined;
         const expected = dependencies.deriveCollections(hqRoot);
-        const qmdStatus = dependencies.runQmd(['status'], { bin, cwd: hqRoot });
-        const qmdVersion = dependencies.resolveQmdVersion();
         const background = (dependencies.backgroundStatus ?? backgroundStatus)(makeBackgroundDependencies(hqRoot, dependencies));
         console.log(`qmd: ${bin}${qmdVersion ? ` (version ${qmdVersion})` : ''}`);
-        console.log(collectionSummary(expected, registered));
+        // The bundled qmd can be present yet unable to open its SQLite store when
+        // pnpm 10 left better-sqlite3 unbuilt (HQ-CLI-J). Degrade rather than
+        // throwing QmdExitError out of the command: still report everything
+        // derivable without qmd, print the reason + remedy on stderr, and exit 1 —
+        // this diagnostic command should describe the broken install, not become a
+        // Sentry crash. Any OTHER qmd failure keeps propagating and reporting.
+        let registered;
+        let qmdStatus;
+        try {
+            registered = dependencies.listRegisteredCollections(hqRoot, { bin, cwd: hqRoot });
+            qmdStatus = dependencies.runQmd(['status'], { bin, cwd: hqRoot });
+        }
+        catch (error) {
+            if (!isQmdNativeBindingError(error))
+                throw error;
+            process.stderr.write(`qmd: unusable — native bindings unbuilt. ${QMD_NATIVE_BINDING_REMEDY}\n`);
+            process.exitCode = 1;
+        }
+        if (registered) {
+            console.log(collectionSummary(expected, registered));
+        }
+        else {
+            console.log(`collections: unavailable (qmd unusable); ${expected.length} expected`);
+        }
         console.log(`background: lock ${background.lock}; last completed ${background.completedAt ?? 'never'}`);
-        if (qmdStatus.stdout)
+        if (qmdStatus?.stdout)
             process.stdout.write(qmdStatus.stdout);
-        if (qmdStatus.stderr)
+        if (qmdStatus?.stderr)
             process.stderr.write(qmdStatus.stderr);
     });
 }

package/dist/lib/search-index/index.d.ts

@@ -28,7 +28,30 @@ export type ResolveQmdBinOptions = {
     packageBin?: () => string | undefined;
     pathBin?: () => string | undefined;
     isUsable?: (bin: string) => boolean;
+    /**
+     * Attempt a one-shot native-binding repair of a package-local qmd, returning
+     * whether the caller should re-probe. Injected in tests; the default is
+     * {@link repairQmdNativeBindings}.
+     */
+    repair?: (bin: string) => boolean;
 };
+/**
+ * Locate the bundled qmd through the dependency-bin link the package manager
+ * installs, walking up from this module.
+ *
+ * Two earlier approaches were wrong and both failed silently, so every host fell
+ * through to PATH and a machine without a global qmd reported "skipped" — which
+ * defeats the point of depending on qmd at all:
+ *
+ *   - `<pkg>/qmd` guessed a filename; the package declares `bin/qmd`.
+ *   - `require.resolve('@tobilu/qmd/package.json')` throws
+ *     ERR_PACKAGE_PATH_NOT_EXPORTED on qmd 2.x, whose `exports` map does not
+ *     expose package.json.
+ *
+ * `node_modules/.bin/qmd` is the contract every package manager honours and is
+ * independent of the dependency's own exports map.
+ */
+export declare function packageLocalBin(): string | undefined;
 /**
  * Return the pinned package version when qmd is supplied by this CLI.
  *
@@ -37,6 +60,52 @@ export type ResolveQmdBinOptions = {
  * disappeared from `hq index status`. Same root cause as packageLocalBin.
  */
 export declare function resolveQmdVersion(): string | undefined;
+/** Reset per-process probe/repair memoisation. Test-only. */
+export declare function __resetQmdProbeStateForTests(): void;
+export declare function isUsableQmd(bin: string): boolean;
+/**
+ * Derive the better-sqlite3 PACKAGE directory qmd tried to load, from a bindings
+ * failure. `bindings` lists every path it tried, each ending in
+ * `.../better-sqlite3/<build-subdir>/better_sqlite3.node`; we take the package
+ * root (up to and including the `/better-sqlite3` segment). Returns undefined
+ * when the text carries no such path.
+ */
+export declare function betterSqlite3DirFromFailure(detail: string): string | undefined;
+/**
+ * A repair may write ONLY inside the same install tree as the resolved
+ * package-local qmd — never a PATH/system qmd, never a path outside that tree.
+ * Both the qmd bin and the better-sqlite3 dir must live under a shared
+ * `node_modules`/`.pnpm` ancestor; anything else is refused.
+ */
+export declare function repairConfinedTo(qmdBin: string, betterSqlite3Dir: string): boolean;
+type RepairSpawn = (cmd: string, args: string[], opts: {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    timeout: number;
+}) => {
+    status: number | null;
+    error?: Error;
+};
+export type QmdRepairOptions = {
+    env?: Record<string, string | undefined>;
+    /** Failure text to derive the better-sqlite3 dir from; defaults to the last probe's. */
+    failureDetail?: string;
+    /** Injected in tests so the real build tools are never spawned. */
+    spawn?: RepairSpawn;
+};
+/**
+ * Bounded, one-shot self-repair of a package-local qmd whose better-sqlite3
+ * native module was never built (pnpm 10 skips the build script for dependency
+ * installs). Runs better-sqlite3's own declared install step —
+ * `prebuild-install`, then `node-gyp rebuild --release` — inside the resolved
+ * package directory, under a hard timeout, at most once per process, then lets
+ * the caller re-probe. Returns whether `better_sqlite3.node` now exists.
+ *
+ * Every failure mode degrades to `false` (the caller then surfaces the
+ * classified native-binding remedy): it never throws, never retries, never
+ * waits unbounded, and never touches anything outside hq's own dependency tree.
+ */
+export declare function repairQmdNativeBindings(bin: string, options?: QmdRepairOptions): boolean;
 /** Resolve qmd without relying on a globally installed copy. */
 export declare function resolveQmdBin(options?: ResolveQmdBinOptions): string;
 export type RunQmdOptions = {
@@ -62,4 +131,5 @@ export type ReconcileCollectionsOptions = {
 /** Register expected collections that qmd does not yet know about. */
 export declare function reconcileCollections(hqRoot: string, options?: ReconcileCollectionsOptions): SearchCollection[];
 export declare function listRegisteredCollections(hqRoot: string, options?: RunQmdOptions): Set<string>;
+export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/lib/search-index/index.js

@@ -1,8 +1,10 @@
 import { spawnSync } from 'node:child_process';
 import * as fs from 'node:fs';
 import { createRequire } from 'node:module';
+import * as os from 'node:os';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { isQmdNativeBindingError } from '../../utils/qmd-native-binding-error.js';
 const require = createRequire(import.meta.url);
 export class QmdBinaryMissingError extends Error {
     name = 'QmdBinaryMissingError';
@@ -49,7 +51,7 @@ function isExecutable(candidate) {
  * `node_modules/.bin/qmd` is the contract every package manager honours and is
  * independent of the dependency's own exports map.
  */
-function packageLocalBin() {
+export function packageLocalBin() {
     const names = process.platform === 'win32' ? ['qmd.cmd', 'qmd.exe', 'qmd'] : ['qmd'];
     let directory = path.dirname(fileURLToPath(import.meta.url));
     for (let depth = 0; depth < 10; depth++) {
@@ -110,24 +112,239 @@ function pathBin() {
 }
 const usableQmdCache = new Map();
 /**
- * Does this qmd binary actually run? `--version` is the cheapest subcommand
- * that still loads the native module, which is exactly what fails when the
- * bindings are missing. Cached per path so resolution stays a single spawn.
+ * Why the last probe of a given bin failed (combined stderr+stdout). Lets the
+ * repair step decide whether the failure is a fixable native-binding problem
+ * and, from the bindings "Tried:" list, WHERE the unbuilt better-sqlite3 lives.
  */
-function isUsableQmd(bin) {
+const lastProbeFailure = new Map();
+/** At most one native-binding repair attempt per process (bounded, no retries). */
+let nativeBindingRepairAttempted = false;
+/** How long a single usability probe or repair sub-step may run. */
+const PROBE_TIMEOUT_MS = 10_000;
+const REPAIR_STEP_TIMEOUT_MS = 180_000;
+/** A stale repair lock older than this is reclaimed rather than trusted. */
+const REPAIR_LOCK_TTL_MS = 10 * 60_000;
+/** Reset per-process probe/repair memoisation. Test-only. */
+export function __resetQmdProbeStateForTests() {
+    usableQmdCache.clear();
+    lastProbeFailure.clear();
+    nativeBindingRepairAttempted = false;
+}
+/**
+ * Does this qmd binary actually OPEN ITS STORE? The 5.94.2 probe spawned
+ * `--version`, which prints and exits 0 even when better-sqlite3's native module
+ * is missing — the exact false positive that let this cluster ship (HQ-CLI-J):
+ * it passed on precisely the bindings-broken install it was added to reject.
+ * `collection list` instead opens the SQLite database, which is the operation
+ * that fails when `better_sqlite3.node` was never built.
+ *
+ * The probe is pointed at a throwaway INDEX_PATH / QMD_CONFIG_DIR / HOME so it
+ * NEVER creates or mutates the user's real qmd store, and is bounded by a hard
+ * timeout. Callers cache the boolean per path so resolution stays one spawn.
+ */
+function probeQmd(bin) {
+    let scratch;
+    try {
+        scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'hq-qmd-probe-'));
+        const env = {
+            ...process.env,
+            HOME: scratch,
+            QMD_CONFIG_DIR: path.join(scratch, 'config'),
+            INDEX_PATH: path.join(scratch, 'probe-index.db'),
+            XDG_CONFIG_HOME: path.join(scratch, 'xdg-config'),
+            XDG_CACHE_HOME: path.join(scratch, 'xdg-cache'),
+        };
+        const probe = spawnSync(bin, ['collection', 'list'], {
+            cwd: scratch,
+            env,
+            encoding: 'utf8',
+            timeout: PROBE_TIMEOUT_MS,
+        });
+        if (probe.error)
+            return { usable: false, detail: probe.error.message };
+        if (probe.status === 0)
+            return { usable: true, detail: '' };
+        return { usable: false, detail: `${probe.stderr ?? ''}\n${probe.stdout ?? ''}`.trim() };
+    }
+    catch (error) {
+        return { usable: false, detail: error instanceof Error ? error.message : String(error) };
+    }
+    finally {
+        if (scratch) {
+            try {
+                fs.rmSync(scratch, { recursive: true, force: true });
+            }
+            catch { /* best-effort cleanup */ }
+        }
+    }
+}
+export function isUsableQmd(bin) {
     const cached = usableQmdCache.get(bin);
     if (cached !== undefined)
         return cached;
-    let usable = false;
+    const result = probeQmd(bin);
+    usableQmdCache.set(bin, result.usable);
+    if (result.usable)
+        lastProbeFailure.delete(bin);
+    else
+        lastProbeFailure.set(bin, result.detail);
+    return result.usable;
+}
+/** Native-binding self-repair is on unless explicitly disabled. */
+function repairEnabled(env) {
+    const flag = env.HQ_QMD_NO_REPAIR;
+    return !(flag === '1' || flag === 'true');
+}
+/**
+ * Derive the better-sqlite3 PACKAGE directory qmd tried to load, from a bindings
+ * failure. `bindings` lists every path it tried, each ending in
+ * `.../better-sqlite3/<build-subdir>/better_sqlite3.node`; we take the package
+ * root (up to and including the `/better-sqlite3` segment). Returns undefined
+ * when the text carries no such path.
+ */
+export function betterSqlite3DirFromFailure(detail) {
+    const match = /([^\s'"]+[/\\]better-sqlite3)[/\\][^\s'"]*better_sqlite3\.node/.exec(detail);
+    return match ? match[1] : undefined;
+}
+/**
+ * A repair may write ONLY inside the same install tree as the resolved
+ * package-local qmd — never a PATH/system qmd, never a path outside that tree.
+ * Both the qmd bin and the better-sqlite3 dir must live under a shared
+ * `node_modules`/`.pnpm` ancestor; anything else is refused.
+ */
+export function repairConfinedTo(qmdBin, betterSqlite3Dir) {
+    const binDir = path.resolve(path.dirname(qmdBin));
+    const target = path.resolve(betterSqlite3Dir);
+    if (!/(?:^|[/\\])node_modules(?:[/\\]|$)/.test(target))
+        return false;
+    const binSegments = binDir.split(/[/\\]/);
+    const targetSegments = target.split(/[/\\]/);
+    let shared = 0;
+    while (shared < binSegments.length &&
+        shared < targetSegments.length &&
+        binSegments[shared] === targetSegments[shared]) {
+        shared++;
+    }
+    const commonAncestor = binSegments.slice(0, shared);
+    // The common ancestor must itself pass THROUGH the dependency tree: a shared
+    // `node_modules` or pnpm `.pnpm` store proves both paths belong to the same
+    // install, which a system path (e.g. /usr/bin) can never satisfy.
+    return commonAncestor.includes('node_modules') || commonAncestor.includes('.pnpm');
+}
+const defaultRepairSpawn = (cmd, args, opts) => {
+    const result = spawnSync(cmd, args, {
+        cwd: opts.cwd,
+        env: opts.env,
+        timeout: opts.timeout,
+        encoding: 'utf8',
+        stdio: 'ignore',
+    });
+    return { status: result.status, error: result.error };
+};
+/**
+ * Bounded, one-shot self-repair of a package-local qmd whose better-sqlite3
+ * native module was never built (pnpm 10 skips the build script for dependency
+ * installs). Runs better-sqlite3's own declared install step —
+ * `prebuild-install`, then `node-gyp rebuild --release` — inside the resolved
+ * package directory, under a hard timeout, at most once per process, then lets
+ * the caller re-probe. Returns whether `better_sqlite3.node` now exists.
+ *
+ * Every failure mode degrades to `false` (the caller then surfaces the
+ * classified native-binding remedy): it never throws, never retries, never
+ * waits unbounded, and never touches anything outside hq's own dependency tree.
+ */
+export function repairQmdNativeBindings(bin, options = {}) {
     try {
-        const probe = spawnSync(bin, ['--version'], { encoding: 'utf8', timeout: 10_000 });
-        usable = !probe.error && probe.status === 0;
+        const detail = options.failureDetail ?? lastProbeFailure.get(bin) ?? '';
+        if (!isQmdNativeBindingError(detail))
+            return false;
+        const betterSqlite3Dir = betterSqlite3DirFromFailure(detail);
+        if (!betterSqlite3Dir || !repairConfinedTo(bin, betterSqlite3Dir))
+            return false;
+        const artifact = path.join(betterSqlite3Dir, 'build', 'Release', 'better_sqlite3.node');
+        // Idempotent: a concurrent or earlier process may already have built it.
+        if (fs.existsSync(artifact))
+            return true;
+        if (nativeBindingRepairAttempted)
+            return false;
+        nativeBindingRepairAttempted = true;
+        const lockDir = path.join(betterSqlite3Dir, '.hq-qmd-repair.lock');
+        if (!acquireRepairLock(lockDir)) {
+            // Another process holds a fresh lock; do not pile a second build on top.
+            // Re-check the artifact once (it may have just finished) and defer.
+            return fs.existsSync(artifact);
+        }
+        try {
+            const env = { ...process.env, ...(options.env ?? {}) };
+            const spawn = options.spawn ?? defaultRepairSpawn;
+            runBetterSqlite3Install(betterSqlite3Dir, env, spawn);
+        }
+        finally {
+            try {
+                fs.rmSync(lockDir, { recursive: true, force: true });
+            }
+            catch { /* best-effort */ }
+        }
+        return fs.existsSync(artifact);
+    }
+    catch {
+        // Repair is strictly best-effort: any unexpected failure degrades to the
+        // classified native-binding remedy rather than crashing the resolver.
+        return false;
+    }
+}
+/** Acquire a bounded, TTL-guarded repair lock. No PID liveness, no wait loop. */
+function acquireRepairLock(lockDir) {
+    try {
+        fs.mkdirSync(lockDir);
+        return true;
     }
     catch {
-        usable = false;
+        // Reclaim a stale lock (a crashed prior repair); otherwise defer.
+        try {
+            const age = Date.now() - fs.statSync(lockDir).mtimeMs;
+            if (age > REPAIR_LOCK_TTL_MS) {
+                fs.rmSync(lockDir, { recursive: true, force: true });
+                fs.mkdirSync(lockDir);
+                return true;
+            }
+        }
+        catch { /* lock vanished or unreadable: fall through to defer */ }
+        return false;
+    }
+}
+/**
+ * Resolve a dependency executable better-sqlite3 would run at install time. pnpm
+ * links a package's dependency bins into the SIBLING `.bin` of its virtual-store
+ * `node_modules` (`.pnpm/better-sqlite3@x/node_modules/.bin/<tool>`), NOT inside
+ * `better-sqlite3/node_modules/.bin`; npm's hoisted layout and some pnpm configs
+ * use the nested form. Check both so the self-repair works on the pnpm-installed
+ * hosts it exists for. Both candidates sit inside the already-confined tree.
+ */
+function resolveRepairTool(betterSqlite3Dir, tool) {
+    const candidates = [
+        path.join(path.dirname(betterSqlite3Dir), '.bin', tool), // pnpm virtual-store sibling
+        path.join(betterSqlite3Dir, 'node_modules', '.bin', tool), // nested (npm / some pnpm)
+    ];
+    for (const candidate of candidates) {
+        if (fs.existsSync(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+/** Run better-sqlite3's declared install step: prebuild-install, then node-gyp. */
+function runBetterSqlite3Install(dir, env, spawn) {
+    const artifact = path.join(dir, 'build', 'Release', 'better_sqlite3.node');
+    const prebuild = resolveRepairTool(dir, 'prebuild-install');
+    if (prebuild) {
+        spawn(prebuild, [], { cwd: dir, env, timeout: REPAIR_STEP_TIMEOUT_MS });
+        if (fs.existsSync(artifact))
+            return;
+    }
+    const nodeGyp = resolveRepairTool(dir, 'node-gyp');
+    if (nodeGyp) {
+        spawn(nodeGyp, ['rebuild', '--release'], { cwd: dir, env, timeout: REPAIR_STEP_TIMEOUT_MS });
     }
-    usableQmdCache.set(bin, usable);
-    return usable;
 }
 /** Resolve qmd without relying on a globally installed copy. */
 export function resolveQmdBin(options = {}) {
@@ -136,6 +353,8 @@ export function resolveQmdBin(options = {}) {
     const probes = [];
     const override = env.HQ_QMD_BIN;
     if (override) {
+        // An explicit user choice is honoured verbatim: never probe or repair a
+        // binary the operator pointed us at.
         if (executable(override))
             return override;
         probes.push(`HQ_QMD_BIN (${override})`);
@@ -146,26 +365,42 @@ export function resolveQmdBin(options = {}) {
     const installed = (options.packageBin ?? packageLocalBin)();
     const onPath = (options.pathBin ?? pathBin)();
     const fallback = onPath && executable(onPath) ? onPath : undefined;
+    const isUsable = options.isUsable ?? isUsableQmd;
     if (installed && executable(installed)) {
-        // Executable is not the same as usable: a global install can ship a qmd
-        // whose native better-sqlite3 bindings were never compiled, so every
-        // invocation crashes. Preferring it blindly turned a dormant packaging
-        // problem into broken search on hosts that had a working qmd on PATH.
-        //
-        // The runnability probe costs a ~0.3s spawn, so only pay it when there is
-        // something to fall back TO. With no alternative the answer is the bundled
-        // binary either way, and a failure there now surfaces loudly rather than
-        // silently, so probing would buy nothing but latency on the hot path.
-        if (!fallback || (options.isUsable ?? isUsableQmd)(installed))
+        // Executable is not the same as usable: pnpm 10 skips better-sqlite3's build
+        // script for dependency installs, so the bundled qmd can be present yet
+        // unable to open its SQLite store. ALWAYS probe — the 5.94.2 short-circuit
+        // that skipped the probe when no PATH fallback existed is exactly how the
+        // outpost in HQ-CLI-J was handed the broken binary — and attempt one bounded
+        // native-binding repair before giving up on it.
+        if (isUsable(installed))
             return installed;
-        probes.push(`package-local @tobilu/qmd (${installed}, present but not runnable)`);
+        if (repairEnabled(env)) {
+            const repair = options.repair ?? repairQmdNativeBindings;
+            if (repair(installed)) {
+                usableQmdCache.delete(installed);
+                if (isUsable(installed))
+                    return installed;
+            }
+        }
+        probes.push(`package-local @tobilu/qmd (${installed}, present but native bindings unbuilt)`);
     }
     else {
         probes.push(`package-local @tobilu/qmd (${installed ?? 'not found'})`);
     }
+    // A working qmd on PATH is the right answer when the bundled one is broken —
+    // the fallback the 5.94.2 fix intended but its short-circuit never reached.
     if (fallback)
         return fallback;
     probes.push(`qmd on PATH (${onPath ?? 'not found'})`);
+    // Last resort: no usable qmd anywhere, but the bundled binary IS present. Hand
+    // it back rather than throwing an opaque "qmd missing" error — running it
+    // yields a QmdExitError whose native-binding signature the top-level handler
+    // turns into an actionable remedy (and skips Sentry). This is the "never
+    // return an unusable binary SILENTLY" contract: we probed, we tried repair,
+    // and the ensuing failure is classified, not swallowed.
+    if (installed && executable(installed))
+        return installed;
     throw new QmdBinaryMissingError(`Unable to resolve qmd. Probed ${probes.join('; ')}. Install @tobilu/qmd or set HQ_QMD_BIN to an executable qmd binary.`);
 }
 function defaultRunner(bin, args, options) {

package/dist/main.js

@@ -62,6 +62,7 @@ import { registerIndexCommand } from "./commands/index-cmd.js";
 import { sanitizeArgv } from "./utils/feedback-diagnostics.js";
 import { environmentalFsErrorMessage } from "./utils/environmental-error.js";
 import { networkTransportErrorMessage } from "./utils/network-transport-error.js";
+import { qmdNativeBindingErrorMessage } from "./utils/qmd-native-binding-error.js";
 import { isExpectedUserError } from "./utils/expected-cli-error.js";
 import { isEpipe } from "./utils/epipe.js";
 import { isInterceptedProcessExit } from "./utils/intercepted-process-exit.js";
@@ -374,7 +375,15 @@ export function handleTopLevelError(err, deps = defaultTopLevelErrorDependencies
         // skip Sentry capture so one full disk doesn't flood the tracker with
         // identical, unfixable crash reports (HQ-CLI-2). Genuine errors still go
         // to Sentry and still exit 1.
-        const envMsg = environmentalFsErrorMessage(err);
+        // A qmd failure caused by an unbuilt better-sqlite3 native module is the
+        // caller's install shape (pnpm 10 skips dependency build scripts), not an
+        // hq-cli defect. Before this branch it fell through to the capture below
+        // and filed 7 identical, unfixable "crashes" (HQ-CLI-J, Sentry
+        // 7656662146). Print the actionable remedy, exit 1, and skip Sentry.
+        // Ordered FIRST so the narrow native-binding signature wins over the
+        // broader environmental / transport / generic branches.
+        const qmdMsg = qmdNativeBindingErrorMessage(err);
+        const envMsg = qmdMsg ? null : environmentalFsErrorMessage(err);
         // A raw network transport failure (undici's `TypeError: fetch failed`
         // with a ConnectTimeoutError / ECONNREFUSED / ENOTFOUND cause) is the
         // caller's connectivity, not an hq-cli defect. Before this branch it fell
@@ -385,8 +394,11 @@ export function handleTopLevelError(err, deps = defaultTopLevelErrorDependencies
         // message that names the unreachable host, exit 1, and skip Sentry.
         // Ordered after the environmental check so a full disk keeps its exact
         // existing message.
-        const transportMsg = envMsg ? null : networkTransportErrorMessage(err);
-        if (envMsg) {
+        const transportMsg = qmdMsg || envMsg ? null : networkTransportErrorMessage(err);
+        if (qmdMsg) {
+            deps.stderr.write(`hq: ${qmdMsg}\n`);
+        }
+        else if (envMsg) {
             deps.stderr.write(`hq: ${envMsg}\n`);
         }
         else if (transportMsg) {

package/dist/utils/qmd-native-binding-error.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The actionable remedy shown to the user. Written to be accurate whether it is
+ * qmd's bundled better-sqlite3 or hq-cli's own copy that is unbuilt (the same
+ * pnpm install leaves both uncompiled), and to distinguish a global install
+ * (the shape recorded in HQ-CLI-J) from a local project.
+ */
+export declare const QMD_NATIVE_BINDING_REMEDY: string;
+/**
+ * True when `err` is a better-sqlite3 native-binding load failure (qmd's or
+ * hq-cli's own). A true result means the caller should print
+ * `QMD_NATIVE_BINDING_REMEDY`, exit non-zero, and SKIP Sentry capture.
+ */
+export declare function isQmdNativeBindingError(err: unknown): boolean;
+/**
+ * If `err` is a native-binding failure, return the actionable remedy message;
+ * otherwise return `null`. Mirrors environmentalFsErrorMessage /
+ * networkTransportErrorMessage so the top-level handler can branch on it the
+ * same way: a non-null result means print-and-skip-Sentry, null means
+ * "handle as usual (capture to Sentry)".
+ */
+export declare function qmdNativeBindingErrorMessage(err: unknown): string | null;
+//# sourceMappingURL=qmd-native-binding-error.d.ts.map

package/dist/utils/qmd-native-binding-error.js

@@ -0,0 +1,93 @@
+// src/utils/qmd-native-binding-error.ts
+//
+// Classify a qmd failure caused by MISSING/UNLOADABLE NATIVE BINDINGS —
+// better-sqlite3's compiled `better_sqlite3.node` was never built (or was built
+// for a different ABI) — rather than an hq-cli code defect. This is the caller's
+// install shape, not a bug HQ can fix in code, so the CLI surfaces an actionable
+// remedy and SKIPS Sentry capture. Sibling of environmental-error.ts (HQ-CLI-2,
+// full disk) and network-transport-error.ts (HQ-CLI-G, connectivity): a failure
+// that is NOT an hq-cli defect is printed with an actionable message and never
+// filed as a crash.
+//
+// HQ-CLI-J (Sentry 7656662146): pnpm 10 blocks dependency lifecycle scripts by
+// default, so `pnpm add [-g] @indigoai-us/hq-cli` lands with better-sqlite3
+// unbuilt. The bundled @tobilu/qmd then dies with `Could not locate the
+// bindings file` the moment it opens its SQLite store; `hq index status`
+// spawned it, runQmd wrapped the exit-1 in a QmdExitError, and that reached the
+// top-level handler's final else, which captured it — 7 identical, unfixable
+// "crashes" for a purely environmental packaging condition.
+//
+// Matching is deliberately narrow, on two axes, so it can neither be tripped by
+// user-controlled input nor silence a real bug:
+//   1. FIELD: for a QmdExitError the qmd process's OWN stderr/stdout is the
+//      diagnostic — NOT the synthesized `message`, which echoes the user's qmd
+//      arguments (a query for "better_sqlite3.node" must never classify). Only a
+//      raw Error with no captured streams falls back to its message (e.g. an
+//      hq-cli `hq db` bindings failure).
+//   2. SHAPE: the distinctive "Could not locate the bindings file" text, OR a
+//      `better_sqlite3.node` reference that co-occurs with a genuine
+//      module-load failure. Either alone would be too loose.
+/** The `bindings` module's exact "not found" text — sufficient on its own. */
+const BINDINGS_NOT_LOCATED = /could not locate the bindings file/i;
+/** A reference to the compiled better-sqlite3 module. */
+const NATIVE_MODULE = /better_sqlite3\.node/i;
+/**
+ * A genuine native-module LOAD failure, required alongside a bare
+ * better_sqlite3.node reference. Covers the missing-binding tries-list, an ABI
+ * mismatch, and OS-level dlopen faults — none of which a user's qmd arguments
+ * can synthesize.
+ */
+const NATIVE_LOAD_FAILURE = /could not locate the bindings file|\bTried:|was compiled against a different node|NODE_MODULE_VERSION|invalid elf header|cannot open shared object|dlopen|is not a valid win32 application/i;
+/**
+ * The actionable remedy shown to the user. Written to be accurate whether it is
+ * qmd's bundled better-sqlite3 or hq-cli's own copy that is unbuilt (the same
+ * pnpm install leaves both uncompiled), and to distinguish a global install
+ * (the shape recorded in HQ-CLI-J) from a local project.
+ */
+export const QMD_NATIVE_BINDING_REMEDY = "hq's local search index can't start: its better-sqlite3 native module was " +
+    "not built during install. pnpm 10 skips dependency build scripts by default, " +
+    "which leaves better-sqlite3 uncompiled. Approve the build and reinstall — for " +
+    "a global install run `pnpm approve-builds -g better-sqlite3` (drop -g for a " +
+    "local project) — or reinstall hq with npm, then run the command again.";
+/**
+ * The text to inspect. For a QmdExitError the captured stderr/stdout is the qmd
+ * process's real diagnostic; the synthesized `message` (which embeds the user's
+ * arguments) is used ONLY when no streams were captured, so user input can never
+ * trip the classifier.
+ */
+function diagnosticText(err) {
+    if (typeof err === "string")
+        return err;
+    if (err === null || typeof err !== "object")
+        return "";
+    const record = err;
+    const stderr = typeof record.stderr === "string" ? record.stderr : "";
+    const stdout = typeof record.stdout === "string" ? record.stdout : "";
+    if (stderr || stdout)
+        return `${stderr}\n${stdout}`;
+    return typeof record.message === "string" ? record.message : "";
+}
+/**
+ * True when `err` is a better-sqlite3 native-binding load failure (qmd's or
+ * hq-cli's own). A true result means the caller should print
+ * `QMD_NATIVE_BINDING_REMEDY`, exit non-zero, and SKIP Sentry capture.
+ */
+export function isQmdNativeBindingError(err) {
+    const text = diagnosticText(err);
+    if (!text)
+        return false;
+    if (BINDINGS_NOT_LOCATED.test(text))
+        return true;
+    return NATIVE_MODULE.test(text) && NATIVE_LOAD_FAILURE.test(text);
+}
+/**
+ * If `err` is a native-binding failure, return the actionable remedy message;
+ * otherwise return `null`. Mirrors environmentalFsErrorMessage /
+ * networkTransportErrorMessage so the top-level handler can branch on it the
+ * same way: a non-null result means print-and-skip-Sentry, null means
+ * "handle as usual (capture to Sentry)".
+ */
+export function qmdNativeBindingErrorMessage(err) {
+    return isQmdNativeBindingError(err) ? QMD_NATIVE_BINDING_REMEDY : null;
+}
+//# sourceMappingURL=qmd-native-binding-error.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.97.0",
+  "version": "5.97.1",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {