@indigoai-us/hq-cli 5.50.1 → 5.51.0

package/src/commands/people.ts

@@ -14,9 +14,17 @@
 import * as fs from "fs";
 import { Command, Option } from "commander";
 import chalk from "chalk";
+import { VaultClient } from "@indigoai-us/hq-cloud";
 import * as yaml from "js-yaml";
 import { findHqRoot } from "../utils/manifest.js";
 import { manifestPath, type ManifestDoc } from "./cloud-provision.js";
+import {
+  DEFAULT_COGNITO,
+  buildVaultConfig,
+  ensureCognitoToken,
+} from "../utils/cognito-session.js";
+import { getCompanyUid } from "../utils/vault-api.js";
+import { createCompanyPresignClient, runGet } from "./files-browse.js";
 import {
   assertSafeCompanySlug,
   listCompanyPeople,
@@ -31,6 +39,39 @@ interface PeopleScopeOpts {
   hqRoot?: string;
 }
 
+export type RefreshPeopleRoster = (
+  hqRoot: string,
+  companySlug: string,
+) => Promise<void>;
+
+interface PeopleCommandDeps {
+  refreshRoster?: RefreshPeopleRoster;
+}
+
+interface PeopleLookupOpts {
+  localOnly?: boolean;
+  json?: boolean;
+}
+
+export async function refreshPeopleRosterFromCloud(
+  hqRoot: string,
+  companySlug: string,
+): Promise<void> {
+  const accessToken = await ensureCognitoToken();
+  const client = new VaultClient(buildVaultConfig(accessToken));
+  await getCompanyUid(accessToken, companySlug);
+
+  await runGet({
+    path: `companies/${companySlug}/people/`,
+    hqRoot,
+    companySlug,
+    vaultClient: client,
+    companyClient: ({ companyUid }) =>
+      createCompanyPresignClient({ token: accessToken, companyUid }),
+    region: DEFAULT_COGNITO.region,
+  });
+}
+
 /** Companies that still exist (anything not explicitly `status: archived`). */
 function activeCompanySlugs(manifest: ManifestDoc): string[] {
   const companies = manifest.companies ?? {};
@@ -118,7 +159,82 @@ function fail(message: string): never {
   process.exit(1);
 }
 
-export function registerPeopleCommand(program: Command): void {
+function logRefreshFailure(companySlug: string, err: unknown): void {
+  const message = err instanceof Error ? err.message : String(err);
+  console.error(
+    chalk.dim(
+      `  Could not refresh people roster for '${companySlug}': ${message}`,
+    ),
+  );
+}
+
+async function tryRefreshRoster(
+  refreshRoster: RefreshPeopleRoster,
+  hqRoot: string,
+  slug: string,
+): Promise<boolean> {
+  try {
+    await refreshRoster(hqRoot, slug);
+    return true;
+  } catch (err) {
+    logRefreshFailure(slug, err);
+    return false;
+  }
+}
+
+export async function resolvePersonWithRosterFallback(
+  input: {
+    hqRoot: string;
+    slug: string;
+    name: string;
+    opts?: PeopleLookupOpts;
+    refreshRoster?: RefreshPeopleRoster;
+  },
+): Promise<ReturnType<typeof resolveNameToEmail>> {
+  const local = resolveNameToEmail(
+    listCompanyPeople(input.hqRoot, input.slug),
+    input.name,
+  );
+  if (local.status !== "not_found" || input.opts?.localOnly) return local;
+
+  const refreshed = await tryRefreshRoster(
+    input.refreshRoster ?? refreshPeopleRosterFromCloud,
+    input.hqRoot,
+    input.slug,
+  );
+  if (!refreshed) return local;
+  return resolveNameToEmail(
+    listCompanyPeople(input.hqRoot, input.slug),
+    input.name,
+  );
+}
+
+export async function searchPeopleWithRosterFallback(input: {
+  hqRoot: string;
+  slug: string;
+  keyword: string;
+  opts?: PeopleLookupOpts;
+  refreshRoster?: RefreshPeopleRoster;
+}): Promise<PersonRecord[]> {
+  const local = searchPeople(
+    listCompanyPeople(input.hqRoot, input.slug),
+    input.keyword,
+  );
+  if (local.length > 0 || input.opts?.localOnly) return local;
+
+  const refreshed = await tryRefreshRoster(
+    input.refreshRoster ?? refreshPeopleRosterFromCloud,
+    input.hqRoot,
+    input.slug,
+  );
+  if (!refreshed) return local;
+  return searchPeople(listCompanyPeople(input.hqRoot, input.slug), input.keyword);
+}
+
+export function registerPeopleCommand(
+  program: Command,
+  deps: PeopleCommandDeps = {},
+): void {
   const people = program
     .command("people")
     .description(
@@ -170,12 +286,22 @@ export function registerPeopleCommand(program: Command): void {
     .command("search <keyword>")
     .description("Keyword search over people names and emails")
     .option("--json", "Output JSON instead of a table")
-    .action((keyword: string, opts: { json?: boolean }) => {
+    .option(
+      "--local-only",
+      "Skip cloud fallback; search only the local people roster",
+    )
+    .action(async (keyword: string, opts: PeopleLookupOpts) => {
       try {
         const scope = people.opts() as PeopleScopeOpts;
         const hqRoot = resolveHqRoot(scope);
         const slug = resolveCompanySlug(hqRoot, scope.company);
-        const matches = searchPeople(listCompanyPeople(hqRoot, slug), keyword);
+        const matches = await searchPeopleWithRosterFallback({
+          hqRoot,
+          slug,
+          keyword,
+          opts,
+          refreshRoster: deps.refreshRoster,
+        });
 
         if (opts.json) {
           console.log(JSON.stringify(matches, null, 2));
@@ -195,12 +321,22 @@ export function registerPeopleCommand(program: Command): void {
     .command("resolve <name>")
     .description("Resolve a person name to their email address")
     .option("--json", "Output JSON instead of plain text")
-    .action((name: string, opts: { json?: boolean }) => {
+    .option(
+      "--local-only",
+      "Skip cloud fallback; resolve only from the local people roster",
+    )
+    .action(async (name: string, opts: PeopleLookupOpts) => {
       try {
         const scope = people.opts() as PeopleScopeOpts;
         const hqRoot = resolveHqRoot(scope);
         const slug = resolveCompanySlug(hqRoot, scope.company);
-        const result = resolveNameToEmail(listCompanyPeople(hqRoot, slug), name);
+        const result = await resolvePersonWithRosterFallback({
+          hqRoot,
+          slug,
+          name,
+          opts,
+          refreshRoster: deps.refreshRoster,
+        });
 
         if (opts.json) {
           console.log(JSON.stringify(result, null, 2));

package/src/commands/secrets-scope.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  describeSecretsScope,
+  formatSecretSaved,
+  formatSecretsListEmpty,
+  formatSecretsListHeader,
+} from "./secrets-scope.js";
+
+describe("describeSecretsScope", () => {
+  it("describes the personal vault", () => {
+    expect(
+      describeSecretsScope({ personal: true, companyUid: "prs_alice" }),
+    ).toBe("your personal vault");
+  });
+
+  it("describes a company by slug when present", () => {
+    expect(
+      describeSecretsScope({
+        personal: false,
+        companySlug: "acme",
+        companyUid: "cmp_01ABC",
+      }),
+    ).toBe("company acme");
+  });
+
+  it("describes a company by uid when no slug is present", () => {
+    expect(
+      describeSecretsScope({ personal: false, companyUid: "cmp_01ABC" }),
+    ).toBe("company cmp_01ABC");
+  });
+});
+
+describe("formatSecretSaved", () => {
+  it("formats the set echo", () => {
+    expect(formatSecretSaved("MY_KEY", "your personal vault")).toBe(
+      "Secret 'MY_KEY' saved to your personal vault.",
+    );
+  });
+});
+
+describe("formatSecretsListHeader", () => {
+  it("formats the list header", () => {
+    expect(formatSecretsListHeader("company acme")).toBe(
+      "Secrets for company acme:",
+    );
+  });
+});
+
+describe("formatSecretsListEmpty", () => {
+  it("formats the empty list message", () => {
+    expect(formatSecretsListEmpty("your personal vault")).toBe(
+      "No secrets found for your personal vault.",
+    );
+  });
+});

package/src/commands/secrets-scope.ts

@@ -0,0 +1,32 @@
+/**
+ * Pure helpers describing WHICH secrets scope a command acted on, so `set` and
+ * `list` can echo it. Users were setting a secret in one scope (personal vs a
+ * company, or company A vs B) and listing another, then seeing "no secrets" with
+ * no indication the scopes differed (feedback_70e059da).
+ */
+export interface SecretsScopeRef {
+  /** True when --personal was used (caller's personal vault). */
+  personal: boolean;
+  /** The slug the user passed via --company, if any. */
+  companySlug?: string;
+  /** Resolved entity uid: prs_* for personal, cmp_* for a company. */
+  companyUid: string;
+}
+
+/** Human label for a secrets scope: "your personal vault" or "company <slug-or-uid>". */
+export function describeSecretsScope(ref: SecretsScopeRef): string {
+  if (ref.personal) return "your personal vault";
+  return `company ${ref.companySlug ?? ref.companyUid}`;
+}
+
+export function formatSecretSaved(name: string, scope: string): string {
+  return `Secret '${name}' saved to ${scope}.`;
+}
+
+export function formatSecretsListHeader(scope: string): string {
+  return `Secrets for ${scope}:`;
+}
+
+export function formatSecretsListEmpty(scope: string): string {
+  return `No secrets found for ${scope}.`;
+}

package/src/commands/secrets.ts

@@ -13,6 +13,12 @@ import {
 } from "../utils/secrets-cache.js";
 import { computeSha256 } from "../utils/integrity.js";
 import { SECRET_NAME_PATTERN, GROUP_ID_PATTERN } from "./_patterns.js";
+import {
+  describeSecretsScope,
+  formatSecretSaved,
+  formatSecretsListEmpty,
+  formatSecretsListHeader,
+} from "./secrets-scope.js";
 import {
   vaultApiFetch,
   getCompanyUid,
@@ -506,10 +512,13 @@ export function registerSecretsCommand(program: Command): void {
         }
 
         const token = await ensureCognitoToken();
-        const companyUid = await getEntityUid(
-          token,
-          scopeOpts(secrets.opts()),
-        );
+        const scope = scopeOpts(secrets.opts());
+        const companyUid = await getEntityUid(token, scope);
+        const scopeLabel = describeSecretsScope({
+          personal: scope.personal,
+          companySlug: scope.companySlug,
+          companyUid,
+        });
 
         const res = await vaultApiFetch({
           token,
@@ -527,7 +536,7 @@ export function registerSecretsCommand(program: Command): void {
         }
 
         removeCacheEntry(companyUid, name);
-        console.log(chalk.green(`Secret '${name}' saved.`));
+        console.log(chalk.green(formatSecretSaved(name, scopeLabel)));
       } catch (err) {
         console.error(
           chalk.red("Error:"),
@@ -703,10 +712,13 @@ export function registerSecretsCommand(program: Command): void {
         }
 
         const token = await ensureCognitoToken();
-        const companyUid = await getEntityUid(
-          token,
-          scopeOpts(secrets.opts()),
-        );
+        const scope = scopeOpts(secrets.opts());
+        const companyUid = await getEntityUid(token, scope);
+        const scopeLabel = describeSecretsScope({
+          personal: scope.personal,
+          companySlug: scope.companySlug,
+          companyUid,
+        });
 
         const query: Record<string, string> = {};
         if (normalizedPrefix) {
@@ -739,7 +751,7 @@ export function registerSecretsCommand(program: Command): void {
         };
 
         if (data.secrets.length === 0) {
-          console.log(chalk.dim("No secrets found."));
+          console.log(chalk.dim(formatSecretsListEmpty(scopeLabel)));
           return;
         }
 
@@ -756,6 +768,7 @@ export function registerSecretsCommand(program: Command): void {
         if (hasPermission) {
           const accessWidth = Math.max(6, ...data.secrets.map((s) => (s.permission ?? "-").length));
           const header = `${"NAME".padEnd(nameWidth)}  ${"ACCESS".padEnd(accessWidth)}  ${"TIER".padEnd(tierWidth)}  ${"SCRIPT LOCK".padEnd(scriptLockWidth)}  LAST MODIFIED`;
+          console.log(chalk.dim(formatSecretsListHeader(scopeLabel)));
           console.log(chalk.bold(header));
           for (const s of data.secrets) {
             const access = s.permission ?? "-";
@@ -766,6 +779,7 @@ export function registerSecretsCommand(program: Command): void {
           }
         } else {
           const header = `${"NAME".padEnd(nameWidth)}  ${"TIER".padEnd(tierWidth)}  ${"SCRIPT LOCK".padEnd(scriptLockWidth)}  LAST MODIFIED`;
+          console.log(chalk.dim(formatSecretsListHeader(scopeLabel)));
           console.log(chalk.bold(header));
           for (const s of data.secrets) {
             const tier = normalizeSecretTier(s.tier);

package/src/index.ts

@@ -4,6 +4,9 @@
  * HQ CLI - Module management, package management, and cloud sync for HQ
  */
 
+// MUST be first: guard the Node version before any dependency that needs a
+// Node 20+ API (e.g. util.styleText) or a newer native ABI is evaluated.
+import "./node-preflight.js";
 import { Command } from "commander";
 import { initSentry, Sentry } from "./sentry.js";
 import { registerAddCommand } from "./commands/add.js";
@@ -47,6 +50,8 @@ import { registerRescueCommand } from "./commands/rescue.js";
 import { registerMcpCommand } from "./commands/mcp-status.js";
 import { sanitizeArgv } from "./utils/feedback-diagnostics.js";
 import { environmentalFsErrorMessage } from "./utils/environmental-error.js";
+import { isEpipe } from "./utils/epipe.js";
+import { isInterceptedProcessExit } from "./utils/intercepted-process-exit.js";
 import {
   maybeWarnNewVersion,
   refreshVersionCache,
@@ -57,9 +62,13 @@ import {
 } from "./utils/version-gate.js";
 import { CLI_VERSION } from "./cli-version.js";
 
-// Swallow EPIPE when a downstream reader (e.g. `source <(…)`, `| head`) closes the pipe early.
+// Swallow EPIPE when a downstream reader (e.g. `source <(…)`, `| head`) closes
+// the pipe early. This covers the ASYNC path — an 'error' event emitted on the
+// stream. The SYNCHRONOUS path (a `write EPIPE` thrown straight out of
+// console.log inside a command) is handled in the top-level catch below; both
+// share `isEpipe` (HQ-6B).
 const onPipeError = (err: NodeJS.ErrnoException): void => {
-  if (err.code === "EPIPE") {
+  if (isEpipe(err)) {
     process.exit(0);
   }
   throw err;
@@ -222,18 +231,37 @@ registerMcpCommand(program);
     }
     await program.parseAsync();
   } catch (err) {
-    // A full disk / exhausted quota / read-only filesystem is the user's
-    // machine, not an HQ code defect. Surface a clear, actionable message and
-    // skip Sentry capture so one full disk doesn't flood the tracker with
-    // identical, unfixable crash reports (HQ-CLI-2). Genuine errors still go
-    // to Sentry and still exit 1.
-    const envMsg = environmentalFsErrorMessage(err);
-    if (envMsg) {
-      process.stderr.write(`hq: ${envMsg}\n`);
+    // A broken pipe (EPIPE) means the reader of `hq`'s output closed it early
+    // (`hq … | head`, `source <(hq …)`, a parent that exited). That is normal
+    // Unix behavior with no user-facing degradation — exit cleanly (0) and
+    // skip Sentry capture instead of shipping a fatal (HQ-6B). A synchronous
+    // `write EPIPE` thrown out of console.log lands here rather than on the
+    // stream 'error' listener above.
+    if (isEpipe(err)) {
+      process.exitCode = 0;
+    } else if (isInterceptedProcessExit(err)) {
+      // A security/audit FUZZ harness replaced `process.exit` with a throw so it
+      // can keep exercising the binary. Commander calling `process.exit` for
+      // normal CLI control flow (e.g. an unknown command → exit 1) then surfaces
+      // here as that synthetic marker. It is a test-harness artifact, NOT an
+      // hq-cli defect — a real user's `process.exit` just exits, so nothing is
+      // thrown or captured. Skip Sentry capture (no signal, no user-facing
+      // degradation) and preserve the intended non-zero exit (HQ-CLI-3).
+      process.exitCode = 1;
     } else {
-      Sentry.captureException(err);
+      // A full disk / exhausted quota / read-only filesystem is the user's
+      // machine, not an HQ code defect. Surface a clear, actionable message and
+      // skip Sentry capture so one full disk doesn't flood the tracker with
+      // identical, unfixable crash reports (HQ-CLI-2). Genuine errors still go
+      // to Sentry and still exit 1.
+      const envMsg = environmentalFsErrorMessage(err);
+      if (envMsg) {
+        process.stderr.write(`hq: ${envMsg}\n`);
+      } else {
+        Sentry.captureException(err);
+      }
+      process.exitCode = 1;
     }
-    process.exitCode = 1;
   } finally {
     // Release health: finalize the per-run session before the flush.
     Sentry.endSession();

package/src/node-preflight.test.ts

@@ -0,0 +1,60 @@
+/**
+ * Unit tests for the runtime Node version guard.
+ *
+ * The guard fails the CLI fast on Node < 20 (where prebuilt native modules hit
+ * an ABI mismatch and `util.styleText` is missing) with an actionable upgrade
+ * message, and is a no-op on Node 20+.
+ */
+
+import { describe, expect, it } from "vitest";
+
+import { MIN_NODE_MAJOR, checkNodeVersion } from "./node-preflight.js";
+
+describe("checkNodeVersion", () => {
+  it("rejects Node 18 with an actionable upgrade message", () => {
+    const result = checkNodeVersion("18.19.0");
+
+    expect(result.ok).toBe(false);
+    expect(result.major).toBe(18);
+    expect(result.message).toContain(`Node.js ${MIN_NODE_MAJOR} or newer`);
+    expect(result.message).toContain("18.19.0");
+    expect(result.message).toMatch(/upgrade/i);
+  });
+
+  it("rejects every major below the minimum", () => {
+    for (const version of ["14.21.3", "16.20.2", "19.9.0"]) {
+      const result = checkNodeVersion(version);
+      expect(result.ok).toBe(false);
+      expect(result.message).toBeDefined();
+    }
+  });
+
+  it("accepts Node 20 (the minimum) without a message", () => {
+    const result = checkNodeVersion("20.11.1");
+
+    expect(result.ok).toBe(true);
+    expect(result.major).toBe(20);
+    expect(result.message).toBeUndefined();
+  });
+
+  it("accepts newer majors (22, 24)", () => {
+    for (const version of ["22.3.0", "24.0.0"]) {
+      const result = checkNodeVersion(version);
+      expect(result.ok).toBe(true);
+      expect(result.message).toBeUndefined();
+    }
+  });
+
+  it("treats an unparseable version as supported (never blocks on a bad string)", () => {
+    const result = checkNodeVersion("not-a-version");
+
+    expect(result.ok).toBe(true);
+    expect(result.message).toBeUndefined();
+  });
+
+  it("defaults to the running runtime, which is supported in CI", () => {
+    // The test runner itself must be on a supported Node, so the default-arg
+    // path returns ok — also proving importing this module did not exit.
+    expect(checkNodeVersion().ok).toBe(true);
+  });
+});

package/src/node-preflight.ts

@@ -0,0 +1,67 @@
+/**
+ * Runtime Node.js version guard for the hq CLI.
+ *
+ * HQ tooling requires Node.js 20 or newer. On older runtimes (notably Node 18)
+ * the CLI dies with cryptic failures long before reaching any of its own code:
+ * a native-module ABI mismatch from a prebuilt dependency, and a missing
+ * `util.styleText` (added in Node 20). Those errors give the user no hint that
+ * the real problem is just an old Node.
+ *
+ * This module exists to fail fast with an actionable message instead. It is
+ * imported FIRST by every CLI entry point (`index.ts`, `bin/hq-auth-refresh.ts`)
+ * so the check runs before commander, Sentry, or any dependency that needs a
+ * Node 20+ API or a newer native ABI is evaluated. ES modules evaluate their
+ * imports in source order, so as long as this is the first import in the entry
+ * module, the guard short-circuits an unsupported runtime cleanly.
+ *
+ * Keep this file dependency-free — it must not import anything that could itself
+ * fail to load on the very runtime it is trying to detect.
+ */
+
+export const MIN_NODE_MAJOR = 20;
+
+export interface NodeVersionCheck {
+  ok: boolean;
+  major: number;
+  message?: string;
+}
+
+/**
+ * Pure check: is the given Node version string (e.g. "18.19.0") supported?
+ * Defaults to the running runtime's version. An unparseable version is treated
+ * as supported so we never block a user on a version string we can't read.
+ */
+export function checkNodeVersion(
+  versionString: string = process.versions.node,
+): NodeVersionCheck {
+  const major = Number.parseInt(String(versionString).split(".")[0] ?? "", 10);
+
+  if (!Number.isFinite(major) || major >= MIN_NODE_MAJOR) {
+    return { ok: true, major };
+  }
+
+  const message =
+    `hq requires Node.js ${MIN_NODE_MAJOR} or newer — you are running Node ${versionString}.\n` +
+    `Older versions fail with native-module ABI mismatches and missing APIs.\n` +
+    `Please upgrade to Node ${MIN_NODE_MAJOR}+ (https://nodejs.org/) and run hq again.`;
+
+  return { ok: false, major, message };
+}
+
+/**
+ * Side-effecting guard run on import: prints the upgrade message to stderr and
+ * exits 1 on an unsupported runtime. A no-op on Node 20+. Set
+ * `HQ_SKIP_NODE_PREFLIGHT=1` to bypass (used by the test runner, which already
+ * runs on a supported Node).
+ */
+export function enforceNodeVersion(): void {
+  if (process.env.HQ_SKIP_NODE_PREFLIGHT) return;
+
+  const result = checkNodeVersion();
+  if (!result.ok && result.message) {
+    process.stderr.write(`${result.message}\n`);
+    process.exit(1);
+  }
+}
+
+enforceNodeVersion();

package/src/sentry-epipe.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it, vi } from "vitest";
+import type { ErrorEvent, EventHint } from "@sentry/node";
+
+// sentry.ts reads BUNDLED_DSN at import time; stub it so the module loads
+// without a real DSN (mirrors sentry.test.ts).
+vi.mock("./sentry-dsn.generated.js", () => ({ BUNDLED_DSN: "" }));
+
+import { epipeAwareBeforeSend } from "./sentry.js";
+
+describe("epipeAwareBeforeSend (HQ-6B)", () => {
+  it("drops an EPIPE crash before it can ship a fatal", () => {
+    const epipe = Object.assign(new Error("write EPIPE"), { code: "EPIPE" });
+    const event = {
+      exception: { values: [{ type: "Error", value: "write EPIPE" }] },
+    } as ErrorEvent;
+    const out = epipeAwareBeforeSend(event, {
+      originalException: epipe,
+    } as EventHint);
+    expect(out).toBeNull();
+  });
+
+  it("forwards a genuine error to the scrubber (still reported)", () => {
+    const err = new Error("boom");
+    const event = { message: "boom" } as ErrorEvent;
+    const out = epipeAwareBeforeSend(event, {
+      originalException: err,
+    } as EventHint);
+    expect(out).not.toBeNull();
+    expect(out?.message).toBe("boom");
+  });
+
+  it("forwards when there is no originalException hint", () => {
+    const event = { message: "no hint" } as ErrorEvent;
+    const out = epipeAwareBeforeSend(event, {} as EventHint);
+    expect(out).not.toBeNull();
+  });
+});

package/src/sentry-release.test.ts

@@ -0,0 +1,54 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+// `@sentry/node`'s `init` is a non-configurable export, so it can't be spied
+// in place — replace it via importOriginal spread (every OTHER Sentry export
+// stays real, so initSentry's setUser/startSession remain harmless no-ops with
+// no real SDK init). We only need to inspect the options handed to `init`.
+const { initMock } = vi.hoisted(() => ({ initMock: vi.fn() }));
+vi.mock("@sentry/node", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("@sentry/node")>();
+  return { ...actual, init: initMock };
+});
+// A DSN must be present for initSentry to reach Sentry.init.
+vi.mock("./sentry-dsn.generated.js", () => ({
+  BUNDLED_DSN: "https://examplePublicKey@o0.ingest.sentry.io/0",
+}));
+
+import { initSentry } from "./sentry.js";
+import { CLI_VERSION } from "./cli-version.js";
+
+const PKG_VERSION = (
+  JSON.parse(
+    readFileSync(
+      path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "package.json"),
+      "utf-8",
+    ),
+  ) as { version: string }
+).version;
+
+describe("initSentry — release tag carries the real CLI version (resolve-by-release)", () => {
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  // Locks the resolve-by-release path for hq-cli: every event must be stamped
+  // with the REAL package version so Sentry's "resolved in next release" works
+  // and old-version stragglers (the legacy `hq-cli@0.0.0` events from pre-#8
+  // installs) sort as the oldest release and stay suppressed. Regression guard
+  // against ever reverting to the `npm_package_version` 0.0.0 pitfall.
+  it("stamps release = hq-cli@<package.json version>, never the 0.0.0 placeholder", () => {
+    initSentry();
+
+    expect(initMock).toHaveBeenCalledTimes(1);
+    const opts = initMock.mock.calls[0][0] as { release?: string };
+
+    // CLI_VERSION resolves from package.json at runtime (not npm_package_version).
+    expect(CLI_VERSION).toBe(PKG_VERSION);
+    expect(CLI_VERSION).not.toBe("0.0.0");
+    expect(opts.release).toBe(`hq-cli@${PKG_VERSION}`);
+    expect(opts.release).not.toBe("hq-cli@0.0.0");
+  });
+});