@indigoai-us/hq-cli 5.94.1 → 5.94.3

package/dist/commands/core-checkpoint.js

@@ -13,12 +13,23 @@ import { homedir } from "node:os";
 import { resolveLiveRoot } from "../utils/hq-roots.js";
 import { peekIdToken } from "../utils/id-token.js";
 const DEFAULT_TRIGGER = "stop-gate";
-const BACKENDS = new Set(["auto", "claude", "codex", "none"]);
+const BACKENDS = new Set(["auto", "claude", "codex", "grok", "none"]);
 // Pinned by operator directive 2026-07-31; change defaults here deliberately.
 const CODEX_SIBLING_MODEL = "gpt-5.6-terra";
 const CODEX_SIBLING_REASONING_EFFORT = "high";
 const CLAUDE_SIBLING_MODEL = "claude-opus-5";
 const CLAUDE_SIBLING_EFFORT = "medium";
+const GROK_SIBLING_MODEL = "grok-4.5";
+const GROK_SIBLING_EFFORT = "high";
+/**
+ * `grok -p` is single-turn by default: without a turn budget it answers with a
+ * plan and exits, having done nothing. The maintenance flow needs many turns.
+ */
+const GROK_SIBLING_MAX_TURNS = "100";
+/** Preference order for `--backend auto`, first healthy candidate wins. */
+const AUTO_BACKEND_ORDER = ["codex", "grok", "claude"];
+/** A backend that cannot answer `--version` this fast is treated as broken. */
+const BACKEND_PROBE_TIMEOUT_MS = 10_000;
 /** A sibling still holding the lock after this long is treated as abandoned. */
 const SIBLING_LOCK_TTL_MS = 60 * 60 * 1000;
 /** Newest-wins cap so a wedged sibling cannot grow an unbounded queue. */
@@ -402,21 +413,150 @@ function backendOnPath(name) {
         }
     });
 }
-function resolveBackend(requested) {
+/**
+ * An installed binary is not necessarily a working one: a partial install, a
+ * broken wrapper or a missing runtime all leave an executable on PATH that
+ * fails the moment it is asked to do anything. Ask it for its version — cheap,
+ * bounded, and enough to reject a backend before handing it a checkpoint.
+ */
+function backendResponds(name) {
+    try {
+        execFileSync(name, ["--version"], {
+            timeout: BACKEND_PROBE_TIMEOUT_MS,
+            stdio: "ignore",
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Backends whose most recent run died without producing a report.
+ *
+ * A version probe cannot catch a backend that starts cleanly and then fails at
+ * runtime — an expired login, a sandbox it cannot write in, a model it is not
+ * entitled to. The evidence for that is a finished run directory with no
+ * report.md in it, so prefer a different backend for the next checkpoint. Only
+ * the newest run per backend counts: one that has since succeeded is healthy.
+ */
+function crashedBackends(siblingRoot) {
+    const crashed = new Set();
+    let runDirs;
+    try {
+        runDirs = fs
+            .readdirSync(siblingRoot)
+            .filter((entry) => entry !== "pending.jsonl")
+            .sort()
+            .reverse();
+    }
+    catch {
+        return crashed;
+    }
+    const seen = new Set();
+    for (const runDir of runDirs) {
+        const absolute = path.join(siblingRoot, runDir);
+        let backend;
+        try {
+            const payload = JSON.parse(fs.readFileSync(path.join(absolute, "payload.json"), "utf8"));
+            backend = payload.backend;
+        }
+        catch {
+            continue;
+        }
+        if (typeof backend !== "string" || !backend || seen.has(backend))
+            continue;
+        seen.add(backend);
+        if (fs.existsSync(path.join(absolute, "report.md")))
+            continue;
+        // A missing report only means a crash once the process itself is gone.
+        let pid = Number.NaN;
+        try {
+            pid = Number.parseInt(fs.readFileSync(path.join(absolute, "sibling.pid"), "utf8").trim(), 10);
+        }
+        catch {
+            // A run that never recorded a PID cannot still be running.
+        }
+        if (Number.isSafeInteger(pid) && pid > 0 && processAlive(pid))
+            continue;
+        crashed.add(backend);
+    }
+    return crashed;
+}
+function resolveBackend(requested, liveRoot) {
     const value = requested ?? "auto";
     if (!BACKENDS.has(value))
         usage(`checkpoint: unknown backend: ${value}`);
-    if (value === "auto") {
-        if (backendOnPath("codex"))
-            return "codex";
-        if (backendOnPath("claude"))
-            return "claude";
+    // An explicitly named backend is honoured as given; only `auto` shops around.
+    if (value !== "auto")
+        return value;
+    const available = AUTO_BACKEND_ORDER.filter((name) => backendOnPath(name) && backendResponds(name));
+    if (available.length === 0)
         return "none";
+    const crashed = crashedBackends(path.join(liveRoot, "workspace", "checkpoints", "sibling"));
+    // If every candidate failed last time, still try the preferred one: a stale
+    // failure is a weaker signal than running no maintenance sibling at all.
+    return available.find((name) => !crashed.has(name)) ?? available[0];
+}
+function siblingArgs(backend, prompt) {
+    switch (backend) {
+        case "claude":
+            return [
+                "-p",
+                prompt,
+                "--model",
+                CLAUDE_SIBLING_MODEL,
+                "--effort",
+                CLAUDE_SIBLING_EFFORT,
+                "--permission-mode",
+                "acceptEdits",
+            ];
+        case "grok":
+            return [
+                "-p",
+                prompt,
+                "-m",
+                GROK_SIBLING_MODEL,
+                "--reasoning-effort",
+                GROK_SIBLING_EFFORT,
+                // `acceptEdits` auto-approves edits only. A terminal command — the git
+                // scan, the journal helper — then hits an approval gate with no human
+                // attached, and grok cancels the whole run: `stopReason: cancelled,
+                // cancellationCategory: PermissionCancelled`. Unattended approval plus
+                // a sandbox is the same posture codex gets from `-s workspace-write`.
+                "--always-approve",
+                "--sandbox",
+                "workspace",
+                "--max-turns",
+                GROK_SIBLING_MAX_TURNS,
+            ];
+        case "codex":
+            return [
+                "exec",
+                "--skip-git-repo-check",
+                "-s",
+                "workspace-write",
+                "--dangerously-bypass-hook-trust",
+                "-m",
+                CODEX_SIBLING_MODEL,
+                "-c",
+                `model_reasoning_effort=${CODEX_SIBLING_REASONING_EFFORT}`,
+                prompt,
+            ];
     }
-    return value;
 }
-function siblingPayload(input, threadPath) {
+function siblingPayload(input, threadPath, backend) {
     return {
+        backend,
         summary: input.summary ?? "",
         files: input.files,
         learnings: input.learnings,
@@ -525,7 +665,7 @@ function startSibling(liveRoot, input, threadPath, backend) {
     const siblingRoot = path.join(liveRoot, "workspace", "checkpoints", "sibling");
     const pendingPath = path.join(siblingRoot, "pending.jsonl");
     const lockPath = path.join(stateDir, "checkpoint-sibling.lock");
-    const payload = siblingPayload(input, threadPath);
+    const payload = siblingPayload(input, threadPath, backend);
     const activePid = existingSiblingPid(lockPath, Date.now());
     fs.mkdirSync(siblingRoot, { recursive: true });
     if (activePid !== null) {
@@ -542,29 +682,7 @@ function startSibling(liveRoot, input, threadPath, backend) {
     fs.writeFileSync(path.join(runDir, "prompt.md"), prompt);
     const logPath = path.join(runDir, "run.log");
     const logFd = fs.openSync(logPath, "a");
-    const args = backend === "claude"
-        ? [
-            "-p",
-            prompt,
-            "--model",
-            CLAUDE_SIBLING_MODEL,
-            "--effort",
-            CLAUDE_SIBLING_EFFORT,
-            "--permission-mode",
-            "acceptEdits",
-        ]
-        : [
-            "exec",
-            "--skip-git-repo-check",
-            "-s",
-            "workspace-write",
-            "--dangerously-bypass-hook-trust",
-            "-m",
-            CODEX_SIBLING_MODEL,
-            "-c",
-            `model_reasoning_effort=${CODEX_SIBLING_REASONING_EFFORT}`,
-            prompt,
-        ];
+    const args = siblingArgs(backend, prompt);
     let child;
     try {
         child = spawn(backend, args, {
@@ -587,7 +705,10 @@ function startSibling(liveRoot, input, threadPath, backend) {
     if (!child.pid)
         throw new Error("checkpoint: sibling did not return a PID");
     fs.writeFileSync(lockPath, String(child.pid));
-    printResult(`checkpoint: sibling started (pid ${child.pid})`);
+    // Recorded per run so a later checkpoint can tell "died without a report"
+    // apart from "still working" without consulting the shared lock.
+    fs.writeFileSync(path.join(runDir, "sibling.pid"), String(child.pid));
+    printResult(`checkpoint: sibling started (${backend}, pid ${child.pid})`);
 }
 function hasGateProbeConflict(options, command) {
     return [
@@ -641,7 +762,7 @@ function runCheckpoint(options, command, group) {
     if (!input.summary?.trim()) {
         usage("checkpoint: --summary is required unless --idle or --gate-probe is used");
     }
-    const backend = resolveBackend(options.backend);
+    const backend = resolveBackend(options.backend, liveRoot);
     const now = new Date();
     const threadId = `T-${formatTimestamp(now)}-auto-${summarySlug(input.summary)}`;
     const threadPath = path.join(liveRoot, "workspace", "threads", `${threadId}.json`);
@@ -730,7 +851,7 @@ export function registerCoreCheckpointCommand(core) {
         .option("--payload <file|->", "JSON payload file, or - for stdin")
         .option("--idle", "touch stamps without a checkpoint")
         .option("--no-agent", "do not spawn the maintenance sibling")
-        .option("--backend <auto|claude|codex|none>", "sibling backend", "auto")
+        .option("--backend <auto|claude|codex|grok|none>", "sibling backend", "auto")
         .option("--gate-probe", "write the local Stop-hook eligibility verdict")
         .option("--hq-root <path>", "HQ installation to operate on")
         .option("--dry-run", "print the planned checkpoint without writing")

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/commands/search.js

@@ -23,26 +23,38 @@ function relay(result) {
         process.stderr.write(result.stderr);
 }
 export function registerSearchCommand(program) {
-    const search = program.command('search').description('Search the local HQ qmd index');
-    search
-        .command('get <document>')
-        .description('Retrieve a qmd document by path or document id')
-        .option('-c, --collection <collection>', 'Restrict retrieval to a collection')
-        .action((document, options) => {
-        relay(runQmd(buildGetArgs(document, options)));
-    });
-    search
-        .command('<query>')
+    // The query is an ARGUMENT on `search` itself, not a subcommand. It was
+    // previously registered as `.command('<query>')`, which makes commander look
+    // for a subcommand literally named `<query>` — so every real query failed
+    // with "unknown command '<the query>'" and plain `hq search` never worked.
+    // Variadic so `hq search foo bar` needs no quoting; `search get` stays a
+    // subcommand and still wins when it is the first token.
+    const search = program
+        .command('search')
         .description('Search the local HQ qmd index')
+        .argument('[query...]', 'Query terms (joined with spaces)')
         .option('--mode <mode>', 'Search mode: keyword, semantic, or hybrid', 'keyword')
         .option('-c, --collection <collection>', 'Restrict search to a collection')
         .option('-n, --count <count>', 'Maximum result count', (value) => Number(value))
         .option('--json', 'Request machine-readable qmd output')
-        .action((query, options) => {
+        .action((queryParts = [], options) => {
+        const query = queryParts.join(' ').trim();
+        if (!query) {
+            search.outputHelp();
+            process.exitCode = 1;
+            return;
+        }
         if (!['keyword', 'semantic', 'hybrid'].includes(options.mode ?? 'keyword')) {
             throw new Error(`Unknown search mode '${options.mode}'. Expected keyword, semantic, or hybrid.`);
         }
         relay(runQmd(buildSearchArgs(query, options)));
     });
+    search
+        .command('get <document>')
+        .description('Retrieve a qmd document by path or document id')
+        .option('-c, --collection <collection>', 'Restrict retrieval to a collection')
+        .action((document, options) => {
+        relay(runQmd(buildGetArgs(document, options)));
+    });
 }
 //# sourceMappingURL=search.js.map

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

@@ -27,6 +27,7 @@ export type ResolveQmdBinOptions = {
     isExecutable?: (candidate: string) => boolean;
     packageBin?: () => string | undefined;
     pathBin?: () => string | undefined;
+    isUsable?: (bin: string) => boolean;
 };
 /**
  * Return the pinned package version when qmd is supplied by this CLI.

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

@@ -108,6 +108,27 @@ function pathBin() {
     }
     return undefined;
 }
+const usableQmdCache = new Map();
+/**
+ * Does this qmd binary actually run? `--version` is the cheapest subcommand
+ * that still loads the native module, which is exactly what fails when the
+ * bindings are missing. Cached per path so resolution stays a single spawn.
+ */
+function isUsableQmd(bin) {
+    const cached = usableQmdCache.get(bin);
+    if (cached !== undefined)
+        return cached;
+    let usable = false;
+    try {
+        const probe = spawnSync(bin, ['--version'], { encoding: 'utf8', timeout: 10_000 });
+        usable = !probe.error && probe.status === 0;
+    }
+    catch {
+        usable = false;
+    }
+    usableQmdCache.set(bin, usable);
+    return usable;
+}
 /** Resolve qmd without relying on a globally installed copy. */
 export function resolveQmdBin(options = {}) {
     const env = options.env ?? process.env;
@@ -123,12 +144,27 @@ export function resolveQmdBin(options = {}) {
         probes.push('HQ_QMD_BIN (not set)');
     }
     const installed = (options.packageBin ?? packageLocalBin)();
-    if (installed && executable(installed))
-        return installed;
-    probes.push(`package-local @tobilu/qmd (${installed ?? 'not found'})`);
     const onPath = (options.pathBin ?? pathBin)();
-    if (onPath && executable(onPath))
-        return onPath;
+    const fallback = onPath && executable(onPath) ? onPath : undefined;
+    if (installed && executable(installed)) {
+        // Executable is not the same as usable: a global install can ship a qmd
+        // whose native better-sqlite3 bindings were never compiled, so every
+        // invocation crashes. Preferring it blindly turned a dormant packaging
+        // problem into broken search on hosts that had a working qmd on PATH.
+        //
+        // The runnability probe costs a ~0.3s spawn, so only pay it when there is
+        // something to fall back TO. With no alternative the answer is the bundled
+        // binary either way, and a failure there now surfaces loudly rather than
+        // silently, so probing would buy nothing but latency on the hot path.
+        if (!fallback || (options.isUsable ?? isUsableQmd)(installed))
+            return installed;
+        probes.push(`package-local @tobilu/qmd (${installed}, present but not runnable)`);
+    }
+    else {
+        probes.push(`package-local @tobilu/qmd (${installed ?? 'not found'})`);
+    }
+    if (fallback)
+        return fallback;
     probes.push(`qmd on PATH (${onPath ?? 'not found'})`);
     throw new QmdBinaryMissingError(`Unable to resolve qmd. Probed ${probes.join('; ')}. Install @tobilu/qmd or set HQ_QMD_BIN to an executable qmd binary.`);
 }

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";
@@ -73,7 +74,7 @@ import { emitCliSessionStarted } from "./utils/cli-telemetry.js";
 import { settleWithin } from "./utils/settle-with-timeout.js";
 import { emitPlanLimitNag } from "./lib/plan-limit-nag.js";
 import { isPackageRootResolutionError, packageRootCaptureContext, } from "./utils/package-root-diagnostics.js";
-import { unexpectedCliErrorMessage } from "./utils/unexpected-cli-error.js";
+import { fallbackOperatorMessage, unexpectedCliErrorMessage } from "./utils/unexpected-cli-error.js";
 /** Hard upper bound for non-user-visible release-health finalization. */
 const RELEASE_HEALTH_SETTLE_TIMEOUT_MS = 3_000;
 // Swallow EPIPE when a downstream reader (e.g. `source <(…)`, `| head`) closes
@@ -343,14 +344,32 @@ 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);
-            const userMessage = unexpectedCliErrorMessage(err);
-            if (userMessage)
-                deps.stderr.write(`hq: ${userMessage}\n`);
+            // 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
+            // caller cannot distinguish from success. The fallback runs through the
+            // same redaction chain, so this widens visibility, not disclosure.
+            const userMessage = unexpectedCliErrorMessage(err) ?? fallbackOperatorMessage(err);
+            deps.stderr.write(`hq: ${userMessage}\n`);
         }
         deps.setExitCode(1);
     }

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