@indigoai-us/hq-cli 5.73.1 → 5.75.0

package/src/commands/outposts.ts

@@ -268,6 +268,8 @@ export interface OutpostExecSubmission {
   instanceId: string;
   commandId: string;
   outputPrefix: string;
+  /** Shell budget applied server-side (AWS-RunShellScript executionTimeout). */
+  executionTimeoutSeconds?: number;
 }
 
 /** Poll response from `mode: "result"`; streams arrive only when terminal. */
@@ -300,12 +302,17 @@ export async function submitExec(
   token: string,
   command: string,
   outpostId?: string,
+  timeoutSeconds?: number,
 ): Promise<OutpostExecSubmission> {
   return outpostRequest({
     token,
     path: "/outpost/exec",
     method: "POST",
-    body: { mode: "submit", command },
+    body: {
+      mode: "submit",
+      command,
+      ...(timeoutSeconds !== undefined ? { timeoutSeconds } : {}),
+    },
     query: outpostId ? { outpostId } : undefined,
   });
 }
@@ -364,14 +371,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 {
@@ -1249,14 +1257,40 @@ export function registerOutpostsCommand(
   outposts
     .command("exec <command...>")
     .description(
-      "Run a shell command on an Outpost and print its output (use -- before flags meant for the remote command)",
+      "Run a shell command on an Outpost and print its output (use -- before flags meant for the remote command). " +
+        "Default is synchronous (API Gateway ~20s cap). Use --async for long jobs, or --detach to print the commandId and return immediately.",
     )
     .option("--id <outpostId>", "Outpost id (defaults to your primary box)")
+    .option(
+      "--async",
+      "Submit via the async transport and wait for completion (bypasses the ~20s sync cap; shell budget defaults to 48h)",
+    )
+    .option(
+      "--detach",
+      "Submit via the async transport, print commandId, and return immediately (pair with `hq outposts exec-result --wait`)",
+    )
+    .option(
+      "--timeout-seconds <n>",
+      "Async shell budget in seconds (AWS-RunShellScript executionTimeout; 1..172800). Implies --async unless --detach is set.",
+      (v: string) => {
+        const n = Number(v);
+        if (!Number.isInteger(n)) {
+          throw new Error("--timeout-seconds must be an integer");
+        }
+        return n;
+      },
+    )
     .option("--json", "Emit raw JSON")
     .action(async function (
       this: Command,
       commandParts: string[],
-      opts: { id?: string; json?: boolean },
+      opts: {
+        id?: string;
+        json?: boolean;
+        async?: boolean;
+        detach?: boolean;
+        timeoutSeconds?: number;
+      },
     ) {
       try {
         const command = joinCommandParts(commandParts);
@@ -1264,11 +1298,137 @@ export function registerOutpostsCommand(
           console.error(chalk.red("No command given. Usage: hq outposts exec -- <command>"));
           process.exit(1);
         }
+        if (opts.async && opts.detach) {
+          console.error(
+            chalk.red("Use either --async (submit + wait) or --detach (submit only), not both."),
+          );
+          process.exit(1);
+        }
+        // --timeout-seconds only applies to the async path; bare use implies --async.
+        const useAsync =
+          Boolean(opts.async) ||
+          Boolean(opts.detach) ||
+          opts.timeoutSeconds !== undefined;
+        if (opts.timeoutSeconds !== undefined) {
+          if (
+            !Number.isInteger(opts.timeoutSeconds) ||
+            opts.timeoutSeconds < 1 ||
+            opts.timeoutSeconds > 172_800
+          ) {
+            console.error(
+              chalk.red(
+                "--timeout-seconds must be an integer between 1 and 172800 (48h, the AWS-RunShellScript max)",
+              ),
+            );
+            process.exit(1);
+          }
+        }
         const token = await ensureCognitoToken();
 
         // Run from the box's HQ folder by default (works over both SSM and SSH).
         const remoteCommand = withRemoteHqDir(command);
 
+        if (useAsync) {
+          try {
+            const submitted = await submitExec(
+              token,
+              remoteCommand,
+              opts.id,
+              opts.timeoutSeconds,
+            );
+            if (opts.detach) {
+              const output = {
+                commandId: submitted.commandId,
+                ...(submitted.executionTimeoutSeconds !== undefined
+                  ? { executionTimeoutSeconds: submitted.executionTimeoutSeconds }
+                  : opts.timeoutSeconds !== undefined
+                    ? { executionTimeoutSeconds: opts.timeoutSeconds }
+                    : {}),
+              };
+              if (opts.json) {
+                process.stdout.write(JSON.stringify(output) + "\n");
+              } else {
+                printKeyValues(output);
+                console.error(
+                  chalk.dim(
+                    "Submitted. Poll with: hq outposts exec-result --command-id " +
+                      submitted.commandId +
+                      (opts.id ? ` --id ${opts.id}` : "") +
+                      " --wait",
+                  ),
+                );
+              }
+              return;
+            }
+
+            // --async (or --timeout-seconds without --detach): wait for terminal.
+            if (!opts.json) {
+              console.error(
+                chalk.dim(
+                  `Submitted ${submitted.commandId}; waiting for completion…`,
+                ),
+              );
+            }
+            const result = await waitForExecResult(
+              token,
+              submitted.commandId,
+              opts.id,
+            );
+            if (opts.json) {
+              process.stdout.write(
+                JSON.stringify(
+                  {
+                    commandId: submitted.commandId,
+                    done: result.done,
+                    status: result.status,
+                    exitCode: result.exitCode ?? null,
+                    stdout: result.stdout ?? "",
+                    stderr: result.stderr ?? "",
+                    truncated: result.truncated ?? false,
+                  },
+                  null,
+                  2,
+                ) + "\n",
+              );
+            } else {
+              if (result.stdout) process.stdout.write(result.stdout);
+              if (result.stderr) process.stderr.write(result.stderr);
+              if (result.truncated) {
+                console.error(
+                  chalk.yellow(
+                    "(output truncated — redirect to a file on the box for full output)",
+                  ),
+                );
+              }
+              if (result.status !== "Success" && result.exitCode === null) {
+                console.error(
+                  chalk.yellow(`(command ended with SSM status: ${result.status})`),
+                );
+              }
+            }
+            process.exitCode =
+              typeof result.exitCode === "number" ? result.exitCode : 0;
+            return;
+          } catch (err) {
+            // Async requires EC2/SSM. Lightsail has no async channel — refuse
+            // rather than silently falling back to a live SSH hold, which is
+            // the exact timeout failure mode --async is meant to escape.
+            if (
+              err instanceof OutpostHttpError &&
+              err.step === "platform-unsupported"
+            ) {
+              console.error(
+                chalk.red(
+                  "Async exec requires an EC2 Outpost (SSM). This box is Lightsail — " +
+                    "re-provision on EC2, or run a short sync command / SSH session instead.",
+                ),
+              );
+              process.exit(1);
+            }
+            throw err;
+          }
+        }
+
         try {
           const result = await execOutpost(token, remoteCommand, opts.id);
           if (opts.json) {
@@ -1368,13 +1528,26 @@ export function registerOutpostsCommand(
 
   outposts
     .command("exec-submit <command...>")
-    .description("Submit an asynchronous shell command to an Outpost")
+    .description(
+      "Submit an asynchronous shell command to an Outpost (returns immediately with commandId; shell budget defaults to 48h)",
+    )
     .option("--id <outpostId>", "Outpost id (defaults to your primary box)")
+    .option(
+      "--timeout-seconds <n>",
+      "Shell budget in seconds (AWS-RunShellScript executionTimeout; 1..172800)",
+      (v: string) => {
+        const n = Number(v);
+        if (!Number.isInteger(n)) {
+          throw new Error("--timeout-seconds must be an integer");
+        }
+        return n;
+      },
+    )
     .option("--json", "Emit raw JSON")
     .action(async function (
       this: Command,
       commandParts: string[],
-      opts: { id?: string; json?: boolean },
+      opts: { id?: string; json?: boolean; timeoutSeconds?: number },
     ) {
       try {
         const command = joinCommandParts(commandParts);
@@ -1384,9 +1557,38 @@ export function registerOutpostsCommand(
           );
           process.exit(1);
         }
+        if (opts.timeoutSeconds !== undefined) {
+          if (
+            !Number.isInteger(opts.timeoutSeconds) ||
+            opts.timeoutSeconds < 1 ||
+            opts.timeoutSeconds > 172_800
+          ) {
+            console.error(
+              chalk.red(
+                "--timeout-seconds must be an integer between 1 and 172800 (48h)",
+              ),
+            );
+            process.exit(1);
+          }
+        }
         const token = await ensureCognitoToken();
-        const submitted = await submitExec(token, command, opts.id);
-        const output = { commandId: submitted.commandId };
+        // exec-submit is the raw fire-and-forget path — do NOT wrap with
+        // withRemoteHqDir here (callers that want the HQ cwd use `exec --async`
+        // or prefix their own cd). Matches the existing contract.
+        const submitted = await submitExec(
+          token,
+          command,
+          opts.id,
+          opts.timeoutSeconds,
+        );
+        const output = {
+          commandId: submitted.commandId,
+          ...(submitted.executionTimeoutSeconds !== undefined
+            ? { executionTimeoutSeconds: submitted.executionTimeoutSeconds }
+            : opts.timeoutSeconds !== undefined
+              ? { executionTimeoutSeconds: opts.timeoutSeconds }
+              : {}),
+        };
         if (opts.json) {
           process.stdout.write(JSON.stringify(output) + "\n");
         } else {

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[];