@indigoai-us/hq-cli 5.108.2 → 5.108.4

package/dist/lib/mesh/live/daemon/presence.js

@@ -6,15 +6,20 @@
  * - Publishes retained online ONLY to own presence topics
  * - Offline is server-only (IoT lifecycle → PresenceIngestFunction)
  * - Never subscribes to thread topics
- * - Reconnects with jittered backoff 1s–60s on close / network change
+ * - Reconnects with monotonic full-jitter backoff 1s–60s on close / network
+ * - Server credential refusals use a long retry (default 10m ±20%)
  */
 import mqtt from "mqtt";
-import { CredentialRenewalManager, MQTT_KEEPALIVE_SECONDS, realTimerHost, } from "./credentials.js";
+import { CredentialVendError, CredentialRenewalManager, MQTT_KEEPALIVE_SECONDS, clampRetryDelayMs, defaultRefusedRetryMs, realTimerHost, refusedRetryDelayMs, scheduleBoundedTimeout, } from "./credentials.js";
 import { presignIotWssUrl } from "./presign.js";
-/** Full-jitter capped exponential backoff (1s base → 60s cap by default). */
-export function backoffDelayMs(attempt, baseMs, maxMs, random) {
+/**
+ * Full-jitter capped exponential backoff (1s base → 60s cap by default),
+ * floored at `previousMs` so consecutive failures never shrink the delay.
+ */
+export function backoffDelayMs(attempt, baseMs, maxMs, random, previousMs = 0) {
     const cap = Math.min(maxMs, baseMs * 2 ** attempt);
-    return Math.max(0, random() * cap);
+    const raw = Math.max(0, random() * cap);
+    return Math.min(maxMs, Math.max(previousMs, raw));
 }
 export function buildPresencePayload(input) {
     return {
@@ -43,15 +48,20 @@ export class PresenceClient {
     bundle = null;
     state = "idle";
     attempt = 0;
+    lastBackoffMs = 0;
     reconnectHandle = null;
     stopped = false;
     generation = 0;
     publishedTopics = [];
+    /** Last refusal code we logged via onError (episode dedupe). */
+    loggedRefusalKey = null;
+    refusal = null;
     mqttConnect;
     timers;
     random;
     baseBackoffMs;
     maxBackoffMs;
+    refusedRetryMs;
     renewal;
     now;
     constructor(options) {
@@ -63,8 +73,10 @@ export class PresenceClient {
         this.random = options.random ?? Math.random;
         this.baseBackoffMs = options.baseBackoffMs ?? 1_000;
         this.maxBackoffMs = options.maxBackoffMs ?? 60_000;
+        this.refusedRetryMs =
+            options.refusedRetryMs ?? defaultRefusedRetryMs(options.env ?? process.env);
         this.now = options.now ?? (() => new Date());
-        this.renewal = new CredentialRenewalManager(options.fetchCredentials, (bundle) => void this.onCredentialsRenewed(bundle), (err) => options.onError?.(err), this.timers);
+        this.renewal = new CredentialRenewalManager(options.fetchCredentials, (bundle) => void this.onCredentialsRenewed(bundle), (err, info) => this.handleRenewalError(err, info), this.timers, 30_000, this.refusedRetryMs, this.random);
     }
     getConnectionState() {
         return this.state;
@@ -72,6 +84,9 @@ export class PresenceClient {
     getBundle() {
         return this.bundle;
     }
+    getRefusal() {
+        return this.refusal;
+    }
     /** Topics this client has published to (for doctor / tests). */
     getPublishedTopics() {
         return this.publishedTopics;
@@ -99,13 +114,21 @@ export class PresenceClient {
         this.renewal.stop();
         this.clearReconnect();
         this.teardownClient(false);
+        this.clearRefusal(/* logClear */ false);
         this.setState("closed");
     }
     /** Force a reconnect cycle (network change / sleep-wake). */
     reconnectNow() {
         if (this.stopped)
             return;
-        this.attempt = 0;
+        // Do not bypass an active refusal / Retry-After wait (network nudges).
+        if (this.refusal) {
+            const nextMs = Date.parse(this.refusal.nextRetryAt);
+            if (!Number.isNaN(nextMs) && nextMs > this.timers.now()) {
+                return;
+            }
+        }
+        // Backoff counters reset only on MQTT connect — not here.
         this.clearReconnect();
         void this.connectOnce();
     }
@@ -128,12 +151,51 @@ export class PresenceClient {
     }
     async onCredentialsRenewed(bundle) {
         this.bundle = bundle;
+        // Successful vend ends a refusal episode (renewal skips connectOnce's vend path).
+        this.clearRefusal(true);
         if (this.stopped)
             return;
-        // Reconnect with the new presigned URL, then re-publish online.
-        this.attempt = 0;
+        // Reconnect with the new presigned URL; backoff resets only on MQTT connect.
         await this.connectOnce();
     }
+    handleRenewalError(err, info) {
+        if (err instanceof CredentialVendError && err.kind === "refused") {
+            this.noteRefusal(err, info?.nextRetryAt);
+            return;
+        }
+        this.options.onError?.(err);
+    }
+    refusalKey(err) {
+        return err.code ?? `HTTP_${err.status}`;
+    }
+    noteRefusal(err, nextRetryAt) {
+        const code = this.refusalKey(err);
+        const keyChanged = this.loggedRefusalKey !== code;
+        if (keyChanged) {
+            this.loggedRefusalKey = code;
+            this.options.onError?.(err);
+        }
+        const refusal = {
+            code,
+            status: err.status,
+            nextRetryAt: nextRetryAt ??
+                this.refusal?.nextRetryAt ??
+                new Date(this.timers.now()).toISOString(),
+        };
+        this.refusal = refusal;
+        this.options.onRefusal?.(refusal);
+    }
+    clearRefusal(logClear) {
+        if (this.loggedRefusalKey === null && this.refusal === null)
+            return;
+        const previous = this.loggedRefusalKey;
+        this.loggedRefusalKey = null;
+        this.refusal = null;
+        if (logClear && previous) {
+            this.options.onError?.(new Error(`presence refusal cleared (was ${previous})`));
+        }
+        this.options.onRefusal?.(null);
+    }
     async connectOnce() {
         if (this.stopped)
             return;
@@ -143,6 +205,8 @@ export class PresenceClient {
         try {
             if (!this.bundle) {
                 this.bundle = await this.options.fetchCredentials();
+                // Successful vend ends a refusal episode (even before MQTT connects).
+                this.clearRefusal(true);
                 this.renewal.schedule(this.bundle);
             }
             const bundle = this.bundle;
@@ -170,6 +234,7 @@ export class PresenceClient {
                 if (this.stopped || generation !== this.generation)
                     return;
                 this.attempt = 0;
+                this.lastBackoffMs = 0;
                 this.setState("connected");
                 void this.publishAll("online").then(() => {
                     this.options.onOnline?.(bundle.companies.map((c) => c.companyUid));
@@ -187,6 +252,10 @@ export class PresenceClient {
             });
         }
         catch (err) {
+            if (err instanceof CredentialVendError && err.kind === "refused") {
+                this.scheduleReconnect({ refused: err });
+                return;
+            }
             this.options.onError?.(err);
             this.scheduleReconnect();
         }
@@ -224,21 +293,43 @@ export class PresenceClient {
             });
         }
     }
-    scheduleReconnect() {
+    scheduleReconnect(opts) {
         if (this.stopped)
             return;
         this.setState("reconnecting");
         this.clearReconnect();
-        const delay = backoffDelayMs(this.attempt, this.baseBackoffMs, this.maxBackoffMs, this.random);
-        this.attempt += 1;
-        this.reconnectHandle = this.timers.setTimeout(() => {
+        let delay;
+        if (opts?.refused) {
+            const refused = opts.refused;
+            if (refused.retryAfterMs !== undefined) {
+                delay = Math.max(0, refused.retryAfterMs);
+            }
+            else {
+                delay = refusedRetryDelayMs(this.refusedRetryMs, this.random);
+            }
+            delay = clampRetryDelayMs(delay);
+            const nextRetryAt = new Date(this.timers.now() + delay).toISOString();
+            this.noteRefusal(refused, nextRetryAt);
+        }
+        else {
+            delay = backoffDelayMs(this.attempt, this.baseBackoffMs, this.maxBackoffMs, this.random, this.lastBackoffMs);
+            this.lastBackoffMs = delay;
+            this.attempt += 1;
+            // Do not clear refusal here — MQTT close must retain doctor/status refusal
+            // until a subsequent credential vend succeeds.
+        }
+        this.reconnectHandle = scheduleBoundedTimeout(this.timers, () => {
             this.reconnectHandle = null;
+            // Drop stale creds so the next attempt re-vends after a refusal/failure.
+            if (opts?.refused) {
+                this.bundle = null;
+            }
             void this.connectOnce();
         }, delay);
     }
     clearReconnect() {
         if (this.reconnectHandle !== null) {
-            this.timers.clearTimeout(this.reconnectHandle);
+            this.reconnectHandle.clear();
             this.reconnectHandle = null;
         }
     }

package/dist/lib/mesh/live/daemon/run.js

@@ -126,6 +126,7 @@ export async function runMeshDaemon(deps = {}) {
             timers,
             random: deps.random,
             now,
+            env,
             onState: (state) => {
                 patchDaemonState(dir, { mqttState: state }, now);
             },
@@ -134,9 +135,18 @@ export async function runMeshDaemon(deps = {}) {
                     mqttState: "connected",
                     companiesOnline: companies,
                     actorUid: presence?.getBundle()?.actorUid,
+                    presenceRefusal: null,
                 }, now);
                 log(dir, `presence online companies=${companies.length}`);
             },
+            onRefusal: (refusal) => {
+                patchDaemonState(dir, {
+                    presenceRefusal: refusal,
+                    lastErrorCode: refusal
+                        ? `refused:${refusal.code}`.slice(0, 120)
+                        : undefined,
+                }, now);
+            },
             onError: (err) => {
                 const msg = err instanceof Error ? err.message : String(err);
                 patchDaemonState(dir, { lastErrorCode: msg.slice(0, 120) }, now);

package/dist/lib/mesh/live/daemon/state.d.ts

@@ -3,6 +3,11 @@
  */
 import type { MqttConnectionState } from "./presence.js";
 import type { FlushSummary } from "../flush.js";
+export interface PresenceRefusalState {
+    code: string;
+    status: number;
+    nextRetryAt: string;
+}
 export interface DaemonStateFile {
     v: 1;
     pid: number;
@@ -15,6 +20,8 @@ export interface DaemonStateFile {
         ok: boolean;
     };
     lastErrorCode?: string;
+    /** Set while credential vend is refused (FEATURE_DISABLED / unsupported / 403). */
+    presenceRefusal?: PresenceRefusalState | null;
     updatedAt: string;
 }
 export declare function defaultDaemonState(pid: number, now?: () => Date): DaemonStateFile;

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