@indigoai-us/hq-cli 5.94.2 → 5.95.0

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## [Unreleased]
 
+## [5.94.3]
+
+### Fixed
+
+- Upstream gateway faults and pure network transport failures no longer open
+  Sentry crash reports against hq-cli. Gateway HTTP 5xx and JSON-RPC
+  `-32050 PROVIDER_ERROR` are third-party/provider failures already recorded
+  first-party in hq-pro; bare `TypeError('fetch failed')` with a recognized
+  transport errno/undici cause (for example `ConnectTimeoutError`) is a
+  network fault, not an hq-cli bug. Both now classify as expected, print an
+  actionable message, skip Sentry, and keep exit 1. Unclassified errors,
+  including hq-cli bugs that surface as a plain TypeError, still report. (#338)
+
 ## [5.94.2]
 
 ### Fixed

package/dist/commands/index-cmd.d.ts

@@ -9,7 +9,7 @@ export type SearchIndexDependencies = {
     resolveQmdVersion: () => string | undefined;
     runQmd: (args: string[], options?: RunQmdOptions) => QmdProcessResult;
     runBackgroundLauncher?: (dependencies: BackgroundDependencies) => BackgroundResult;
-    runBackgroundWorker?: (dependencies: BackgroundDependencies) => BackgroundResult;
+    runBackgroundWorker?: (dependencies: BackgroundDependencies) => BackgroundResult | Promise<BackgroundResult>;
     backgroundStatus?: (dependencies: BackgroundDependencies) => BackgroundStatus;
 };
 /** Incrementally update qmd, embedding only when an operator explicitly asks. */

package/dist/commands/index-cmd.js

@@ -73,13 +73,13 @@ export function registerIndexCommand(program, dependencies = defaults) {
         .option('--log <path>', 'Write worker output to this log file')
         .addOption(new Option('--worker').hideHelp())
         .option('--hq-root <path>', 'HQ root to index (defaults to auto-detected root)')
-        .action((options) => {
+        .action(async (options) => {
         const hqRoot = resolveRoot(options.hqRoot);
         const background = makeBackgroundDependencies(hqRoot, dependencies);
         if (options.log)
             background.env = { ...background.env, QMD_REINDEX_LOG: options.log };
         const result = options.worker
-            ? (dependencies.runBackgroundWorker ?? runBackgroundWorker)(background)
+            ? await (dependencies.runBackgroundWorker ?? runBackgroundWorker)(background)
             : (dependencies.runBackgroundLauncher ?? runBackgroundLauncher)(background);
         if (!options.worker && result.state === 'launched')
             console.log(result.pid);

package/dist/commands/integrations.js

@@ -30,6 +30,7 @@ import chalk from "chalk";
 import { ensureCognitoIdToken } from "../utils/cognito-session.js";
 import { getCompanyUid, vaultApiFetch } from "../utils/vault-api.js";
 import { AuthError } from "../utils/auth-error.js";
+import { redactErrorText } from "../utils/redact-error-text.js";
 export class IntegrationsCliError extends Error {
     /**
      * True when the error is the caller's request/state/permission (a client 4xx
@@ -53,6 +54,43 @@ export class IntegrationsCliError extends Error {
 function isClientError(status) {
     return status >= 400 && status < 500;
 }
+/**
+ * Statuses that mean HQ's integration gateway (or the third-party provider
+ * behind it) could not serve this request right now — an UPSTREAM AVAILABILITY
+ * event, not an hq-cli defect and not something the caller did wrong.
+ *
+ * HQ-CLI-F: the 500/503s in Sentry correlate request-for-request with the
+ * hq-pro `IntegrationMcpFunction` Lambda hitting its 30s timeout while waiting
+ * on a provider (CloudWatch `integration_mcp_audit event=provider_error`, and
+ * the same spikes counted in the AWS/Lambda `Errors` metric). The event is
+ * already recorded first-party, in the project that owns the fix; mirroring it
+ * into hq-cli's tracker is duplicate, unactionable noise. 429 is included
+ * because a rate-limited call is the same "retry in a moment" outcome (it was
+ * already `expected` via `isClientError`; only its wording changes here).
+ */
+function isUpstreamUnavailable(status) {
+    return status === 429 || status === 500 || status === 502 || status === 503 || status === 504;
+}
+/** Actionable wording for an upstream-availability status. */
+function upstreamUnavailableMessage(status) {
+    return status === 429
+        ? `HQ's integration gateway is rate-limiting this request (HTTP 429). Wait a moment and retry.`
+        : `HQ's integration gateway is temporarily unavailable (HTTP ${status}). ` +
+            `This is a service-side hiccup, not a problem with your command — retry in a moment.`;
+}
+/**
+ * Shared non-2xx guard for every integration-gateway call site. Raises the
+ * expected, actionable upstream-availability error when the status says the
+ * service is down or throttling; returns otherwise so the caller keeps its own
+ * status-specific message and `expected` classification unchanged.
+ */
+function raiseIfUpstreamUnavailable(res) {
+    if (isUpstreamUnavailable(res.status)) {
+        throw new IntegrationsCliError(upstreamUnavailableMessage(res.status), {
+            expected: true,
+        });
+    }
+}
 // The integration gateway answers `POST /v1/integrations/mcp` JSON-RPC-style: a
 // transport failure is a non-2xx HTTP status, but a GOVERNED refusal arrives as
 // HTTP 200 carrying a JSON-RPC `error` object (mirrors hq-pro's
@@ -67,12 +105,35 @@ function isClientError(status) {
 //                           read-only share rejecting a write.
 //   -32602 INVALID_PARAMS — an unknown tool or unsupported provider for the
 //                           connection (a bad request the caller can correct).
+//   -32050 PROVIDER_ERROR  — a THIRD-PARTY provider fault, surfaced verbatim.
+//                           hq-pro mints this code for EVERY provider fault
+//                           and for nothing else: `integration-mcp/server.ts`
+//                           maps an `IntegrationMcpError` with status
+//                           'provider_error' to -32050, raised by
+//                           `integration-mcp/dispatch.ts` for ProviderTimeout,
+//                           ProviderRateLimited, ProviderParseError,
+//                           ProviderWriteUnknown and TokenRefreshFailed.
+//                           NOTE the remote server's OWN JSON-RPC code is
+//                           embedded in the message TEXT ("Remote MCP request
+//                           failed (-32602): …"); the wire code hq-cli sees is
+//                           always -32050, so the codes above never match it.
+//                           Every occurrence is already recorded first-party
+//                           in hq-pro — `integration_mcp_audit
+//                           event=provider_error` with reason/provider/tool,
+//                           an `integration_mcp_health_signal` metric, and
+//                           hq-pro's own Sentry project — so hq-cli reporting
+//                           it again is duplicate noise in the wrong tracker,
+//                           filed against a codebase that cannot fix it
+//                           (HQ-CLI-F). Should hq-pro ever reuse -32050 for
+//                           an hq-pro-side fault, the mapping site named above
+//                           is where that change is traceable; -32603 below
+//                           remains the code for hq-pro's own faults.
 // Everything else stays unexpected so a genuine fault still reaches Sentry:
-// PROVIDER_ERROR (-32050, an upstream provider fault), INTERNAL_ERROR (-32603),
-// CONFLICT (-32009, which the gateway also raises for a confirm queue being
-// unavailable or an owner notification failing — real backend faults worth a
-// report), METHOD_NOT_FOUND / PARSE_ERROR, and any absent or unrecognized code.
-const EXPECTED_GATEWAY_ERROR_CODES = new Set([-32003, -32602]);
+// INTERNAL_ERROR (-32603), CONFLICT (-32009, which the gateway also raises for
+// a confirm queue being unavailable or an owner notification failing — real
+// backend faults worth a report), METHOD_NOT_FOUND / PARSE_ERROR, and any
+// absent or unrecognized code.
+const EXPECTED_GATEWAY_ERROR_CODES = new Set([-32003, -32602, -32050]);
 function isExpectedGatewayError(code) {
     return code != null && EXPECTED_GATEWAY_ERROR_CODES.has(code);
 }
@@ -104,6 +165,7 @@ export async function fetchConnections(token, companyUid) {
     });
     if (!res.ok) {
         raiseIfUnauthorized(res);
+        raiseIfUpstreamUnavailable(res);
         const body = (await res.json().catch(() => ({})));
         throw new IntegrationsCliError(body.error ?? `Failed to list integrations (HTTP ${res.status})`, { expected: isClientError(res.status) });
     }
@@ -162,10 +224,20 @@ export async function callGateway(token, params) {
     const message = (await res.json().catch(() => null));
     if (!res.ok || !message) {
         raiseIfUnauthorized(res);
+        raiseIfUpstreamUnavailable(res);
         throw new IntegrationsCliError(`Integration gateway request failed (HTTP ${res.status}).`, { expected: isClientError(res.status) });
     }
     if (message.error) {
-        throw new IntegrationsCliError(message.error.message ?? "Integration gateway returned an error.", { expected: isExpectedGatewayError(message.error.code) });
+        // The gateway's error text is minted UPSTREAM (hq-pro, the integration
+        // factory, and beyond it the third-party provider), so it is untrusted:
+        // scrub credentials and bound the length here, at the throw site, because
+        // an `expected` error is printed straight from `err.message` by the
+        // top-level handler and never passes through `unexpectedCliErrorMessage`.
+        // The chain is idempotent, so the unexpected path scrubbing again is a
+        // no-op. This preserves PR #298's user-visible diagnostic; it only makes
+        // it safe on the newly-expected path.
+        throw new IntegrationsCliError(redactErrorText(message.error.message ?? "") ||
+            "Integration gateway returned an error.", { expected: isExpectedGatewayError(message.error.code) });
     }
     return message;
 }
@@ -344,6 +416,7 @@ export function registerIntegrationsCommand(program) {
             const body = (await res.json().catch(() => ({})));
             if (!res.ok) {
                 raiseIfUnauthorized(res);
+                raiseIfUpstreamUnavailable(res);
                 throw new IntegrationsCliError(body.error ?? `${decision} failed (HTTP ${res.status})`, { expected: isClientError(res.status) });
             }
             if (opts.json) {

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

@@ -1,6 +1,6 @@
 import { type QmdProcessResult, type RunQmdOptions } from './index.js';
 export type BackgroundResult = {
-    state: 'skipped-agent' | 'skipped' | 'quiet' | 'busy' | 'completed' | 'update-failed';
+    state: 'skipped-agent' | 'skipped' | 'quiet' | 'busy' | 'completed' | 'update-failed' | 'terminated';
 } | {
     state: 'launched';
     pid: number;
@@ -20,6 +20,9 @@ export type BackgroundDependencies = {
     }) => number;
     /** Test seam for simulating a competing owner replacing the atomic record. */
     afterOwnerPublish?: (ownerFile: string) => void;
+    /** Test seams for signal delivery; production uses the real process. */
+    processEvents?: Pick<NodeJS.Process, 'once'>;
+    exit?: (code: number) => void;
 };
 export type BackgroundStatus = {
     lock: 'held' | 'stale' | 'free';
@@ -33,7 +36,7 @@ export declare function installWorkerCleanup(cleanup: () => void, processEvents?
 /** Start a detached worker; this public entry never owns the qmd pipeline. */
 export declare function runBackgroundLauncher(dependencies: BackgroundDependencies): BackgroundResult;
 /** Run the single-flight cleanup → update → embed pipeline in a worker only. */
-export declare function runBackgroundWorker(dependencies: BackgroundDependencies): BackgroundResult;
+export declare function runBackgroundWorker(dependencies: BackgroundDependencies): Promise<BackgroundResult>;
 /** Report the background lock and latest successful completion for `hq index status`. */
 export declare function backgroundStatus(dependencies: BackgroundDependencies): BackgroundStatus;
 //# sourceMappingURL=background.d.ts.map

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

@@ -170,6 +170,10 @@ function acquireClaim(home, observedGeneration, dependencies) {
         const claimant = path.join(claim, `c.${dependencies.pid}.${dependencies.random()}`);
         try {
             fs.mkdirSync(claimant);
+            // Test-only deterministic failure inject (unset in production) — shell
+            // parity with the script's claimant write_owner_record injection.
+            if (dependencies.env.QMD_FORCE_CLAIMANT_WRITE_FAIL)
+                throw new Error('forced claimant write failure');
             fs.writeFileSync(path.join(claimant, 'owner'), `pid=${dependencies.pid}\nts=${dependencies.now()}\n`);
             return { claim, claimant };
         }
@@ -236,6 +240,10 @@ function createAndPublishLock(home, dependencies) {
     const ownerFile = path.join(directory, 'owner');
     const temporary = path.join(directory, `.owner.tmp.${dependencies.pid}.${dependencies.random()}`);
     try {
+        // Test-only deterministic failure inject (unset in production) — shell
+        // parity: the script's write_owner_record honored the same variable.
+        if (dependencies.env.QMD_FORCE_OWNER_WRITE_FAIL)
+            throw new Error('forced owner write failure');
         fs.writeFileSync(temporary, `pid=${dependencies.pid}\nts=${dependencies.now()}\nnonce=${nonce}\n`);
         fs.renameSync(temporary, ownerFile);
         dependencies.afterOwnerPublish?.(ownerFile);
@@ -290,11 +298,52 @@ function releaseLock(home, dependencies) {
 export function installWorkerCleanup(cleanup, processEvents = process, exit = () => undefined) {
     processEvents.once('exit', cleanup);
     // Unlike Bash, Node cannot turn a SIGKILL or an already-defaulted signal into
-    // catchable cleanup. SIGINT/SIGTERM are registered here and the CLI's normal
-    // process exit then runs the same idempotent owner release. Exiting prevents
-    // a synchronous pipeline from continuing after it has released ownership.
+    // catchable cleanup. SIGINT/SIGTERM/SIGHUP are registered here (the shell
+    // worker trapped `INT TERM HUP`; a detached worker's controlling terminal
+    // going away delivers HUP, and the default disposition would kill the
+    // process without releasing the lock) and the CLI's normal process exit then
+    // runs the same idempotent owner release. Exiting prevents a synchronous
+    // pipeline from continuing after it has released ownership.
     processEvents.once('SIGINT', () => { cleanup(); exit(0); });
     processEvents.once('SIGTERM', () => { cleanup(); exit(0); });
+    processEvents.once('SIGHUP', () => { cleanup(); exit(0); });
+}
+function workerLogPath(env) {
+    return env.QMD_REINDEX_LOG
+        ?? env.QMD_HANDOFF_LOG
+        ?? path.join(env.HANDOFF_LOG_DIR ?? '/tmp', 'qmd-handoff.log');
+}
+function appendWorkerLog(logPath, text) {
+    if (!text)
+        return;
+    try {
+        fs.mkdirSync(path.dirname(logPath), { recursive: true });
+        fs.appendFileSync(logPath, text.endsWith('\n') ? text : `${text}\n`);
+    }
+    catch { /* logging is best-effort, exactly like the shell worker's >>"$LOG" */ }
+}
+/** Keep only the trailing QMD_HANDOFF_LOG_MAX_BYTES of the worker log (shell cap_log parity). */
+function capWorkerLog(logPath, env) {
+    const raw = env.QMD_HANDOFF_LOG_MAX_BYTES ?? '65536';
+    if (!/^\d+$/.test(raw))
+        return;
+    const max = Number(raw);
+    if (max === 0)
+        return;
+    try {
+        if (!fs.existsSync(logPath) || fs.statSync(logPath).size <= max)
+            return;
+        const content = fs.readFileSync(logPath);
+        fs.writeFileSync(logPath, content.subarray(content.length - max));
+    }
+    catch { /* best-effort, matching the shell's cap_log */ }
+}
+function stepOutput(result) {
+    return `${result.stdout ?? ''}${result.stderr ?? ''}`;
+}
+function errorOutput(error) {
+    const e = error;
+    return `${e.stdout ?? ''}${e.stderr ?? ''}` || (e.message ?? '');
 }
 /** Start a detached worker; this public entry never owns the qmd pipeline. */
 export function runBackgroundLauncher(dependencies) {
@@ -309,13 +358,10 @@ export function runBackgroundLauncher(dependencies) {
     catch {
         return { state: 'skipped' };
     }
-    const logPath = dependencies.env.QMD_REINDEX_LOG
-        ?? dependencies.env.QMD_HANDOFF_LOG
-        ?? path.join(dependencies.env.HANDOFF_LOG_DIR ?? '/tmp', 'qmd-handoff.log');
-    return { state: 'launched', pid: dependencies.spawnWorker({ logPath }) };
+    return { state: 'launched', pid: dependencies.spawnWorker({ logPath: workerLogPath(dependencies.env) }) };
 }
 /** Run the single-flight cleanup → update → embed pipeline in a worker only. */
-export function runBackgroundWorker(dependencies) {
+export async function runBackgroundWorker(dependencies) {
     if (isHostedAgent(dependencies.env))
         return { state: 'skipped-agent' };
     const home = dependencies.env.HOME;
@@ -329,14 +375,32 @@ export function runBackgroundWorker(dependencies) {
     }
     if (isRecentCompletion(home, dependencies) || !acquireLock(home, dependencies))
         return { state: 'busy' };
+    // Shell-worker log parity: each step's captured output appends to the
+    // handoff log and the log keeps only its trailing QMD_HANDOFF_LOG_MAX_BYTES.
+    // The cap lives inside the exit cleanup because a signal-path process.exit
+    // never unwinds to a `finally` — the shell capped in its EXIT trap for the
+    // same reason.
+    const logPath = workerLogPath(dependencies.env);
     let released = false;
     const cleanup = () => {
         if (released)
             return;
         released = true;
         releaseLock(home, dependencies);
+        capWorkerLog(logPath, dependencies.env);
+    };
+    installWorkerCleanup(cleanup, dependencies.processEvents ?? process, dependencies.exit ?? ((code) => process.exit(code)));
+    // A signal that lands during a synchronous qmd step cannot interrupt it, and
+    // Node defers the handler until the event loop next turns — which a fully
+    // synchronous pipeline never lets happen, so SIGTERM used to be processed
+    // only AFTER update/embed had already run. Bash traps fire between commands;
+    // yielding one event-loop turn between steps restores that contract. If the
+    // handler ran (production exits; tests inject `exit`), `released` is set and
+    // the pipeline stops before its next step.
+    const signalWindow = async () => {
+        await new Promise((resolve) => setImmediate(resolve));
+        return released;
     };
-    installWorkerCleanup(cleanup, process, (code) => process.exit(code));
     try {
         if (isRecentCompletion(home, dependencies))
             return { state: 'busy' };
@@ -349,21 +413,36 @@ export function runBackgroundWorker(dependencies) {
             // The shell worker has no collection-registration step. Keep this #306
             // integration best-effort so it cannot suppress a later index update.
         }
+        if (await signalWindow())
+            return { state: 'terminated' };
         try {
-            dependencies.runQmd(['cleanup'], { cwd: dependencies.hqRoot });
+            appendWorkerLog(logPath, stepOutput(dependencies.runQmd(['cleanup'], { cwd: dependencies.hqRoot })));
         }
-        catch { /* cleanup is intentionally best-effort */ }
+        catch (error) {
+            appendWorkerLog(logPath, errorOutput(error)); // cleanup is intentionally best-effort
+        }
+        if (await signalWindow())
+            return { state: 'terminated' };
         try {
-            dependencies.runQmd(['update'], { cwd: dependencies.hqRoot });
+            appendWorkerLog(logPath, stepOutput(dependencies.runQmd(['update'], { cwd: dependencies.hqRoot })));
         }
-        catch {
+        catch (error) {
+            appendWorkerLog(logPath, errorOutput(error));
+            appendWorkerLog(logPath, `[qmd-reindex-bg] update-failed ts=${dependencies.now()}`);
             return { state: 'update-failed' };
         }
+        if (await signalWindow())
+            return { state: 'terminated' };
         try {
-            dependencies.runQmd(['embed'], { cwd: dependencies.hqRoot });
+            appendWorkerLog(logPath, stepOutput(dependencies.runQmd(['embed'], { cwd: dependencies.hqRoot })));
+        }
+        catch (error) {
+            appendWorkerLog(logPath, errorOutput(error)); // a completed embed attempt still permits the stamp
         }
-        catch { /* a completed embed attempt still permits the completion stamp */ }
+        if (await signalWindow())
+            return { state: 'terminated' };
         writeCompletion(home, dependencies);
+        appendWorkerLog(logPath, `[qmd-reindex-bg] done ts=${dependencies.now()}`);
         return { state: 'completed' };
     }
     finally {

package/dist/main.js

@@ -61,6 +61,7 @@ import { registerSearchCommand } from "./commands/search.js";
 import { registerIndexCommand } from "./commands/index-cmd.js";
 import { sanitizeArgv } from "./utils/feedback-diagnostics.js";
 import { environmentalFsErrorMessage } from "./utils/environmental-error.js";
+import { networkTransportErrorMessage } from "./utils/network-transport-error.js";
 import { isExpectedUserError } from "./utils/expected-cli-error.js";
 import { isEpipe } from "./utils/epipe.js";
 import { isInterceptedProcessExit } from "./utils/intercepted-process-exit.js";
@@ -343,9 +344,23 @@ export function handleTopLevelError(err, deps = defaultTopLevelErrorDependencies
         // identical, unfixable crash reports (HQ-CLI-2). Genuine errors still go
         // to Sentry and still exit 1.
         const envMsg = 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
+        // through to the capture below: it filed a crash report with the useless
+        // culprit `?(undici)`, and printed only the equally useless line
+        // `hq: TypeError: fetch failed` (before #337 landed the always-print
+        // fallback, it printed nothing at all) — HQ-CLI-G. Print an actionable
+        // message that names the unreachable host, exit 1, and skip Sentry.
+        // Ordered after the environmental check so a full disk keeps its exact
+        // existing message.
+        const transportMsg = envMsg ? null : networkTransportErrorMessage(err);
         if (envMsg) {
             deps.stderr.write(`hq: ${envMsg}\n`);
         }
+        else if (transportMsg) {
+            deps.stderr.write(`hq: ${transportMsg}\n`);
+        }
         else {
             deps.sentry.captureException(err);
             // Always emit something. Printing only when unexpectedCliErrorMessage()

package/dist/utils/network-transport-error.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The recognized transport code for `err`, or null when `err` is not a
+ * transport failure. Used for breadcrumb annotation at the fetch call site —
+ * a bounded, non-secret label, never the error text itself.
+ */
+export declare function networkTransportErrorCode(err: unknown): string | null;
+/**
+ * If `err` is a raw network transport failure, return a short, actionable
+ * user-facing message; otherwise return `null`.
+ *
+ * A non-null result means the caller should PRINT the message, exit non-zero,
+ * and SKIP Sentry capture — the condition is the caller's network, not a bug
+ * HQ can fix. A null result means "handle this as usual (capture to Sentry)".
+ */
+export declare function networkTransportErrorMessage(err: unknown): string | null;
+//# sourceMappingURL=network-transport-error.d.ts.map

package/dist/utils/network-transport-error.js

@@ -0,0 +1,184 @@
+// src/utils/network-transport-error.ts
+//
+// Classify raw NETWORK TRANSPORT failures — the request never reached (or
+// never completed against) the server — as the user's connectivity rather
+// than an hq-cli code defect. Sibling of `environmental-error.ts` (HQ-CLI-2,
+// full disk / read-only fs) and `expected-cli-error.ts` (HQ-CLI-6, client
+// 4xx): a failure that is not an hq-cli defect is surfaced to the user with an
+// actionable message and skipped for Sentry capture.
+//
+// HQ-CLI-G (Sentry 7652140783): `hq integrations list` resolved the caller's
+// company through `vaultApiFetch` → bare `fetch`; undici could not connect and
+// threw `TypeError: fetch failed` whose `cause` was
+// `ConnectTimeoutError: Connect Timeout Error (attempted address:
+// hqapi.hq.computer:443, timeout: 10000ms)`. That value is not an
+// `IntegrationsCliError`, so `environmentalFsErrorMessage` and
+// `unexpectedCliErrorMessage` both returned null and the top-level handler
+// took its last-resort branch: capture to Sentry (culprit `?(undici)`, no
+// actionable stack) and print NOTHING. The same process had reached the same
+// host one second earlier, so this was a transient client-side connect
+// failure. Suppressing the crash report is only half the fix — the silent
+// exit is the other half, which is why this returns a MESSAGE, never a bare
+// boolean.
+//
+// Matching is deliberately conservative. A recognized errno / undici code (or
+// a recognized undici error name) must appear on the error or somewhere in its
+// bounded cause chain; message text alone never qualifies. That keeps an
+// hq-cli bug that happens to surface as a `TypeError` reportable.
+import { redactErrorText } from "./redact-error-text.js";
+/** The exact message undici gives the `fetch()` wrapper around a transport fault. */
+const FETCH_FAILED_MESSAGE = "fetch failed";
+/**
+ * Recognized transport codes → the phrase shown to the user.
+ *
+ * Deliberately absent:
+ *   - EPIPE — a closed downstream reader, handled earlier and exits 0 (HQ-6B).
+ *   - UND_ERR_RESPONSE_STATUS_CODE — the server answered; that is an HTTP
+ *     status to classify at the call site, not a transport failure.
+ */
+const TRANSPORT_CODE_REASONS = {
+    ECONNREFUSED: "the connection was refused",
+    ECONNRESET: "the connection was reset",
+    ENOTFOUND: "the hostname could not be resolved",
+    EAI_AGAIN: "the DNS lookup failed temporarily",
+    ETIMEDOUT: "the connection timed out",
+    EHOSTUNREACH: "the host is unreachable",
+    ENETUNREACH: "the network is unreachable",
+    ENETDOWN: "the network is down",
+    UND_ERR_CONNECT_TIMEOUT: "the connection timed out",
+    UND_ERR_HEADERS_TIMEOUT: "the server did not respond in time",
+    UND_ERR_SOCKET: "the connection closed unexpectedly",
+};
+/**
+ * Recognized undici error names, for builds where the `code` property is
+ * absent but the typed error still identifies itself (the shape Sentry
+ * recorded for HQ-CLI-G was `ConnectTimeoutError`).
+ */
+const TRANSPORT_NAME_REASONS = {
+    ConnectTimeoutError: "the connection timed out",
+    HeadersTimeoutError: "the server did not respond in time",
+    SocketError: "the connection closed unexpectedly",
+};
+/**
+ * Depth cap for `cause` traversal. A self-referential or mutually-referential
+ * cause chain must terminate rather than hang the error boundary, so the walk
+ * is bounded on BOTH depth and a visited set.
+ */
+const MAX_CAUSE_DEPTH = 8;
+/** Hostnames/IPs only — anything else is dropped before it reaches stderr. */
+const SAFE_HOST_CHARACTERS = /[^A-Za-z0-9._:[\]-]/g;
+const MAX_HOST_LENGTH = 80;
+function readStringProperty(node, key) {
+    const value = node[key];
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+function errorNameOf(node) {
+    return (readStringProperty(node, "name") ??
+        (typeof node.constructor?.name === "string"
+            ? (node.constructor.name)
+            : null));
+}
+/**
+ * Best-effort host recovery: Node errno errors carry `hostname`/`address`
+ * (+ `port`); undici's ConnectTimeoutError only names the peer in its message
+ * ("attempted address: host:443").
+ */
+function hostFrom(node) {
+    const base = readStringProperty(node, "hostname") ?? readStringProperty(node, "address");
+    if (base) {
+        const port = node.port;
+        return typeof port === "number" && Number.isFinite(port) ? `${base}:${port}` : base;
+    }
+    const message = readStringProperty(node, "message");
+    if (message) {
+        const match = /attempted address:\s*([^\s,)]+)/i.exec(message);
+        if (match)
+            return match[1];
+    }
+    return null;
+}
+/**
+ * Walk `root` and its `cause` chain (plus any `AggregateError.errors`, which
+ * is how undici reports a multi-address connect failure) for a recognized
+ * transport code or error name. Bounded by depth AND a visited set.
+ */
+function findTransportFailure(root) {
+    const seen = new Set();
+    const queue = [{ node: root, depth: 0 }];
+    let host = null;
+    while (queue.length > 0) {
+        const { node, depth } = queue.shift();
+        if (node === null || typeof node !== "object")
+            continue;
+        if (seen.has(node))
+            continue;
+        seen.add(node);
+        host = host ?? hostFrom(node);
+        const code = readStringProperty(node, "code");
+        if (code && TRANSPORT_CODE_REASONS[code]) {
+            return { code, reason: TRANSPORT_CODE_REASONS[code], host };
+        }
+        const name = errorNameOf(node);
+        if (name && TRANSPORT_NAME_REASONS[name]) {
+            return { code: name, reason: TRANSPORT_NAME_REASONS[name], host };
+        }
+        if (depth >= MAX_CAUSE_DEPTH)
+            continue;
+        const cause = node.cause;
+        if (cause !== undefined && cause !== null) {
+            queue.push({ node: cause, depth: depth + 1 });
+        }
+        const aggregated = node.errors;
+        if (Array.isArray(aggregated)) {
+            for (const entry of aggregated)
+                queue.push({ node: entry, depth: depth + 1 });
+        }
+    }
+    return null;
+}
+/**
+ * Reject anything whose SHAPE says "this may be an hq-cli defect" before the
+ * allowlist even runs. A `TypeError` is the one thing undici reuses for a
+ * transport fault, and only with the exact `fetch failed` message; every other
+ * `TypeError` is far likelier to be our own bug (calling a non-function,
+ * reading a property of undefined) and must stay reportable.
+ */
+function hasTransportShape(err) {
+    if (!(err instanceof Error))
+        return false;
+    if (err instanceof TypeError && err.message !== FETCH_FAILED_MESSAGE)
+        return false;
+    return true;
+}
+function classify(err) {
+    if (!hasTransportShape(err))
+        return null;
+    return findTransportFailure(err);
+}
+/**
+ * The recognized transport code for `err`, or null when `err` is not a
+ * transport failure. Used for breadcrumb annotation at the fetch call site —
+ * a bounded, non-secret label, never the error text itself.
+ */
+export function networkTransportErrorCode(err) {
+    return classify(err)?.code ?? null;
+}
+/**
+ * If `err` is a raw network transport failure, return a short, actionable
+ * user-facing message; otherwise return `null`.
+ *
+ * A non-null result means the caller should PRINT the message, exit non-zero,
+ * and SKIP Sentry capture — the condition is the caller's network, not a bug
+ * HQ can fix. A null result means "handle this as usual (capture to Sentry)".
+ */
+export function networkTransportErrorMessage(err) {
+    const failure = classify(err);
+    if (!failure)
+        return null;
+    const host = failure.host
+        ? redactErrorText(failure.host).replace(SAFE_HOST_CHARACTERS, "").slice(0, MAX_HOST_LENGTH)
+        : "";
+    const where = host ? ` (${host})` : "";
+    return `Could not reach HQ${where}: ${failure.reason}. Check your network connection and try again.`;
+}
+//# sourceMappingURL=network-transport-error.js.map

package/dist/utils/redact-error-text.d.ts

@@ -0,0 +1,10 @@
+/** Upper bound on any redacted diagnostic — a message, not a payload dump. */
+export declare const REDACTED_TEXT_MAX_LENGTH = 1000;
+/**
+ * Strip credentials from `text`, flatten control characters/whitespace, and
+ * bound the length. Idempotent, so applying it at both the throw site and the
+ * print site is safe. Returns `""` when nothing survives — callers supply
+ * their own fallback wording.
+ */
+export declare function redactErrorText(text: string): string;
+//# sourceMappingURL=redact-error-text.d.ts.map

package/dist/utils/redact-error-text.js

@@ -0,0 +1,33 @@
+// src/utils/redact-error-text.ts
+//
+// One credential-redaction + bounding chain for error text that leaves the
+// process — printed to the user's terminal or shipped to Sentry.
+//
+// It was originally inline in `unexpected-cli-error.ts`, which only runs on the
+// UNEXPECTED path. Once upstream-minted gateway text can be classified
+// `expected` (HQ-CLI-F), that text is printed by the top-level handler's
+// expected branch instead, which prints `err.message` verbatim. Rather than
+// duplicate the chain at the second print site, it lives here and both callers
+// share it: provider-minted text is untrusted and must never be printed raw.
+/** Upper bound on any redacted diagnostic — a message, not a payload dump. */
+export const REDACTED_TEXT_MAX_LENGTH = 1_000;
+/**
+ * Strip credentials from `text`, flatten control characters/whitespace, and
+ * bound the length. Idempotent, so applying it at both the throw site and the
+ * print site is safe. Returns `""` when nothing survives — callers supply
+ * their own fallback wording.
+ */
+export function redactErrorText(text) {
+    return text
+        .replace(/-----BEGIN[^-]+PRIVATE KEY-----[\s\S]*?-----END[^-]+PRIVATE KEY-----/g, "[REDACTED]")
+        .replace(/\p{Cc}/gu, " ")
+        .replace(/\b(?:Bearer|Basic)\s+[A-Za-z0-9._~+/=-]+/gi, "[REDACTED]")
+        .replace(/\b(password|secret|client[_-]?secret|api[_-]?key|(?:id|access|refresh)[_-]?token|token|authorization)\s*[:=]\s*(?:"[^"]*"|'[^']*'|[^\s&"'<>;,}]+)/gi, (_match, label) => `${label}=[REDACTED]`)
+        .replace(/\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g, "[REDACTED]")
+        .replace(/\b(?:hqk_|xox[abprs]-|github_pat_|gh[pousr]_)[A-Za-z0-9_-]+\b/gi, "[REDACTED]")
+        .replace(/\bAKIA[0-9A-Z]{16}\b/g, "[REDACTED]")
+        .replace(/\s+/g, " ")
+        .trim()
+        .slice(0, REDACTED_TEXT_MAX_LENGTH);
+}
+//# sourceMappingURL=redact-error-text.js.map

package/dist/utils/unexpected-cli-error.d.ts

@@ -3,22 +3,22 @@
  * messages are already part of a user-facing protocol contract. Unknown
  * exceptions remain Sentry-only so local implementation details and secrets
  * are not printed indiscriminately.
+ *
+ * The redaction chain lives in `redact-error-text.ts` so the EXPECTED print
+ * path (which prints `err.message` directly from the top-level handler) can
+ * scrub the same upstream-minted text with the same rules.
  */
 export declare function unexpectedCliErrorMessage(err: unknown): string | null;
 /**
- * Apply the same redaction chain to an arbitrary error message.
+ * Last-resort operator message for an error the CLI has no specific handling
+ * for. Redacted through the same chain as the integrations path; falls back to
+ * a fixed string when the value carries no usable message.
  *
- * Exists so the top-level handler can ALWAYS emit a diagnostic. Previously it
+ * Exists so the top-level handler can ALWAYS emit a diagnostic. It previously
  * printed only when unexpectedCliErrorMessage() returned a value, and that
  * returns null for everything except IntegrationsCliError — so any other
  * failure (a qmd crash, for instance) exited 1 with zero bytes on both
  * streams, which is indistinguishable from success-with-no-output.
  */
-export declare function redactForOperator(raw: string): string;
-/**
- * Last-resort operator message for an error the CLI has no specific handling
- * for. Redacted through the same chain as the integrations path; falls back to
- * a fixed string when the value carries no usable message.
- */
 export declare function fallbackOperatorMessage(err: unknown): string;
 //# sourceMappingURL=unexpected-cli-error.d.ts.map

package/dist/utils/unexpected-cli-error.js

@@ -1,48 +1,37 @@
 import { IntegrationsCliError } from "../commands/integrations.js";
+import { redactErrorText } from "./redact-error-text.js";
 /**
  * Return a bounded operator-facing diagnostic for unexpected errors whose
  * messages are already part of a user-facing protocol contract. Unknown
  * exceptions remain Sentry-only so local implementation details and secrets
  * are not printed indiscriminately.
+ *
+ * The redaction chain lives in `redact-error-text.ts` so the EXPECTED print
+ * path (which prints `err.message` directly from the top-level handler) can
+ * scrub the same upstream-minted text with the same rules.
  */
 export function unexpectedCliErrorMessage(err) {
     if (!(err instanceof IntegrationsCliError) || err.expected)
         return null;
-    return redactForOperator(err.message) || "Integration request failed";
+    return redactErrorText(err.message) || "Integration request failed";
 }
 /**
- * Apply the same redaction chain to an arbitrary error message.
+ * Last-resort operator message for an error the CLI has no specific handling
+ * for. Redacted through the same chain as the integrations path; falls back to
+ * a fixed string when the value carries no usable message.
  *
- * Exists so the top-level handler can ALWAYS emit a diagnostic. Previously it
+ * Exists so the top-level handler can ALWAYS emit a diagnostic. It previously
  * printed only when unexpectedCliErrorMessage() returned a value, and that
  * returns null for everything except IntegrationsCliError — so any other
  * failure (a qmd crash, for instance) exited 1 with zero bytes on both
  * streams, which is indistinguishable from success-with-no-output.
  */
-export function redactForOperator(raw) {
-    return raw
-        .replace(/-----BEGIN[^-]+PRIVATE KEY-----[\s\S]*?-----END[^-]+PRIVATE KEY-----/g, "[REDACTED]")
-        .replace(/\p{Cc}/gu, " ")
-        .replace(/\b(?:Bearer|Basic)\s+[A-Za-z0-9._~+/=-]+/gi, "[REDACTED]")
-        .replace(/\b(password|secret|client[_-]?secret|api[_-]?key|(?:id|access|refresh)[_-]?token|token|authorization)\s*[:=]\s*(?:"[^"]*"|'[^']*'|[^\s&"'<>;,}]+)/gi, (_match, label) => `${label}=[REDACTED]`)
-        .replace(/\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g, "[REDACTED]")
-        .replace(/\b(?:hqk_|xox[abprs]-|github_pat_|gh[pousr]_)[A-Za-z0-9_-]+\b/gi, "[REDACTED]")
-        .replace(/\bAKIA[0-9A-Z]{16}\b/g, "[REDACTED]")
-        .replace(/\s+/g, " ")
-        .trim()
-        .slice(0, 1_000);
-}
-/**
- * Last-resort operator message for an error the CLI has no specific handling
- * for. Redacted through the same chain as the integrations path; falls back to
- * a fixed string when the value carries no usable message.
- */
 export function fallbackOperatorMessage(err) {
     const raw = err instanceof Error
         ? `${err.name}: ${err.message}`
         : typeof err === "string"
             ? err
             : "";
-    return redactForOperator(raw) || "command failed with an unreported error";
+    return redactErrorText(raw) || "command failed with an unreported error";
 }
 //# sourceMappingURL=unexpected-cli-error.js.map

package/dist/utils/vault-api.js

@@ -3,6 +3,7 @@ import { Sentry } from '../sentry.js';
 import { AuthError } from './auth-error.js';
 import { CompanySelectionError } from './company-selection-error.js';
 import { recordPlanLimitStatus } from '../lib/plan-limit-nag.js';
+import { networkTransportErrorCode } from './network-transport-error.js';
 /**
  * Best-effort peek of a 2xx JSON body for plan-limit status (US-016).
  *
@@ -134,15 +135,34 @@ export async function vaultApiFetch(opts) {
         level: "info",
         data: { url: safeUrl, method },
     });
-    const response = await fetch(url.toString(), {
-        method,
-        headers: {
-            Authorization: `Bearer ${opts.token}`,
-            'Content-Type': 'application/json',
-        },
-        body: opts.body ? JSON.stringify(opts.body) : undefined,
-        signal: opts.signal,
-    });
+    let response;
+    try {
+        response = await fetch(url.toString(), {
+            method,
+            headers: {
+                Authorization: `Bearer ${opts.token}`,
+                'Content-Type': 'application/json',
+            },
+            body: opts.body ? JSON.stringify(opts.body) : undefined,
+            signal: opts.signal,
+        });
+    }
+    catch (err) {
+        // A transport failure never reaches the server, so the non-2xx breadcrumb
+        // below never fires and the run's last HTTP trace is the request that
+        // silently vanished (exactly what made HQ-CLI-G's event unreadable). Leave
+        // a bounded, non-secret trail — the already-redacted safeUrl plus the
+        // recognized transport code — then RE-THROW the original error untouched,
+        // so `main.ts`'s classifier stays the single decision point.
+        const code = networkTransportErrorCode(err);
+        Sentry.addBreadcrumb({
+            category: "http",
+            message: `${method} ${path} → transport error`,
+            level: "warning",
+            data: { url: safeUrl, method, ...(code ? { code } : {}) },
+        });
+        throw err;
+    }
     if (!response.ok) {
         Sentry.addBreadcrumb({
             category: "http",

package/package.json

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