@indigoai-us/hq-cli 5.108.2 → 5.108.3

package/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## [Unreleased]
 
+## [5.108.3] — 2026-09-04
+
 ## [5.108.2] — 2026-09-04
 
 ### Fixed

package/dist/commands/index-cmd.js

@@ -5,6 +5,7 @@ import { findHqRoot } from '../utils/manifest.js';
 import { QMD_NATIVE_BINDING_REMEDY, isQmdNativeBindingError, } from '../utils/qmd-native-binding-error.js';
 import { isQmdStoreMissingError, qmdStoreMissingMessage, } from '../utils/qmd-store-missing-error.js';
 import { isQmdStoreUnopenableError, qmdStoreUnopenableMessage, } from '../utils/qmd-store-unopenable-error.js';
+import { isQmdWorkdirMissingError, qmdWorkdirMissingMessage, } from '../utils/qmd-workdir-missing-error.js';
 const defaults = {
     reconcileCollections,
     deriveCollections,
@@ -147,6 +148,18 @@ export function registerIndexCommand(program, dependencies = defaults) {
                 process.stderr.write(`qmd: unusable — ${remedy}\n`);
                 process.exitCode = 1;
             }
+            else if (isQmdWorkdirMissingError(error)) {
+                // The working directory hq handed qmd (the resolved hq root) does not
+                // exist, so the spawn failed with ENOENT (HQ-CLI-1A). Like the
+                // store-missing/unopenable cases, this diagnostic command should
+                // DESCRIBE the broken working directory, not crash on it or send the
+                // user to reinstall qmd: print the classified reason + remedy naming
+                // the directory and exit 1 without rethrowing. Every OTHER qmd failure
+                // keeps propagating.
+                const remedy = qmdWorkdirMissingMessage(error) ?? 'its working directory does not exist';
+                process.stderr.write(`qmd: unusable — ${remedy}\n`);
+                process.exitCode = 1;
+            }
             else {
                 throw error;
             }

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

@@ -38,6 +38,25 @@ export type QmdInvocation = {
     prefixArgs: string[];
     execDir?: string;
 };
+/**
+ * Bounded, hq-DERIVED evidence stamped onto a CAPTURED qmd spawn-level failure
+ * (the interpreter-missing and residual QmdBinaryMissingError cases). The
+ * reporting host (HQ-CLI-1A) shipped no platform log, so spawnSync's ENOENT
+ * could not be pinned to a missing command vs. a missing working directory. The
+ * boundary forwards this into a bounded Sentry context so the NEXT occurrence
+ * carries the evidence this one lacked. Every field is hq-derived — the errno
+ * code, the resolved `cwd`, `process.execPath`, the bundled launcher, and their
+ * existence at failure time — never caller argv or query text.
+ */
+export type QmdSpawnDiagnostics = {
+    errnoCode: string | null;
+    cwd: string | null;
+    cwdExists: boolean | null;
+    command: string;
+    commandExists: boolean;
+    launcher: string;
+    launcherExists: boolean;
+};
 /** Low-level spawn seam (defaults to `spawnSync`); injected in tests. */
 export type QmdSpawn = (cmd: string, args: string[], options: {
     cwd?: string;
@@ -59,6 +78,34 @@ export type QmdSpawn = (cmd: string, args: string[], options: {
 export declare function withNodeDirOnPath(env: NodeJS.ProcessEnv | undefined, execDir: string | undefined, platform?: NodeJS.Platform): NodeJS.ProcessEnv | undefined;
 export declare class QmdBinaryMissingError extends Error {
     name: string;
+    /**
+     * Present only when the failure came through the real spawn path (attribution
+     * available): the errno code and per-component existence booleans captured at
+     * failure time, forwarded to a bounded Sentry context by the boundary so the
+     * next occurrence carries the evidence the reported one lacked (HQ-CLI-1A).
+     * Absent on the legacy injected-runner path and the resolver's opaque throws,
+     * so their existing shapes are unchanged.
+     */
+    readonly spawnDiagnostics?: QmdSpawnDiagnostics;
+    constructor(message: string, spawnDiagnostics?: QmdSpawnDiagnostics);
+}
+/**
+ * qmd could not be SPAWNED because its working directory does not exist:
+ * spawnSync returned ENOENT while chdir-ing into `cwd` (the resolved hq root at
+ * every index call site) before it could exec the command. On Linux that ENOENT
+ * is byte-identical to a missing-command ENOENT — Node sets `error.path` to the
+ * COMMAND either way — so finishRunQmd disambiguates by existence and raises
+ * THIS typed carrier only when the working directory itself is absent. Carries
+ * the hq-DERIVED `workdir`, the `command` that was spawned, and the bounded
+ * `errnoCode`; a missing working directory is the caller's filesystem, so the
+ * boundary prints qmdWorkdirMissingMessage and SKIPS capture (HQ-CLI-1A).
+ */
+export declare class QmdWorkdirMissingError extends Error {
+    readonly workdir: string;
+    readonly command: string;
+    readonly errnoCode: string;
+    name: string;
+    constructor(message: string, workdir: string, command: string, errnoCode: string);
 }
 export declare class QmdExitError extends Error {
     readonly args: string[];
@@ -469,6 +516,12 @@ export type RunQmdOptions = {
     execPath?: string;
     /** Invocation resolver seam (default {@link resolveQmdInvocation}). */
     resolveInvocation?: (options: ResolveQmdInvocationOptions) => QmdInvocation;
+    /**
+     * Existence-check seam threaded into finishRunQmd's spawn-failure
+     * disambiguation (default `fs.existsSync`); injected in tests so the missing
+     * cwd / interpreter branches are provable without touching the real disk.
+     */
+    exists?: (candidate: string) => boolean;
 };
 /** Run qmd with captured output and typed failures. */
 export declare function runQmd(args: string[], options?: RunQmdOptions): QmdProcessResult;

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

@@ -30,6 +30,43 @@ export function withNodeDirOnPath(env, execDir, platform = process.platform) {
 }
 export class QmdBinaryMissingError extends Error {
     name = 'QmdBinaryMissingError';
+    /**
+     * Present only when the failure came through the real spawn path (attribution
+     * available): the errno code and per-component existence booleans captured at
+     * failure time, forwarded to a bounded Sentry context by the boundary so the
+     * next occurrence carries the evidence the reported one lacked (HQ-CLI-1A).
+     * Absent on the legacy injected-runner path and the resolver's opaque throws,
+     * so their existing shapes are unchanged.
+     */
+    spawnDiagnostics;
+    constructor(message, spawnDiagnostics) {
+        super(message);
+        if (spawnDiagnostics)
+            this.spawnDiagnostics = spawnDiagnostics;
+    }
+}
+/**
+ * qmd could not be SPAWNED because its working directory does not exist:
+ * spawnSync returned ENOENT while chdir-ing into `cwd` (the resolved hq root at
+ * every index call site) before it could exec the command. On Linux that ENOENT
+ * is byte-identical to a missing-command ENOENT — Node sets `error.path` to the
+ * COMMAND either way — so finishRunQmd disambiguates by existence and raises
+ * THIS typed carrier only when the working directory itself is absent. Carries
+ * the hq-DERIVED `workdir`, the `command` that was spawned, and the bounded
+ * `errnoCode`; a missing working directory is the caller's filesystem, so the
+ * boundary prints qmdWorkdirMissingMessage and SKIPS capture (HQ-CLI-1A).
+ */
+export class QmdWorkdirMissingError extends Error {
+    workdir;
+    command;
+    errnoCode;
+    name = 'QmdWorkdirMissingError';
+    constructor(message, workdir, command, errnoCode) {
+        super(message);
+        this.workdir = workdir;
+        this.command = command;
+        this.errnoCode = errnoCode;
+    }
 }
 export class QmdExitError extends Error {
     args;
@@ -966,7 +1003,7 @@ function describeQmdTermination(stdout, stderr) {
     return '';
 }
 /** Normalise a spawn result and raise the typed qmd failures. */
-function finishRunQmd(result, bin, args) {
+function finishRunQmd(result, bin, args, attribution) {
     const normalized = {
         status: result.status,
         stdout: result.stdout ?? '',
@@ -975,6 +1012,54 @@ function finishRunQmd(result, bin, args) {
         signal: result.signal,
     };
     if (normalized.error) {
+        // A spawn-LEVEL failure: the child could not even be exec'd. When the real
+        // spawn path supplied attribution we can attribute it to the right
+        // component; the legacy injected-runner path passes none and keeps today's
+        // exact class and message.
+        if (attribution) {
+            const spawnError = normalized.error;
+            const errnoCode = typeof spawnError.code === 'string' ? spawnError.code : null;
+            const exists = attribution.exists ?? ((candidate) => fs.existsSync(candidate));
+            const cwd = attribution.cwd ?? null;
+            const cwdExists = cwd !== null ? exists(cwd) : null;
+            const commandExists = exists(attribution.command);
+            const launcherExists = exists(attribution.launcher);
+            // (a) MISSING WORKING DIRECTORY. On Linux spawnSync reports ENOENT with
+            // `error.path` set to the COMMAND both when the command is absent AND when
+            // chdir into `cwd` fails, so this cwd check MUST precede the command check
+            // below — a path-based test alone would keep blaming the interpreter for a
+            // directory that is simply gone (HQ-CLI-1A). The directory is the caller's
+            // filesystem, so it is raised as its own carrier and the boundary skips
+            // capture.
+            if (errnoCode === 'ENOENT' && cwd !== null && cwdExists === false) {
+                throw new QmdWorkdirMissingError(`qmd could not run: its working directory (${cwd}) does not exist`, cwd, attribution.command, errnoCode);
+            }
+            const diagnostics = {
+                errnoCode,
+                cwd,
+                cwdExists,
+                command: attribution.command,
+                commandExists,
+                launcher: attribution.launcher,
+                launcherExists,
+            };
+            // (b) MISSING INTERPRETER. The bundled qmd is launched as `<node> <qmd
+            // launcher>`; when the interpreter (`command`, distinct from the launcher)
+            // is what could not be executed, name IT rather than the launcher the
+            // reported message wrongly blamed. Still captured — an absent interpreter
+            // is a genuine defect — but now correct and self-describing.
+            if (errnoCode === 'ENOENT' &&
+                attribution.command !== attribution.launcher &&
+                commandExists === false) {
+                throw new QmdBinaryMissingError(`Unable to execute qmd: its Node interpreter (${attribution.command}) could not be executed: ${normalized.error.message}`, diagnostics);
+            }
+            // (c) RESIDUAL: an ENOENT the fix cannot attribute (a genuinely missing
+            // qmd, or a race where the directory/interpreter reappeared) or any other
+            // spawn errno (EACCES/EINVAL/…). Keep today's class and message byte-for-
+            // byte, and attach the bounded diagnostics so the next occurrence carries
+            // the per-component existence evidence.
+            throw new QmdBinaryMissingError(`Unable to execute qmd at ${bin}: ${normalized.error.message}`, diagnostics);
+        }
         throw new QmdBinaryMissingError(`Unable to execute qmd at ${bin}: ${normalized.error.message}`);
     }
     if (normalized.status === 0)
@@ -1157,13 +1242,24 @@ export function runQmd(args, options = {}) {
     // idempotent; only the real spawn path needs it (the injected-runner path
     // above never opens a store).
     ensureQmdStoreDir(options.env ?? process.env, { cwd: options.cwd });
+    const launcher = invocationBin(invocation);
     const result = spawnQmd(invocation, args, {
         cwd: options.cwd,
         env: options.env ?? process.env,
         platform: options.platform,
         spawn: options.spawn,
     });
-    return finishRunQmd(result, invocationBin(invocation), args);
+    // Thread attribution so finishRunQmd can attribute a spawn-level ENOENT to the
+    // right component — the working directory, the Node interpreter, or a
+    // genuinely missing qmd — instead of blaming the launcher for all three
+    // (HQ-CLI-1A). `command` is the process actually spawned; `launcher` is qmd's
+    // file identity.
+    return finishRunQmd(result, launcher, args, {
+        command: invocation.command,
+        launcher,
+        cwd: options.cwd,
+        exists: options.exists,
+    });
 }
 function containsIndexedMarkdown(directory) {
     if (!fs.existsSync(directory))

package/dist/main.js

@@ -75,6 +75,7 @@ import { qmdStoreMissingMessage } from "./utils/qmd-store-missing-error.js";
 import { qmdStoreUnopenableMessage } from "./utils/qmd-store-unopenable-error.js";
 import { qmdQueryDocumentMessage } from "./utils/qmd-query-document-error.js";
 import { qmdModelDownloadMessage } from "./utils/qmd-model-download-error.js";
+import { qmdWorkdirMissingMessage } from "./utils/qmd-workdir-missing-error.js";
 import { hqStateWriteErrorMessage } from "./utils/hq-state-write-error.js";
 import { isExpectedUserError } from "./utils/expected-cli-error.js";
 import { isVarlockEnvError } from "./run/env-graph-guard.js";
@@ -379,6 +380,26 @@ const defaultTopLevelErrorDependencies = {
         process.exitCode = code;
     },
 };
+/**
+ * Bounded Sentry context for a CAPTURED qmd spawn-level failure (the
+ * interpreter-missing and residual QmdBinaryMissingError cases). finishRunQmd
+ * stamps the errno code and per-component existence booleans onto the error at
+ * failure time; because the reporting host (HQ-CLI-1A) shipped no platform log,
+ * this is the evidence the next occurrence carries. Read STRUCTURALLY off the
+ * error's own `spawnDiagnostics` field (the boundary reconstructs typed carriers
+ * structurally in tests). Only hq-DERIVED paths (the resolved cwd,
+ * process.execPath, the bundled launcher) and a bounded errno code appear —
+ * never caller argv or query text. Returns undefined when the error carries no
+ * such diagnostics, so the generic capture stays a bare captureException(err).
+ */
+function qmdSpawnFailureCaptureContext(err) {
+    if (err === null || typeof err !== "object")
+        return undefined;
+    const diagnostics = err.spawnDiagnostics;
+    if (diagnostics === null || typeof diagnostics !== "object")
+        return undefined;
+    return { contexts: { qmd_spawn_failure: diagnostics } };
+}
 /** Classify a top-level failure without making the CLI process boundary opaque to tests. */
 export async function handleTopLevelError(err, deps = defaultTopLevelErrorDependencies) {
     // A broken pipe (EPIPE) means the reader of `hq`'s output closed it early
@@ -628,6 +649,23 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         const modelDownloadMsg = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg || moduleMissingMsg || storeMissingMsg || storeUnopenableMsg || queryDocumentMsg
             ? null
             : qmdModelDownloadMessage(err);
+        // A qmd spawn-level failure whose ENOENT was a MISSING WORKING DIRECTORY
+        // (the resolved hq root the qmd child was handed as `cwd` does not exist).
+        // finishRunQmd types it QmdWorkdirMissingError, carrying the hq-derived
+        // directory; the boundary prints a self-describing remedy naming that
+        // directory and skips capture — a working directory that does not exist is
+        // the caller's filesystem, the same disposition as the store-missing /
+        // store-unopenable branches. Before this branch it was MISATTRIBUTED to a
+        // missing qmd (QmdBinaryMissingError, remedy `Install @tobilu/qmd`) and,
+        // with no boundary branch for it, captured as a crash (HQ-CLI-1A, Sentry
+        // 7705642434). Evaluated immediately AFTER the store-unopenable /
+        // query-document / model-download checks and BEFORE the environmental /
+        // transport / generic branches; the carrier's name is disjoint from every
+        // neighbour and it carries no `.code` environmentalFsErrorMessage could
+        // read, so ordering changes no existing branch.
+        const workdirMissingMsg = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg || moduleMissingMsg || storeMissingMsg || storeUnopenableMsg || queryDocumentMsg || modelDownloadMsg
+            ? null
+            : qmdWorkdirMissingMessage(err);
         // An hq STATE-TREE write that failed for an environmental errno
         // (permission/quota/read-only/parent-gone) is typed at the write site as an
         // HqStateWriteError carrying the exact hq-DERIVED path it tried to write.
@@ -637,10 +675,10 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         // remedy and skip capture. Placed with the environmental-fs family — BEFORE
         // the generic envMsg computation — so this typed carrier wins even though
         // it also carries an errno `code` environmentalFsErrorMessage could read.
-        const stateWriteMsg = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg || moduleMissingMsg || storeMissingMsg || storeUnopenableMsg || queryDocumentMsg || modelDownloadMsg
+        const stateWriteMsg = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg || moduleMissingMsg || storeMissingMsg || storeUnopenableMsg || queryDocumentMsg || modelDownloadMsg || workdirMissingMsg
             ? null
             : hqStateWriteErrorMessage(err);
-        const envMsg = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg || moduleMissingMsg || storeMissingMsg || storeUnopenableMsg || queryDocumentMsg || modelDownloadMsg || stateWriteMsg
+        const envMsg = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg || moduleMissingMsg || storeMissingMsg || storeUnopenableMsg || queryDocumentMsg || modelDownloadMsg || workdirMissingMsg || stateWriteMsg
             ? null
             : environmentalFsErrorMessage(err);
         // A LOCAL sync-state lock failure (@indigoai-us/hq-cloud's
@@ -657,7 +695,7 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         // environmental-fs check, before network-transport — is pinned by tests.
         // The `in-process-async-holder` reason is deliberately NOT suppressed here
         // (see sync-state-lock-error.ts); it stays captured.
-        const lockMsg = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg || moduleMissingMsg || storeMissingMsg || storeUnopenableMsg || queryDocumentMsg || modelDownloadMsg || stateWriteMsg || envMsg
+        const lockMsg = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg || moduleMissingMsg || storeMissingMsg || storeUnopenableMsg || queryDocumentMsg || modelDownloadMsg || workdirMissingMsg || stateWriteMsg || envMsg
             ? null
             : syncStateLockMessage(err);
         // A raw network transport failure (undici's `TypeError: fetch failed`
@@ -679,6 +717,7 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
             storeUnopenableMsg ||
             queryDocumentMsg ||
             modelDownloadMsg ||
+            workdirMissingMsg ||
             stateWriteMsg ||
             envMsg ||
             lockMsg
@@ -711,6 +750,9 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         else if (modelDownloadMsg) {
             deps.stderr.write(`hq: ${modelDownloadMsg}\n`);
         }
+        else if (workdirMissingMsg) {
+            deps.stderr.write(`hq: ${workdirMissingMsg}\n`);
+        }
         else if (stateWriteMsg) {
             deps.stderr.write(`hq: ${stateWriteMsg}\n`);
         }
@@ -724,7 +766,17 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
             deps.stderr.write(`hq: ${transportMsg}\n`);
         }
         else {
-            deps.sentry.captureException(err);
+            // A genuinely unclassified fault is still captured exactly once. When it
+            // is a qmd spawn-level failure the fix could not attribute, attach the
+            // bounded existence context so the next occurrence carries the evidence
+            // the reported HQ-CLI-1A event lacked; every other error captures bare.
+            const spawnContext = qmdSpawnFailureCaptureContext(err);
+            if (spawnContext) {
+                deps.sentry.captureException(err, spawnContext);
+            }
+            else {
+                deps.sentry.captureException(err);
+            }
             // Always emit something. Printing only when unexpectedCliErrorMessage()
             // returned a value meant every error class except IntegrationsCliError
             // exited 1 with zero bytes on stdout AND stderr — a silent failure the

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

@@ -0,0 +1,18 @@
+/**
+ * True when `err` is a qmd working-directory-missing failure: it carries the
+ * QmdWorkdirMissingError name and an hq-populated `workdir`. Accepts either the
+ * thrown error or a bare `{ name, workdir }` probe object. A true result means
+ * the caller should print the classified remedy, exit non-zero, and SKIP Sentry
+ * capture.
+ */
+export declare function isQmdWorkdirMissingError(err: unknown): boolean;
+/**
+ * If `err` is a qmd working-directory-missing failure, return the actionable
+ * remedy; otherwise return `null`. Mirrors qmdStoreMissingMessage /
+ * qmdStoreUnopenableMessage 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". The working directory is read STRUCTURALLY from the error's own
+ * hq-populated `workdir` field, NEVER from qmd's output.
+ */
+export declare function qmdWorkdirMissingMessage(err: unknown): string | null;
+//# sourceMappingURL=qmd-workdir-missing-error.d.ts.map

package/dist/utils/qmd-workdir-missing-error.js

@@ -0,0 +1,78 @@
+// src/utils/qmd-workdir-missing-error.ts
+//
+// Classify a qmd spawn failure caused by a MISSING WORKING DIRECTORY — the
+// directory the qmd child was told to run in (`cwd`, always the resolved hq
+// root at the qmd call sites) does not exist — rather than an hq-cli code
+// defect or a genuinely missing qmd. This is the caller's LOCAL filesystem (a
+// deleted tree, a `--hq-root` pointing at a directory that is not there), not a
+// bug HQ can fix in code, so the CLI surfaces an actionable remedy and SKIPS
+// Sentry capture. Sibling of qmd-store-missing-error.ts (HQ-CLI-16, a missing
+// STORE directory) and qmd-store-unopenable-error.ts (HQ-CLI-18): a failure
+// that is NOT an hq-cli defect is printed with an actionable message and never
+// filed as a crash.
+//
+// HQ-CLI-1A (Sentry indigo-d0/hq-cli 7705642434): `hq index status --hq-root
+// /home/ec2-user/hq` spawned the bundled qmd as `<node interpreter> <qmd
+// launcher>`, and spawnSync failed with `spawnSync /usr/bin/node ENOENT`. On
+// Linux, spawnSync reports ENOENT with `path`/`syscall` set to the COMMAND both
+// when the command is missing AND when chdir into `cwd` fails — two distinct
+// causes with byte-identical text. finishRunQmd was handed only the qmd
+// launcher path, so it blamed a THIRD path Node never faulted
+// (`QmdBinaryMissingError: Unable to execute qmd at …/@tobilu/qmd/bin/qmd`) with
+// a remedy (`Install @tobilu/qmd`) that cannot fix either real cause, and — with
+// no boundary branch for it — the misattributed error was captured as a crash.
+// finishRunQmd now disambiguates at the failure site: when the ENOENT is a
+// missing working directory it raises the typed carrier this module classifies.
+//
+// Classification is STRUCTURAL — the typed carrier's own `name` plus its
+// hq-populated `workdir` field, NEVER a text match on qmd's output or the
+// caller's argv — so a search query or a document body can never trip it, and
+// the class need not be imported here (avoiding a cycle with the module that
+// defines it). Reading `name`/`workdir` off the error object also lets the
+// top-level boundary, which reconstructs typed carriers structurally, branch on
+// it the same way it does the sibling qmd errors.
+/**
+ * True when `err` is a qmd working-directory-missing failure: it carries the
+ * QmdWorkdirMissingError name and an hq-populated `workdir`. Accepts either the
+ * thrown error or a bare `{ name, workdir }` probe object. A true result means
+ * the caller should print the classified remedy, exit non-zero, and SKIP Sentry
+ * capture.
+ */
+export function isQmdWorkdirMissingError(err) {
+    if (err === null || typeof err !== "object")
+        return false;
+    const record = err;
+    return (record.name === "QmdWorkdirMissingError" &&
+        typeof record.workdir === "string" &&
+        record.workdir.length > 0);
+}
+/**
+ * The actionable remedy, naming the working directory that does not exist. The
+ * directory is an hq-DERIVED value — the resolved `cwd` (the hq root) the qmd
+ * child was handed — never caller argv/query or upstream free text, so the line
+ * stays input-free. Deliberately does NOT suggest reinstalling qmd (the reported
+ * misattribution's dead-end remedy) or `hq index sync` (reconciliation runs the
+ * same spawn and would hit the identical failure, a dead-end loop): the only fix
+ * is to make the working directory exist.
+ */
+function remedyMessage(workdir) {
+    return (`hq's working directory (${workdir}) does not exist, so its local search index ` +
+        "could not run there. This is your machine's filesystem, not an hq bug: " +
+        "re-create that directory, or re-run with --hq-root pointing at a directory " +
+        "that exists.");
+}
+/**
+ * If `err` is a qmd working-directory-missing failure, return the actionable
+ * remedy; otherwise return `null`. Mirrors qmdStoreMissingMessage /
+ * qmdStoreUnopenableMessage 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". The working directory is read STRUCTURALLY from the error's own
+ * hq-populated `workdir` field, NEVER from qmd's output.
+ */
+export function qmdWorkdirMissingMessage(err) {
+    if (!isQmdWorkdirMissingError(err))
+        return null;
+    const record = err;
+    return remedyMessage(record.workdir);
+}
+//# sourceMappingURL=qmd-workdir-missing-error.js.map

package/dist/utils/sentry-fingerprint.js

@@ -86,6 +86,11 @@ const KNOWN_ERROR_NAMES = new Set([
     "QmdStoreUnopenableError",
     "QmdQueryDocumentError",
     "QmdModelDownloadError",
+    // Shares the `Qmd` prefix the qmd branch keys on. The boundary now SUPPRESSES
+    // capture for this class, so it should never reach a capture route — allow-
+    // listed defensively so a future capture path cannot mint an unbounded group
+    // (HQ-CLI-1A).
+    "QmdWorkdirMissingError",
 ]);
 /** Fixed bucket for any error name outside the closed allowlist. */
 const FALLBACK_ERROR_NAME = "other";

package/package.json

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