@indigoai-us/hq-cli 5.73.0 → 5.74.0

package/src/commands/integrations.test.ts

@@ -34,6 +34,7 @@ vi.mock("../utils/vault-api.js", async (importOriginal) => {
 });
 
 import { vaultApiFetch } from "../utils/vault-api.js";
+import { AuthError, isAuthError } from "../utils/auth-error.js";
 import {
   IntegrationsCliError,
   queuedOutcome,
@@ -258,6 +259,16 @@ describe("hq integrations call", () => {
     ).rejects.toThrow(/--args must be a JSON object/);
     expect(vaultApiFetchMock).not.toHaveBeenCalled();
   });
+
+  it("marks non-object --args as expected", async () => {
+    try {
+      await runCli(["integrations", "call", "t", "--provider", "linear", "--args", "[1]"]);
+      throw new Error("expected runCli to throw");
+    } catch (err) {
+      expect(err).toBeInstanceOf(IntegrationsCliError);
+      expect((err as IntegrationsCliError).expected).toBe(true);
+    }
+  });
 });
 
 describe("hq integrations approve", () => {
@@ -282,3 +293,223 @@ describe("hq integrations approve", () => {
     expect(logged()).toContain("Approved");
   });
 });
+
+describe("expected integrations errors", () => {
+  const linear = {
+    id: "acct_1",
+    provider: "factory:linear",
+    status: "connected",
+  };
+  const notion = {
+    id: "acct_2",
+    provider: "factory:notion",
+    status: "connected",
+  };
+
+  it("marks a non-owner 403 approve as expected (skips Sentry) and preserves the message", async () => {
+    vaultApiFetchMock
+      .mockResolvedValueOnce(connectionsResponse())
+      .mockResolvedValueOnce(
+        jsonResponse(
+          { error: "Only a company owner can approve or reject queued integration writes" },
+          403,
+        ),
+      );
+
+    try {
+      await runCli(["integrations", "approve", "cq_123", "--provider", "linear"]);
+      throw new Error("expected runCli to throw");
+    } catch (err) {
+      expect(err).toBeInstanceOf(IntegrationsCliError);
+      expect((err as IntegrationsCliError).expected).toBe(true);
+      expect((err as Error).message).toContain("Only a company owner");
+    }
+  });
+
+  it("still captures a genuine server 500 on approve (expected === false)", async () => {
+    vaultApiFetchMock
+      .mockResolvedValueOnce(connectionsResponse())
+      .mockResolvedValueOnce(jsonResponse({ error: "boom" }, 500));
+
+    try {
+      await runCli(["integrations", "approve", "cq_123", "--provider", "linear"]);
+      throw new Error("expected runCli to throw");
+    } catch (err) {
+      expect(err).toBeInstanceOf(IntegrationsCliError);
+      expect((err as IntegrationsCliError).expected).toBe(false);
+    }
+  });
+
+  it("marks reject 403 as expected too", async () => {
+    vaultApiFetchMock
+      .mockResolvedValueOnce(connectionsResponse())
+      .mockResolvedValueOnce(
+        jsonResponse(
+          { error: "Only a company owner can approve or reject queued integration writes" },
+          403,
+        ),
+      );
+
+    try {
+      await runCli(["integrations", "reject", "cq_123", "--provider", "linear"]);
+      throw new Error("expected runCli to throw");
+    } catch (err) {
+      expect(err).toBeInstanceOf(IntegrationsCliError);
+      expect((err as IntegrationsCliError).expected).toBe(true);
+    }
+
+    expect(vaultApiFetchMock.mock.calls[1]![0].path).toBe(
+      "/v1/integrations/confirm/cq_123/reject",
+    );
+  });
+
+  it("marks local connection selection usage errors as expected", () => {
+    for (const fn of [
+      () => selectConnection([], {}),
+      () => selectConnection([linear, notion], {}),
+      () => selectConnection([linear], { provider: "jira" }),
+    ]) {
+      try {
+        fn();
+        throw new Error("expected selectConnection to throw");
+      } catch (err) {
+        expect(err).toBeInstanceOf(IntegrationsCliError);
+        expect((err as IntegrationsCliError).expected).toBe(true);
+      }
+    }
+  });
+});
+
+// HQ-CLI-9: `hq integrations call get_board_info --provider monday …` hit a 401
+// on POST /v1/integrations/mcp while the caller's HQ session was rejected. The
+// old `callGateway` threw a plain, opaque `IntegrationsCliError("Integration
+// gateway request failed (HTTP 401).")` that shipped to Sentry as an
+// unactionable fatal. A gateway 401 is an expired/missing session — the same
+// expected auth state the vault company-resolution paths already raise as
+// `AuthError` (HQ-CLI-8). The fix routes every integration-gateway 401 through
+// that typed AuthError so the user gets one actionable "run `hq login`" message
+// and Sentry is skipped, while genuine 4xx/5xx faults keep their behavior.
+describe("integration gateway 401 → AuthError (HQ-CLI-9)", () => {
+  it("throws an actionable AuthError (not an opaque IntegrationsCliError) when callGateway 401s", async () => {
+    vaultApiFetchMock
+      .mockResolvedValueOnce(connectionsResponse())
+      .mockResolvedValueOnce(jsonResponse({ error: "Unauthorized" }, 401));
+
+    const err = await runCli([
+      "integrations",
+      "call",
+      "get_board_info",
+      "--provider",
+      "linear",
+      "--args",
+      "{}",
+    ]).then(
+      () => {
+        throw new Error("expected runCli to throw");
+      },
+      (e: unknown) => e,
+    );
+
+    expect(isAuthError(err)).toBe(true);
+    expect(err).toBeInstanceOf(AuthError);
+    expect((err as Error).message).toMatch(/hq login/);
+    // The gateway request was actually attempted (connections + gateway call).
+    expect(vaultApiFetchMock.mock.calls[1]![0].path).toBe("/v1/integrations/mcp");
+  });
+
+  it("throws an AuthError when the admin (fetchConnections) call 401s", async () => {
+    vaultApiFetchMock.mockResolvedValueOnce(jsonResponse({ error: "Unauthorized" }, 401));
+
+    const err = await runCli(["integrations", "list"]).then(
+      () => {
+        throw new Error("expected runCli to throw");
+      },
+      (e: unknown) => e,
+    );
+
+    expect(isAuthError(err)).toBe(true);
+    expect((err as Error).message).toMatch(/hq login/);
+  });
+
+  it("throws an AuthError when an approve confirm call 401s", async () => {
+    vaultApiFetchMock
+      .mockResolvedValueOnce(connectionsResponse())
+      .mockResolvedValueOnce(jsonResponse({ error: "Unauthorized" }, 401));
+
+    const err = await runCli([
+      "integrations",
+      "approve",
+      "cq_123",
+      "--provider",
+      "linear",
+    ]).then(
+      () => {
+        throw new Error("expected runCli to throw");
+      },
+      (e: unknown) => e,
+    );
+
+    expect(isAuthError(err)).toBe(true);
+    expect((err as Error).message).toMatch(/hq login/);
+  });
+
+  // Scope guards: only a 401 becomes an AuthError. A genuine server 500 still
+  // reports (expected === false), and a provider-level JSON-RPC error (HTTP 200
+  // with `message.error`) stays an IntegrationsCliError — so real faults and
+  // upstream tool errors are never misclassified as an auth state.
+  it("keeps a gateway 500 as a reporting IntegrationsCliError (not an AuthError)", async () => {
+    vaultApiFetchMock
+      .mockResolvedValueOnce(connectionsResponse())
+      .mockResolvedValueOnce(jsonResponse({ error: "boom" }, 500));
+
+    const err = await runCli([
+      "integrations",
+      "call",
+      "get_board_info",
+      "--provider",
+      "linear",
+      "--args",
+      "{}",
+    ]).then(
+      () => {
+        throw new Error("expected runCli to throw");
+      },
+      (e: unknown) => e,
+    );
+
+    expect(isAuthError(err)).toBe(false);
+    expect(err).toBeInstanceOf(IntegrationsCliError);
+    expect((err as IntegrationsCliError).expected).toBe(false);
+  });
+
+  it("keeps an upstream provider error (HTTP 200 message.error) as an IntegrationsCliError", async () => {
+    vaultApiFetchMock
+      .mockResolvedValueOnce(connectionsResponse())
+      .mockResolvedValueOnce(
+        jsonResponse({
+          jsonrpc: "2.0",
+          id: "x",
+          error: { code: -32050, message: "monday rejected the board id" },
+        }),
+      );
+
+    const err = await runCli([
+      "integrations",
+      "call",
+      "get_board_info",
+      "--provider",
+      "linear",
+      "--args",
+      "{}",
+    ]).then(
+      () => {
+        throw new Error("expected runCli to throw");
+      },
+      (e: unknown) => e,
+    );
+
+    expect(isAuthError(err)).toBe(false);
+    expect(err).toBeInstanceOf(IntegrationsCliError);
+    expect((err as Error).message).toMatch(/monday rejected the board id/);
+  });
+});

package/src/commands/integrations.ts

@@ -31,6 +31,7 @@ import { Command } from "commander";
 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";
 
 interface AdminConnection {
   id: string;
@@ -50,12 +51,43 @@ interface GatewayMessage {
 }
 
 export class IntegrationsCliError extends Error {
-  constructor(message: string) {
+  /**
+   * True when the error is the caller's request/state/permission (a client 4xx
+   * or a local input/usage error) rather than an hq-cli defect. Expected errors
+   * are printed to the user but skipped for Sentry capture (HQ-CLI-6). Defaults
+   * to false so an unclassified error still reaches Sentry.
+   */
+  readonly expected: boolean;
+
+  constructor(message: string, opts: { expected?: boolean } = {}) {
     super(message);
     this.name = "IntegrationsCliError";
+    this.expected = opts.expected ?? false;
   }
 }
 
+/**
+ * A client 4xx is the caller's request/state/permission (bad params, stale
+ * queueId, a non-owner approving) — expected and user-facing, not a bug. A 5xx
+ * (or a 2xx protocol violation) is a genuine server/unknown fault worth a Sentry
+ * crash report.
+ */
+function isClientError(status: number): boolean {
+  return status >= 400 && status < 500;
+}
+
+// A 401 from ANY integration-gateway vault call means the caller's HQ session
+// is expired or missing — an expected auth state fixed by `hq login`, not an
+// hq-cli defect. Raise the same typed AuthError the vault company-resolution
+// paths use (HQ-CLI-8) so the top-level handler prints one actionable message
+// and skips Sentry, instead of surfacing the opaque, unactionable
+// "Integration gateway request failed (HTTP 401)" that shipped as a fatal from
+// `callGateway` (HQ-CLI-9). Non-401 statuses keep their existing behavior:
+// other 4xx stay expected client errors, 5xx still report.
+function raiseIfUnauthorized(res: Response): void {
+  if (res.status === 401) throw new AuthError();
+}
+
 /** "factory:linear" → "linear"; mirrors hq-pro's factoryToolPrefix. */
 export function toolPrefixForProvider(provider: string): string {
   return provider
@@ -75,9 +107,11 @@ export async function fetchConnections(
     query: { companyUid },
   });
   if (!res.ok) {
+    raiseIfUnauthorized(res);
     const body = (await res.json().catch(() => ({}))) as { error?: string };
     throw new IntegrationsCliError(
       body.error ?? `Failed to list integrations (HTTP ${res.status})`,
+      { expected: isClientError(res.status) },
     );
   }
   const data = (await res.json()) as { connections?: AdminConnection[] };
@@ -99,6 +133,7 @@ export function selectConnection(
     if (!match) {
       throw new IntegrationsCliError(
         `No connection '${opts.connection}'. Run \`hq integrations list\` to see connected apps.`,
+        { expected: true },
       );
     }
     return match;
@@ -116,6 +151,7 @@ export function selectConnection(
       throw new IntegrationsCliError(
         `No connected app matches '${opts.provider}'.` +
           (available ? ` Connected: ${available}.` : " Nothing is connected yet — connect apps on the console Integrations page."),
+        { expected: true },
       );
     }
     return match;
@@ -124,11 +160,13 @@ export function selectConnection(
   if (active.length === 0) {
     throw new IntegrationsCliError(
       "No connected apps yet. Connect one on the console Integrations page, then retry.",
+      { expected: true },
     );
   }
   throw new IntegrationsCliError(
     `Multiple apps are connected — pick one with --provider:\n` +
       active.map((c) => `  --provider ${c.provider.replace(/^factory:/, "")}`).join("\n"),
+    { expected: true },
   );
 }
 
@@ -149,8 +187,10 @@ export async function callGateway(
   });
   const message = (await res.json().catch(() => null)) as GatewayMessage | null;
   if (!res.ok || !message) {
+    raiseIfUnauthorized(res);
     throw new IntegrationsCliError(
       `Integration gateway request failed (HTTP ${res.status}).`,
+      { expected: isClientError(res.status) },
     );
   }
   if (message.error) {
@@ -331,6 +371,7 @@ export function registerIntegrationsCommand(program: Command): void {
         } catch {
           throw new IntegrationsCliError(
             `--args must be a JSON object, e.g. --args '{"assignee":"me"}'`,
+            { expected: true },
           );
         }
         const token = await ensureCognitoIdToken();
@@ -416,8 +457,10 @@ export function registerIntegrationsCommand(program: Command): void {
             error?: string;
           };
           if (!res.ok) {
+            raiseIfUnauthorized(res);
             throw new IntegrationsCliError(
               body.error ?? `${decision} failed (HTTP ${res.status})`,
+              { expected: isClientError(res.status) },
             );
           }
           if (opts.json) {

package/src/commands/outposts.test.ts

@@ -305,6 +305,9 @@ describe("hq outposts exec", () => {
 
   it("wraps the command to run from the box's HQ folder, then runs it", () => {
     const wrapped = withRemoteHqDir("pwd");
+    // SSM may invoke the command as root with HOME unset. Seed a real home so
+    // tools such as gh do not write machine state into the HQ checkout.
+    expect(wrapped).toContain('export HOME="${HOME:-/root}"');
     // cd into $HOME/hq (SSH/login user) …
     expect(wrapped).toContain('cd "$HOME/hq"');
     // … falling back to ec2-user's home for the SSM/root path (no $HOME) …

package/src/commands/outposts.ts

@@ -364,14 +364,15 @@ async function waitForExecResult(
  * caller's command. `exec` runs over two transports with two different default
  * working directories — SSM runs as root with no `$HOME` (cwd `/usr/bin`) and
  * SSH lands in the login user's home — so without this, `hq outposts exec -- pwd`
- * printed an unhelpful, transport-dependent directory. We resolve the HQ folder
- * in-shell: `$HOME/hq` for the login/SSH user, falling back to ec2-user's home
- * for the SSM/root path. The trailing `|| true` keeps the command running from
- * the default directory when no HQ checkout is present, so exec never fails
- * merely because the box has no HQ folder.
+ * printed an unhelpful, transport-dependent directory. Initialize a real root
+ * home for the SSM case before resolving the HQ folder: tools run by the caller
+ * (notably `gh`) otherwise treat the HQ checkout as their home and can create
+ * root-owned machine state inside it. The trailing `|| true` keeps the command
+ * running from the default directory when no HQ checkout is present, so exec
+ * never fails merely because the box has no HQ folder.
  */
 export const REMOTE_HQ_DIR_PREFIX =
-  'cd "$HOME/hq" 2>/dev/null || cd ~ec2-user/hq 2>/dev/null || true';
+  'export HOME="${HOME:-/root}"; cd "$HOME/hq" 2>/dev/null || cd ~ec2-user/hq 2>/dev/null || true';
 
 /** Wrap `command` so it runs from the box's HQ folder (see REMOTE_HQ_DIR_PREFIX). */
 export function withRemoteHqDir(command: string): string {

package/src/main.ts

@@ -60,8 +60,11 @@ import { registerBillingCommand } from "./commands/billing.js";
 import { registerDbCommand } from "./commands/db.js";
 import { sanitizeArgv } from "./utils/feedback-diagnostics.js";
 import { environmentalFsErrorMessage } from "./utils/environmental-error.js";
+import { isExpectedUserError } from "./utils/expected-cli-error.js";
 import { isEpipe } from "./utils/epipe.js";
 import { isInterceptedProcessExit } from "./utils/intercepted-process-exit.js";
+import { isAuthError } from "./utils/auth-error.js";
+import { isCompanySelectionError } from "./utils/company-selection-error.js";
 import {
   maybeWarnNewVersion,
   refreshVersionCache,
@@ -303,6 +306,34 @@ export async function runCli(): Promise<void> {
       // 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 if (isCompanySelectionError(err)) {
+      // The user has multiple (or zero) active company memberships and ran a
+      // command that needs exactly one without `--company`, or a `--company`
+      // slug collided across companies. That's an expected, user-actionable
+      // disambiguation prompt — the message already tells them exactly how to
+      // proceed (re-run with `--company <slug-or-uid>`) — not an hq-cli defect.
+      // The CLI can't pick a company for them. Print the actionable message and
+      // exit non-zero, but skip Sentry capture so a normal "pick a company"
+      // prompt doesn't flood the tracker with unfixable "crashes" (HQ-CLI-7).
+      process.stderr.write(`hq: ${(err as Error).message}\n`);
+      process.exitCode = 1;
+    } else if (isAuthError(err)) {
+      // HQ-CLI-8: the vault API returned 401 Unauthorized — the caller's HQ
+      // session is expired or missing. That's an expected auth state the user
+      // fixes with `hq login`, not an hq-cli defect. Print the actionable
+      // message and skip Sentry so an expired login doesn't flood the tracker
+      // with identical, unfixable "crashes".
+      process.stderr.write(`hq: ${(err as Error).message}\n`);
+      process.exitCode = 1;
+    } else if (isExpectedUserError(err)) {
+      // HQ-CLI-6: a user-facing, client-caused error (a non-owner running
+      // `hq integrations approve`, a stale queueId, a bad --args, an unknown
+      // connection) is the caller's request/state/permission, not an hq-cli
+      // defect. Print the actionable message and skip Sentry so a correctly-
+      // denied 4xx doesn't flood the tracker with identical, unfixable crash
+      // reports. Genuine server (5xx) / unknown failures still capture below.
+      process.stderr.write(`hq: ${err.message}\n`);
+      process.exitCode = 1;
     } else {
       // A full disk / exhausted quota / read-only filesystem is the user's
       // machine, not an HQ code defect. Surface a clear, actionable message and

package/src/packaging.test.ts

@@ -18,6 +18,8 @@ const pkg = JSON.parse(
   readFileSync(resolve(repoRoot, "package.json"), "utf8"),
 ) as {
   bin?: Record<string, string> | string;
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
   scripts?: Record<string, string>;
 };
 
@@ -53,3 +55,10 @@ describe("packaging: bin executable bit", () => {
     }
   });
 });
+
+describe("packaging: runtime dependencies", () => {
+  it("ships the S3 client imported by files-browse", () => {
+    expect(pkg.dependencies).toHaveProperty("@aws-sdk/client-s3");
+    expect(pkg.devDependencies).not.toHaveProperty("@aws-sdk/client-s3");
+  });
+});

package/src/utils/auth-error.test.ts

@@ -0,0 +1,40 @@
+import { describe, it, expect } from "vitest";
+import { AuthError, isAuthError } from "./auth-error.js";
+
+describe("isAuthError", () => {
+  // HQ-CLI-8: an expired HQ session surfaced as a vault 401 during company
+  // slug resolution. The user fixes it with `hq login`; it should skip Sentry.
+  it("classifies an AuthError as an expected auth state (skip Sentry)", () => {
+    expect(isAuthError(new AuthError())).toBe(true);
+  });
+
+  it("uses an actionable default message", () => {
+    expect(new AuthError().message).toMatch(/hq login/);
+  });
+
+  it("preserves a custom user-facing message verbatim", () => {
+    const msg = "Sign in again before continuing.";
+    expect(new AuthError(msg).message).toBe(msg);
+  });
+
+  it("keeps instanceof across the transpile target", () => {
+    const err = new AuthError();
+    expect(err).toBeInstanceOf(AuthError);
+    expect(err).toBeInstanceOf(Error);
+    expect(err.name).toBe("AuthError");
+  });
+
+  // A genuine defect must still reach Sentry — only the typed auth class is
+  // diverted, so real bugs are never silently swallowed.
+  it("does NOT match a plain Error (so real faults still report)", () => {
+    expect(isAuthError(new Error("Unauthorized"))).toBe(false);
+    expect(isAuthError(new Error("Your HQ session has expired. Run `hq login`."))).toBe(false);
+  });
+
+  it("does NOT match non-error values", () => {
+    expect(isAuthError(null)).toBe(false);
+    expect(isAuthError(undefined)).toBe(false);
+    expect(isAuthError("Unauthorized")).toBe(false);
+    expect(isAuthError({ message: "Unauthorized" })).toBe(false);
+  });
+});

package/src/utils/auth-error.ts

@@ -0,0 +1,42 @@
+// src/utils/auth-error.ts
+//
+// Classify expired or missing HQ session conditions surfaced by the vault API
+// (HQ-CLI-8). These are expected, user-actionable auth states — NOT hq-cli
+// defects — so the top-level catch prints the message and exits non-zero but
+// SKIPS Sentry capture, mirroring the company-selection (HQ-CLI-7),
+// expected-user-error (HQ-CLI-6), and environmental-FS (HQ-CLI-2) carve-outs.
+//
+// HQ-CLI-8: a user ran `hq integrations list --company liverecover --json`
+// with an expired HQ session. Company-slug resolution tried the caller-scoped
+// `/entity/check-slug/me` lookup and the global `/entity/by-slug/company/...`
+// fallback; both returned 401 Unauthorized. The plain Error that bubbled up
+// looked like a company-resolution defect and was shipped to Sentry as a fatal.
+// A 401 from vault resolution means the caller needs to run `hq login`; the
+// code cannot repair an expired token, so this is normal auth state, not a
+// crash to triage.
+
+/**
+ * Thrown when the vault API reports the caller's HQ session is expired or
+ * missing. The `message` is user-facing and actionable; the top-level handler
+ * prints it verbatim and skips Sentry capture.
+ */
+export class AuthError extends Error {
+  constructor(
+    message = "Your HQ session has expired or you're not signed in. Run `hq login` and try again.",
+  ) {
+    super(message);
+    this.name = "AuthError";
+    // Preserve `instanceof` across the TS→ES5/ES2015 transpile target.
+    Object.setPrototypeOf(this, AuthError.prototype);
+  }
+}
+
+/**
+ * True when `err` is an expected auth-state failure the user must resolve with
+ * `hq login`. Callers should print `err.message` and SKIP Sentry capture while
+ * preserving a non-zero exit. Genuine faults are plain `Error`s and return
+ * `false`, so real bugs still report.
+ */
+export function isAuthError(err: unknown): boolean {
+  return err instanceof AuthError;
+}

package/src/utils/company-selection-error.test.ts

@@ -0,0 +1,42 @@
+import { describe, it, expect } from "vitest";
+import {
+  CompanySelectionError,
+  isCompanySelectionError,
+} from "./company-selection-error.js";
+
+describe("isCompanySelectionError", () => {
+  // HQ-CLI-7: the exact error that flooded Sentry when a user with multiple
+  // active memberships ran a command with no --company.
+  it("classifies a CompanySelectionError as a selection prompt (skip Sentry)", () => {
+    const err = new CompanySelectionError(
+      "Multiple active companies found. Re-run with --company <slug-or-uid> to pick one:\n  --company cmp_a\n  --company cmp_b",
+    );
+    expect(isCompanySelectionError(err)).toBe(true);
+  });
+
+  it("preserves the user-facing message verbatim for the top-level handler", () => {
+    const msg = "No active company memberships found. Use --company <slug> to specify.";
+    expect(new CompanySelectionError(msg).message).toBe(msg);
+  });
+
+  it("keeps instanceof across the transpile target", () => {
+    const err = new CompanySelectionError("pick one");
+    expect(err).toBeInstanceOf(CompanySelectionError);
+    expect(err).toBeInstanceOf(Error);
+    expect(err.name).toBe("CompanySelectionError");
+  });
+
+  // A genuine defect must still reach Sentry — only the disambiguation class is
+  // diverted, so real bugs are never silently swallowed.
+  it("does NOT match a plain Error (so real faults still report)", () => {
+    expect(isCompanySelectionError(new Error("Multiple active companies found."))).toBe(false);
+    expect(isCompanySelectionError(new Error("boom"))).toBe(false);
+  });
+
+  it("does NOT match non-error values", () => {
+    expect(isCompanySelectionError(null)).toBe(false);
+    expect(isCompanySelectionError(undefined)).toBe(false);
+    expect(isCompanySelectionError("Multiple active companies found.")).toBe(false);
+    expect(isCompanySelectionError({ message: "pick one" })).toBe(false);
+  });
+});

package/src/utils/company-selection-error.ts

@@ -0,0 +1,45 @@
+// src/utils/company-selection-error.ts
+//
+// Classify the "the caller must pick a company with --company" conditions
+// (HQ-CLI-7). These are expected, user-actionable disambiguation prompts —
+// NOT hq-cli defects — so the top-level catch prints the message and exits
+// non-zero but SKIPS Sentry capture, mirroring the EPIPE (HQ-6B),
+// intercepted-process-exit (HQ-CLI-3), and environmental-FS (HQ-CLI-2)
+// carve-outs.
+//
+// HQ-CLI-7: a user with THREE active company memberships ran `hq integrations`
+// with no `--company`. `resolveCompanyFromMemberships` correctly threw
+// "Multiple active companies found. Re-run with --company <slug-or-uid>…" —
+// the message literally tells the user how to proceed — but it propagated to
+// the CLI's top-level handler as a plain Error and was shipped to Sentry as a
+// fatal. The command needs the human to disambiguate; the code cannot pick a
+// company for them, so this is normal usage, not a crash to triage.
+
+/**
+ * Thrown when the CLI cannot resolve a single company on the user's behalf and
+ * the user must re-run with `--company <slug-or-uid>`:
+ *   - they have multiple active memberships and passed no `--company`,
+ *   - they have no active membership and passed no `--company`, or
+ *   - a `--company` slug collides across companies, none in their namespace.
+ *
+ * The `message` is already user-facing and actionable — the top-level handler
+ * prints it verbatim and skips Sentry capture.
+ */
+export class CompanySelectionError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "CompanySelectionError";
+    // Preserve `instanceof` across the TS→ES5/ES2015 transpile target.
+    Object.setPrototypeOf(this, CompanySelectionError.prototype);
+  }
+}
+
+/**
+ * True when `err` is a company-selection disambiguation prompt the user must
+ * resolve with `--company`. Callers should print `err.message` and SKIP Sentry
+ * capture (expected usage, no defect) while preserving a non-zero exit. Genuine
+ * faults are plain `Error`s and return `false`, so real bugs still report.
+ */
+export function isCompanySelectionError(err: unknown): boolean {
+  return err instanceof CompanySelectionError;
+}

package/src/utils/expected-cli-error.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+import { isExpectedUserError } from "./expected-cli-error.js";
+
+describe("isExpectedUserError", () => {
+  it("matches an Error explicitly marked expected", () => {
+    expect(isExpectedUserError(Object.assign(new Error("usage"), { expected: true }))).toBe(
+      true,
+    );
+  });
+
+  it("does NOT match Errors marked expected false or unmarked", () => {
+    expect(isExpectedUserError(Object.assign(new Error("boom"), { expected: false }))).toBe(
+      false,
+    );
+    expect(isExpectedUserError(new Error("boom"))).toBe(false);
+  });
+
+  it("does NOT match a plain object carrying expected true", () => {
+    expect(isExpectedUserError({ message: "usage", expected: true })).toBe(false);
+  });
+
+  it("does NOT match non-error values", () => {
+    expect(isExpectedUserError(null)).toBe(false);
+    expect(isExpectedUserError(undefined)).toBe(false);
+    expect(isExpectedUserError(42)).toBe(false);
+    expect(isExpectedUserError("usage")).toBe(false);
+  });
+});