@indigoai-us/hq-cli 5.72.0 → 5.73.1

package/dist/commands/outposts.d.ts

@@ -73,6 +73,13 @@ export declare function listOutposts(token: string): Promise<OutpostSummary[]>;
 export declare function getOutpostStatus(token: string, outpostId?: string): Promise<Record<string, unknown>>;
 export declare function enableCodex(token: string, outpostId?: string): Promise<Record<string, unknown>>;
 export declare function regenerateLoginUrl(token: string, outpostId?: string): Promise<Record<string, unknown>>;
+/**
+ * Hand the box the one-time Claude sign-in code the operator got from the login
+ * URL. hq-pro stores it as the row's pending code; the box polls for it, feeds
+ * it to `claude`, and flips itself `awaiting-claude-login → ready`. This is the
+ * terminal-native equivalent of pasting the code into the web console.
+ */
+export declare function submitLoginCode(token: string, code: string, outpostId?: string): Promise<Record<string, unknown>>;
 export declare function destroyOutpost(token: string, outpostId?: string): Promise<Record<string, unknown>>;
 /** Result of `POST /outpost/exec` — a terminal SSM invocation on the box. */
 export interface OutpostExecResult {

package/dist/commands/outposts.js

@@ -116,6 +116,21 @@ export async function regenerateLoginUrl(token, outpostId) {
         query: outpostId ? { outpostId } : undefined,
     });
 }
+/**
+ * Hand the box the one-time Claude sign-in code the operator got from the login
+ * URL. hq-pro stores it as the row's pending code; the box polls for it, feeds
+ * it to `claude`, and flips itself `awaiting-claude-login → ready`. This is the
+ * terminal-native equivalent of pasting the code into the web console.
+ */
+export async function submitLoginCode(token, code, outpostId) {
+    return outpostRequest({
+        token,
+        path: "/outpost/login-code",
+        method: "POST",
+        body: { code },
+        query: outpostId ? { outpostId } : undefined,
+    });
+}
 export async function destroyOutpost(token, outpostId) {
     return outpostRequest({
         token,
@@ -1011,8 +1026,40 @@ export function registerOutpostsCommand(program, selfDeployOverrides = {}) {
                 process.stdout.write(JSON.stringify(result, null, 2) + "\n");
                 return;
             }
-            console.log(chalk.green("Login-URL regeneration requested. The box mints a fresh URL shortly — " +
-                "check `hq outposts status` to pick it up."));
+            console.log(chalk.green("Login-URL regeneration requested. The box mints a fresh URL shortly."));
+            console.log(chalk.dim("Next: `hq outposts status" +
+                (opts.id ? ` --id ${opts.id}` : "") +
+                "` to read the login URL, open it and sign in, then paste the code back with " +
+                "`hq outposts login-code <code>" +
+                (opts.id ? ` --id ${opts.id}` : "") +
+                "`."));
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    outposts
+        .command("login-code <code>")
+        .description("Submit the Claude sign-in code for an Outpost that is awaiting login")
+        .option("--id <outpostId>", "Outpost id (defaults to your primary box)")
+        .option("--json", "Emit raw JSON")
+        .action(async function (code, opts) {
+        try {
+            const trimmed = code.trim();
+            if (!trimmed) {
+                console.error(chalk.red("Provide the sign-in code: hq outposts login-code <code>"));
+                process.exit(1);
+            }
+            const token = await ensureCognitoToken();
+            const result = await submitLoginCode(token, trimmed, opts.id);
+            if (opts.json) {
+                process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+                return;
+            }
+            console.log(chalk.green("Code submitted — the box will finish signing in shortly."));
+            console.log(chalk.dim("Track it: `hq outposts status" +
+                (opts.id ? ` --id ${opts.id}` : "") +
+                "` (it flips to `ready` once Claude auth completes)."));
         }
         catch (err) {
             fail(err);

package/dist/main.js

@@ -60,6 +60,7 @@ import { sanitizeArgv } from "./utils/feedback-diagnostics.js";
 import { environmentalFsErrorMessage } from "./utils/environmental-error.js";
 import { isEpipe } from "./utils/epipe.js";
 import { isInterceptedProcessExit } from "./utils/intercepted-process-exit.js";
+import { isCompanySelectionError } from "./utils/company-selection-error.js";
 import { maybeWarnNewVersion, refreshVersionCache, } from "./utils/version-check.js";
 import { enforceVersionGate, shouldSkipGate, } from "./utils/version-gate.js";
 import { CLI_VERSION } from "./cli-version.js";
@@ -253,6 +254,18 @@ export async function runCli() {
             // 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.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/company-selection-error.d.ts

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

package/dist/utils/company-selection-error.js

@@ -0,0 +1,44 @@
+// 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) {
+        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) {
+    return err instanceof CompanySelectionError;
+}
+//# sourceMappingURL=company-selection-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 { CompanySelectionError } from './company-selection-error.js';
 export async function vaultApiFetch(opts) {
     const url = new URL(opts.path, DEFAULT_VAULT_API_URL);
     if (opts.query) {
@@ -158,7 +159,7 @@ async function resolveCompanyUid(token, ref) {
         // tell them exactly how — re-run with `--company <uid>` — and list the
         // candidates, instead of echoing the generic server message.
         if (res.status === 409 && Array.isArray(body.uids) && body.uids.length > 0) {
-            throw new Error(`Company slug '${ref}' matches ${body.uids.length} companies and none ` +
+            throw new CompanySelectionError(`Company slug '${ref}' matches ${body.uids.length} companies and none ` +
                 `is in your namespace. Re-run with --company <uid> to pick one:\n` +
                 body.uids.map((u) => `  --company ${u}`).join('\n'));
         }
@@ -178,13 +179,13 @@ async function resolveCompanyFromMemberships(token) {
     const data = (await res.json());
     const active = data.memberships.filter((m) => m.status === 'active');
     if (active.length === 0) {
-        throw new Error('No active company memberships found. Use --company <slug> to specify.');
+        throw new CompanySelectionError('No active company memberships found. Use --company <slug> to specify.');
     }
     if (active.length === 1) {
         return active[0].companyUid;
     }
     const uids = active.map((m) => m.companyUid);
-    throw new Error(`Multiple active companies found. Re-run with --company <slug-or-uid> to ` +
+    throw new CompanySelectionError(`Multiple active companies found. Re-run with --company <slug-or-uid> to ` +
         `pick one:\n` +
         uids.map((u) => `  --company ${u}`).join('\n'));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.72.0",
+  "version": "5.73.1",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -20,6 +20,7 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
+    "@aws-sdk/client-s3": "^3.1049.0",
     "@indigoai-us/hq-cloud": "^6.14.4",
     "@indigoai-us/hq-onboarding": "^0.1.0",
     "@sentry/node": "^10.49.0",
@@ -34,7 +35,6 @@
     "varlock": "1.0.0"
   },
   "devDependencies": {
-    "@aws-sdk/client-s3": "^3.1049.0",
     "@eslint/js": "^10.0.1",
     "@types/better-sqlite3": "^7.6.13",
     "@types/js-yaml": "^4.0.9",

package/src/commands/outposts.test.ts

@@ -171,6 +171,38 @@ describe("hq outposts codex-enable / login", () => {
     expect(String(url)).toContain("/outpost/regenerate-login-url");
     expect(init?.method).toBe("POST");
   });
+
+  it("login-code POSTs /outpost/login-code with the code in the body", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, { ok: true, userId: "u1" }));
+    await run(["outposts", "login-code", "ABC-123"]);
+    const [url, init] = fetchSpy.mock.calls[0];
+    expect(String(url)).toContain("/outpost/login-code");
+    expect(init?.method).toBe("POST");
+    expect(JSON.parse(String(init?.body))).toEqual({ code: "ABC-123" });
+  });
+
+  it("login-code targets a specific box via --id (outpostId query)", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, { ok: true, userId: "u1" }));
+    await run(["outposts", "login-code", "CODE", "--id", "3"]);
+    const [url] = fetchSpy.mock.calls[0];
+    expect(String(url)).toContain("outpostId=3");
+  });
+
+  it("login-code trims whitespace and refuses an empty code without calling the API", async () => {
+    await expect(run(["outposts", "login-code", "   "])).rejects.toThrow(
+      "process.exit(1)",
+    );
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  it("login-code surfaces an awaiting-login not-found error", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(404, { error: true, step: "not-found", message: "no outpost" }),
+    );
+    await expect(run(["outposts", "login-code", "CODE"])).rejects.toThrow(
+      "process.exit(1)",
+    );
+  });
 });
 
 describe("hq outposts destroy", () => {

package/src/commands/outposts.ts

@@ -182,6 +182,26 @@ export async function regenerateLoginUrl(
   });
 }
 
+/**
+ * Hand the box the one-time Claude sign-in code the operator got from the login
+ * URL. hq-pro stores it as the row's pending code; the box polls for it, feeds
+ * it to `claude`, and flips itself `awaiting-claude-login → ready`. This is the
+ * terminal-native equivalent of pasting the code into the web console.
+ */
+export async function submitLoginCode(
+  token: string,
+  code: string,
+  outpostId?: string,
+): Promise<Record<string, unknown>> {
+  return outpostRequest({
+    token,
+    path: "/outpost/login-code",
+    method: "POST",
+    body: { code },
+    query: outpostId ? { outpostId } : undefined,
+  });
+}
+
 export async function destroyOutpost(
   token: string,
   outpostId?: string,
@@ -1450,8 +1470,58 @@ export function registerOutpostsCommand(
         }
         console.log(
           chalk.green(
-            "Login-URL regeneration requested. The box mints a fresh URL shortly — " +
-              "check `hq outposts status` to pick it up.",
+            "Login-URL regeneration requested. The box mints a fresh URL shortly.",
+          ),
+        );
+        console.log(
+          chalk.dim(
+            "Next: `hq outposts status" +
+              (opts.id ? ` --id ${opts.id}` : "") +
+              "` to read the login URL, open it and sign in, then paste the code back with " +
+              "`hq outposts login-code <code>" +
+              (opts.id ? ` --id ${opts.id}` : "") +
+              "`.",
+          ),
+        );
+      } catch (err) {
+        fail(err);
+      }
+    });
+
+  outposts
+    .command("login-code <code>")
+    .description(
+      "Submit the Claude sign-in code for an Outpost that is awaiting login",
+    )
+    .option("--id <outpostId>", "Outpost id (defaults to your primary box)")
+    .option("--json", "Emit raw JSON")
+    .action(async function (
+      this: Command,
+      code: string,
+      opts: { id?: string; json?: boolean },
+    ) {
+      try {
+        const trimmed = code.trim();
+        if (!trimmed) {
+          console.error(chalk.red("Provide the sign-in code: hq outposts login-code <code>"));
+          process.exit(1);
+        }
+        const token = await ensureCognitoToken();
+        const result = await submitLoginCode(token, trimmed, opts.id);
+        if (opts.json) {
+          process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+          return;
+        }
+        console.log(
+          chalk.green(
+            "Code submitted — the box will finish signing in shortly.",
+          ),
+        );
+        console.log(
+          chalk.dim(
+            "Track it: `hq outposts status" +
+              (opts.id ? ` --id ${opts.id}` : "") +
+              "` (it flips to `ready` once Claude auth completes).",
           ),
         );
       } catch (err) {

package/src/main.ts

@@ -62,6 +62,7 @@ import { sanitizeArgv } from "./utils/feedback-diagnostics.js";
 import { environmentalFsErrorMessage } from "./utils/environmental-error.js";
 import { isEpipe } from "./utils/epipe.js";
 import { isInterceptedProcessExit } from "./utils/intercepted-process-exit.js";
+import { isCompanySelectionError } from "./utils/company-selection-error.js";
 import {
   maybeWarnNewVersion,
   refreshVersionCache,
@@ -303,6 +304,17 @@ 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 {
       // 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/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/vault-api.test.ts

@@ -5,7 +5,8 @@ vi.mock('../sentry.js', () => ({
 }));
 
 import { Sentry } from '../sentry.js';
-import { getEntityUid, resolveCallerPersonUid, vaultApiFetch } from './vault-api.js';
+import { getCompanyUid, getEntityUid, resolveCallerPersonUid, vaultApiFetch } from './vault-api.js';
+import { isCompanySelectionError } from './company-selection-error.js';
 
 const fetchMock = vi.fn();
 const originalFetch = globalThis.fetch;
@@ -199,6 +200,76 @@ describe('getEntityUid', () => {
   });
 });
 
+describe('getCompanyUid company-selection classification (HQ-CLI-7)', () => {
+  // The exact production scenario: a user with multiple active memberships runs
+  // a command with no --company. The prompt is expected, user-actionable guidance
+  // — it must be a CompanySelectionError so the top-level handler prints it and
+  // SKIPS Sentry capture, not a plain Error that gets shipped as a fatal.
+  it('throws a CompanySelectionError (not a plain Error) on multiple active memberships', async () => {
+    fetchMock.mockResolvedValueOnce(
+      mockResponse(200, {
+        memberships: [
+          { companyUid: 'cmp_a', role: 'member', status: 'active', membershipKey: 'k1' },
+          { companyUid: 'cmp_b', role: 'owner', status: 'active', membershipKey: 'k2' },
+          { companyUid: 'cmp_c', role: 'member', status: 'active', membershipKey: 'k3' },
+        ],
+      }),
+    );
+    const err = await getCompanyUid('tok', undefined).catch((e: unknown) => e);
+    expect(isCompanySelectionError(err)).toBe(true);
+    expect((err as Error).message).toMatch(/Multiple active companies found/);
+    expect((err as Error).message).toMatch(/--company cmp_a/);
+  });
+
+  it('throws a CompanySelectionError when the caller has no active memberships', async () => {
+    fetchMock.mockResolvedValueOnce(
+      mockResponse(200, {
+        memberships: [
+          { companyUid: 'cmp_x', role: 'member', status: 'invited', membershipKey: 'k' },
+        ],
+      }),
+    );
+    const err = await getCompanyUid('tok', undefined).catch((e: unknown) => e);
+    expect(isCompanySelectionError(err)).toBe(true);
+    expect((err as Error).message).toMatch(/No active company memberships/);
+  });
+
+  it('resolves silently to the single active membership (no selection error)', async () => {
+    fetchMock.mockResolvedValueOnce(
+      mockResponse(200, {
+        memberships: [
+          { companyUid: 'cmp_only', role: 'member', status: 'active', membershipKey: 'k' },
+        ],
+      }),
+    );
+    const uid = await getCompanyUid('tok', undefined);
+    expect(uid).toBe('cmp_only');
+  });
+
+  it('classifies the slug-collision (409, none in namespace) case as a selection error', async () => {
+    fetchMock
+      .mockResolvedValueOnce(mockResponse(200, { available: true }))
+      .mockResolvedValueOnce(
+        mockResponse(409, {
+          error: 'Slug "acme" matches 2 live entities',
+          uids: ['cmp_one', 'cmp_two'],
+        }),
+      );
+    const err = await getCompanyUid('tok', 'acme').catch((e: unknown) => e);
+    expect(isCompanySelectionError(err)).toBe(true);
+    expect((err as Error).message).toMatch(/--company cmp_one/);
+  });
+
+  // A genuine fault must NOT be classified as a selection prompt — it still
+  // reports to Sentry. Guards against over-broadening the carve-out.
+  it('does NOT classify a failed membership fetch as a selection error (still reports)', async () => {
+    fetchMock.mockResolvedValueOnce(mockResponse(401, { error: 'unauthorized' }));
+    const err = await getCompanyUid('tok', undefined).catch((e: unknown) => e);
+    expect(isCompanySelectionError(err)).toBe(false);
+    expect((err as Error).message).toMatch(/Failed to fetch memberships/);
+  });
+});
+
 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 { CompanySelectionError } from './company-selection-error.js';
 
 export interface VaultApiOptions {
   token: string;
@@ -197,7 +198,7 @@ async function resolveCompanyUid(token: string, ref: string): Promise<string> {
     // tell them exactly how — re-run with `--company <uid>` — and list the
     // candidates, instead of echoing the generic server message.
     if (res.status === 409 && Array.isArray(body.uids) && body.uids.length > 0) {
-      throw new Error(
+      throw new CompanySelectionError(
         `Company slug '${ref}' matches ${body.uids.length} companies and none ` +
           `is in your namespace. Re-run with --company <uid> to pick one:\n` +
           body.uids.map((u) => `  --company ${u}`).join('\n'),
@@ -222,13 +223,13 @@ async function resolveCompanyFromMemberships(token: string): Promise<string> {
   const data = (await res.json()) as { memberships: MembershipEntry[] };
   const active = data.memberships.filter((m) => m.status === 'active');
   if (active.length === 0) {
-    throw new Error('No active company memberships found. Use --company <slug> to specify.');
+    throw new CompanySelectionError('No active company memberships found. Use --company <slug> to specify.');
   }
   if (active.length === 1) {
     return active[0].companyUid;
   }
   const uids = active.map((m) => m.companyUid);
-  throw new Error(
+  throw new CompanySelectionError(
     `Multiple active companies found. Re-run with --company <slug-or-uid> to ` +
       `pick one:\n` +
       uids.map((u) => `  --company ${u}`).join('\n'),