@indigoai-us/hq-cli 5.103.14 → 5.103.16

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## [Unreleased]
 
+## [5.103.16] — 2026-08-22
+
+## [5.103.15] — 2026-08-21
+
+### Fixed
+
+- The bundled sync engine now starts at `@indigoai-us/hq-cloud` 6.15.27, so
+  execution-time file decisions use fresh bytes, downloaded files immediately
+  journal their cloud hash, and unchanged local/cloud content no longer creates
+  false conflicts or gets uploaded again.
+
 ## [5.103.14] — 2026-08-21
 
 ### Fixed

package/dist/commands/integrations-core.d.ts

@@ -129,11 +129,22 @@ export declare class IntegrationsCliError extends Error {
      * surface the error instead of switching to the browser sign-in.
      */
     readonly oauthProtected?: boolean;
+    /**
+     * The gateway's numeric JSON-RPC error code (e.g. -32603, -32009), when the
+     * failure came back as a JSON-RPC error body. Read at the throw site for the
+     * `expected` decision and, previously, discarded there — now retained as a
+     * BOUNDED machine discriminator so an error that still reaches Sentry can be
+     * grouped by its protocol code (HQ-CLI collision, Sentry 7642756130). Like
+     * `code`, branch on THIS, never on the human message. It never reaches a
+     * fingerprint as anything but the finite allowlist in sentry-fingerprint.ts.
+     */
+    readonly rpcCode?: number;
     constructor(message: string, opts?: {
         expected?: boolean;
         code?: string;
         status?: number;
         oauthProtected?: boolean;
+        rpcCode?: number;
     });
 }
 /**

package/dist/commands/integrations-core.js

@@ -37,6 +37,16 @@ export class IntegrationsCliError extends Error {
      * surface the error instead of switching to the browser sign-in.
      */
     oauthProtected;
+    /**
+     * The gateway's numeric JSON-RPC error code (e.g. -32603, -32009), when the
+     * failure came back as a JSON-RPC error body. Read at the throw site for the
+     * `expected` decision and, previously, discarded there — now retained as a
+     * BOUNDED machine discriminator so an error that still reaches Sentry can be
+     * grouped by its protocol code (HQ-CLI collision, Sentry 7642756130). Like
+     * `code`, branch on THIS, never on the human message. It never reaches a
+     * fingerprint as anything but the finite allowlist in sentry-fingerprint.ts.
+     */
+    rpcCode;
     constructor(message, opts = {}) {
         super(message);
         this.name = "IntegrationsCliError";
@@ -47,6 +57,8 @@ export class IntegrationsCliError extends Error {
             this.status = opts.status;
         if (opts.oauthProtected !== undefined)
             this.oauthProtected = opts.oauthProtected;
+        if (opts.rpcCode !== undefined)
+            this.rpcCode = opts.rpcCode;
     }
 }
 /**
@@ -281,7 +293,12 @@ export async function callGateway(token, params) {
     if (!res.ok || !message) {
         raiseIfUnauthorized(res);
         raiseIfUpstreamUnavailable(res);
-        throw new IntegrationsCliError(`Integration gateway request failed (HTTP ${res.status}).`, { expected: isClientError(res.status) });
+        // Carry the HTTP status so a reportable transport failure (e.g. a 501 that
+        // is neither 401 nor an upstream-availability status, so it is captured)
+        // reaches the Sentry fingerprint's HTTP bucket instead of colliding under
+        // default grouping. Same reasoning as raiseForResponse, which already sets
+        // `status`. This does not change the `expected` decision above.
+        throw new IntegrationsCliError(`Integration gateway request failed (HTTP ${res.status}).`, { expected: isClientError(res.status), status: res.status });
     }
     if (message.error) {
         // The gateway's error text is minted UPSTREAM (hq-pro, the integration
@@ -293,7 +310,13 @@ export async function callGateway(token, params) {
         // 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) });
+            "Integration gateway returned an error.", {
+            expected: isExpectedGatewayError(message.error.code),
+            // Carry the protocol code to the capture site as a bounded grouping
+            // discriminator (HQ-CLI collision, Sentry 7642756130). This does not
+            // alter the `expected` decision above; it only labels the error.
+            ...(message.error.code !== undefined ? { rpcCode: message.error.code } : {}),
+        });
     }
     return message;
 }

package/dist/sentry.js

@@ -6,6 +6,7 @@ import { CLI_VERSION } from "./cli-version.js";
 import { getCachedSentryUser } from "./utils/sentry-identity.js";
 import { isEpipe } from "./utils/epipe.js";
 import { environmentalFsErrorMessage } from "./utils/environmental-error.js";
+import { sentryFingerprintFor } from "./utils/sentry-fingerprint.js";
 /**
  * Drop broken-pipe (EPIPE) crashes before scrubbing/send. A closed downstream
  * reader (`hq … | head`, `source <(hq …)`, a parent that exited) is normal
@@ -30,6 +31,18 @@ export function epipeAwareBeforeSend(event, hint) {
     // route, while the CLI still exits non-zero. HQ-CLI-R (Sentry 7671416365).
     if (environmentalFsErrorMessage(hint?.originalException))
         return null;
+    // Group an event that survives to send by a BOUNDED machine discriminator so
+    // unrelated gateway/HTTP failures stop colliding into one fungible issue
+    // (HQ-CLI collision, Sentry 7642756130). Placed here — path-independent,
+    // before the fleet scrubber — so it covers EVERY capture route (the top-level
+    // boundary, the command-level captureException sites, bin/hq-auth-refresh,
+    // any uncaughtException), mirroring the EPIPE and environmental-fs drops
+    // above. The classifier reads only a closed allowlist (never message/argv),
+    // and returns null for anything it cannot bound, in which case Sentry's
+    // default grouping is left untouched.
+    const fingerprint = sentryFingerprintFor(hint?.originalException);
+    if (fingerprint)
+        event.fingerprint = fingerprint;
     return beforeSend(event, hint);
 }
 export function initSentry() {

package/dist/utils/sentry-fingerprint.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Return a bounded `event.fingerprint` array for `err`, or `null` when `err`
+ * carries no discriminator from the closed allowlist (in which case the caller
+ * must leave the fingerprint unset so Sentry's default grouping applies).
+ *
+ * The shape is always `[DEFAULT_GROUPING, errorName, discriminator]`:
+ *   - a numeric `rpcCode` (only the gateway's IntegrationsCliError carries one)
+ *     yields `rpc:<code>` for a known code, else `rpc:other`;
+ *   - otherwise a numeric HTTP `status` yields `http:<status>` for a known
+ *     status, else `http:other`.
+ *
+ * `rpcCode` is checked first so a gateway JSON-RPC fault groups by its protocol
+ * code; the two carriers are disjoint in practice (the JSON-RPC throw site sets
+ * only `rpcCode`, the REST throw sites set only `status`).
+ */
+export declare function sentryFingerprintFor(err: unknown): string[] | null;
+//# sourceMappingURL=sentry-fingerprint.d.ts.map

package/dist/utils/sentry-fingerprint.js

@@ -0,0 +1,118 @@
+// src/utils/sentry-fingerprint.ts
+//
+// Compute a BOUNDED Sentry grouping fingerprint from an error, using only a
+// CLOSED allowlist of enumerable discriminators — never any upstream- or
+// user-minted text. Sibling in spirit to qmd-collection-missing-error.ts
+// (HQ-CLI-S): the same unbounded-fingerprint discipline, applied to grouping
+// instead of to a printed line.
+//
+// HQ-CLI collision (Sentry 7642756130): hq-cli captures every unclassified
+// error with a bare `captureException(err)` and sets no `event.fingerprint`
+// anywhere, so Sentry falls back to grouping on the exception type plus the
+// bundled `callGateway` culprit frame — which is IDENTICAL for unrelated
+// gateway failures. Two disjoint defects (a July confirm-queue enqueue fault
+// and an August remote-MCP HTTP 403) therefore landed in ONE issue, and the
+// issue's title silently rewrote itself to the latest event. That fungible
+// bucket destroys the regression watermark for every lane keyed on the issue.
+//
+// The remedy is a client-side fingerprint that SPLITS by a bounded machine
+// discriminator while preserving Sentry's default grouping. The returned array
+// leads with the `{{ default }}` placeholder (Sentry expands it to the normal
+// stack-based grouping hash) and appends the error's own name plus a single
+// discriminator token drawn from a finite set — so genuinely different failure
+// classes form distinct, PREDICTABLE groups, and everything else is left to
+// default grouping untouched.
+//
+// Two hard rules, mirroring HQ-CLI-S:
+//   1. CLOSED ALLOWLIST. The discriminator is one of a finite set of known
+//      JSON-RPC codes / HTTP statuses, or the literal `rpc:other` / `http:other`
+//      bucket. Total cardinality is therefore bounded — an over-wide key that
+//      minted a brand-new permanent issue per invocation is impossible.
+//   2. NO FREE TEXT. Only the error's `name` (a class identifier), a numeric
+//      `rpcCode`, and a numeric HTTP `status` are read. `message`, argv, URLs,
+//      connection ids, company slugs and any other upstream/user text can NEVER
+//      reach the fingerprint, so the key cannot be inflated by input.
+//
+// An error that carries no bounded discriminator returns `null`: the caller
+// leaves `event.fingerprint` unset and Sentry keeps its DEFAULT grouping, so the
+// blast radius of this change is limited to gateway- and HTTP-typed failures.
+/**
+ * The finite set of JSON-RPC error codes the integration gateway is known to
+ * mint (hq-pro's `IntegrationMcpError` → code map plus the JSON-RPC reserved
+ * range it uses): PARSE_ERROR (-32700), METHOD_NOT_FOUND (-32601),
+ * INVALID_PARAMS (-32602), INTERNAL_ERROR (-32603), UNAUTHORIZED (-32003),
+ * CONFLICT (-32009, also raised for a confirm queue being unavailable), and
+ * PROVIDER_ERROR (-32050). Anything outside this set collapses to `rpc:other`.
+ */
+const KNOWN_JSONRPC_CODES = new Set([
+    -32700, -32601, -32602, -32603, -32003, -32009, -32050,
+]);
+/**
+ * The finite set of HTTP statuses worth their own group. Any other numeric
+ * status collapses to `http:other`, so the bucket count stays bounded no matter
+ * what an upstream returns.
+ */
+const KNOWN_HTTP_STATUSES = new Set([
+    400, 401, 403, 404, 405, 408, 409, 410, 422, 429,
+    500, 501, 502, 503, 504,
+]);
+/** Sentry's placeholder for "keep the normal, stack-based grouping too". */
+const DEFAULT_GROUPING = "{{ default }}";
+/**
+ * The CLOSED set of error class names allowed to appear VERBATIM in a
+ * fingerprint. This hook runs on every capture route and accepts `unknown`, so
+ * a status-bearing error whose `name` is dynamic — an upstream error TYPE, or a
+ * request identifier spliced into the name — could otherwise mint an unbounded
+ * number of groups DESPITE the bounded discriminator. The finite-cardinality
+ * promise must hold for the WHOLE key, so any name outside this set collapses to
+ * FALLBACK_ERROR_NAME. The only first-party error carrying `rpcCode`/`status`
+ * is IntegrationsCliError; add a name here only when a new bounded carrier
+ * genuinely warrants its own family of groups.
+ */
+const KNOWN_ERROR_NAMES = new Set(["IntegrationsCliError"]);
+/** Fixed bucket for any error name outside the closed allowlist. */
+const FALLBACK_ERROR_NAME = "other";
+/**
+ * Return a bounded `event.fingerprint` array for `err`, or `null` when `err`
+ * carries no discriminator from the closed allowlist (in which case the caller
+ * must leave the fingerprint unset so Sentry's default grouping applies).
+ *
+ * The shape is always `[DEFAULT_GROUPING, errorName, discriminator]`:
+ *   - a numeric `rpcCode` (only the gateway's IntegrationsCliError carries one)
+ *     yields `rpc:<code>` for a known code, else `rpc:other`;
+ *   - otherwise a numeric HTTP `status` yields `http:<status>` for a known
+ *     status, else `http:other`.
+ *
+ * `rpcCode` is checked first so a gateway JSON-RPC fault groups by its protocol
+ * code; the two carriers are disjoint in practice (the JSON-RPC throw site sets
+ * only `rpcCode`, the REST throw sites set only `status`).
+ */
+export function sentryFingerprintFor(err) {
+    if (err === null || typeof err !== "object")
+        return null;
+    const record = err;
+    // The error's class identifier for the fingerprint's middle component. A name
+    // is required (so the key has a stable label), but it is bounded to the closed
+    // allowlist: a recognized class keeps its name, anything else collapses to the
+    // fixed FALLBACK_ERROR_NAME bucket so a dynamic name cannot inflate the key.
+    const rawName = typeof record.name === "string" && record.name.length > 0 ? record.name : null;
+    if (rawName === null)
+        return null;
+    const name = KNOWN_ERROR_NAMES.has(rawName) ? rawName : FALLBACK_ERROR_NAME;
+    const rpcCode = record.rpcCode;
+    if (typeof rpcCode === "number" && Number.isInteger(rpcCode)) {
+        const discriminator = KNOWN_JSONRPC_CODES.has(rpcCode)
+            ? `rpc:${rpcCode}`
+            : "rpc:other";
+        return [DEFAULT_GROUPING, name, discriminator];
+    }
+    const status = record.status;
+    if (typeof status === "number" && Number.isInteger(status)) {
+        const discriminator = KNOWN_HTTP_STATUSES.has(status)
+            ? `http:${status}`
+            : "http:other";
+        return [DEFAULT_GROUPING, name, discriminator];
+    }
+    return null;
+}
+//# sourceMappingURL=sentry-fingerprint.js.map

package/package.json

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