@indigoai-us/hq-cli 5.314.0 → 5.316.0

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

@@ -1,13 +1,35 @@
+export interface SentryMcpCollisionContext {
+    tags: {
+        mcp_client: "codex";
+        server_name: string;
+        existing_entry_owner: "hq" | "foreign" | "unknown";
+        diff_fields: string;
+    };
+    fingerprint: string[];
+}
+/** Return bounded, value-free Sentry context for an instrumented Codex name collision. */
+export declare function sentryMcpCollisionContextFor(err: unknown): SentryMcpCollisionContext | null;
+/**
+ * Bounded, aggregatable tags for an unrecovered install-tree failure. Phase,
+ * outcome, state, and OS are closed values. Paths and raw lock-tool strings stay
+ * in context; only a known updater source becomes a tag.
+ */
+export declare function installTreeTornSentryTagsFor(err: unknown): Record<string, string> | null;
 /**
  * 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]`:
+ * 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.
  *
  * `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

@@ -1,8 +1,8 @@
 // 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
+// Compute a BOUNDED Sentry grouping fingerprint from an error, using only
+// closed discriminators and a fixed Codex collision bucket, never arbitrary
+// 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.
 //
@@ -16,22 +16,45 @@
 // 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>"]. This PR keeps
+//     the existing explicit key so the new stale-tree outcome extends the current
+//     groups without splitting them.
+//
+// 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
-//      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.
+//   1. BOUNDED DISCRIMINATORS. RPC/HTTP values use closed allowlists and
+//      fallback buckets. Codex collisions use one fixed client bucket. The
+//      server-name tag is restricted to 64 lowercase letters, digits,
+//      underscores or hyphens; other names share one fallback value. Owner and
+//      field tags also use closed sets.
+//   2. NO FREE TEXT. Error messages, argv, URLs, connection ids, company slugs,
+//      config values and paths never reach a fingerprint or tags. The Codex
+//      branch uses a fixed fingerprint and bounded diagnostic tags.
 //
 // An error that carries no bounded discriminator returns `null`: the caller
 // leaves `event.fingerprint` unset and Sentry keeps its DEFAULT grouping, so the
@@ -58,6 +81,48 @@ const KNOWN_HTTP_STATUSES = new Set([
 ]);
 /** Sentry's placeholder for "keep the normal, stack-based grouping too". */
 const DEFAULT_GROUPING = "{{ default }}";
+const CODEX_COLLISION_NAME_RE = /^[a-z0-9_-]{1,64}$/;
+const CODEX_COLLISION_OWNERS = new Set(["hq", "foreign", "unknown"]);
+const CODEX_COLLISION_FIELDS = new Set(["command", "args", "env", "url", "other"]);
+function isCodexCollisionOwner(value) {
+    return typeof value === "string" && CODEX_COLLISION_OWNERS.has(value);
+}
+/** Return bounded, value-free Sentry context for an instrumented Codex name collision. */
+export function sentryMcpCollisionContextFor(err) {
+    if (err === null || typeof err !== "object")
+        return null;
+    const record = err;
+    if (record.name !== "McpNameCollisionError" || record.code !== "McpNameCollisionError") {
+        return null;
+    }
+    const diagnostics = record.codexDiagnostics;
+    if (diagnostics === null || typeof diagnostics !== "object")
+        return null;
+    const context = diagnostics;
+    const owner = context.existingEntryOwner;
+    if (context.client !== "codex" ||
+        typeof context.serverName !== "string" ||
+        !isCodexCollisionOwner(owner) ||
+        !Array.isArray(context.diffFields) ||
+        context.diffFields.length === 0 ||
+        context.diffFields.length > CODEX_COLLISION_FIELDS.size ||
+        !context.diffFields.every((field) => typeof field === "string" && CODEX_COLLISION_FIELDS.has(field))) {
+        return null;
+    }
+    const fields = [...new Set(context.diffFields)].sort();
+    const serverName = CODEX_COLLISION_NAME_RE.test(context.serverName)
+        ? context.serverName
+        : "other";
+    return {
+        tags: {
+            mcp_client: "codex",
+            server_name: serverName,
+            existing_entry_owner: owner,
+            diff_fields: fields.join(","),
+        },
+        fingerprint: ["mcp-name-collision", "codex"],
+    };
+}
 /**
  * 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
@@ -92,18 +157,124 @@ const KNOWN_ERROR_NAMES = new Set([
     // (HQ-CLI-1A).
     "QmdWorkdirMissingError",
     // A torn-install failure the bounded settle-wait + single re-exec could not
-    // recover (HQ-CLI-1G/1H/1J/1K). Fingerprinted on its own branch below by the
-    // bounded `diagnostics.outcome`, so the whole family groups into ≤3 issues.
+    // recover (HQ-CLI-1G/1H/1J/1K, HQ-CLI-1Y). Fingerprinted on its own branch below
+    // by the normalized recovery result, so the family groups into two stable buckets.
     "InstallTreeTornError",
 ]);
 /**
- * The CLOSED set of InstallTreeTornError recovery outcomes worth their own
- * group. Anything else collapses to `outcome:other`, so the axis stays finite;
- * the carrier's message is fixed, so this outcome IS the only discriminator.
+ * The closed loader dialects accepted for the install_tree_phase tag. Anything
+ * outside this set collapses to unknown, so tags stay safe to aggregate.
  */
+const INSTALL_TREE_PHASES = new Set([
+    "cjs-enoent",
+    "cjs-package",
+    "cjs-path",
+    "cjs-relative",
+    "esm-enoent",
+    "esm-package",
+    "esm-path",
+    "eval-throw",
+    "resolve-enoent",
+    "unknown",
+]);
+const KNOWN_INSTALL_TREE_UPDATERS = new Map([
+    ["hq-cli-self-update", "cli-self-update"],
+    ["hq-cli-update", "box-timer"],
+    ["hq-cli-version-gate", "cli-version-gate"],
+    ["hq-desktop-app-cli-update", "desktop-app"],
+]);
 const KNOWN_INSTALL_TREE_OUTCOMES = new Set([
-    "guarded", "unsettled", "reexec-failed",
+    "guarded",
+    "unsettled",
+    "reexec-failed",
+    "lock-held",
+    "stale_tree",
+    "retired_unverified",
 ]);
+function installTreeRecoveryOutcomeTag(value) {
+    return typeof value === "string" && KNOWN_INSTALL_TREE_OUTCOMES.has(value)
+        ? value
+        : null;
+}
+function installTreeStateTag(value) {
+    return value === "stale" ? "stale" : "in_flight";
+}
+function installTreePhaseTag(value) {
+    if (typeof value !== "string" || !INSTALL_TREE_PHASES.has(value))
+        return "unknown";
+    if (value === "esm-enoent" || value === "cjs-enoent")
+        return "loader_read";
+    if (value === "eval-throw")
+        return "module_evaluation";
+    if (value === "esm-package" || value === "cjs-package")
+        return "package_resolution";
+    if (value === "unknown")
+        return "unknown";
+    return "path_resolution";
+}
+function installTreeOsTag(platform) {
+    if (platform === "win32")
+        return "windows";
+    if (platform === "darwin")
+        return "macos";
+    if (platform === "linux")
+        return "linux";
+    return "other";
+}
+/**
+ * Bounded, aggregatable tags for an unrecovered install-tree failure. Phase,
+ * outcome, state, and OS are closed values. Paths and raw lock-tool strings stay
+ * in context; only a known updater source becomes a tag.
+ */
+export function installTreeTornSentryTagsFor(err) {
+    if (err === null || typeof err !== "object")
+        return null;
+    const record = err;
+    if (record.name !== "InstallTreeTornError")
+        return null;
+    const diagnostics = record.diagnostics !== null && typeof record.diagnostics === "object"
+        ? record.diagnostics
+        : {};
+    const recoveryOutcome = installTreeRecoveryOutcomeTag(diagnostics.outcome);
+    const tags = {
+        install_tree_phase: installTreePhaseTag(diagnostics.dialect),
+        tree_state: installTreeStateTag(diagnostics.treeState),
+        os: installTreeOsTag(process.platform),
+    };
+    if (diagnostics.code === "ERR_MODULE_NOT_FOUND" || diagnostics.code === "MODULE_NOT_FOUND") {
+        tags.error_shape = "module_not_found";
+    }
+    else if (diagnostics.code === "ENOENT") {
+        tags.error_shape = "loader_enoent";
+    }
+    if (typeof diagnostics.retiredSiblingPresent === "boolean") {
+        tags.retired_sibling = diagnostics.retiredSiblingPresent ? "present" : "absent";
+    }
+    const retiredSiblingKind = diagnostics.retiredSiblingKind;
+    tags.retired_sibling_kind = typeof retiredSiblingKind === "string" &&
+        ["npm_hash_retired", "hq_staging", "hq_backup", "other", "unknown"].includes(retiredSiblingKind)
+        ? retiredSiblingKind
+        : "unknown";
+    const targetState = diagnostics.installTargetState;
+    tags.install_target_state = typeof targetState === "string" &&
+        ["missing", "manifest_valid", "manifest_invalid", "unreadable", "unknown"].includes(targetState)
+        ? targetState
+        : "unknown";
+    const gatePhase = diagnostics.versionGatePhase;
+    tags.version_gate_phase = typeof gatePhase === "string" &&
+        ["preflight", "lock_acquired", "installer_running", "verifying", "rollback", "complete", "failed", "unknown"].includes(gatePhase)
+        ? gatePhase
+        : "unknown";
+    const pidAlive = diagnostics.updaterPidAlive;
+    tags.updater_pid_alive = pidAlive === "true" || pidAlive === "false" ? pidAlive : "unknown";
+    if (recoveryOutcome)
+        tags.recovery_outcome = recoveryOutcome;
+    const lockTool = diagnostics.lockTool;
+    const updaterSource = typeof lockTool === "string" ? KNOWN_INSTALL_TREE_UPDATERS.get(lockTool) : undefined;
+    if (updaterSource)
+        tags.updater_source = updaterSource;
+    return tags;
+}
 /** Fixed bucket for any error name outside the closed allowlist. */
 const FALLBACK_ERROR_NAME = "other";
 /**
@@ -169,11 +340,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.
  *
  * `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
@@ -190,6 +366,9 @@ export function sentryFingerprintFor(err) {
     const rawName = typeof record.name === "string" && record.name.length > 0 ? record.name : null;
     if (rawName === null)
         return null;
+    const mcpCollision = sentryMcpCollisionContextFor(record);
+    if (mcpCollision)
+        return mcpCollision.fingerprint;
     // qmd process failures carry a PROCESS EXIT CODE in `status` (never an HTTP
     // status) plus a subcommand in args[0]. Fingerprint them on a dedicated,
     // fully-bounded key BEFORE the HTTP-status branch so an exit code is never read
@@ -213,18 +392,31 @@ 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 ≤3 predictable
-    // issues (guarded / unsettled / reexec-failed) rather than one fungible bucket.
+    // only bounded discriminator is the existing recovery outcome. Keyed
+    // BEFORE the rpc/status branches so the family groups into a bounded set of
+    // predictable issues 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 recovery outcome, independent of machine, install path and module.
     if (rawName === "InstallTreeTornError") {
         const diagnostics = record.diagnostics;
         const outcome = diagnostics !== null && typeof diagnostics === "object"
             ? diagnostics.outcome
             : undefined;
-        const token = typeof outcome === "string" && KNOWN_INSTALL_TREE_OUTCOMES.has(outcome)
-            ? `outcome:${outcome}`
-            : "outcome:other";
-        return [DEFAULT_GROUPING, "InstallTreeTornError", token];
+        return [
+            "InstallTreeTornError",
+            `outcome:${installTreeRecoveryOutcomeTag(outcome) ?? "other"}`,
+        ];
     }
     const name = KNOWN_ERROR_NAMES.has(rawName) ? rawName : FALLBACK_ERROR_NAME;
     const rpcCode = record.rpcCode;

package/dist/utils/staged-install.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Staged npm self-update: install the new hq-cli beside the running package,
+ * check that it starts, then swap it in with two renames.
+ *
+ * The in-place update moves the live package aside for the whole
+ * `npm install -g`, so anything that starts `hq` during the install finds no
+ * CLI on disk ("hq: command not found", MODULE_NOT_FOUND; outposts primary and
+ * 2, 5.290.0 -> 5.291.0). Here the live package stays in place until the new
+ * one is complete and has answered `--version`.
+ *
+ * Only a plain npm global layout is staged: `<prefix>/lib/node_modules/<pkg>`
+ * as a real directory, with bin links in `<prefix>/bin`. pnpm, Bun, Windows
+ * and linked checkouts keep the in-place update.
+ */
+import * as fs from "node:fs";
+import { type RunningInstall, type UpdateResult } from "./version-gate.js";
+/** Set for the staging install; hq-cli's own postinstall skips itself on it. */
+export declare const STAGED_INSTALL_ENV = "HQ_STAGED_INSTALL";
+export interface StagedInstallDeps {
+    /** Runs the package manager. Defaults to {@link runUpdateCommand}. */
+    run?: (cmd: string, args: string[], env?: NodeJS.ProcessEnv) => UpdateResult;
+    env?: NodeJS.ProcessEnv;
+    /** The version the staged package's `hq --version` reports, or null. */
+    probeVersion?: (packageRoot: string) => string | null;
+    /** The package's postinstall, run from the live path after the swap. */
+    runPostinstall?: (packageRoot: string) => void;
+    rename?: typeof fs.renameSync;
+    /** Removes the staging and backup directories. */
+    remove?: (target: string) => void;
+    platform?: NodeJS.Platform;
+}
+export declare function canStageInstall(install: RunningInstall, platform?: NodeJS.Platform): boolean;
+export declare function stagedNpmInstall(install: RunningInstall, version: string, deps?: StagedInstallDeps): UpdateResult;
+//# sourceMappingURL=staged-install.d.ts.map