@indigoai-us/hq-cli 5.109.13 → 5.109.14

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## [Unreleased]
 
+## [5.109.14] — 2026-09-13
+
+### Fixed
+
+- Repeated "install tree was being rewritten" reports from a background reinstall
+  now collapse into one stable issue per outcome instead of spawning a fresh crash
+  report on every occurrence (Sentry HQ-CLI-21, HQ-CLI-22, HQ-CLI-23). hq already
+  groups these by their recovery outcome, but the grouping key led with a
+  placeholder that also told Sentry to fold in its own default grouping — and for
+  this error that default is the underlying loader failure, whose details differ
+  every time (which dependency file the reinstall happened to be rewriting, under
+  each machine's install path). So each occurrence minted a new issue and the
+  family never settled down. The key is now fully explicit and no longer inherits
+  that default, so future occurrences with the same outcome share one group. The
+  existing issues HQ-CLI-21/22/23 stay open as they are: a grouping change only
+  affects events reported after it ships.
+
 ## [5.109.13] — 2026-09-13
 
 ### Fixed

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

@@ -3,11 +3,16 @@
  * 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]`:
+ * For the rpc/http carriers the shape is `[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`.
+ * The InstallTreeTornError branch is the deliberate exception: it returns a
+ * fully explicit `["InstallTreeTornError", "outcome:<token>"]` with NO
+ * DEFAULT_GROUPING lead, because its chained loader cause makes the default
+ * component unbounded (see the module header — HQ-CLI-21/22/23).
  *
  * `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

package/dist/utils/sentry-fingerprint.js

@@ -16,12 +16,33 @@
 // 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.
+// discriminator. Two shapes are used, and the difference between them is
+// load-bearing — it is the lesson HQ-CLI-21/22/23 taught:
+//
+//   - MOST branches (qmd, rpc, http) LEAD the array with the `{{ default }}`
+//     placeholder, then append the error's own name plus one discriminator token
+//     from a finite set. Sentry expands `{{ default }}` into the event's default
+//     grouping component and SALTS the appended tokens with it, so the key is only
+//     as bounded as that default component. For those carriers that is fine: they
+//     are thrown from hq-cli's own code with no chained third-party cause, so
+//     their default component is itself bounded.
+//
+//   - The InstallTreeTornError branch must NOT lead with the placeholder. Its
+//     carrier wraps a CHAINED loader failure whose stack differs on every
+//     occurrence — whichever dependency file a concurrent global reinstall was
+//     mid-rewrite, under each machine's absolute install path — so its default
+//     component is UNBOUNDED. Leading with `{{ default }}` salted the bounded
+//     `outcome:` key with that unbounded component and minted a brand-new Sentry
+//     issue per occurrence: three events carrying the byte-identical array
+//     ["{{ default }}", "InstallTreeTornError", "outcome:unsettled"] still landed
+//     in three different groups (hashes a4289a5e530e166ebdedea9d34dcad0a,
+//     b563c1b891bd975bdc605efc86034b44, b4ee254473ea249758617de1a98848fa —
+//     HQ-CLI-21/22/23). So that branch returns a FULLY EXPLICIT key with no
+//     default lead: ["InstallTreeTornError", "outcome:<token>"].
+//
+// Genuinely different failure classes therefore form distinct, PREDICTABLE
+// groups, and everything with no bounded discriminator 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
@@ -169,11 +190,16 @@ function qmdDispositionToken(status, signal) {
  * 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]`:
+ * For the rpc/http carriers the shape is `[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`.
+ * The InstallTreeTornError branch is the deliberate exception: it returns a
+ * fully explicit `["InstallTreeTornError", "outcome:<token>"]` with NO
+ * DEFAULT_GROUPING lead, because its chained loader cause makes the default
+ * component unbounded (see the module header — HQ-CLI-21/22/23).
  *
  * `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
@@ -214,8 +240,22 @@ export function sentryFingerprintFor(err) {
     }
     // A torn-install failure carries neither an rpcCode nor an HTTP status; its
     // only bounded discriminator is the recovery `diagnostics.outcome`. Keyed
-    // BEFORE the rpc/status branches so the family groups into ≤4 predictable issues
-    // (guarded / unsettled / reexec-failed / lock-held) rather than one fungible bucket.
+    // BEFORE the rpc/status branches so the family groups into a bounded set of
+    // predictable issues (guarded / unsettled / reexec-failed / lock-held, plus the
+    // `outcome:other` fallback) rather than one fungible bucket.
+    //
+    // The key is FULLY EXPLICIT — it does NOT lead with DEFAULT_GROUPING. Leading
+    // with the placeholder salts the appended tokens with Sentry's default grouping
+    // component, and THIS carrier's default component is UNBOUNDED: it wraps a
+    // chained loader cause whose stack differs on every occurrence (the dependency
+    // file a concurrent global reinstall was mid-rewrite, under each machine's
+    // absolute install path). With the placeholder lead, three events carrying the
+    // byte-identical array ["{{ default }}", "InstallTreeTornError",
+    // "outcome:unsettled"] still split into three Sentry groups —
+    // a4289a5e530e166ebdedea9d34dcad0a, b563c1b891bd975bdc605efc86034b44 and
+    // b4ee254473ea249758617de1a98848fa (HQ-CLI-21/22/23) — defeating the very bound
+    // this branch exists to enforce. The explicit key collapses them to one stable
+    // group per outcome, independent of machine, install path and which module tore.
     if (rawName === "InstallTreeTornError") {
         const diagnostics = record.diagnostics;
         const outcome = diagnostics !== null && typeof diagnostics === "object"
@@ -224,7 +264,7 @@ export function sentryFingerprintFor(err) {
         const token = typeof outcome === "string" && KNOWN_INSTALL_TREE_OUTCOMES.has(outcome)
             ? `outcome:${outcome}`
             : "outcome:other";
-        return [DEFAULT_GROUPING, "InstallTreeTornError", token];
+        return ["InstallTreeTornError", token];
     }
     const name = KNOWN_ERROR_NAMES.has(rawName) ? rawName : FALLBACK_ERROR_NAME;
     const rpcCode = record.rpcCode;

package/package.json

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