@indigoai-us/hq-cli 5.15.0 → 5.17.0-sources-rc.0

package/scripts/smoke-sources-signals.sh

@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+#
+# smoke-sources-signals.sh — end-to-end verification of `hq sources` /
+# `hq signals` against a real vault bucket. Owned by US-008 of the
+# hq-cli-sources-signals PRD.
+#
+# Usage:
+#   # 1. Make sure you have a working Cognito session OR export a token:
+#   hq whoami            # interactive Cognito login if needed
+#   #   or: export HQ_ACCESS_TOKEN="$(...)"   # service-account JWT bypass
+#
+#   # 2. Run the smoke against an entity slug you have access to (default: indigo):
+#   ./scripts/smoke-sources-signals.sh              # uses ENTITY=indigo
+#   ENTITY=personal ./scripts/smoke-sources-signals.sh
+#
+# Behavior:
+#   Runs four CLI invocations, each asserted to exit 0 AND produce parseable
+#   JSON (where --format json is used). Stdout from each invocation is
+#   appended to a temp file; the script prints a summary table at the end.
+#
+# Exit codes:
+#   0  all four invocations succeeded and produced valid JSON
+#   1  one or more invocations failed (script aborts on first failure with set -e)
+#
+# Dependencies:
+#   - hq (built locally via `pnpm --filter @indigoai-us/hq-cli build`, or
+#     `npx @indigoai-us/hq-cli@rc ...` against a published rc)
+#   - jq (for JSON validation)
+#
+
+set -euo pipefail
+
+ENTITY="${ENTITY:-indigo}"
+LIMIT="${LIMIT:-5}"
+HQ_BIN="${HQ_BIN:-hq}"
+
+# Resolve workspace-local journal location for capturing output. The
+# operator running this script may redirect the script's stdout to a journal
+# file under companies/indigo/projects/hq-cli-sources-signals/journal/.
+SMOKE_TMP="$(mktemp -d -t hq-smoke-XXXXXX)"
+trap 'rm -rf "$SMOKE_TMP"' EXIT
+
+echo "==> hq sources/signals smoke for entity=$ENTITY limit=$LIMIT"
+echo "    binary: $HQ_BIN"
+echo "    tmpdir: $SMOKE_TMP"
+echo
+
+require_cmd() {
+  if ! command -v "$1" >/dev/null 2>&1; then
+    echo "ERROR: required command '$1' not found in PATH" >&2
+    exit 1
+  fi
+}
+
+require_cmd "$HQ_BIN"
+require_cmd jq
+
+# --- 1. entities -----------------------------------------------------------
+echo "[1/4] hq sources entities"
+"$HQ_BIN" sources entities --format json > "$SMOKE_TMP/entities.json"
+jq -e 'type == "array"' "$SMOKE_TMP/entities.json" > /dev/null
+ENTITY_COUNT=$(jq 'length' "$SMOKE_TMP/entities.json")
+echo "      ok — $ENTITY_COUNT entity/entities visible"
+echo
+
+# --- 2. sources channels (no auth required) --------------------------------
+echo "[2/4] hq sources channels"
+"$HQ_BIN" sources channels > "$SMOKE_TMP/channels.txt"
+grep -qx 'meeting' "$SMOKE_TMP/channels.txt"
+grep -qx 'email' "$SMOKE_TMP/channels.txt"
+grep -qx 'slack' "$SMOKE_TMP/channels.txt"
+grep -qx 'linear' "$SMOKE_TMP/channels.txt"
+grep -qx 'notion' "$SMOKE_TMP/channels.txt"
+echo "      ok — all five canonical channels present"
+echo
+
+# --- 3. sources list --type meeting (the headline acceptance criterion) ---
+echo "[3/4] hq sources list --entity $ENTITY --type meeting --limit $LIMIT --format json"
+"$HQ_BIN" sources list \
+  --entity "$ENTITY" \
+  --type meeting \
+  --limit "$LIMIT" \
+  --format json > "$SMOKE_TMP/sources-list.json"
+jq -e '.entries | type == "array"' "$SMOKE_TMP/sources-list.json" > /dev/null
+SOURCE_COUNT=$(jq '.entries | length' "$SMOKE_TMP/sources-list.json")
+echo "      ok — $SOURCE_COUNT meeting source(s) listed"
+echo
+
+# --- 4. signals list --type action_item (the other headline) --------------
+echo "[4/4] hq signals list --entity $ENTITY --type action_item --limit $LIMIT --format json"
+"$HQ_BIN" signals list \
+  --entity "$ENTITY" \
+  --type action_item \
+  --limit "$LIMIT" \
+  --format json > "$SMOKE_TMP/signals-list.json"
+jq -e '.entries | type == "array"' "$SMOKE_TMP/signals-list.json" > /dev/null
+SIGNAL_COUNT=$(jq '.entries | length' "$SMOKE_TMP/signals-list.json")
+echo "      ok — $SIGNAL_COUNT action_item signal(s) listed"
+echo
+
+echo "==> SMOKE PASSED"
+echo "    entities=$ENTITY_COUNT  meeting_sources=$SOURCE_COUNT  action_item_signals=$SIGNAL_COUNT"
+echo "    raw outputs preserved in $SMOKE_TMP until process exit"

package/src/cli-version.ts

@@ -4,6 +4,10 @@ import path from "node:path";
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 const pkgPath = path.resolve(here, "..", "package.json");
-const pkg = JSON.parse(readFileSync(pkgPath, "utf-8")) as { version: string };
+const pkg = JSON.parse(readFileSync(pkgPath, "utf-8")) as {
+  name: string;
+  version: string;
+};
 
+export const CLI_NAME: string = pkg.name;
 export const CLI_VERSION: string = pkg.version;

package/src/commands/cloud-provision.test.ts

@@ -582,6 +582,20 @@ describe("provisionCompany", () => {
       listMyPersonEntities: vi.fn().mockResolvedValue([
         { uid: "prs_01H", type: "person", slug: "test-user", name: "Test User" },
       ]),
+      // Default to "slug available in caller's namespace" so happy-path
+      // tests fall through to createCompanyEntity. Reuse-path tests
+      // override with {available: false, conflictingCompanyUid: ...}
+      // and supply a getCompanyByUid that returns the existing entity.
+      checkSlugInMyNamespace: vi
+        .fn()
+        .mockResolvedValue({ available: true }),
+      getCompanyByUid: vi
+        .fn()
+        .mockRejectedValue(
+          new Error(
+            "getCompanyByUid called without an explicit per-test mock — happy path should never hit it",
+          ),
+        ),
       findCompanyBySlug: vi.fn().mockResolvedValue(null),
       createCompanyEntity: vi.fn(),
       ...overrides,
@@ -716,7 +730,13 @@ describe("provisionCompany", () => {
       kmsKeyId: null,
     };
     const vaultClient = makeVaultClient({
-      findCompanyBySlug: vi.fn().mockResolvedValue(entity),
+      // Reuse path under the per-user-namespace model: checkSlugInMyNamespace
+      // reports `available: false` with the existing entity's uid, and
+      // getCompanyByUid materializes the full entity for downstream use.
+      checkSlugInMyNamespace: vi
+        .fn()
+        .mockResolvedValue({ available: false, conflictingCompanyUid: entity.uid }),
+      getCompanyByUid: vi.fn().mockResolvedValue(entity),
       createCompanyEntity: vi.fn(),
     });
     const result = await provisionCompany({
@@ -731,6 +751,7 @@ describe("provisionCompany", () => {
     expect(result.created_entity).toBe(false);
     expect(result.kms_key_id).toBeNull();
     expect(vaultClient.createCompanyEntity).not.toHaveBeenCalled();
+    expect(vaultClient.getCompanyByUid).toHaveBeenCalledWith(entity.uid);
   });
 
   it("throws code 1 when entity has no bucketName (incomplete provisioning)", async () => {
@@ -743,7 +764,11 @@ describe("provisionCompany", () => {
       // bucketName intentionally absent
     };
     const vaultClient = makeVaultClient({
-      findCompanyBySlug: vi.fn().mockResolvedValue(entity),
+      // Same reuse-path mock shape as the idempotent-path test above.
+      checkSlugInMyNamespace: vi
+        .fn()
+        .mockResolvedValue({ available: false, conflictingCompanyUid: entity.uid }),
+      getCompanyByUid: vi.fn().mockResolvedValue(entity),
     });
     try {
       await provisionCompany({

package/src/commands/cloud-provision.ts

@@ -133,7 +133,32 @@ export interface VaultClient {
    * entity.
    */
   listMyPersonEntities(): Promise<VaultEntity[]>;
+  /**
+   * Legacy global-uniqueness lookup. Under the per-user-namespace model
+   * (hq-pro 2026-05-15) this can return any tenant's entity when more
+   * than one user holds the same slug, OR `null` when the caller doesn't
+   * have it but a different user does. Kept on the interface for any
+   * remaining callers, but `provisionCompany` now uses
+   * `checkSlugInMyNamespace` instead — same-slug-different-owner is
+   * legitimate and should NOT trigger reuse of the stranger's entity.
+   */
   findCompanyBySlug(slug: string): Promise<VaultEntity | null>;
+  /**
+   * Caller-scoped slug availability check via
+   * `GET /entity/check-slug/me?type=company&slug=...`. Returns
+   * `{available: true}` when the caller's namespace
+   * (owned ∪ active-member-of, soft-deleted excluded) doesn't hold the
+   * slug, or `{available: false, conflictingCompanyUid}` when it does
+   * — `provisionCompany` reuses the `conflictingCompanyUid` as the
+   * idempotent entity instead of creating a duplicate.
+   */
+  checkSlugInMyNamespace(slug: string): Promise<{
+    available: boolean;
+    conflictingCompanyUid?: string;
+  }>;
+  /** Fetch a company entity by uid. Used to materialize the entity
+   * after `checkSlugInMyNamespace` reports a same-namespace collision. */
+  getCompanyByUid(uid: string): Promise<VaultEntity>;
   createCompanyEntity(input: {
     slug: string;
     name: string;
@@ -475,6 +500,45 @@ export function createDefaultVaultClient(
       }
       return data.entity;
     },
+    async checkSlugInMyNamespace(slug: string): Promise<{
+      available: boolean;
+      conflictingCompanyUid?: string;
+    }> {
+      const url = `${apiUrl.replace(/\/$/, "")}/entity/check-slug/me?type=company&slug=${encodeURIComponent(
+        slug,
+      )}`;
+      const res = await fetch(url, { method: "GET", headers });
+      if (!res.ok) {
+        const body = await safeBody(res);
+        throw new ProvisionError(
+          1,
+          `Vault GET /entity/check-slug/me failed: ${res.status} ${res.statusText} — ${body}`,
+        );
+      }
+      return (await res.json()) as {
+        available: boolean;
+        conflictingCompanyUid?: string;
+      };
+    },
+    async getCompanyByUid(uid: string): Promise<VaultEntity> {
+      const url = `${apiUrl.replace(/\/$/, "")}/entity/${encodeURIComponent(uid)}`;
+      const res = await fetch(url, { method: "GET", headers });
+      if (!res.ok) {
+        const body = await safeBody(res);
+        throw new ProvisionError(
+          1,
+          `Vault GET /entity/${uid} failed: ${res.status} ${res.statusText} — ${body}`,
+        );
+      }
+      const data = (await res.json()) as { entity?: VaultEntity };
+      if (!data.entity) {
+        throw new ProvisionError(
+          1,
+          `Vault GET /entity/${uid} returned 200 with no entity body`,
+        );
+      }
+      return data.entity;
+    },
     async createCompanyEntity(input: {
       slug: string;
       name: string;
@@ -494,9 +558,15 @@ export function createDefaultVaultClient(
       });
       if (!res.ok) {
         const text = await safeBody(res);
-        // 409 means a concurrent client created it between our GET and POST —
-        // surface it as a vault error. The orchestrator is responsible for
-        // retrying GET if it wants idempotency on collisions.
+        // 409 SLUG_IN_USE_FOR_PERSON: the caller already has the slug
+        // in their namespace (owned ∪ active-member-of). Under the
+        // per-user-namespace model this is the new same-user-collision
+        // signal — distinct from the legacy global EntityAlreadyExists.
+        // The CLI normally reaches `createCompanyEntity` only after
+        // `checkSlugInMyNamespace` reported `available: true`, so a
+        // 409 here means a race between the pre-check and the POST.
+        // Surface the response body verbatim so the caller can see the
+        // `code` + `conflictingCompanyUid` and resolve / retry.
         throw new ProvisionError(
           1,
           `Vault POST /entity failed: ${res.status} ${res.statusText} — ${text}`,
@@ -600,12 +670,57 @@ export async function provisionCompany(
   }
   log(`pre-flight ok — caller has ${persons.length} person entity(ies)`);
 
-  let entity = await vaultClient.findCompanyBySlug(options.slug);
+  // Per-user-namespace-aware reuse-or-create. Replaces the legacy
+  // global `findCompanyBySlug` lookup, which under the per-user model
+  // (hq-pro 2026-05-15) returns ANY tenant's entity when more than one
+  // user holds the same slug, OR null when a different user has it —
+  // both wrong for the CLI's "reuse mine, or create" intent.
+  //
+  // `--owner` override: `options.ownerUid`, when set, lets a caller
+  // create the entity under a DIFFERENT person's ownership (e.g. an
+  // admin provisioning on behalf of someone). `/entity/check-slug/me`
+  // answers about the CALLER's namespace, not the target owner's, so
+  // the pre-check is meaningless in that case. Codex P2 on PR 7
+  // flagged this. The gate: only run the namespace check when the
+  // owner is the caller (or defaulted to the caller — i.e. no
+  // --owner supplied). On override, fall through to
+  // `createCompanyEntity` and let the server's authoritative 409
+  // (which IS scoped to the target's namespace, per the
+  // callerIsOwner gate on POST /entity in hq-pro PR 67) surface any
+  // real conflict.
+  //
+  // `callerIsOwner` is `true` whenever `options.ownerUid` is unset
+  // (defaults to caller server-side) OR — when set — happens to
+  // match the caller's own person UID(s) from `listMyPersonEntities`.
+  const callerOwnedUids = new Set(persons.map((p) => p.uid));
+  const callerIsOwner =
+    !options.ownerUid || callerOwnedUids.has(options.ownerUid);
+
+  let entity: VaultEntity;
   let createdEntity = false;
-  if (entity) {
-    log(`reusing existing vault entity uid=${entity.uid}`);
+  if (callerIsOwner) {
+    const slugCheck = await vaultClient.checkSlugInMyNamespace(options.slug);
+    if (!slugCheck.available && slugCheck.conflictingCompanyUid) {
+      log(
+        `reusing existing vault entity uid=${slugCheck.conflictingCompanyUid} (slug already in caller's namespace)`,
+      );
+      entity = await vaultClient.getCompanyByUid(
+        slugCheck.conflictingCompanyUid,
+      );
+    } else {
+      log(`slug available in caller's namespace — creating vault entity`);
+      entity = await vaultClient.createCompanyEntity({
+        slug: options.slug,
+        name: options.name ?? options.slug,
+        ownerUid: options.ownerUid,
+      });
+      createdEntity = true;
+      log(`created vault entity uid=${entity.uid}`);
+    }
   } else {
-    log(`vault entity not found — creating`);
+    log(
+      `--owner ${options.ownerUid} differs from caller's person(s); skipping namespace pre-check (server authoritatively gates per-target-namespace)`,
+    );
     entity = await vaultClient.createCompanyEntity({
       slug: options.slug,
       name: options.name ?? options.slug,

package/src/commands/groups.ts

@@ -66,7 +66,7 @@ export function registerGroupsCommand(program: Command): void {
           if (res.status === 401) {
             console.error(chalk.red("Not authenticated — please run `hq login`"));
           } else if (res.status === 403) {
-            console.error(chalk.red("Not authorized — owner or admin role required"));
+            console.error(chalk.red("Not authorized — owner role required"));
           } else if (res.status === 409) {
             console.error(chalk.red(`Group already exists: ${groupId}`));
           } else if (res.status >= 500) {
@@ -110,7 +110,7 @@ export function registerGroupsCommand(program: Command): void {
           if (res.status === 401) {
             console.error(chalk.red("Not authenticated — please run `hq login`"));
           } else if (res.status === 403) {
-            console.error(chalk.red("Not authorized — owner or admin role required"));
+            console.error(chalk.red("Not authorized — owner role required"));
           } else if (res.status === 404) {
             console.error(chalk.red(`Group not found: ${groupId}`));
           } else if (res.status >= 500) {
@@ -160,7 +160,7 @@ export function registerGroupsCommand(program: Command): void {
           if (res.status === 401) {
             console.error(chalk.red("Not authenticated — please run `hq login`"));
           } else if (res.status === 403) {
-            console.error(chalk.red("Not authorized — owner/admin role or group creator required"));
+            console.error(chalk.red("Not authorized — owner role or group creator required"));
           } else if (res.status === 404) {
             // Server provides a helpful message (email not found vs group not found)
             console.error(chalk.red(err.error ?? `Not found`));
@@ -215,7 +215,7 @@ export function registerGroupsCommand(program: Command): void {
           if (res.status === 401) {
             console.error(chalk.red("Not authenticated — please run `hq login`"));
           } else if (res.status === 403) {
-            console.error(chalk.red("Not authorized — owner/admin role or group creator required"));
+            console.error(chalk.red("Not authorized — owner role or group creator required"));
           } else if (res.status === 404) {
             console.error(chalk.red(err.error ?? `Not found`));
           } else if (res.status >= 500) {

package/src/commands/meetings.ts

@@ -1,7 +1,7 @@
 import { Command } from "commander";
 import chalk from "chalk";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
-import { vaultApiFetch } from "../utils/vault-api.js";
+import { vaultApiFetch, getCompanyUid } from "../utils/vault-api.js";
 
 interface MeetingListItem {
   meetingId: string;
@@ -210,7 +210,7 @@ export function registerMeetingsCommand(program: Command): void {
 
         if (opts.limit) query.limit = opts.limit;
         if (opts.next) query.nextToken = opts.next;
-        if (companySlug) query.companyId = companySlug;
+        if (companySlug) query.companyId = await getCompanyUid(token, companySlug);
 
         const res = await vaultApiFetch({ token, path: "/v1/meetings", query });
         if (!res.ok) await handleApiError(res);
@@ -250,7 +250,7 @@ export function registerMeetingsCommand(program: Command): void {
         const token = await ensureCognitoToken();
         const query: Record<string, string> = {};
         const companySlug = meetings.opts().company as string | undefined;
-        if (companySlug) query.companyId = companySlug;
+        if (companySlug) query.companyId = await getCompanyUid(token, companySlug);
 
         const meetingId = await resolveShortId(token, rawId, query);
         const res = await vaultApiFetch({
@@ -309,7 +309,7 @@ export function registerMeetingsCommand(program: Command): void {
         const token = await ensureCognitoToken();
         const params: Record<string, string> = { q: query };
         const companySlug = meetings.opts().company as string | undefined;
-        if (companySlug) params.companyId = companySlug;
+        if (companySlug) params.companyId = await getCompanyUid(token, companySlug);
 
         const res = await vaultApiFetch({
           token,
@@ -347,7 +347,7 @@ export function registerMeetingsCommand(program: Command): void {
         const token = await ensureCognitoToken();
         const query: Record<string, string> = {};
         const companySlug = meetings.opts().company as string | undefined;
-        if (companySlug) query.companyId = companySlug;
+        if (companySlug) query.companyId = await getCompanyUid(token, companySlug);
 
         const meetingId = await resolveShortId(token, rawId, query);
         const res = await vaultApiFetch({
@@ -403,7 +403,7 @@ export function registerMeetingsCommand(program: Command): void {
         const token = await ensureCognitoToken();
         const query: Record<string, string> = {};
         const companySlug = meetings.opts().company as string | undefined;
-        if (companySlug) query.companyId = companySlug;
+        if (companySlug) query.companyId = await getCompanyUid(token, companySlug);
 
         const meetingId = await resolveShortId(token, rawId, query);
         const res = await vaultApiFetch({

package/src/commands/members.test.ts

@@ -222,6 +222,47 @@ describe("inviteMember", () => {
       }),
     ).rejects.toBeInstanceOf(InviteHttpError);
   });
+
+  it("resolves the token when it is nested on the membership row", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        membership: {
+          role: "admin",
+          status: "pending",
+          inviteToken: "tok_nested",
+        },
+      }),
+    );
+
+    const result = await inviteMember({
+      target: "alice@example.com",
+      role: "admin",
+      companyUid: "cmp_acme",
+      callerUid: "prs_admin",
+      token: "test-token",
+    });
+
+    expect(result.inviteToken).toBe("tok_nested");
+    expect(result.magicLink).toBe("hq://accept/tok_nested");
+  });
+
+  it("throws instead of emitting hq://accept/undefined when no token is present", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        membership: { role: "admin", status: "pending" },
+      }),
+    );
+
+    await expect(
+      inviteMember({
+        target: "alice@example.com",
+        role: "admin",
+        companyUid: "cmp_acme",
+        callerUid: "prs_admin",
+        token: "test-token",
+      }),
+    ).rejects.toThrow(/did not include an invite token/);
+  });
 });
 
 // ---------------------------------------------------------------------------
@@ -257,6 +298,21 @@ describe("listPendingInvites", () => {
       InviteHttpError,
     );
   });
+
+  it("returns [] for an empty invites array", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, { invites: [] }));
+    await expect(listPendingInvites("test-token", "cmp_acme")).resolves.toEqual([]);
+  });
+
+  it("returns [] when invites is null", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, { invites: null }));
+    await expect(listPendingInvites("test-token", "cmp_acme")).resolves.toEqual([]);
+  });
+
+  it("returns [] when the invites key is missing", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, {}));
+    await expect(listPendingInvites("test-token", "cmp_acme")).resolves.toEqual([]);
+  });
 });
 
 // ---------------------------------------------------------------------------

package/src/commands/members.ts

@@ -41,7 +41,7 @@ export interface InviteOptions {
 export interface InviteResult {
   inviteToken: string;
   magicLink: string;
-  membership: { role: string; status: string };
+  membership: { role: string; status: string; inviteToken?: string };
 }
 
 export interface DetectedTarget {
@@ -132,30 +132,53 @@ export async function inviteMember(
     throw new InviteHttpError(
       res.status,
       err.message ?? err.error ?? res.statusText,
+      err.code,
     );
   }
 
   const data = (await res.json()) as {
-    membership: { role: string; status: string };
-    inviteToken: string;
+    membership?: { role: string; status: string; inviteToken?: string };
+    inviteToken?: string;
   };
+  // The token may arrive at the response root OR nested on the membership row,
+  // depending on vault-service version. Resolve from either; never emit
+  // `hq://accept/undefined` (a broken link that looks like success).
+  const inviteToken = data.inviteToken ?? data.membership?.inviteToken;
+  if (!inviteToken) {
+    const keys = Object.keys(data ?? {}).join(", ") || "<empty>";
+    throw new Error(
+      `Invite was created but the server response did not include an invite token (response keys: ${keys}). ` +
+        "Run `hq members list` to retrieve the pending invite, or upgrade hq.",
+    );
+  }
   return {
-    inviteToken: data.inviteToken,
-    magicLink: `hq://accept/${data.inviteToken}`,
-    membership: data.membership,
+    inviteToken,
+    magicLink: `hq://accept/${inviteToken}`,
+    membership: data.membership ?? { role: options.role, status: "pending" },
   };
 }
 
 export class InviteHttpError extends Error {
-  constructor(public status: number, message: string) {
+  constructor(
+    public status: number,
+    message: string,
+    public code?: string,
+  ) {
     super(message);
     this.name = "InviteHttpError";
   }
 }
 
-export function formatInviteHttpError(status: number, fallback: string): string {
+export function formatInviteHttpError(
+  status: number,
+  fallback: string,
+  code?: string,
+): string {
   if (status === 401) return "Not authenticated — please run `hq login`";
   if (status === 403) {
+    if (code === "ADMIN_ROLE_TARGET_RESTRICTED") {
+      return "Admin can only invite at role=member; ask an owner to invite at this role";
+    }
     return "Not authorized — only admins and owners can invite members";
   }
   if (status === 409) {
@@ -178,10 +201,11 @@ export async function listPendingInvites(
     throw new InviteHttpError(
       res.status,
       err.message ?? err.error ?? res.statusText,
+      err.code,
     );
   }
-  const data = (await res.json()) as { invites: PendingInvite[] };
-  return data.invites;
+  const data = (await res.json()) as { invites?: PendingInvite[] | null };
+  return data?.invites ?? [];
 }
 
 export async function revokeInvite(
@@ -200,6 +224,7 @@ export async function revokeInvite(
     throw new InviteHttpError(
       res.status,
       err.message ?? err.error ?? res.statusText,
+      err.code,
     );
   }
 }
@@ -260,7 +285,11 @@ export function registerMembersCommand(program: Command): void {
           );
         } catch (err) {
           if (err instanceof InviteHttpError) {
-            console.error(chalk.red(formatInviteHttpError(err.status, err.message)));
+            console.error(
+              chalk.red(
+                formatInviteHttpError(err.status, err.message, err.code),
+              ),
+            );
             process.exit(1);
           }
           console.error(
@@ -350,10 +379,12 @@ export function registerMembersCommand(program: Command): void {
         if (err instanceof InviteHttpError) {
           const msg =
             err.status === 403
-              ? "Not authorized — only admins and owners can revoke invites"
+              ? err.code === "ADMIN_ROLE_TARGET_RESTRICTED"
+                ? "Admin can only revoke role=member; ask an owner to revoke this membership"
+                : "Not authorized — only admins and owners can revoke invites"
               : err.status === 404
                 ? "Invite not found — it may have already been accepted or revoked"
-                : formatInviteHttpError(err.status, err.message);
+                : formatInviteHttpError(err.status, err.message, err.code);
           console.error(chalk.red(msg));
           process.exit(1);
         }