@indigoai-us/hq-cli 5.73.1 → 5.74.0

package/dist/commands/integrations.d.ts

@@ -45,7 +45,16 @@ interface GatewayMessage {
     };
 }
 export declare 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;
+    });
 }
 /** "factory:linear" → "linear"; mirrors hq-pro's factoryToolPrefix. */
 export declare function toolPrefixForProvider(provider: string): string;

package/dist/commands/integrations.js

@@ -29,12 +29,42 @@ import { randomUUID } from "node:crypto";
 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";
 export class IntegrationsCliError extends Error {
-    constructor(message) {
+    /**
+     * 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.
+     */
+    expected;
+    constructor(message, opts = {}) {
         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) {
+    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) {
+    if (res.status === 401)
+        throw new AuthError();
+}
 /** "factory:linear" → "linear"; mirrors hq-pro's factoryToolPrefix. */
 export function toolPrefixForProvider(provider) {
     return provider
@@ -50,8 +80,9 @@ export async function fetchConnections(token, companyUid) {
         query: { companyUid },
     });
     if (!res.ok) {
+        raiseIfUnauthorized(res);
         const body = (await res.json().catch(() => ({})));
-        throw new IntegrationsCliError(body.error ?? `Failed to list integrations (HTTP ${res.status})`);
+        throw new IntegrationsCliError(body.error ?? `Failed to list integrations (HTTP ${res.status})`, { expected: isClientError(res.status) });
     }
     const data = (await res.json());
     return data.connections ?? [];
@@ -66,7 +97,7 @@ export function selectConnection(connections, opts) {
     if (opts.connection) {
         const match = connections.find((c) => c.id === opts.connection);
         if (!match) {
-            throw new IntegrationsCliError(`No connection '${opts.connection}'. Run \`hq integrations list\` to see connected apps.`);
+            throw new IntegrationsCliError(`No connection '${opts.connection}'. Run \`hq integrations list\` to see connected apps.`, { expected: true });
         }
         return match;
     }
@@ -81,17 +112,17 @@ export function selectConnection(connections, opts) {
                 .map((c) => c.provider.replace(/^factory:/, ""))
                 .join(", ");
             throw new IntegrationsCliError(`No connected app matches '${opts.provider}'.` +
-                (available ? ` Connected: ${available}.` : " Nothing is connected yet — connect apps on the console Integrations page."));
+                (available ? ` Connected: ${available}.` : " Nothing is connected yet — connect apps on the console Integrations page."), { expected: true });
         }
         return match;
     }
     if (active.length === 1)
         return active[0];
     if (active.length === 0) {
-        throw new IntegrationsCliError("No connected apps yet. Connect one on the console Integrations page, then retry.");
+        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"));
+        active.map((c) => `  --provider ${c.provider.replace(/^factory:/, "")}`).join("\n"), { expected: true });
 }
 export async function callGateway(token, params) {
     const res = await vaultApiFetch({
@@ -107,7 +138,8 @@ export async function callGateway(token, params) {
     });
     const message = (await res.json().catch(() => null));
     if (!res.ok || !message) {
-        throw new IntegrationsCliError(`Integration gateway request failed (HTTP ${res.status}).`);
+        raiseIfUnauthorized(res);
+        throw new IntegrationsCliError(`Integration gateway request failed (HTTP ${res.status}).`, { expected: isClientError(res.status) });
     }
     if (message.error) {
         throw new IntegrationsCliError(message.error.message ?? "Integration gateway returned an error.");
@@ -232,7 +264,7 @@ export function registerIntegrationsCommand(program) {
             parsedArgs = raw;
         }
         catch {
-            throw new IntegrationsCliError(`--args must be a JSON object, e.g. --args '{"assignee":"me"}'`);
+            throw new IntegrationsCliError(`--args must be a JSON object, e.g. --args '{"assignee":"me"}'`, { expected: true });
         }
         const token = await ensureCognitoIdToken();
         const companyUid = await getCompanyUid(token, opts.company);
@@ -288,7 +320,8 @@ export function registerIntegrationsCommand(program) {
             });
             const body = (await res.json().catch(() => ({})));
             if (!res.ok) {
-                throw new IntegrationsCliError(body.error ?? `${decision} failed (HTTP ${res.status})`);
+                raiseIfUnauthorized(res);
+                throw new IntegrationsCliError(body.error ?? `${decision} failed (HTTP ${res.status})`, { expected: isClientError(res.status) });
             }
             if (opts.json) {
                 printJson(body);

package/dist/commands/outposts.d.ts

@@ -143,13 +143,14 @@ export declare function joinCommandParts(commandParts: string[]): string;
  * 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 declare const REMOTE_HQ_DIR_PREFIX = "cd \"$HOME/hq\" 2>/dev/null || cd ~ec2-user/hq 2>/dev/null || true";
+export declare const REMOTE_HQ_DIR_PREFIX = "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 declare function withRemoteHqDir(command: string): string;
 /** SSH connection details vended by `POST /outpost/ssh-access`. */

package/dist/commands/outposts.js

@@ -215,13 +215,14 @@ async function waitForExecResult(token, commandId, outpostId) {
  * 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 const REMOTE_HQ_DIR_PREFIX = '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) {
     return `${REMOTE_HQ_DIR_PREFIX}; ${command}`;

package/dist/main.js

@@ -58,8 +58,10 @@ 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, } from "./utils/version-check.js";
 import { enforceVersionGate, shouldSkipGate, } from "./utils/version-gate.js";
@@ -266,6 +268,25 @@ export async function runCli() {
             process.stderr.write(`hq: ${err.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.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/dist/utils/auth-error.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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 declare class AuthError extends Error {
+    constructor(message?: string);
+}
+/**
+ * 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 declare function isAuthError(err: unknown): boolean;
+//# sourceMappingURL=auth-error.d.ts.map

package/dist/utils/auth-error.js

@@ -0,0 +1,39 @@
+// 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) {
+    return err instanceof AuthError;
+}
+//# sourceMappingURL=auth-error.js.map

package/dist/utils/expected-cli-error.d.ts

@@ -0,0 +1,15 @@
+/**
+ * An error the CLI should surface to the user (clear message, exit 1) but NOT
+ * report to Sentry. Carriers set `expected: true`.
+ */
+export interface ExpectedUserError extends Error {
+    expected: true;
+}
+/**
+ * True when `err` is an Error explicitly marked `expected === true`. A non-null
+ * result means the top-level handler should print `err.message` and skip Sentry
+ * capture. Anything else (unmarked errors, non-Error values) returns false so
+ * genuine faults still reach Sentry.
+ */
+export declare function isExpectedUserError(err: unknown): err is ExpectedUserError;
+//# sourceMappingURL=expected-cli-error.d.ts.map

package/dist/utils/expected-cli-error.js

@@ -0,0 +1,29 @@
+// src/utils/expected-cli-error.ts
+//
+// Classify errors that are the CALLER's request/state/permission rather than an
+// hq-cli code defect: a bad flag, malformed input, a correctly-denied client
+// 4xx (e.g. a non-owner running `hq integrations approve`). These are
+// user-facing and actionable — the CLI prints a clear message and does NOT
+// report them to Sentry, otherwise a correctly-enforced authorization denial
+// floods the tracker with identical, unfixable crash reports.
+//
+// This is the caller-side analog of hq-pro's `expectedDenialResponse`, and a
+// sibling of `environmental-error.ts` (HQ-CLI-2) and
+// `intercepted-process-exit.ts` (HQ-CLI-3): errors that are NOT hq-cli defects
+// are surfaced to the user but skipped for Sentry capture.
+//
+// HQ-CLI-6: `hq integrations approve|reject` by a non-owner got a correct 403
+// ("Only a company owner can approve or reject queued integration writes"); the
+// thrown error propagated to the top-level handler, which captured it to Sentry
+// as an error-level crash and printed nothing to the user.
+/**
+ * True when `err` is an Error explicitly marked `expected === true`. A non-null
+ * result means the top-level handler should print `err.message` and skip Sentry
+ * capture. Anything else (unmarked errors, non-Error values) returns false so
+ * genuine faults still reach Sentry.
+ */
+export function isExpectedUserError(err) {
+    return (err instanceof Error &&
+        err.expected === true);
+}
+//# sourceMappingURL=expected-cli-error.js.map

package/dist/utils/vault-api.js

@@ -1,5 +1,6 @@
 import { DEFAULT_VAULT_API_URL } from './cognito-session.js';
 import { Sentry } from '../sentry.js';
+import { AuthError } from './auth-error.js';
 import { CompanySelectionError } from './company-selection-error.js';
 export async function vaultApiFetch(opts) {
     const url = new URL(opts.path, DEFAULT_VAULT_API_URL);
@@ -83,12 +84,21 @@ const COMPANY_UID_PREFIX = 'cmp_';
 export function looksLikeCompanyUid(ref) {
     return ref.startsWith(COMPANY_UID_PREFIX);
 }
+// A 401 from ANY vault resolution call means the caller's HQ session is
+// expired or missing — an expected auth state fixed by `hq login`, not a
+// code defect. Raise a typed AuthError so the top-level handler prints an
+// actionable message and skips Sentry capture (HQ-CLI-8).
+function raiseIfUnauthorized(res) {
+    if (res.status === 401)
+        throw new AuthError();
+}
 async function resolveCompanyByUid(token, uid) {
     const res = await vaultApiFetch({
         token,
         path: `/entity/${encodeURIComponent(uid)}`,
     });
     if (!res.ok) {
+        raiseIfUnauthorized(res);
         const body = (await res.json().catch(() => ({})));
         throw new Error(`Failed to resolve company '${uid}': ${body.error ?? res.statusText}`);
     }
@@ -120,11 +130,13 @@ async function resolveSlugInCallerNamespace(token, slug) {
         query: { type: 'company', slug },
     });
     if (!res.ok) {
+        raiseIfUnauthorized(res);
         // Namespace lookup unavailable (e.g. membership table not configured →
-        // 503, or the caller has no person entity). Signal "couldn't resolve here"
-        // and let the caller fall back to the global lookup. vaultApiFetch already
-        // recorded the non-2xx as a Sentry breadcrumb, so this is not a silent
-        // swallow.
+        // 503, or the caller has no person entity). A 401 short-circuits above
+        // because the token is bad and the global fallback would only 401 again;
+        // other non-2xx statuses signal "couldn't resolve here" and let the caller
+        // fall back to the global lookup. vaultApiFetch already recorded the
+        // non-2xx as a Sentry breadcrumb, so this is not a silent swallow.
         return null;
     }
     const data = (await res.json());
@@ -152,6 +164,7 @@ async function resolveCompanyUid(token, ref) {
         path: `/entity/by-slug/company/${encodeURIComponent(ref)}`,
     });
     if (!res.ok) {
+        raiseIfUnauthorized(res);
         const body = (await res.json().catch(() => ({})));
         // Residual true ambiguity: the slug matches multiple live companies and
         // NONE is in the caller's namespace (server returns 409 SlugNotUniqueError

package/package.json

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

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,10 @@ 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,
@@ -315,6 +317,23 @@ export async function runCli(): Promise<void> {
       // 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/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/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);
+  });
+});

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

@@ -0,0 +1,39 @@
+// src/utils/expected-cli-error.ts
+//
+// Classify errors that are the CALLER's request/state/permission rather than an
+// hq-cli code defect: a bad flag, malformed input, a correctly-denied client
+// 4xx (e.g. a non-owner running `hq integrations approve`). These are
+// user-facing and actionable — the CLI prints a clear message and does NOT
+// report them to Sentry, otherwise a correctly-enforced authorization denial
+// floods the tracker with identical, unfixable crash reports.
+//
+// This is the caller-side analog of hq-pro's `expectedDenialResponse`, and a
+// sibling of `environmental-error.ts` (HQ-CLI-2) and
+// `intercepted-process-exit.ts` (HQ-CLI-3): errors that are NOT hq-cli defects
+// are surfaced to the user but skipped for Sentry capture.
+//
+// HQ-CLI-6: `hq integrations approve|reject` by a non-owner got a correct 403
+// ("Only a company owner can approve or reject queued integration writes"); the
+// thrown error propagated to the top-level handler, which captured it to Sentry
+// as an error-level crash and printed nothing to the user.
+
+/**
+ * An error the CLI should surface to the user (clear message, exit 1) but NOT
+ * report to Sentry. Carriers set `expected: true`.
+ */
+export interface ExpectedUserError extends Error {
+  expected: true;
+}
+
+/**
+ * True when `err` is an Error explicitly marked `expected === true`. A non-null
+ * result means the top-level handler should print `err.message` and skip Sentry
+ * capture. Anything else (unmarked errors, non-Error values) returns false so
+ * genuine faults still reach Sentry.
+ */
+export function isExpectedUserError(err: unknown): err is ExpectedUserError {
+  return (
+    err instanceof Error &&
+    (err as { expected?: unknown }).expected === true
+  );
+}

package/src/utils/vault-api.test.ts

@@ -6,6 +6,7 @@ vi.mock('../sentry.js', () => ({
 
 import { Sentry } from '../sentry.js';
 import { getCompanyUid, getEntityUid, resolveCallerPersonUid, vaultApiFetch } from './vault-api.js';
+import { isAuthError } from './auth-error.js';
 import { isCompanySelectionError } from './company-selection-error.js';
 
 const fetchMock = vi.fn();
@@ -270,6 +271,68 @@ describe('getCompanyUid company-selection classification (HQ-CLI-7)', () => {
   });
 });
 
+describe('resolveCompanyUid 401 → AuthError', () => {
+  it('short-circuits when check-slug/me returns 401 and does not call global by-slug', async () => {
+    fetchMock.mockResolvedValueOnce(mockResponse(401, { error: 'Unauthorized' }));
+
+    const err = await getEntityUid('tok', { companySlug: 'liverecover' }).catch(
+      (e: unknown) => e,
+    );
+
+    expect(isAuthError(err)).toBe(true);
+    expect((err as Error).message).toMatch(/hq login/);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(fetchMock.mock.calls[0][0]).toMatch(/\/entity\/check-slug\/me/);
+  });
+
+  it('classifies a 401 from the global by-slug fallback as an AuthError', async () => {
+    fetchMock
+      .mockResolvedValueOnce(mockResponse(404, { available: true }))
+      .mockResolvedValueOnce(mockResponse(401, { error: 'Unauthorized' }));
+
+    const err = await getCompanyUid('tok', 'liverecover').catch(
+      (e: unknown) => e,
+    );
+
+    expect(isAuthError(err)).toBe(true);
+    expect((err as Error).message).toMatch(/hq login/);
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+  });
+
+  it('keeps a global 409 slug collision on the CompanySelectionError path', async () => {
+    fetchMock
+      .mockResolvedValueOnce(mockResponse(200, { available: true }))
+      .mockResolvedValueOnce(
+        mockResponse(409, {
+          error: 'Slug "liverecover" matches 2 live entities',
+          uids: ['cmp_one', 'cmp_two'],
+        }),
+      );
+
+    const err = await getCompanyUid('tok', 'liverecover').catch(
+      (e: unknown) => e,
+    );
+
+    expect(isAuthError(err)).toBe(false);
+    expect(isCompanySelectionError(err)).toBe(true);
+    expect((err as Error).message).toMatch(/--company cmp_one/);
+  });
+
+  it('keeps a global 500 as a plain company-resolution Error', async () => {
+    fetchMock
+      .mockResolvedValueOnce(mockResponse(200, { available: true }))
+      .mockResolvedValueOnce(mockResponse(500, { error: 'Internal Server Error' }));
+
+    const err = await getCompanyUid('tok', 'liverecover').catch(
+      (e: unknown) => e,
+    );
+
+    expect(err).toBeInstanceOf(Error);
+    expect(isAuthError(err)).toBe(false);
+    expect((err as Error).message).toMatch(/Failed to resolve company slug/);
+  });
+});
+
 describe('vaultApiFetch breadcrumb URL sanitization', () => {
   it('redacts query string in request breadcrumb data.url', async () => {
     fetchMock.mockResolvedValueOnce(mockResponse(200, {}));

package/src/utils/vault-api.ts

@@ -1,5 +1,6 @@
 import { DEFAULT_VAULT_API_URL } from './cognito-session.js';
 import { Sentry } from '../sentry.js';
+import { AuthError } from './auth-error.js';
 import { CompanySelectionError } from './company-selection-error.js';
 
 export interface VaultApiOptions {
@@ -107,12 +108,21 @@ export function looksLikeCompanyUid(ref: string): boolean {
   return ref.startsWith(COMPANY_UID_PREFIX);
 }
 
+// A 401 from ANY vault resolution call means the caller's HQ session is
+// expired or missing — an expected auth state fixed by `hq login`, not a
+// code defect. Raise a typed AuthError so the top-level handler prints an
+// actionable message and skips Sentry capture (HQ-CLI-8).
+function raiseIfUnauthorized(res: Response): void {
+  if (res.status === 401) throw new AuthError();
+}
+
 async function resolveCompanyByUid(token: string, uid: string): Promise<string> {
   const res = await vaultApiFetch({
     token,
     path: `/entity/${encodeURIComponent(uid)}`,
   });
   if (!res.ok) {
+    raiseIfUnauthorized(res);
     const body = (await res.json().catch(() => ({}))) as { error?: string };
     throw new Error(
       `Failed to resolve company '${uid}': ${body.error ?? res.statusText}`,
@@ -150,11 +160,13 @@ async function resolveSlugInCallerNamespace(
     query: { type: 'company', slug },
   });
   if (!res.ok) {
+    raiseIfUnauthorized(res);
     // Namespace lookup unavailable (e.g. membership table not configured →
-    // 503, or the caller has no person entity). Signal "couldn't resolve here"
-    // and let the caller fall back to the global lookup. vaultApiFetch already
-    // recorded the non-2xx as a Sentry breadcrumb, so this is not a silent
-    // swallow.
+    // 503, or the caller has no person entity). A 401 short-circuits above
+    // because the token is bad and the global fallback would only 401 again;
+    // other non-2xx statuses signal "couldn't resolve here" and let the caller
+    // fall back to the global lookup. vaultApiFetch already recorded the
+    // non-2xx as a Sentry breadcrumb, so this is not a silent swallow.
     return null;
   }
   const data = (await res.json()) as {
@@ -188,6 +200,7 @@ async function resolveCompanyUid(token: string, ref: string): Promise<string> {
     path: `/entity/by-slug/company/${encodeURIComponent(ref)}`,
   });
   if (!res.ok) {
+    raiseIfUnauthorized(res);
     const body = (await res.json().catch(() => ({}))) as {
       error?: string;
       uids?: string[];