@indigoai-us/hq-cli 5.38.1 → 5.39.0

package/CHANGELOG.md

@@ -2,6 +2,51 @@
 
 ## [Unreleased]
 
+## [5.39.0]
+
+### Added
+
+- **`hq secrets exists <name>` — HEAD existence probe (HQ-4H).** Checks whether a
+  secret exists without fetching or decrypting its value, so optional-credential
+  readers can HEAD-first instead of blind-`GET`ting:
+  `hq secrets exists FOO && hq secrets get FOO --reveal`. A missing secret no
+  longer fires a spurious server-side `Secret not found` Sentry warning (HQ-4H:
+  706 nameless events / 0 users) — a `HEAD` is by contract an expected-absence
+  probe, so a not-found is its normal answer and is not captured. Exit codes are
+  built for shell chaining: `0` present, `1` absent (the normal "no", not an
+  error), `2` real failure (auth/network/permission) so `&&` chains never
+  mistake an outage for "absent and proceed". `--quiet` suppresses the
+  present/absent line. Backed by the new hq-pro `HEAD
+  /secrets/{companyUid}/name/{proxy+}` route. Callers that genuinely *require* a
+  secret keep `GET`ting directly — their 404s still surface.
+
+## [5.38.2]
+
+### Fixed
+
+- **`--company <slug>` no longer strands a user when two tenants share a slug
+  (DEV-1742 / feedback_a7e5abd9).** Under hq-pro's per-user-namespace model two
+  unrelated tenants may each legitimately hold the same company slug. The shared
+  company resolver resolved `--company` through the **global** `/entity/by-slug`
+  lookup, which `409`s on a collision and told the user to "disambiguate by
+  uid" — but passing that uid back to `--company` was fed into the same by-slug
+  path and `404`d, leaving no working escape (the dead-end behind the
+  liverecover duplicate). The resolver now resolves a slug **within the caller's
+  namespace first** via `/entity/check-slug/me` — within one caller's world a
+  slug is unique (enforced by hq-pro at create/accept/claim), so the caller's
+  own company resolves cleanly and a stranger's same-slug company is invisible.
+  Falls back to the global lookup for cross-company/admin resolutions; a residual
+  multi-match the caller doesn't belong to now yields an actionable
+  `--company <uid>` message; a `cmp_` uid resolves directly as a silent escape
+  hatch. One shared resolver, so this fixes `files`, `members`, `groups`,
+  `group-grants`, `meetings`, and `secrets` at once.
+
+### Changed
+
+- **`hq onboard create-company` guidance** now steers a would-be joiner toward
+  `hq onboard join`, so people stop minting a separate same-named company they're
+  alone in. No create-time behavior change.
+
 ## [5.38.0]
 
 ### Fixed

package/dist/commands/onboard.js

@@ -19,7 +19,7 @@
  * browser-OAuth flow opens automatically.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="8f6c7f48-0ce5-55f3-bfd9-b4a6040adb0b")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="99e9ce57-1051-59ce-8897-edcc83e83a16")}catch(e){}}();
 import chalk from "chalk";
 import { runOnboardCli, readCheckpoint } from "@indigoai-us/hq-onboarding";
 import { DEFAULT_HQ_ROOT, DEFAULT_VAULT_API_URL, ensureCognitoToken, buildVaultConfig, } from "../utils/cognito-session.js";
@@ -34,7 +34,9 @@ export function registerOnboardCommand(program) {
         .description("Provision an HQ vault: sign in, create company, S3 bucket, STS, sync");
     onboard
         .command("create-company")
-        .description("Sign in and provision a brand new HQ vault for a company")
+        .description("Sign in and provision a brand NEW HQ vault for a company. To join a " +
+        "teammate's EXISTING company instead, use `hq onboard join` — creating " +
+        "a same-named company makes a separate one you'd be alone in.")
         .requiredOption("--slug <slug>", "Company slug (used as bucket name suffix)")
         .requiredOption("--name <name>", "Company display name")
         .requiredOption("--email <email>", "Your email (must match Cognito sign-in)")
@@ -46,6 +48,9 @@ export function registerOnboardCommand(program) {
             console.log(`  Company:  ${options.name} (${options.slug})`);
             console.log(`  Person:   ${options.personName} <${options.email}>`);
             console.log(`  HQ root:  ${options.hqRoot}\n`);
+            console.log(chalk.gray("  This creates a NEW company you own. Joining a teammate's existing\n" +
+                "  company? Stop and run `hq onboard join --invite-token <token>` —\n" +
+                "  creating a same-named company leaves you alone in a separate one.\n"));
             const accessToken = await ensureCognitoToken();
             const result = await runOnboardCli({
                 mode: "create-company",
@@ -174,4 +179,4 @@ export function registerOnboardCommand(program) {
     });
 }
 //# sourceMappingURL=onboard.js.map
-//# debugId=8f6c7f48-0ce5-55f3-bfd9-b4a6040adb0b
+//# debugId=99e9ce57-1051-59ce-8897-edcc83e83a16

package/dist/commands/secrets.js

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="b75c8495-7e0e-53f8-a0d2-c92a993e6492")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="7e988c72-7dae-5ad2-aaa3-2c5b430fa5ae")}catch(e){}}();
 import chalk from "chalk";
 import * as readline from "node:readline";
 import { spawn } from "node:child_process";
@@ -227,6 +227,48 @@ export function registerSecretsCommand(program) {
             process.exit(1);
         }
     });
+    // HQ-4H: existence probe via the HEAD route. Optional-credential readers
+    // should HEAD-first so a missing secret no longer fires a spurious GET-404
+    // Sentry warning server-side: `hq secrets exists FOO && hq secrets get FOO …`.
+    // A HEAD never decrypts or reveals the value.
+    //
+    // Exit codes are designed for shell chaining:
+    //   0 → secret exists (200)
+    //   1 → secret is absent (404) — the normal "no" answer, NOT an error
+    //   2 → a real failure (auth/network/permission) — distinct from absence so
+    //       `&&` chains don't mistake an outage for "absent and proceed"
+    secrets
+        .command("exists <name>")
+        .description("Check whether a secret exists (HEAD; exit 0=present, 1=absent, 2=error)")
+        .option("--quiet", "Suppress the present/absent line (use the exit code only)")
+        .action(async (name, opts) => {
+        try {
+            const token = await ensureCognitoToken();
+            const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
+            const res = await vaultApiFetch({
+                token,
+                method: "HEAD",
+                path: buildSecretNamePath(companyUid, name),
+            });
+            if (res.status === 200) {
+                if (!opts.quiet)
+                    console.log(chalk.green(`exists: ${name}`));
+                process.exit(0);
+            }
+            if (res.status === 404) {
+                if (!opts.quiet)
+                    console.log(chalk.dim(`absent: ${name}`));
+                process.exit(1);
+            }
+            // Any other status (401/403/5xx) is a real failure, not an absence.
+            console.error(chalk.red(`Failed to check secret '${name}': HTTP ${res.status} ${res.statusText}`));
+            process.exit(2);
+        }
+        catch (err) {
+            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            process.exit(2);
+        }
+    });
     secrets
         .command("list")
         .description("List all secrets for the company (including nested path-based names)")
@@ -712,4 +754,4 @@ export function registerSecretsCommand(program) {
     });
 }
 //# sourceMappingURL=secrets.js.map
-//# debugId=b75c8495-7e0e-53f8-a0d2-c92a993e6492
+//# debugId=7e988c72-7dae-5ad2-aaa3-2c5b430fa5ae

package/dist/utils/vault-api.d.ts

@@ -17,6 +17,7 @@ export declare function vaultApiFetchPublic(opts: {
     path: string;
     query?: Record<string, string>;
 }): Promise<Response>;
+export declare function looksLikeCompanyUid(ref: string): boolean;
 export declare function getCompanyUid(token: string, companySlug: string | undefined): Promise<string>;
 export declare function resolveCallerPersonUid(token: string): Promise<string>;
 export declare function getEntityUid(token: string, opts: {

package/dist/utils/vault-api.js

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="bdd04f0a-8d43-5072-916d-a801a2f25731")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="85e24f6f-4027-5b00-a4a4-b9a140897d7e")}catch(e){}}();
 import { DEFAULT_VAULT_API_URL } from './cognito-session.js';
 import { Sentry } from '../sentry.js';
 export async function vaultApiFetch(opts) {
@@ -72,14 +72,98 @@ export async function vaultApiFetchPublic(opts) {
     }
     return response;
 }
-async function resolveCompanyUid(token, slug) {
+/**
+ * A `--company` value beginning with `cmp_` is a company UID (globally unique
+ * by ULID), not a slug. Recognised so the resolver can route it directly by
+ * uid — a silent escape hatch, NOT the path users are expected to type.
+ * Mirrors hq-cloud's `KNOWN_UID_PREFIXES` / `context.ts` dispatch so the two
+ * CLI codebases agree on the uid shape.
+ */
+const COMPANY_UID_PREFIX = 'cmp_';
+export function looksLikeCompanyUid(ref) {
+    return ref.startsWith(COMPANY_UID_PREFIX);
+}
+async function resolveCompanyByUid(token, uid) {
     const res = await vaultApiFetch({
         token,
-        path: `/entity/by-slug/company/${encodeURIComponent(slug)}`,
+        path: `/entity/${encodeURIComponent(uid)}`,
     });
     if (!res.ok) {
-        const body = await res.json().catch(() => ({}));
-        throw new Error(`Failed to resolve company slug '${slug}': ${body.error ?? res.statusText}`);
+        const body = (await res.json().catch(() => ({})));
+        throw new Error(`Failed to resolve company '${uid}': ${body.error ?? res.statusText}`);
+    }
+    const data = (await res.json());
+    return data.entity.uid;
+}
+/**
+ * Resolve a company slug WITHIN THE CALLER'S NAMESPACE via the server's
+ * caller-scoped `/entity/check-slug/me` endpoint. Returns the caller's own
+ * company uid for that slug, or `null` when the caller owns / actively belongs
+ * to no company with that slug.
+ *
+ * This is the load-bearing fix for DEV-1742. Under hq-pro's per-user-namespace
+ * model two unrelated tenants may each hold "acme", so the legacy GLOBAL
+ * `/entity/by-slug` lookup 409s `SlugNotUniqueError` on a collision and strands
+ * the caller — exactly how the liverecover duplicate stayed unreachable. But
+ * within ONE caller's world a slug IS unique: hq-pro blocks a second same-slug
+ * company from entering a caller's namespace at every seam — create
+ * (`findSlugInPersonNamespace` in POST /entity), accept (POST /membership/accept
+ * → SlugInUserNamespaceError), and claim (claimByEmail skips the colliding
+ * invite). So "the caller's company called <slug>" is unambiguous, and the
+ * stranger's same-slug company is correctly invisible to resolution. This is
+ * the same primitive hq-cloud's `context.ts` already resolves slugs through.
+ */
+async function resolveSlugInCallerNamespace(token, slug) {
+    const res = await vaultApiFetch({
+        token,
+        path: '/entity/check-slug/me',
+        query: { type: 'company', slug },
+    });
+    if (!res.ok) {
+        // 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.
+        return null;
+    }
+    const data = (await res.json());
+    // `available: false` carries the caller's own company holding the slug.
+    return data.conflictingCompanyUid ?? null;
+}
+async function resolveCompanyUid(token, ref) {
+    // Silent escape hatch: a `cmp_` ref is a uid, not a slug — resolve directly.
+    if (looksLikeCompanyUid(ref)) {
+        return resolveCompanyByUid(token, ref);
+    }
+    // PRIMARY PATH — caller-scoped slug resolution. Resolves the slug to the
+    // caller's OWN company (unique within their namespace by the invariant
+    // above), making a stranger's same-slug company invisible.
+    const mine = await resolveSlugInCallerNamespace(token, ref);
+    if (mine) {
+        return mine;
+    }
+    // The caller owns / belongs to no company with this slug. Fall back to the
+    // GLOBAL by-slug lookup for the cross-company / admin resolutions that
+    // intentionally target a company the caller isn't a member of (e.g. a
+    // group-grant target). A single global match resolves cleanly.
+    const res = await vaultApiFetch({
+        token,
+        path: `/entity/by-slug/company/${encodeURIComponent(ref)}`,
+    });
+    if (!res.ok) {
+        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
+        // with the colliding `uids`). The caller-scoped path can't pick one, so
+        // 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 ` +
+                `is in your namespace. Re-run with --company <uid> to pick one:\n` +
+                body.uids.map((u) => `  --company ${u}`).join('\n'));
+        }
+        throw new Error(`Failed to resolve company slug '${ref}': ${body.error ?? res.statusText}`);
     }
     const data = (await res.json());
     return data.entity.uid;
@@ -100,8 +184,10 @@ async function resolveCompanyFromMemberships(token) {
     if (active.length === 1) {
         return active[0].companyUid;
     }
-    const uids = active.map((m) => m.companyUid).join(', ');
-    throw new Error(`Multiple companies found (${uids}). Use --company <slug> to specify which one.`);
+    const uids = active.map((m) => m.companyUid);
+    throw new Error(`Multiple active companies found. Re-run with --company <slug-or-uid> to ` +
+        `pick one:\n` +
+        uids.map((u) => `  --company ${u}`).join('\n'));
 }
 export async function getCompanyUid(token, companySlug) {
     if (companySlug) {
@@ -143,4 +229,4 @@ export async function getEntityUid(token, opts) {
     return getCompanyUid(token, opts.companySlug);
 }
 //# sourceMappingURL=vault-api.js.map
-//# debugId=bdd04f0a-8d43-5072-916d-a801a2f25731
+//# debugId=85e24f6f-4027-5b00-a4a4-b9a140897d7e

package/package.json

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

package/src/commands/onboard.ts

@@ -43,7 +43,11 @@ export function registerOnboardCommand(program: Command): void {
 
   onboard
     .command("create-company")
-    .description("Sign in and provision a brand new HQ vault for a company")
+    .description(
+      "Sign in and provision a brand NEW HQ vault for a company. To join a " +
+        "teammate's EXISTING company instead, use `hq onboard join` — creating " +
+        "a same-named company makes a separate one you'd be alone in.",
+    )
     .requiredOption("--slug <slug>", "Company slug (used as bucket name suffix)")
     .requiredOption("--name <name>", "Company display name")
     .requiredOption("--email <email>", "Your email (must match Cognito sign-in)")
@@ -65,6 +69,13 @@ export function registerOnboardCommand(program: Command): void {
         console.log(`  Company:  ${options.name} (${options.slug})`);
         console.log(`  Person:   ${options.personName} <${options.email}>`);
         console.log(`  HQ root:  ${options.hqRoot}\n`);
+        console.log(
+          chalk.gray(
+            "  This creates a NEW company you own. Joining a teammate's existing\n" +
+              "  company? Stop and run `hq onboard join --invite-token <token>` —\n" +
+              "  creating a same-named company leaves you alone in a separate one.\n",
+          ),
+        );
 
         const accessToken = await ensureCognitoToken();
         const result = await runOnboardCli({

package/src/commands/secrets.test.ts

@@ -62,6 +62,71 @@ function buildProgram(): Command {
   return program;
 }
 
+// HQ-4H: `hq secrets exists` — HEAD existence probe with shell-chaining exit
+// codes (0=present, 1=absent, 2=error). process.exit is spied so the command's
+// terminal exit doesn't kill the runner; we assert the code it requested.
+describe("secrets exists (HQ-4H HEAD probe)", () => {
+  let exitSpy: MockInstance<typeof process.exit>;
+
+  beforeEach(() => {
+    // Throw so the command stops at its first process.exit (the real runtime
+    // terminates there). The action's own try/catch re-invokes exit(2) on the
+    // thrown sentinel, so we assert on the FIRST recorded exit code — the one
+    // the command actually intended — not the last.
+    exitSpy = vi.spyOn(process, "exit").mockImplementation((() => {
+      throw new Error("__exit__");
+    }) as never);
+  });
+
+  async function firstExitCode(name: string): Promise<number | undefined> {
+    const program = buildProgram();
+    try {
+      await program.parseAsync(["node", "hq", "secrets", "exists", name]);
+    } catch {
+      // sentinel(s) from the exit spy
+    }
+    return exitSpy.mock.calls[0]?.[0] as number | undefined;
+  }
+
+  it("issues a HEAD and intends exit 0 when the secret exists (200)", async () => {
+    vi.mocked(vaultApiFetch).mockResolvedValueOnce(
+      new Response(null, { status: 200 }),
+    );
+
+    const code = await firstExitCode("MY_KEY");
+
+    expect(vaultApiFetch).toHaveBeenCalledWith({
+      token: "test-token",
+      method: "HEAD",
+      path: "/secrets/prs_alice/name/MY_KEY",
+    });
+    expect(code).toBe(0);
+  });
+
+  it("intends exit 1 (absent, not an error) on 404", async () => {
+    vi.mocked(vaultApiFetch).mockResolvedValueOnce(
+      new Response(
+        JSON.stringify({ error: "Secret not found", name: "MISSING" }),
+        { status: 404, headers: { "Content-Type": "application/json" } },
+      ),
+    );
+
+    const code = await firstExitCode("MISSING");
+
+    expect(code).toBe(1);
+  });
+
+  it("intends exit 2 (real failure, distinct from absence) on a 5xx", async () => {
+    vi.mocked(vaultApiFetch).mockResolvedValueOnce(
+      new Response("boom", { status: 503 }),
+    );
+
+    const code = await firstExitCode("MY_KEY");
+
+    expect(code).toBe(2);
+  });
+});
+
 describe("secrets generate-link", () => {
   it("mints one-time submission links for personal secrets", async () => {
     const program = buildProgram();

package/src/commands/secrets.ts

@@ -294,6 +294,58 @@ export function registerSecretsCommand(program: Command): void {
       }
     });
 
+  // HQ-4H: existence probe via the HEAD route. Optional-credential readers
+  // should HEAD-first so a missing secret no longer fires a spurious GET-404
+  // Sentry warning server-side: `hq secrets exists FOO && hq secrets get FOO …`.
+  // A HEAD never decrypts or reveals the value.
+  //
+  // Exit codes are designed for shell chaining:
+  //   0 → secret exists (200)
+  //   1 → secret is absent (404) — the normal "no" answer, NOT an error
+  //   2 → a real failure (auth/network/permission) — distinct from absence so
+  //       `&&` chains don't mistake an outage for "absent and proceed"
+  secrets
+    .command("exists <name>")
+    .description("Check whether a secret exists (HEAD; exit 0=present, 1=absent, 2=error)")
+    .option("--quiet", "Suppress the present/absent line (use the exit code only)")
+    .action(async (name: string, opts: { quiet?: boolean }) => {
+      try {
+        const token = await ensureCognitoToken();
+        const companyUid = await getEntityUid(
+          token,
+          scopeOpts(secrets.opts()),
+        );
+
+        const res = await vaultApiFetch({
+          token,
+          method: "HEAD",
+          path: buildSecretNamePath(companyUid, name),
+        });
+
+        if (res.status === 200) {
+          if (!opts.quiet) console.log(chalk.green(`exists: ${name}`));
+          process.exit(0);
+        }
+        if (res.status === 404) {
+          if (!opts.quiet) console.log(chalk.dim(`absent: ${name}`));
+          process.exit(1);
+        }
+        // Any other status (401/403/5xx) is a real failure, not an absence.
+        console.error(
+          chalk.red(
+            `Failed to check secret '${name}': HTTP ${res.status} ${res.statusText}`,
+          ),
+        );
+        process.exit(2);
+      } catch (err) {
+        console.error(
+          chalk.red("Error:"),
+          err instanceof Error ? err.message : String(err),
+        );
+        process.exit(2);
+      }
+    });
+
   secrets
     .command("list")
     .description("List all secrets for the company (including nested path-based names)")

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

@@ -85,14 +85,98 @@ describe('getEntityUid', () => {
     expect(url).toMatch(/\/entity\/by-type\/person/);
   });
 
-  it('routes to company-slug resolution when companySlug is set', async () => {
+  it('resolves a slug CALLER-SCOPED — to the caller\'s own company, ignoring a stranger\'s same-slug company (DEV-1742)', async () => {
+    // The slug resolves within the caller's namespace via check-slug/me, which
+    // returns the caller's OWN company. A stranger's same-slug company is
+    // invisible — no by-slug 409, no stranding.
     fetchMock.mockResolvedValueOnce(
-      mockResponse(200, { entity: { uid: 'cmp_acme' } }),
+      mockResponse(200, { available: false, conflictingCompanyUid: 'cmp_mine' }),
     );
     const uid = await getEntityUid('tok', { companySlug: 'acme' });
-    expect(uid).toBe('cmp_acme');
+    expect(uid).toBe('cmp_mine');
     const url = fetchMock.mock.calls[0][0] as string;
-    expect(url).toMatch(/\/entity\/by-slug\/company\/acme/);
+    expect(url).toMatch(/\/entity\/check-slug\/me/);
+    // The caller-scoped hit is authoritative — never falls through to by-slug.
+    expect(fetchMock.mock.calls.length).toBe(1);
+  });
+
+  it('falls back to the global by-slug lookup when the slug is not in the caller\'s namespace', async () => {
+    fetchMock
+      .mockResolvedValueOnce(mockResponse(200, { available: true }))
+      .mockResolvedValueOnce(mockResponse(200, { entity: { uid: 'cmp_other' } }));
+    const uid = await getEntityUid('tok', { companySlug: 'other-co' });
+    expect(uid).toBe('cmp_other');
+    expect(fetchMock.mock.calls[0][0]).toMatch(/\/entity\/check-slug\/me/);
+    expect(fetchMock.mock.calls[1][0]).toMatch(/\/entity\/by-slug\/company\/other-co/);
+  });
+
+  it('resolves a cmp_ uid DIRECTLY by uid, never via by-slug (silent escape hatch)', async () => {
+    fetchMock.mockResolvedValueOnce(
+      mockResponse(200, { entity: { uid: 'cmp_01ABC' } }),
+    );
+    const uid = await getEntityUid('tok', { companySlug: 'cmp_01ABC' });
+    expect(uid).toBe('cmp_01ABC');
+    const url = fetchMock.mock.calls[0][0] as string;
+    expect(url).toMatch(/\/entity\/cmp_01ABC$/);
+    expect(url).not.toMatch(/by-slug/);
+    expect(url).not.toMatch(/check-slug/);
+  });
+
+  it('surfaces a clean error when a cmp_ uid does not resolve', async () => {
+    fetchMock.mockResolvedValueOnce(
+      mockResponse(404, { error: 'Entity not found', uid: 'cmp_nope' }),
+    );
+    await expect(
+      getEntityUid('tok', { companySlug: 'cmp_nope' }),
+    ).rejects.toThrow(/Failed to resolve company 'cmp_nope'/);
+  });
+
+  it('falls through to by-slug when the namespace check is unavailable (503)', async () => {
+    fetchMock
+      .mockResolvedValueOnce(mockResponse(503, { error: 'Membership table not configured' }))
+      .mockResolvedValueOnce(mockResponse(200, { entity: { uid: 'cmp_legacy' } }));
+    const uid = await getEntityUid('tok', { companySlug: 'acme' });
+    expect(uid).toBe('cmp_legacy');
+    expect(fetchMock.mock.calls[1][0]).toMatch(/\/entity\/by-slug\/company\/acme/);
+  });
+
+  it('on residual global ambiguity (not in namespace) gives actionable --company <uid> guidance', async () => {
+    // Caller belongs to no "acme"; the slug matches multiple strangers'
+    // companies. The server 409s with the colliding uids and the CLI must tell
+    // the user exactly how to disambiguate.
+    fetchMock
+      .mockResolvedValueOnce(mockResponse(200, { available: true }))
+      .mockResolvedValueOnce(
+        mockResponse(409, {
+          error:
+            'Slug "acme" of type "company" matches 2 live entities — caller must disambiguate by uid or ownerUid',
+          type: 'company',
+          slug: 'acme',
+          uids: ['cmp_one', 'cmp_two'],
+        }),
+      );
+    const err = await getEntityUid('tok', { companySlug: 'acme' }).catch(
+      (e: Error) => e,
+    );
+    expect(err).toBeInstanceOf(Error);
+    expect((err as Error).message).toMatch(/matches 2 companies/);
+    expect((err as Error).message).toMatch(/--company cmp_one/);
+    expect((err as Error).message).toMatch(/--company cmp_two/);
+  });
+
+  it('lists candidate companies when membership fallback is ambiguous', async () => {
+    fetchMock.mockResolvedValueOnce(
+      mockResponse(200, {
+        memberships: [
+          { companyUid: 'cmp_a', role: 'member', status: 'active', membershipKey: 'k1' },
+          { companyUid: 'cmp_b', role: 'owner', status: 'active', membershipKey: 'k2' },
+        ],
+      }),
+    );
+    const err = await getEntityUid('tok', {}).catch((e: Error) => e);
+    expect(err).toBeInstanceOf(Error);
+    expect((err as Error).message).toMatch(/--company cmp_a/);
+    expect((err as Error).message).toMatch(/--company cmp_b/);
   });
 
   it('falls back to membership lookup when neither personal nor slug is set', async () => {

package/src/utils/vault-api.ts

@@ -91,15 +91,118 @@ interface MembershipEntry {
   membershipKey: string;
 }
 
-async function resolveCompanyUid(token: string, slug: string): Promise<string> {
+/**
+ * A `--company` value beginning with `cmp_` is a company UID (globally unique
+ * by ULID), not a slug. Recognised so the resolver can route it directly by
+ * uid — a silent escape hatch, NOT the path users are expected to type.
+ * Mirrors hq-cloud's `KNOWN_UID_PREFIXES` / `context.ts` dispatch so the two
+ * CLI codebases agree on the uid shape.
+ */
+const COMPANY_UID_PREFIX = 'cmp_';
+
+export function looksLikeCompanyUid(ref: string): boolean {
+  return ref.startsWith(COMPANY_UID_PREFIX);
+}
+
+async function resolveCompanyByUid(token: string, uid: string): Promise<string> {
   const res = await vaultApiFetch({
     token,
-    path: `/entity/by-slug/company/${encodeURIComponent(slug)}`,
+    path: `/entity/${encodeURIComponent(uid)}`,
   });
   if (!res.ok) {
-    const body = await res.json().catch(() => ({}));
+    const body = (await res.json().catch(() => ({}))) as { error?: string };
+    throw new Error(
+      `Failed to resolve company '${uid}': ${body.error ?? res.statusText}`,
+    );
+  }
+  const data = (await res.json()) as { entity: { uid: string } };
+  return data.entity.uid;
+}
+
+/**
+ * Resolve a company slug WITHIN THE CALLER'S NAMESPACE via the server's
+ * caller-scoped `/entity/check-slug/me` endpoint. Returns the caller's own
+ * company uid for that slug, or `null` when the caller owns / actively belongs
+ * to no company with that slug.
+ *
+ * This is the load-bearing fix for DEV-1742. Under hq-pro's per-user-namespace
+ * model two unrelated tenants may each hold "acme", so the legacy GLOBAL
+ * `/entity/by-slug` lookup 409s `SlugNotUniqueError` on a collision and strands
+ * the caller — exactly how the liverecover duplicate stayed unreachable. But
+ * within ONE caller's world a slug IS unique: hq-pro blocks a second same-slug
+ * company from entering a caller's namespace at every seam — create
+ * (`findSlugInPersonNamespace` in POST /entity), accept (POST /membership/accept
+ * → SlugInUserNamespaceError), and claim (claimByEmail skips the colliding
+ * invite). So "the caller's company called <slug>" is unambiguous, and the
+ * stranger's same-slug company is correctly invisible to resolution. This is
+ * the same primitive hq-cloud's `context.ts` already resolves slugs through.
+ */
+async function resolveSlugInCallerNamespace(
+  token: string,
+  slug: string,
+): Promise<string | null> {
+  const res = await vaultApiFetch({
+    token,
+    path: '/entity/check-slug/me',
+    query: { type: 'company', slug },
+  });
+  if (!res.ok) {
+    // 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.
+    return null;
+  }
+  const data = (await res.json()) as {
+    available?: boolean;
+    conflictingCompanyUid?: string;
+  };
+  // `available: false` carries the caller's own company holding the slug.
+  return data.conflictingCompanyUid ?? null;
+}
+
+async function resolveCompanyUid(token: string, ref: string): Promise<string> {
+  // Silent escape hatch: a `cmp_` ref is a uid, not a slug — resolve directly.
+  if (looksLikeCompanyUid(ref)) {
+    return resolveCompanyByUid(token, ref);
+  }
+
+  // PRIMARY PATH — caller-scoped slug resolution. Resolves the slug to the
+  // caller's OWN company (unique within their namespace by the invariant
+  // above), making a stranger's same-slug company invisible.
+  const mine = await resolveSlugInCallerNamespace(token, ref);
+  if (mine) {
+    return mine;
+  }
+
+  // The caller owns / belongs to no company with this slug. Fall back to the
+  // GLOBAL by-slug lookup for the cross-company / admin resolutions that
+  // intentionally target a company the caller isn't a member of (e.g. a
+  // group-grant target). A single global match resolves cleanly.
+  const res = await vaultApiFetch({
+    token,
+    path: `/entity/by-slug/company/${encodeURIComponent(ref)}`,
+  });
+  if (!res.ok) {
+    const body = (await res.json().catch(() => ({}))) as {
+      error?: string;
+      uids?: string[];
+    };
+    // Residual true ambiguity: the slug matches multiple live companies and
+    // NONE is in the caller's namespace (server returns 409 SlugNotUniqueError
+    // with the colliding `uids`). The caller-scoped path can't pick one, so
+    // 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 ` +
+          `is in your namespace. Re-run with --company <uid> to pick one:\n` +
+          body.uids.map((u) => `  --company ${u}`).join('\n'),
+      );
+    }
     throw new Error(
-      `Failed to resolve company slug '${slug}': ${(body as Record<string, string>).error ?? res.statusText}`,
+      `Failed to resolve company slug '${ref}': ${body.error ?? res.statusText}`,
     );
   }
   const data = (await res.json()) as { entity: { uid: string } };
@@ -122,9 +225,11 @@ async function resolveCompanyFromMemberships(token: string): Promise<string> {
   if (active.length === 1) {
     return active[0].companyUid;
   }
-  const uids = active.map((m) => m.companyUid).join(', ');
+  const uids = active.map((m) => m.companyUid);
   throw new Error(
-    `Multiple companies found (${uids}). Use --company <slug> to specify which one.`,
+    `Multiple active companies found. Re-run with --company <slug-or-uid> to ` +
+      `pick one:\n` +
+      uids.map((u) => `  --company ${u}`).join('\n'),
   );
 }