@indigoai-us/hq-cli 5.103.27 → 5.103.28

package/dist/lib/integrations/health.js

@@ -0,0 +1,255 @@
+/**
+ * Connection health classification, shared by every surface that has to explain
+ * why an integration is not usable.
+ *
+ * This lived inside the `hq doctor` integrations check until `list`/`show` had
+ * to answer the same question. It is deliberately presentation-free and makes
+ * no network calls: it classifies stored health signals only, so a caller can
+ * render a finding without deciding what the underlying codes mean. Keeping one
+ * copy is the point — `hq doctor` and `hq integrations show` disagreeing about
+ * whether a row needs a reconnect is exactly the confusion this family exists
+ * to remove.
+ *
+ * It never echoes untrusted provider text: upstream messages can carry tokens or
+ * secret-bearing URLs, so every user-visible string here is HQ-authored, and the
+ * only externally-sourced string that reaches a user is the server's own
+ * `fix_path`.
+ */
+import { bareProvider } from "./provider-slug.js";
+const RECONNECT_REASON_CODES = new Set([
+    "oauth_refresh_invalid_grant",
+    "oauth_refresh_unavailable",
+    "token_refresh_failed",
+    "credentials_rejected",
+]);
+const RETRYABLE_REASON_CODES = new Set([
+    "oauth_refresh_transient",
+    "oauth_refresh_write_conflict",
+]);
+const HQ_CONFIGURATION_REASON_CODE = "oauth_client_secret_unavailable";
+const UNSPECIFIED_REASON_CODE = "unspecified";
+/** Classify without echoing untrusted provider text, which may contain secrets. */
+export function classifyConnection(connection) {
+    if (connection.status === "revoked")
+        return [];
+    const provider = bareProvider(connection.provider);
+    const reason = recordedReason(connection);
+    const connectedWithRecordedFailure = connection.status === "connected" && reason !== "";
+    const knownReasonCode = knownReasonCodeFor(connection);
+    // `unspecified` is a recognised member of the server vocabulary, but it is an
+    // absence of diagnosis rather than one. Short-circuiting on it here would skip
+    // the status-aware branches below and report a degraded connection as an error
+    // needing a reconnect. It is deliberately allowed to fall through, where the
+    // server's role- and credential-aware remediation is applied like any other
+    // undiagnosed row.
+    if (knownReasonCode && knownReasonCode !== UNSPECIFIED_REASON_CODE) {
+        const finding = findingForKnownReasonCode(connection, provider, knownReasonCode);
+        // Retryable and HQ-configuration reason codes diagnose conditions that a
+        // caller-specific remediation cannot change. Reconnect-class codes defer
+        // to the server's credential/role-aware remediation classification, so an
+        // install in progress is never interrupted by a reconnect.
+        return [withServerRemediation(connection, RECONNECT_REASON_CODES.has(knownReasonCode)
+                ? findingForServerFixKind(finding, connection.fix_kind)
+                : finding)];
+    }
+    // A stale remediation value does not make a clean connected row unhealthy.
+    if (!connectedWithRecordedFailure && connection.status === "connected")
+        return [];
+    if (isProviderBlocked(reason) || connection.status === "degraded") {
+        return [withServerRemediation(connection, {
+                provider,
+                connectionId: connection.id,
+                kind: "provider-blocked",
+                message: connectedWithRecordedFailure
+                    ? "reports connected, but recorded provider health says access is blocked upstream"
+                    : "provider-side access is blocked or unavailable",
+            })];
+    }
+    const fallback = genericReconnectFinding(connection, provider);
+    const serverClassified = findingForServerFixKind(fallback, connection.fix_kind);
+    if (serverClassified.kind !== "reconnect") {
+        return [withServerRemediation(connection, serverClassified)];
+    }
+    if (isTokenRefreshFailure(reason) || isCredentialFailure(reason)) {
+        const problem = isTokenRefreshFailure(reason)
+            ? "token refresh failed"
+            : connectedWithRecordedFailure
+                ? "reports connected, but the provider rejected the stored credentials"
+                : "the provider rejected the stored credentials";
+        return [withServerRemediation(connection, {
+                provider,
+                connectionId: connection.id,
+                kind: "reconnect",
+                message: problem,
+            })];
+    }
+    // Past this point the reason vocabulary has diagnosed nothing: no recognised
+    // reason code and no reason text this module can read. Two things can still
+    // have diagnosed the row, and both are honoured before HQ admits it does not
+    // know:
+    //   - an explicit server `fix_kind: "reconnect"`; and
+    //   - a Factory installation parked at `needs_credentials`, which means the
+    //     install exists but has never been given a sign-in. `hq integrations
+    //     list` and `show` already say exactly that, so calling the same row
+    //     undiagnosed would print two contradictory diagnoses on one screen.
+    // Absent both, saying "reconnect" is a guess dressed as advice — see the
+    // FindingKind doc comment.
+    const serverSaidReconnect = connection.fix_kind === "reconnect";
+    const installNeedsSignIn = connection.installation?.status === "needs_credentials";
+    if (connection.status === "needs-reauth" || connection.status === "error") {
+        const diagnosed = serverSaidReconnect
+            ? fallback
+            : installNeedsSignIn
+                ? { ...fallback, message: "has an installation that has never been given a sign-in" }
+                : undefined;
+        return [withServerRemediation(connection, diagnosed ?? { ...fallback, kind: "undiagnosed", message: undiagnosedMessage(connection) })];
+    }
+    if (connection.status !== "connected") {
+        return [withServerRemediation(connection, {
+                provider,
+                connectionId: connection.id,
+                kind: serverSaidReconnect || installNeedsSignIn ? "reconnect" : "undiagnosed",
+                message: `reports an unrecognized non-healthy status (${connection.status}) and HQ was not told why`,
+            })];
+    }
+    return [];
+}
+/**
+ * HQ-authored wording for a fault the control plane did not explain. It states
+ * the observable fact and stops there, rather than naming a repair nothing has
+ * justified.
+ */
+function undiagnosedMessage(connection) {
+    if (connection.status !== "needs-reauth")
+        return "is not working, and HQ was not told why";
+    // A server-supplied `fix_path` means HQ WAS told what to do about the row,
+    // just not why it happened. `withServerRemediation` prints that instruction
+    // directly beneath this line, so claiming HQ does not know the fix would
+    // contradict the advice the reader is being handed.
+    return connection.fix_path
+        ? "reports that its saved sign-in is no longer valid, but HQ was not told why"
+        : "reports that its saved sign-in is no longer valid, but HQ was not told why or what will fix it";
+}
+function genericReconnectFinding(connection, provider) {
+    return {
+        provider,
+        connectionId: connection.id,
+        kind: "reconnect",
+        message: connection.status === "needs-reauth"
+            ? "needs re-authentication"
+            : "is in an error state",
+    };
+}
+/** Only values emitted by hq-pro affect the classification; future values fall back. */
+function findingForServerFixKind(fallback, fixKind) {
+    switch (fixKind) {
+        case "re-add":
+            return {
+                ...fallback,
+                kind: "re-add",
+                message: "requires its API key to be re-entered",
+            };
+        case "contact-admin":
+            return {
+                ...fallback,
+                kind: "contact-admin",
+                message: "must be repaired by a company owner or admin",
+            };
+        case "wait":
+            return {
+                ...fallback,
+                kind: "wait",
+                message: "is waiting for the Factory installation to complete",
+            };
+        case "reconnect":
+        default:
+            return fallback;
+    }
+}
+/**
+ * A fix path is server-authored, role- and credential-aware wording. It cannot
+ * make a connection unhealthy: the caller must first have classified a health
+ * signal, so a stale fix path on an otherwise clean connected row is ignored.
+ */
+function withServerRemediation(connection, finding) {
+    return connection.fix_path
+        ? { ...finding, remediation: connection.fix_path }
+        : finding;
+}
+/**
+ * These are a closed hq-pro contract. Exact matching deliberately comes before
+ * the legacy text heuristics, which remain below for old and unknown rows.
+ */
+function knownReasonCodeFor(connection) {
+    const values = [connection.errorReason, connection.needsReauthReason, connection.degradedReason];
+    if (values.includes(HQ_CONFIGURATION_REASON_CODE))
+        return HQ_CONFIGURATION_REASON_CODE;
+    return values.find((value) => (typeof value === "string" &&
+        (RECONNECT_REASON_CODES.has(value) ||
+            RETRYABLE_REASON_CODES.has(value) ||
+            value === UNSPECIFIED_REASON_CODE)));
+}
+function findingForKnownReasonCode(connection, provider, code) {
+    if (RECONNECT_REASON_CODES.has(code)) {
+        return {
+            provider,
+            connectionId: connection.id,
+            kind: "reconnect",
+            message: "stored credentials need re-authentication",
+        };
+    }
+    if (RETRYABLE_REASON_CODES.has(code)) {
+        return {
+            provider,
+            connectionId: connection.id,
+            kind: "retryable",
+            message: code === "oauth_refresh_write_conflict"
+                ? "token refresh lost a concurrent write race; the stored credential remains intact"
+                : "token refresh is temporarily unavailable; the stored credential remains intact",
+        };
+    }
+    return {
+        provider,
+        connectionId: connection.id,
+        kind: "hq-configuration",
+        message: "the HQ OAuth client secret is unavailable",
+    };
+}
+function recordedReason(connection) {
+    return [connection.errorReason, connection.needsReauthReason, connection.degradedReason]
+        .filter((value) => typeof value === "string")
+        .join(" ")
+        .toLowerCase();
+}
+function isTokenRefreshFailure(reason) {
+    return /token[\s_-]*refresh|refresh[\s_-]*token|invalid_grant/.test(reason);
+}
+function isCredentialFailure(reason) {
+    return /rejected[\s_-]*(the[\s_-]*)?stored[\s_-]*credentials|credentials[\s_-]*rejected|unauthori[sz]ed|invalid[\s_-]*(token|credentials)/.test(reason);
+}
+function isProviderBlocked(reason) {
+    return /\b403\b|access[\s_-]*denied|upstream[\s_-]*(block|blocked)|provider[\s_-]*(block|blocked|unavailable)|service[\s_-]*unavailable/.test(reason);
+}
+/**
+ * A status alone ("error") tells a user nothing they can act on. The control
+ * plane already sends the diagnosis and the fix path on every non-healthy row;
+ * this turns those into the two lines a surface should print next to the status.
+ *
+ * Revoked rows return `null` on purpose. They are tombstones rather than broken
+ * connections, and `revokedConnectionDetails` already produces the correct
+ * re-add wording for them — classifying them here would print two competing
+ * recovery paths for the same row.
+ */
+export function connectionHealthNotice(connection) {
+    if (connection.status === "revoked")
+        return null;
+    const finding = classifyConnection(connection)[0];
+    if (!finding)
+        return null;
+    return {
+        kind: finding.kind,
+        headline: `${finding.provider} ${finding.message}.`,
+        ...(finding.remediation ? { remediation: finding.remediation } : {}),
+    };
+}
+//# sourceMappingURL=health.js.map

package/dist/lib/integrations/provider-slug.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The `factory:` runtime prefix, stripped.
+ *
+ * A leaf on purpose. Health classification needs it, and so does every command
+ * surface, but `commands/integrations-core.ts` imports the health module — so
+ * homing this there would close a runtime import cycle. Nothing else belongs in
+ * this file.
+ */
+export declare function bareProvider(provider: string): string;
+//# sourceMappingURL=provider-slug.d.ts.map

package/dist/lib/integrations/provider-slug.js

@@ -0,0 +1,12 @@
+/**
+ * The `factory:` runtime prefix, stripped.
+ *
+ * A leaf on purpose. Health classification needs it, and so does every command
+ * surface, but `commands/integrations-core.ts` imports the health module — so
+ * homing this there would close a runtime import cycle. Nothing else belongs in
+ * this file.
+ */
+export function bareProvider(provider) {
+    return provider.replace(/^factory:/, "");
+}
+//# sourceMappingURL=provider-slug.js.map

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

@@ -130,6 +130,28 @@ export declare class QmdTerminatedError extends QmdExitError {
 export declare class QmdLlmDisabledError extends QmdExitError {
     name: string;
 }
+/**
+ * A qmd child died on MODULE RESOLUTION — Node could not load a JavaScript
+ * module qmd needs (`Cannot find module …` / `ERR_MODULE_NOT_FOUND`, alongside a
+ * `Require stack:` or a node_modules path). hq-cli bundles qmd and its whole
+ * dependency tree, so a missing module means the caller's INSTALL is incomplete
+ * — a partial or interrupted global `npm i -g` / `pnpm add -g` left some files
+ * unwritten — not a bug HQ can fix in code.
+ *
+ * HQ-CLI-Y (Sentry 7690356976): a qmd child died with `Cannot find module
+ * './stringifyComment.js'`, its Require stack rooted at
+ * /usr/lib/node_modules/@indigoai-us/hq-cli/node_modules/yaml/dist/stringify/… .
+ * The generic template rendered that as `qmd <full argv> exited with 1: <raw
+ * multi-line stderr>`; the argv split the Sentry group per query, and the
+ * child's `    at …` stderr lines were parsed as REAL frames of the hq-cli
+ * process, so grouping rode foreign frames and every distinct child failure
+ * minted a new permanent issue. finishRunQmd now types the condition (raised
+ * only from qmd's OWN captured streams, message naming the subcommand only); the
+ * boundary prints a reinstall remedy and skips capture for caller-driven reads.
+ */
+export declare class QmdModuleMissingError extends QmdExitError {
+    name: string;
+}
 export type ResolveQmdBinOptions = {
     env?: Record<string, string | undefined>;
     isExecutable?: (candidate: string) => boolean;

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

@@ -4,6 +4,7 @@ import { createRequire } from 'node:module';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { isQmdModuleMissingError } from '../../utils/qmd-module-missing-error.js';
 import { isQmdNativeBindingError } from '../../utils/qmd-native-binding-error.js';
 import { redactErrorText } from '../../utils/redact-error-text.js';
 import { planCommandSpawn } from '../../utils/windows-spawn.js';
@@ -108,6 +109,28 @@ export class QmdTerminatedError extends QmdExitError {
 export class QmdLlmDisabledError extends QmdExitError {
     name = 'QmdLlmDisabledError';
 }
+/**
+ * A qmd child died on MODULE RESOLUTION — Node could not load a JavaScript
+ * module qmd needs (`Cannot find module …` / `ERR_MODULE_NOT_FOUND`, alongside a
+ * `Require stack:` or a node_modules path). hq-cli bundles qmd and its whole
+ * dependency tree, so a missing module means the caller's INSTALL is incomplete
+ * — a partial or interrupted global `npm i -g` / `pnpm add -g` left some files
+ * unwritten — not a bug HQ can fix in code.
+ *
+ * HQ-CLI-Y (Sentry 7690356976): a qmd child died with `Cannot find module
+ * './stringifyComment.js'`, its Require stack rooted at
+ * /usr/lib/node_modules/@indigoai-us/hq-cli/node_modules/yaml/dist/stringify/… .
+ * The generic template rendered that as `qmd <full argv> exited with 1: <raw
+ * multi-line stderr>`; the argv split the Sentry group per query, and the
+ * child's `    at …` stderr lines were parsed as REAL frames of the hq-cli
+ * process, so grouping rode foreign frames and every distinct child failure
+ * minted a new permanent issue. finishRunQmd now types the condition (raised
+ * only from qmd's OWN captured streams, message naming the subcommand only); the
+ * boundary prints a reinstall remedy and skips capture for caller-driven reads.
+ */
+export class QmdModuleMissingError extends QmdExitError {
+    name = 'QmdModuleMissingError';
+}
 function isExecutable(candidate) {
     try {
         fs.accessSync(candidate, fs.constants.X_OK);
@@ -698,27 +721,31 @@ export function resolveQmdInvocation(options = {}) {
 const ANSI_ESCAPE = new RegExp(`${String.fromCharCode(0x1b)}\\[[0-9;?]*[ -/]*[@-~]`, 'g');
 /** Lines qmd prints as ADVISORIES (a tip, a warning) — never a failure reason. */
 const QMD_ADVISORY_LINE = /^(?:Tip:|Warning:|QMD Warning:)/i;
-/**
- * Render qmd's captured output as a human diagnostic for a SIGNALLED run: strip
- * ANSI/control noise, then drop purely-advisory lines as long as a substantive
- * line survives. If ONLY advisory lines were printed — the reported shape, where
- * an embeddings tip and a GPU warning were all qmd emitted before it was killed —
- * say so explicitly rather than presenting an advisory as the cause of death.
- * Any retained qmd text is redacted + length-bounded, so a hostile line can
- * neither forge a second `hq:` line, emit terminal escapes, nor leak a token.
- */
-function describeQmdTermination(stdout, stderr) {
-    const lines = `${stderr}\n${stdout}`
+function summarizeQmdOutput(combined) {
+    const lines = combined
         .split(/\r?\n/)
         .map((line) => line.replace(ANSI_ESCAPE, '').trim())
         .filter((line) => line.length > 0);
     if (lines.length === 0)
-        return '';
+        return { kind: 'empty' };
     const substantive = lines.filter((line) => !QMD_ADVISORY_LINE.test(line));
     if (substantive.length === 0)
+        return { kind: 'advisory-only' };
+    const reason = redactErrorText(substantive.join(' '));
+    return reason ? { kind: 'reason', reason } : { kind: 'empty' };
+}
+/**
+ * Render qmd's captured output as a human diagnostic for a SIGNALLED run.
+ * Byte-for-byte identical to its prior behaviour, now expressed through the
+ * shared {@link summarizeQmdOutput} core so the exited path renders the same way.
+ */
+function describeQmdTermination(stdout, stderr) {
+    const summary = summarizeQmdOutput(`${stderr}\n${stdout}`);
+    if (summary.kind === 'advisory-only')
         return 'qmd printed only advisory output before it was terminated';
-    const detail = redactErrorText(substantive.join(' '));
-    return detail ? `qmd reported: ${detail}` : '';
+    if (summary.kind === 'reason')
+        return `qmd reported: ${summary.reason}`;
+    return '';
 }
 /** Normalise a spawn result and raise the typed qmd failures. */
 function finishRunQmd(result, bin, args) {
@@ -750,8 +777,24 @@ function finishRunQmd(result, bin, args) {
             : `qmd ${subcommand} was terminated by signal ${namedSignal} before it finished`;
         throw new QmdTerminatedError(signalMessage, args, normalized.status, normalized.stdout, normalized.stderr, signal);
     }
-    const detail = normalized.stderr || normalized.stdout || 'qmd returned no diagnostic output';
-    const message = `qmd ${args.join(' ')} exited with ${normalized.status ?? 'an unknown status'}: ${detail}`;
+    // Name the SUBCOMMAND only (args[0]) — never args.join(' '), which used to
+    // interpolate the caller's whole argv (their search query, -c collection name,
+    // any absolute paths) straight into the Sentry issue title and split the group
+    // per invocation. `classifyText` keeps qmd's RAW captured streams for the
+    // wording-based branches below (byte-identical to the prior `detail`), while
+    // `reason` is the flattened, redacted, single-line rendering that goes into the
+    // human-facing message. Collapsing `reason` is what stops a child process's
+    // `    at …` stderr frames from polluting this error's stack and minting a
+    // brand-new Sentry issue per child failure (HQ-CLI-Y / Sentry 7690356976).
+    const subcommand = typeof args[0] === 'string' && args[0].length > 0 ? redactErrorText(args[0]) || 'qmd' : 'qmd';
+    const classifyText = normalized.stderr || normalized.stdout || 'qmd returned no diagnostic output';
+    const summary = summarizeQmdOutput(normalized.stderr || normalized.stdout || '');
+    const reason = summary.kind === 'reason'
+        ? summary.reason
+        : summary.kind === 'advisory-only'
+            ? 'qmd printed only advisory output'
+            : 'qmd returned no diagnostic output';
+    const message = `qmd ${subcommand} exited with ${normalized.status ?? 'an unknown status'}: ${reason}`;
     // qmd refused because its local LLM is disabled: whenever CI is set in the
     // environment, qmd hard-disables every LLM operation, so `vsearch`/`query`
     // (query expansion) and `embed` (vector build) throw `Error: LLM operations
@@ -764,10 +807,23 @@ function finishRunQmd(result, bin, args) {
     // the collection wordings: the refusal text matches none of them, so order is
     // safe, and the narrower typed signature stays first.
     if (/LLM operations are disabled/i.test(`${normalized.stderr}\n${normalized.stdout}`)) {
-        const subcommand = typeof args[0] === 'string' && args[0].length > 0 ? redactErrorText(args[0]) || 'qmd' : 'qmd';
         throw new QmdLlmDisabledError(`qmd ${subcommand} could not run: its local LLM is disabled because CI is set in the environment`, args, normalized.status, normalized.stdout, normalized.stderr);
     }
-    if (/(?:collection|qmd:\/\/).*(?:not found|does not exist|unknown)|(?:not found|does not exist).*collection/i.test(detail)) {
+    // A qmd child that died on MODULE RESOLUTION — `Cannot find module …` with a
+    // Require stack / node_modules path — means the caller's hq install tree is
+    // incomplete (a partial or interrupted global install), not an hq-cli defect.
+    // Type it so the boundary can print a reinstall remedy and skip capture for a
+    // caller-driven read, and so its grouping is bounded. Read qmd's OWN captured
+    // streams only, never the synthesized message, so a query for "Cannot find
+    // module" cannot trip it. Placed AFTER the LLM-disabled check and BEFORE the
+    // collection checks: the wordings are disjoint (the collection regex needs
+    // `collection`/`qmd://` adjacent to a not-found token, which this stderr
+    // lacks), so no existing branch changes behaviour (HQ-CLI-Y / Sentry
+    // 7690356976).
+    if (isQmdModuleMissingError({ stderr: normalized.stderr, stdout: normalized.stdout })) {
+        throw new QmdModuleMissingError(`qmd ${subcommand} could not run: a module it needs was not found (the hq install tree looks incomplete)`, args, normalized.status, normalized.stdout, normalized.stderr);
+    }
+    if (/(?:collection|qmd:\/\/).*(?:not found|does not exist|unknown)|(?:not found|does not exist).*collection/i.test(classifyText)) {
         throw new QmdCollectionMissingError(message, args, normalized.status, normalized.stdout, normalized.stderr);
     }
     // qmd's same-name duplicate: `collection add` targeted a name YAML already
@@ -778,7 +834,7 @@ function finishRunQmd(result, bin, args) {
     // stays a plain QmdExitError. Colour is off under capture (qmd gates on
     // isTTY) and any surrounding ANSI sits outside this substring, so the plain
     // match is robust either way.
-    const alreadyExists = /Collection '([^']+)' already exists\./.exec(detail);
+    const alreadyExists = /Collection '([^']+)' already exists\./.exec(classifyText);
     if (alreadyExists) {
         throw new QmdCollectionExistsError(message, args, normalized.status, normalized.stdout, normalized.stderr, alreadyExists[1]);
     }

package/dist/main.js

@@ -69,6 +69,7 @@ import { qmdNativeBindingErrorMessage } from "./utils/qmd-native-binding-error.j
 import { qmdMissingCollectionMessage } from "./utils/qmd-collection-missing-error.js";
 import { qmdTerminatedMessage } from "./utils/qmd-terminated-error.js";
 import { qmdLlmDisabledMessage } from "./utils/qmd-llm-disabled-error.js";
+import { qmdModuleMissingMessage } from "./utils/qmd-module-missing-error.js";
 import { isExpectedUserError } from "./utils/expected-cli-error.js";
 import { isEpipe } from "./utils/epipe.js";
 import { isInterceptedProcessExit } from "./utils/intercepted-process-exit.js";
@@ -501,7 +502,25 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         // that legitimately need the LLM (vsearch/query/embed); an LLM-disabled
         // failure from hq's OWN reconciliation stays a captured internal error.
         const llmDisabledMsg = qmdMsg || collectionMsg || terminatedMsg ? null : qmdLlmDisabledMessage(err);
-        const envMsg = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg
+        // A qmd child that died on MODULE RESOLUTION (`Cannot find module …` with a
+        // Require stack / node_modules path) means the caller's hq install tree is
+        // incomplete — a partial or interrupted global install — not an hq-cli
+        // defect. Before this branch the broken-install condition reached the final
+        // else and, because the generic message embedded the caller's whole argv
+        // AND the child's raw stderr frames, filed a high-priority crash and minted
+        // a NEW permanent issue per child failure (HQ-CLI-Y, Sentry 7690356976).
+        // finishRunQmd now types it QmdModuleMissingError; print the input-free
+        // reinstall remedy and skip capture. Evaluated AFTER the native-binding /
+        // collection-missing / terminated / llm-disabled checks (native-binding in
+        // particular MUST keep winning when a bindings failure also looks
+        // module-missing, since it is checked first) and BEFORE the environmental /
+        // transport / generic branches. Scoped to caller-supplied reads
+        // (search/vsearch/query/get); a module-missing raised by hq's OWN
+        // reconciliation names a packaging fault hq could own, so it stays captured.
+        const moduleMissingMsg = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg
+            ? null
+            : qmdModuleMissingMessage(err);
+        const envMsg = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg || moduleMissingMsg
             ? null
             : environmentalFsErrorMessage(err);
         // A raw network transport failure (undici's `TypeError: fetch failed`
@@ -514,7 +533,7 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         // 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 = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg || envMsg
+        const transportMsg = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg || moduleMissingMsg || envMsg
             ? null
             : networkTransportErrorMessage(err);
         if (qmdMsg) {
@@ -529,6 +548,9 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         else if (llmDisabledMsg) {
             deps.stderr.write(`hq: ${llmDisabledMsg}\n`);
         }
+        else if (moduleMissingMsg) {
+            deps.stderr.write(`hq: ${moduleMissingMsg}\n`);
+        }
         else if (envMsg) {
             deps.stderr.write(`hq: ${envMsg}\n`);
         }

package/dist/utils/qmd-module-missing-error.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The actionable remedy shown to the operator. Input-free — nothing is
+ * interpolated from the error, the argv, or qmd's output — so there is no
+ * injection surface, matching the bounded-fingerprint discipline of its
+ * siblings. Names the concrete reinstall for both a global npm and a global
+ * pnpm install.
+ *
+ * Covers BOTH qmd origins deliberately, because they cannot be told apart at
+ * runtime: HQ_QMD_BIN is honoured verbatim, and it is also the seam a dev build
+ * (and this repo's e2e harness) uses to inject the bundled qmd, so a truthy
+ * HQ_QMD_BIN is NOT a reliable "external qmd" signal. A missing module is not an
+ * hq-cli code defect on either path, so the remedy — not the classification —
+ * carries the origin nuance: it names the bundled reinstall first, then the
+ * HQ_QMD_BIN case so an operator running their own qmd is pointed at that
+ * install rather than only at hq.
+ */
+export declare const QMD_MODULE_MISSING_REMEDY: string;
+/**
+ * True when `err` carries, in qmd's OWN captured streams, a module-resolution
+ * failure corroborated by a Node module-loader artifact — i.e. qmd's dependency
+ * tree is incomplete on this machine. finishRunQmd calls this on the raw streams
+ * to type the condition {@link import('../lib/search-index/index.js').QmdModuleMissingError};
+ * a true result there means the caller should reinstall.
+ */
+export declare function isQmdModuleMissingError(err: unknown): boolean;
+/**
+ * If `err` is a caller-driven qmd module-missing failure (a QmdModuleMissingError
+ * from `hq search` or its `vsearch`/`query`/`get` siblings), return the
+ * actionable, input-free reinstall remedy; otherwise return `null`. Mirrors
+ * qmdNativeBindingErrorMessage / qmdMissingCollectionMessage so the top-level
+ * handler branches the same way: a non-null result means print-and-skip-Sentry,
+ * null means "handle as usual (capture to Sentry)".
+ *
+ * Gated on the TYPED CLASS plus a caller-reads invocation allow-list: a
+ * module-missing raised by hq's OWN reconciliation (`collection list`, `context
+ * add`, …) points at a packaging fault hq itself could be responsible for, so it
+ * stays a captured internal error rather than being silenced as the user's
+ * install.
+ */
+export declare function qmdModuleMissingMessage(err: unknown): string | null;
+//# sourceMappingURL=qmd-module-missing-error.d.ts.map