@indigoai-us/hq-cli 5.103.18 → 5.103.20

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 ## [Unreleased]
 
+## [5.103.20] — 2026-08-24
+
+### Changed
+
+- The bundled sync engine now requires `@indigoai-us/hq-cloud` 6.15.37, the
+  current production release.
+
+## [5.103.19] — 2026-08-22
+
+### Fixed
+
+- `hq search` (and its `--mode semantic`/`hybrid` siblings) no longer files a
+  Sentry crash when the qmd child is stopped by the host — for example when the
+  out-of-memory killer stops a CPU-only embedding run on a small box, or an
+  operator interrupts the search. The spawn seam now keeps the terminating
+  signal instead of discarding it, so such a run is reported to the operator as
+  an actionable, signal-named line (tailored to whether a search or an index
+  build was killed) and is no longer captured as an hq-cli defect. Because the
+  synthesized message no longer interpolates the caller's query, it can no longer
+  mint a brand-new permanent Sentry issue per distinct query. Crash-class signals
+  (SIGSEGV/SIGABRT/SIGBUS), which usually indicate a genuine native fault, and
+  every non-zero qmd exit are unchanged and still reported. (Sentry 7677702704)
+
 ## [5.103.18] — 2026-08-22
 
 ### Fixed

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

@@ -3,6 +3,13 @@ export type QmdProcessResult = {
     stdout: string;
     stderr: string;
     error?: Error;
+    /**
+     * The signal that terminated the child, when qmd was KILLED rather than
+     * exited (spawnSync then reports `status: null`, `signal: <name>`). OPTIONAL
+     * so every existing runner and test double keeps compiling unchanged; read by
+     * finishRunQmd to classify a signalled qmd (HQ-CLI 7677702704).
+     */
+    signal?: NodeJS.Signals | string | null;
 };
 export type QmdProcessRunner = (bin: string, args: string[], options: {
     cwd?: string;
@@ -43,6 +50,7 @@ export type QmdSpawn = (cmd: string, args: string[], options: {
     stdout?: string;
     stderr?: string;
     error?: Error;
+    signal?: NodeJS.Signals | string | null;
 };
 /**
  * Prefix `execDir` onto the child env PATH so a node-entry launcher can re-spawn
@@ -79,6 +87,27 @@ export declare class QmdCollectionExistsError extends QmdExitError {
     name: string;
     constructor(message: string, args: string[], status: number | null, stdout: string, stderr: string, collectionName: string);
 }
+/**
+ * qmd did NOT exit — it was KILLED BY A SIGNAL before it finished (spawnSync
+ * reports `status: null` with a non-null `signal`). hq-cli passes qmd no timeout
+ * and never signals the child itself, so the signal always originates OUTSIDE
+ * hq-cli: most often the host OOM killer during CPU-only embedding on a small
+ * box, or an operator interrupt (Ctrl-C, a terminated shell). `signal` carries
+ * the signal name so the top-level handler can name it and branch its remedy.
+ *
+ * Before this class a signalled qmd rendered as `exited with an unknown status:
+ * <qmd's raw stderr>` — and because that stderr was often purely advisory (an
+ * embeddings tip, a GPU warning) and the message interpolated the caller's whole
+ * argv, every distinct search query minted a brand-new permanent Sentry issue
+ * (HQ-CLI 7677702704 — the same unbounded-fingerprint failure fixed for
+ * HQ-CLI-S). This typed subclass lets the boundary classify the condition as the
+ * caller's environment and stop fingerprinting on the query text.
+ */
+export declare class QmdTerminatedError extends QmdExitError {
+    readonly signal: string;
+    name: string;
+    constructor(message: string, args: string[], status: number | null, stdout: string, stderr: string, signal: string);
+}
 export type ResolveQmdBinOptions = {
     env?: Record<string, string | undefined>;
     isExecutable?: (candidate: string) => boolean;

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

@@ -5,6 +5,7 @@ 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';
+import { redactErrorText } from '../../utils/redact-error-text.js';
 import { planCommandSpawn } from '../../utils/windows-spawn.js';
 const require = createRequire(import.meta.url);
 /** The `path` implementation for a (possibly injected) platform. */
@@ -61,6 +62,30 @@ export class QmdCollectionExistsError extends QmdExitError {
         this.collectionName = collectionName;
     }
 }
+/**
+ * qmd did NOT exit — it was KILLED BY A SIGNAL before it finished (spawnSync
+ * reports `status: null` with a non-null `signal`). hq-cli passes qmd no timeout
+ * and never signals the child itself, so the signal always originates OUTSIDE
+ * hq-cli: most often the host OOM killer during CPU-only embedding on a small
+ * box, or an operator interrupt (Ctrl-C, a terminated shell). `signal` carries
+ * the signal name so the top-level handler can name it and branch its remedy.
+ *
+ * Before this class a signalled qmd rendered as `exited with an unknown status:
+ * <qmd's raw stderr>` — and because that stderr was often purely advisory (an
+ * embeddings tip, a GPU warning) and the message interpolated the caller's whole
+ * argv, every distinct search query minted a brand-new permanent Sentry issue
+ * (HQ-CLI 7677702704 — the same unbounded-fingerprint failure fixed for
+ * HQ-CLI-S). This typed subclass lets the boundary classify the condition as the
+ * caller's environment and stop fingerprinting on the query text.
+ */
+export class QmdTerminatedError extends QmdExitError {
+    signal;
+    name = 'QmdTerminatedError';
+    constructor(message, args, status, stdout, stderr, signal) {
+        super(message, args, status, stdout, stderr);
+        this.signal = signal;
+    }
+}
 function isExecutable(candidate) {
     try {
         fs.accessSync(candidate, fs.constants.X_OK);
@@ -231,6 +256,9 @@ const defaultSpawn = (cmd, args, options) => {
         stdout: result.stdout ?? undefined,
         stderr: result.stderr ?? undefined,
         error: result.error,
+        // Carry the signal that killed the child (status null) so finishRunQmd can
+        // classify a signalled qmd instead of erasing the cause (HQ-CLI 7677702704).
+        signal: result.signal,
     };
 };
 /**
@@ -644,6 +672,32 @@ export function resolveQmdInvocation(options = {}) {
         return bundled;
     throw new QmdBinaryMissingError(`Unable to resolve qmd. Probed ${probes.join('; ')}. Install @tobilu/qmd or set HQ_QMD_BIN to an executable qmd binary.`);
 }
+/** ANSI CSI escape sequences qmd may leave on its streams (SGR colour, a trailing show-cursor control). */
+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}`
+        .split(/\r?\n/)
+        .map((line) => line.replace(ANSI_ESCAPE, '').trim())
+        .filter((line) => line.length > 0);
+    if (lines.length === 0)
+        return '';
+    const substantive = lines.filter((line) => !QMD_ADVISORY_LINE.test(line));
+    if (substantive.length === 0)
+        return 'qmd printed only advisory output before it was terminated';
+    const detail = redactErrorText(substantive.join(' '));
+    return detail ? `qmd reported: ${detail}` : '';
+}
 /** Normalise a spawn result and raise the typed qmd failures. */
 function finishRunQmd(result, bin, args) {
     const normalized = {
@@ -651,12 +705,29 @@ function finishRunQmd(result, bin, args) {
         stdout: result.stdout ?? '',
         stderr: result.stderr ?? '',
         error: result.error,
+        signal: result.signal,
     };
     if (normalized.error) {
         throw new QmdBinaryMissingError(`Unable to execute qmd at ${bin}: ${normalized.error.message}`);
     }
     if (normalized.status === 0)
         return normalized;
+    // qmd did not EXIT — it was KILLED BY A SIGNAL before it finished (spawnSync:
+    // status null, signal set). hq-cli passes qmd no timeout and never signals the
+    // child, so the signal came from OUTSIDE hq-cli — most often the host OOM
+    // killer during CPU-only embedding on a small box, or an operator interrupt.
+    // Name the signal and the SUBCOMMAND only, never args.join(' '), so the Sentry
+    // group can no longer fingerprint per search query (HQ-CLI 7677702704).
+    if (normalized.status === null && normalized.signal) {
+        const signal = String(normalized.signal);
+        const subcommand = typeof args[0] === 'string' && args[0].length > 0 ? redactErrorText(args[0]) || 'qmd' : 'qmd';
+        const namedSignal = redactErrorText(signal) || 'an unknown signal';
+        const context = describeQmdTermination(normalized.stdout, normalized.stderr);
+        const signalMessage = context
+            ? `qmd ${subcommand} was terminated by signal ${namedSignal} before it finished (${context})`
+            : `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}`;
     if (/(?:collection|qmd:\/\/).*(?:not found|does not exist|unknown)|(?:not found|does not exist).*collection/i.test(detail)) {

package/dist/main.js

@@ -67,6 +67,7 @@ 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 { qmdMissingCollectionMessage } from "./utils/qmd-collection-missing-error.js";
+import { qmdTerminatedMessage } from "./utils/qmd-terminated-error.js";
 import { isExpectedUserError } from "./utils/expected-cli-error.js";
 import { isEpipe } from "./utils/epipe.js";
 import { isInterceptedProcessExit } from "./utils/intercepted-process-exit.js";
@@ -457,7 +458,20 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         // raised by hq's OWN reconciliation (`collection add`/`context add`) names
         // a collection hq built itself, so it stays a captured internal error.
         const collectionMsg = qmdMsg ? null : qmdMissingCollectionMessage(err);
-        const envMsg = qmdMsg || collectionMsg ? null : environmentalFsErrorMessage(err);
+        // A qmd child KILLED BY A SIGNAL (spawnSync status null + signal) is the
+        // caller's HOST, not an hq-cli defect: hq-cli passes qmd no timeout and
+        // never signals the child, so the signal came from outside — most often the
+        // OOM killer during CPU-only embedding on a small box, or an operator
+        // interrupt. Before this branch the discarded signal rendered as `exited
+        // with an unknown status: <qmd's raw advisory stderr>`, and because that
+        // message embedded the caller's whole argv, each distinct query minted a
+        // brand-new permanent issue (HQ-CLI 7677702704, the HQ-CLI-S failure mode).
+        // finishRunQmd now types it QmdTerminatedError; print the signal-named
+        // remedy and skip capture. Evaluated AFTER the native-binding and
+        // collection-missing checks (both narrower typed signatures) and BEFORE the
+        // environmental / transport / generic branches.
+        const terminatedMsg = qmdMsg || collectionMsg ? null : qmdTerminatedMessage(err);
+        const envMsg = qmdMsg || collectionMsg || terminatedMsg ? 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
@@ -468,13 +482,16 @@ 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 || envMsg ? null : networkTransportErrorMessage(err);
+        const transportMsg = qmdMsg || collectionMsg || terminatedMsg || envMsg ? null : networkTransportErrorMessage(err);
         if (qmdMsg) {
             deps.stderr.write(`hq: ${qmdMsg}\n`);
         }
         else if (collectionMsg) {
             deps.stderr.write(`hq: ${collectionMsg}\n`);
         }
+        else if (terminatedMsg) {
+            deps.stderr.write(`hq: ${terminatedMsg}\n`);
+        }
         else if (envMsg) {
             deps.stderr.write(`hq: ${envMsg}\n`);
         }

package/dist/utils/qmd-terminated-error.d.ts

@@ -0,0 +1,11 @@
+/**
+ * If `err` is a qmd child terminated by a genuinely EXTERNAL signal (the host
+ * OOM killer or an operator interrupt), return an actionable, signal-named
+ * remedy tailored to what qmd was doing; otherwise return `null`. A null result
+ * covers non-QmdTerminatedError values AND crash-class/unrecognised signals,
+ * which must stay on the captured-error path. Mirrors qmdNativeBindingErrorMessage
+ * / qmdMissingCollectionMessage so the top-level handler branches the same way:
+ * non-null means print-and-skip-Sentry, null means "handle as usual (capture)".
+ */
+export declare function qmdTerminatedMessage(err: unknown): string | null;
+//# sourceMappingURL=qmd-terminated-error.d.ts.map

package/dist/utils/qmd-terminated-error.js

@@ -0,0 +1,95 @@
+// src/utils/qmd-terminated-error.ts
+//
+// Classify a qmd child that was KILLED BY A SIGNAL — not one that exited
+// non-zero — and decide whether it is the caller's HOST ENVIRONMENT (print an
+// actionable remedy, SKIP Sentry) or a genuine qmd/native CRASH (leave it on the
+// captured-error path). Sibling of qmd-native-binding-error.ts (HQ-CLI-J),
+// qmd-collection-missing-error.ts (HQ-CLI-S), environmental-error.ts (HQ-CLI-2)
+// and network-transport-error.ts (HQ-CLI-G).
+//
+// HQ-CLI 7677702704: `hq search --mode semantic ...` spawned qmd, which was
+// KILLED BY A SIGNAL before it finished. The reported profile — a 2 GB / 2-vCPU
+// box, qmd warning it had no GPU and was building embeddings on CPU, ~12 minutes
+// of runtime before the throw — is the shape of an out-of-memory kill (the Linux
+// OOM killer sends SIGKILL). The spawn seam discarded spawnSync's `signal`, so
+// the failure rendered as `exited with an unknown status: <qmd's raw advisory
+// stderr>`; because that synthesized message interpolated the caller's whole
+// argv, every distinct query minted a brand-new permanent issue — the same
+// unbounded-fingerprint failure fixed for HQ-CLI-S. finishRunQmd now types the
+// condition QmdTerminatedError; this classifier closes the boundary.
+//
+// Which signals are the caller's environment (and skip Sentry):
+//   - SIGKILL: the process cannot catch it, so it is always sent from OUTSIDE —
+//     almost always the host OOM killer here.
+//   - SIGINT / SIGTERM / SIGHUP / SIGQUIT: an operator or a terminated shell
+//     interrupting the run.
+// CRASH-class signals — SIGSEGV / SIGABRT / SIGBUS — are deliberately NOT
+// carved out: they usually mean qmd's OWN native code faulted (a genuine
+// bundled-qmd defect), so a swallow would hide a real regression AND mislead the
+// user with a memory remedy. For those (and any unrecognised or missing signal)
+// this returns null so the boundary reports them to Sentry. That stays safe:
+// finishRunQmd's message names the signal and subcommand ONLY (never the query),
+// so a captured crash still groups per signal, not per query.
+//
+// The gate is the TYPED CLASS (`name === 'QmdTerminatedError'`) plus a signal
+// allow-list — never qmd's advisory wording ('Tip:', 'needs embeddings'), which
+// this fix's reproduction shows also rides a SUCCESSFUL exit-0 run. hq-cli passes
+// qmd no timeout and never signals the child, so a carved-out signal always
+// originates outside hq-cli. The only value rendered into the remedy is the
+// signal name, drawn from the allow-list of safe constants and passed through
+// redactErrorText defensively; the caller's query and the raw subcommand are
+// never echoed.
+import { redactErrorText } from "./redact-error-text.js";
+/** SIGKILL: uncatchable, so always sent from outside — here, the host OOM killer. */
+const HOST_KILL = "SIGKILL";
+/** Signals that mean an operator or shell INTERRUPTED qmd before it finished. */
+const INTERRUPTS = new Set(["SIGINT", "SIGTERM", "SIGHUP", "SIGQUIT"]);
+/** qmd subcommands that are caller-supplied SEARCH reads (mirrors search.ts). */
+const SEARCH_READS = new Set(["search", "vsearch", "query", "get"]);
+/**
+ * If `err` is a qmd child terminated by a genuinely EXTERNAL signal (the host
+ * OOM killer or an operator interrupt), return an actionable, signal-named
+ * remedy tailored to what qmd was doing; otherwise return `null`. A null result
+ * covers non-QmdTerminatedError values AND crash-class/unrecognised signals,
+ * which must stay on the captured-error path. Mirrors qmdNativeBindingErrorMessage
+ * / qmdMissingCollectionMessage so the top-level handler branches the same way:
+ * non-null means print-and-skip-Sentry, null means "handle as usual (capture)".
+ */
+export function qmdTerminatedMessage(err) {
+    if (err === null || typeof err !== "object")
+        return null;
+    const record = err;
+    if (record.name !== "QmdTerminatedError")
+        return null;
+    const rawSignal = typeof record.signal === "string" ? record.signal : "";
+    const isHostKill = rawSignal === HOST_KILL;
+    const isInterrupt = INTERRUPTS.has(rawSignal);
+    // Crash-class (SIGSEGV/SIGABRT/SIGBUS) and any unrecognised/missing signal are
+    // left to the captured-error path — they are likely a real qmd/native defect.
+    if (!isHostKill && !isInterrupt)
+        return null;
+    // rawSignal is now one of a fixed allow-list, so it is safe to name; redact
+    // defensively to match the sibling classifiers' discipline.
+    const signal = redactErrorText(rawSignal) || "an unknown signal";
+    if (isInterrupt) {
+        return (`qmd was interrupted (signal ${signal}) before it finished, so the command ` +
+            `returned no results. Re-run it when the machine is free.`);
+    }
+    // SIGKILL: the host reclaimed qmd — most often the OOM killer during CPU-only
+    // embedding on a small box. Tailor the remedy to what qmd was doing so an
+    // index-build kill is not told to re-run the very command that was killed or
+    // offered a search-only `--mode keyword` that does not apply to it.
+    const args = record.args;
+    const subcommand = Array.isArray(args) && typeof args[0] === "string" ? args[0] : "";
+    if (SEARCH_READS.has(subcommand)) {
+        return (`The local search was stopped by the host (signal ${signal}) before qmd finished — ` +
+            `most often the machine ran out of memory while building embeddings on CPU. Run ` +
+            `'hq index sync' once (ideally on a host with more memory) to build embeddings up ` +
+            `front, retry with '--mode keyword' (which needs far less memory), or run the ` +
+            `search on a host with more free memory.`);
+    }
+    return (`qmd was stopped by the host (signal ${signal}) before it finished — most often the ` +
+        `machine ran out of memory (building a large index on CPU is memory-heavy). Re-run it ` +
+        `on a host with more free memory, or index fewer collections at a time.`);
+}
+//# sourceMappingURL=qmd-terminated-error.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.103.18",
+  "version": "5.103.20",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -30,7 +30,7 @@
   "dependencies": {
     "@aws-sdk/client-iot-data-plane": "^3.1096.0",
     "@aws-sdk/client-s3": "^3.1049.0",
-    "@indigoai-us/hq-cloud": "~6.15.30",
+    "@indigoai-us/hq-cloud": "~6.15.37",
     "@indigoai-us/hq-onboarding": "^0.1.0",
     "@sentry/node": "^10.49.0",
     "@tobilu/qmd": "2.5.3",