@indigoai-us/hq-cli 5.18.0 → 5.18.2

package/dist/commands/cloud.d.ts

@@ -163,5 +163,42 @@ export declare function assertSingleSelector(opts: {
     personal?: boolean;
     company?: string;
 }, command: string): void;
+/**
+ * Per-company pull resolution helper used by `hq sync pull --company <slug>`
+ * (US-011 fix, 2026-05-21). Mirrors the inline lookup that `runNowSingle`
+ * does for sync-now. Pulled out so the action handler stays thin AND so
+ * unit tests can exercise the banner / strict-refusal decision without
+ * spinning up commander + a real VaultClient.
+ *
+ * Input shape:
+ *   - `targetCompany` — slug or UID the caller passed to `--company`. If
+ *     undefined, the helper short-circuits to a "no resolution" result
+ *     (the action handler falls back to .hq/config.json via sync()).
+ *   - `client` — minimal VaultClient surface: listMyMemberships + entity.get
+ *     + getMembershipSyncConfig.
+ *
+ * Output: `{ resolvedCompanyUid, resolvedMode }` — either may be undefined
+ * if the membership / sync-config call failed. Both undefined is a clean
+ * degradation — the caller pulls without a banner.
+ */
+export interface PerCompanyPullResolveClient {
+    listMyMemberships(): Promise<Array<{
+        companyUid: string;
+        membershipKey: string;
+    }>>;
+    getMembershipSyncConfig(membershipKey: string): Promise<{
+        syncMode: MembershipSyncConfig["syncMode"];
+    }>;
+    entity: {
+        get(uid: string): Promise<{
+            slug?: string;
+        }>;
+    };
+}
+export interface PerCompanyPullResolveResult {
+    resolvedCompanyUid: string | undefined;
+    resolvedMode: MembershipSyncConfig["syncMode"] | undefined;
+}
+export declare function resolvePerCompanyPullPlan(client: PerCompanyPullResolveClient, targetCompany: string | undefined): Promise<PerCompanyPullResolveResult>;
 export declare function registerCloudCommands(program: Command): void;
 //# sourceMappingURL=cloud.d.ts.map

package/dist/commands/cloud.js

@@ -13,7 +13,7 @@
  *   hq sync status            — show local journal summary
  */
 
-!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]="2eb7da1d-e84f-591c-b930-b84c5c96986b")}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]="4672d875-1dc8-56a2-bef1-49c7f4ff6c76")}catch(e){}}();
 import chalk from "chalk";
 import * as fs from "fs";
 import * as path from "path";
@@ -252,6 +252,54 @@ export function assertSingleSelector(opts, command) {
             `--company; got: ${selectors.join(", ")}.`);
     }
 }
+export async function resolvePerCompanyPullPlan(client, targetCompany) {
+    if (!targetCompany)
+        return { resolvedCompanyUid: undefined, resolvedMode: undefined };
+    try {
+        const memberships = await client.listMyMemberships();
+        // Direct UID / membershipKey match first (cheapest).
+        const direct = memberships.find((m) => m.companyUid === targetCompany || m.membershipKey === targetCompany);
+        if (direct) {
+            let mode;
+            try {
+                const cfg = await client.getMembershipSyncConfig(direct.membershipKey);
+                mode = cfg.syncMode;
+            }
+            catch {
+                mode = undefined;
+            }
+            return { resolvedCompanyUid: direct.companyUid, resolvedMode: mode };
+        }
+        // Slug match — listMyMemberships returns companyUid only, so fan out
+        // entity.get to find the row whose slug matches the caller's input.
+        for (const m of memberships) {
+            try {
+                const entity = await client.entity.get(m.companyUid);
+                if (entity.slug === targetCompany) {
+                    let mode;
+                    try {
+                        const cfg = await client.getMembershipSyncConfig(m.membershipKey);
+                        mode = cfg.syncMode;
+                    }
+                    catch {
+                        mode = undefined;
+                    }
+                    return { resolvedCompanyUid: m.companyUid, resolvedMode: mode };
+                }
+            }
+            catch {
+                // Entity not visible — skip and continue. Worst case the loop ends
+                // with no match and we return undefined for both — the pull still
+                // proceeds, banner just stays quiet.
+            }
+        }
+    }
+    catch {
+        // listMyMemberships failed — degrade silently. Sync still works without
+        // the banner; this matches the runPullAll catch behavior.
+    }
+    return { resolvedCompanyUid: undefined, resolvedMode: undefined };
+}
 export function registerCloudCommands(program) {
     program
         .command("push")
@@ -482,10 +530,37 @@ export function registerCloudCommands(program) {
             console.log(`  HQ root:  ${options.hqRoot}`);
             console.log(`  Company:  ${options.company ?? "(from .hq/config.json)"}\n`);
             const accessToken = await ensureCognitoToken();
+            const vaultConfig = buildVaultConfig(accessToken);
+            // US-011 (2026-05-21 fix): resolve the caller's sync-config for
+            // the targeted membership BEFORE the pull, so we can (a) emit the
+            // narrow-hint banner after success if still on all-mode and
+            // (b) respect strict-mode refusal mirror of the --all + sync-now
+            // paths. Failure to resolve degrades silently — pull still works,
+            // banner just stays quiet (same as the catch in runPullAll).
+            const narrowHintLevel = resolveBannerLevel();
+            const { resolvedCompanyUid, resolvedMode } = await resolvePerCompanyPullPlan(new VaultClient(vaultConfig), options.company);
+            // Strict-mode refusal: matches runPullAll + runNowSingle behavior.
+            // Default banner level is 'hint' which never triggers refusal —
+            // wired now so future hq-core-staging releases can flip the
+            // default to 'strict' without re-touching this command.
+            if (resolvedMode === "all" &&
+                isStrictRefusal(resolvedMode, narrowHintLevel) &&
+                options.modeAll !== true &&
+                resolvedCompanyUid) {
+                emitNarrowHint({
+                    companyUid: resolvedCompanyUid,
+                    syncMode: resolvedMode,
+                    level: narrowHintLevel,
+                });
+                console.error(chalk.red("\n✗ Pull refused: strict narrow-hint mode is on and this " +
+                    "membership still pulls everything. Run `hq sync narrow --apply` " +
+                    "to migrate, or re-run with --mode-all."));
+                process.exit(1);
+            }
             const result = await sync({
                 company: options.company,
                 onConflict: options.onConflict,
-                vaultConfig: buildVaultConfig(accessToken),
+                vaultConfig,
                 hqRoot: options.hqRoot,
             });
             if (result.aborted) {
@@ -493,6 +568,16 @@ export function registerCloudCommands(program) {
                 process.exit(1);
             }
             console.log(chalk.green(`\n✓ Pulled ${result.filesDownloaded} file(s) (${formatBytes(result.bytesDownloaded)}, ${result.filesSkipped} skipped, ${result.conflicts} conflicts)`));
+            // US-011 (2026-05-21 fix): emit the hint banner after success
+            // so it appears alongside the summary line. Mirrors the wiring
+            // in runPullAll (cloud.ts:331) and runNowSingle (cloud.ts:1371).
+            if (resolvedMode === "all" && resolvedCompanyUid) {
+                emitNarrowHint({
+                    companyUid: resolvedCompanyUid,
+                    syncMode: resolvedMode,
+                    level: narrowHintLevel,
+                });
+            }
         }
         catch (err) {
             console.error(chalk.red("\n✗ Pull failed:"), err instanceof Error ? err.message : String(err));
@@ -978,4 +1063,4 @@ function resolveUploadAuthorFromCache() {
     }
 }
 //# sourceMappingURL=cloud.js.map
-//# debugId=2eb7da1d-e84f-591c-b930-b84c5c96986b
+//# debugId=4672d875-1dc8-56a2-bef1-49c7f4ff6c76

package/dist/commands/members.d.ts

@@ -20,13 +20,29 @@ export interface InviteOptions {
     callerUid: string;
     token: string;
 }
+/**
+ * Outcome of `hq members invite`. Two shapes depending on server schema:
+ *
+ *  - **schemaVersion ≤ 1** — server returns a random `inviteToken` the
+ *    invitee redeems via the `hq://accept/{token}` magic link. `magicLink`
+ *    is populated so the caller can print or paste it.
+ *  - **schemaVersion 2+** (current production) — membership row is
+ *    email-keyed and authoritative. There is no token; the invitee
+ *    accepts by signing into HQ with the same email. `inviteToken` +
+ *    `magicLink` are both `undefined`; the caller prints sign-in
+ *    instructions instead.
+ *
+ * `membership` is always populated when the server returned 2xx.
+ */
 export interface InviteResult {
-    inviteToken: string;
-    magicLink: string;
+    inviteToken?: string;
+    magicLink?: string;
     membership: {
+        membershipKey?: string;
         role: string;
         status: string;
         inviteToken?: string;
+        inviteeEmail?: string;
     };
 }
 export interface DetectedTarget {

package/dist/commands/members.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]="5f8b5b62-a00e-5ca3-b293-23906579a464")}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]="20c76490-0485-592f-856b-3b20e403a392")}catch(e){}}();
 import chalk from "chalk";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch, getCompanyUid } from "../utils/vault-api.js";
@@ -72,19 +72,26 @@ export async function inviteMember(options) {
         throw new InviteHttpError(res.status, err.message ?? err.error ?? res.statusText, err.code);
     }
     const data = (await res.json());
-    // 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) {
+    if (!data.membership) {
         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.");
+        throw new Error(`Invite endpoint returned 2xx with no membership row (response keys: ${keys}). ` +
+            "This is a server-side regression — file an issue.");
     }
+    // Two server schemas in the wild:
+    //   - Legacy (schemaVersion ≤ 1): response carries a random `inviteToken`
+    //     the invitee redeems via `hq://accept/{token}`.
+    //   - Current (schemaVersion 2+): membership row is email-keyed and
+    //     authoritative — there is no token. The invitee accepts by signing
+    //     into HQ with the invited email. The CLI must NOT throw here
+    //     (previously did: "response did not include an invite token") — the
+    //     invite IS successfully created on the server; the caller just gets
+    //     undefined for inviteToken/magicLink and prints sign-in instructions.
+    const inviteToken = data.inviteToken ?? data.membership.inviteToken;
     return {
-        inviteToken,
-        magicLink: `hq://accept/${inviteToken}`,
-        membership: data.membership ?? { role: options.role, status: "pending" },
+        ...(inviteToken
+            ? { inviteToken, magicLink: `hq://accept/${inviteToken}` }
+            : {}),
+        membership: data.membership,
     };
 }
 export class InviteHttpError extends Error {
@@ -122,8 +129,11 @@ export async function listPendingInvites(token, companyUid) {
         const err = (await res.json().catch(() => ({})));
         throw new InviteHttpError(res.status, err.message ?? err.error ?? res.statusText, err.code);
     }
+    // Server schema: `{ pending: [...] }`. Earlier dev branches used
+    // `{ invites: [...] }` which the CLI still accepts as a fallback for
+    // operators running staging stages that haven't caught up yet.
     const data = (await res.json());
-    return data?.invites ?? [];
+    return data?.pending ?? data?.invites ?? [];
 }
 export async function revokeInvite(token, tokenOrKey, companyUid) {
     const res = await vaultApiFetch({
@@ -163,10 +173,28 @@ export function registerMembersCommand(program) {
             });
             console.log(chalk.green(`Invited ${target} as ${result.membership.role} (status: ${result.membership.status})`));
             console.log();
-            console.log(chalk.bold("Magic link:"));
-            console.log(`  ${result.magicLink}`);
-            console.log();
-            console.log(chalk.dim("Share this link with the invitee. They can run `hq onboard join --invite-token <token>` to accept."));
+            if (result.magicLink) {
+                // Legacy server schema — magic-link redemption.
+                console.log(chalk.bold("Magic link:"));
+                console.log(`  ${result.magicLink}`);
+                console.log();
+                console.log(chalk.dim("Share this link with the invitee. They can run `hq onboard join --invite-token <token>` to accept."));
+            }
+            else {
+                // schemaVersion 2+ — email-keyed authoritative membership row.
+                // No magic link to share; invitee accepts by signing into HQ.
+                const inviteeEmail = result.membership.inviteeEmail ??
+                    (typeof target === "string" && target.includes("@")
+                        ? target
+                        : undefined);
+                console.log(chalk.bold("Next step:"));
+                console.log(`  Tell ${inviteeEmail ?? "the invitee"} to sign into HQ at https://hq.getindigo.ai with that email.`);
+                console.log(chalk.dim("  The pending membership row claims itself on first sign-in — no separate token redemption."));
+                if (result.membership.membershipKey) {
+                    console.log();
+                    console.log(chalk.dim(`  Membership key: ${result.membership.membershipKey}`));
+                }
+            }
         }
         catch (err) {
             if (err instanceof InviteHttpError) {
@@ -253,4 +281,4 @@ export function registerMembersCommand(program) {
     });
 }
 //# sourceMappingURL=members.js.map
-//# debugId=5f8b5b62-a00e-5ca3-b293-23906579a464
+//# debugId=20c76490-0485-592f-856b-3b20e403a392

package/package.json

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

package/src/commands/cloud.pull-per-company.test.ts

@@ -0,0 +1,188 @@
+/**
+ * Unit tests for `resolvePerCompanyPullPlan` — the helper extracted from the
+ * `hq sync pull --company <slug>` action handler so the US-011 banner +
+ * strict-refusal wiring can be exercised without commander / a real
+ * VaultClient (US-011 fix, 2026-05-21).
+ *
+ * The action handler itself stays a thin orchestrator. These tests cover
+ * the membership-resolution decision tree, which is the part that broke
+ * on the pre-fix code path (banner silently never fired because the
+ * handler never looked up the sync-config).
+ *
+ * Coverage:
+ *   1. Undefined targetCompany short-circuits to no-op.
+ *   2. Direct UID match returns mode + companyUid.
+ *   3. Direct membershipKey match returns mode + companyUid.
+ *   4. Slug match via entity.get returns mode + companyUid.
+ *   5. listMyMemberships error degrades silently to no resolution.
+ *   6. getMembershipSyncConfig error degrades to undefined mode but keeps companyUid.
+ *   7. Slug iteration stops at first match (doesn't fan out to all entities).
+ *   8. No matching membership returns no resolution.
+ */
+
+import { describe, expect, it, vi } from "vitest";
+import {
+  resolvePerCompanyPullPlan,
+  type PerCompanyPullResolveClient,
+} from "./cloud.js";
+
+function makeClient(opts: {
+  memberships?: Array<{ companyUid: string; membershipKey: string }>;
+  syncConfigs?: Record<string, { syncMode: "shared" | "all" | "custom" }>;
+  entities?: Record<string, { slug?: string }>;
+  failListMemberships?: boolean;
+  failSyncConfigFor?: Set<string>;
+  failEntityFor?: Set<string>;
+}): PerCompanyPullResolveClient & {
+  _entityCalls: () => string[];
+} {
+  const entityCalls: string[] = [];
+  return {
+    listMyMemberships: vi.fn(async () => {
+      if (opts.failListMemberships) throw new Error("listMyMemberships boom");
+      return opts.memberships ?? [];
+    }),
+    getMembershipSyncConfig: vi.fn(async (key: string) => {
+      if (opts.failSyncConfigFor?.has(key))
+        throw new Error(`getMembershipSyncConfig boom for ${key}`);
+      const cfg = (opts.syncConfigs ?? {})[key];
+      if (!cfg) throw new Error(`no fake config for ${key}`);
+      return cfg;
+    }),
+    entity: {
+      get: vi.fn(async (uid: string) => {
+        entityCalls.push(uid);
+        if (opts.failEntityFor?.has(uid))
+          throw new Error(`entity.get boom for ${uid}`);
+        return (opts.entities ?? {})[uid] ?? {};
+      }),
+    },
+    _entityCalls: () => entityCalls,
+  };
+}
+
+describe("resolvePerCompanyPullPlan (US-011 per-company pull fix)", () => {
+  it("returns undefined+undefined when targetCompany is undefined", async () => {
+    const client = makeClient({});
+    const result = await resolvePerCompanyPullPlan(client, undefined);
+    expect(result.resolvedCompanyUid).toBeUndefined();
+    expect(result.resolvedMode).toBeUndefined();
+    // Should not call any API — short-circuit.
+    expect(client.listMyMemberships).not.toHaveBeenCalled();
+  });
+
+  it("matches by direct companyUid and returns the live syncMode", async () => {
+    const client = makeClient({
+      memberships: [
+        { companyUid: "cmp_personal", membershipKey: "mbr_personal" },
+        { companyUid: "cmp_indigo", membershipKey: "mbr_indigo" },
+      ],
+      syncConfigs: {
+        mbr_personal: { syncMode: "all" },
+        mbr_indigo: { syncMode: "shared" },
+      },
+    });
+    const result = await resolvePerCompanyPullPlan(client, "cmp_indigo");
+    expect(result.resolvedCompanyUid).toBe("cmp_indigo");
+    expect(result.resolvedMode).toBe("shared");
+    // Slug-fallback loop must not fire — no entity calls.
+    expect(client._entityCalls()).toEqual([]);
+  });
+
+  it("matches by direct membershipKey", async () => {
+    const client = makeClient({
+      memberships: [
+        { companyUid: "cmp_x", membershipKey: "mbr_special" },
+      ],
+      syncConfigs: { mbr_special: { syncMode: "custom" } },
+    });
+    const result = await resolvePerCompanyPullPlan(client, "mbr_special");
+    expect(result.resolvedCompanyUid).toBe("cmp_x");
+    expect(result.resolvedMode).toBe("custom");
+  });
+
+  it("matches by slug via entity.get fan-out", async () => {
+    const client = makeClient({
+      memberships: [
+        { companyUid: "cmp_one", membershipKey: "mbr_one" },
+        { companyUid: "cmp_two", membershipKey: "mbr_two" },
+      ],
+      syncConfigs: { mbr_two: { syncMode: "all" } },
+      entities: {
+        cmp_one: { slug: "foo" },
+        cmp_two: { slug: "personal" },
+      },
+    });
+    const result = await resolvePerCompanyPullPlan(client, "personal");
+    expect(result.resolvedCompanyUid).toBe("cmp_two");
+    expect(result.resolvedMode).toBe("all");
+  });
+
+  it("stops slug iteration at the first match — does not fan out", async () => {
+    const client = makeClient({
+      memberships: [
+        { companyUid: "cmp_a", membershipKey: "mbr_a" },
+        { companyUid: "cmp_b", membershipKey: "mbr_b" },
+        { companyUid: "cmp_c", membershipKey: "mbr_c" },
+      ],
+      syncConfigs: { mbr_b: { syncMode: "shared" } },
+      entities: {
+        cmp_a: { slug: "alpha" },
+        cmp_b: { slug: "beta" },
+        cmp_c: { slug: "gamma" },
+      },
+    });
+    const result = await resolvePerCompanyPullPlan(client, "beta");
+    expect(result.resolvedCompanyUid).toBe("cmp_b");
+    expect(result.resolvedMode).toBe("shared");
+    // cmp_a was probed, cmp_b matched, cmp_c never touched.
+    expect(client._entityCalls()).toEqual(["cmp_a", "cmp_b"]);
+  });
+
+  it("returns undefined for both when no matching membership/slug", async () => {
+    const client = makeClient({
+      memberships: [
+        { companyUid: "cmp_x", membershipKey: "mbr_x" },
+      ],
+      entities: { cmp_x: { slug: "foo" } },
+    });
+    const result = await resolvePerCompanyPullPlan(client, "doesnotexist");
+    expect(result.resolvedCompanyUid).toBeUndefined();
+    expect(result.resolvedMode).toBeUndefined();
+  });
+
+  it("degrades silently when listMyMemberships fails — no banner, pull continues", async () => {
+    const client = makeClient({ failListMemberships: true });
+    const result = await resolvePerCompanyPullPlan(client, "personal");
+    expect(result.resolvedCompanyUid).toBeUndefined();
+    expect(result.resolvedMode).toBeUndefined();
+    // Sync-config never reached.
+    expect(client.getMembershipSyncConfig).not.toHaveBeenCalled();
+  });
+
+  it("on direct match, keeps companyUid even when getMembershipSyncConfig throws", async () => {
+    const client = makeClient({
+      memberships: [{ companyUid: "cmp_p", membershipKey: "mbr_p" }],
+      failSyncConfigFor: new Set(["mbr_p"]),
+    });
+    const result = await resolvePerCompanyPullPlan(client, "cmp_p");
+    expect(result.resolvedCompanyUid).toBe("cmp_p");
+    // Mode unknown — caller will skip banner emit (it only fires when mode='all').
+    expect(result.resolvedMode).toBeUndefined();
+  });
+
+  it("on slug-fallback match, skips broken entity rows and keeps looking", async () => {
+    const client = makeClient({
+      memberships: [
+        { companyUid: "cmp_broken", membershipKey: "mbr_broken" },
+        { companyUid: "cmp_good", membershipKey: "mbr_good" },
+      ],
+      syncConfigs: { mbr_good: { syncMode: "all" } },
+      entities: { cmp_good: { slug: "wanted" } },
+      failEntityFor: new Set(["cmp_broken"]),
+    });
+    const result = await resolvePerCompanyPullPlan(client, "wanted");
+    expect(result.resolvedCompanyUid).toBe("cmp_good");
+    expect(result.resolvedMode).toBe("all");
+  });
+});

package/src/commands/cloud.ts

@@ -473,6 +473,86 @@ export function assertSingleSelector(opts: {
   }
 }
 
+/**
+ * Per-company pull resolution helper used by `hq sync pull --company <slug>`
+ * (US-011 fix, 2026-05-21). Mirrors the inline lookup that `runNowSingle`
+ * does for sync-now. Pulled out so the action handler stays thin AND so
+ * unit tests can exercise the banner / strict-refusal decision without
+ * spinning up commander + a real VaultClient.
+ *
+ * Input shape:
+ *   - `targetCompany` — slug or UID the caller passed to `--company`. If
+ *     undefined, the helper short-circuits to a "no resolution" result
+ *     (the action handler falls back to .hq/config.json via sync()).
+ *   - `client` — minimal VaultClient surface: listMyMemberships + entity.get
+ *     + getMembershipSyncConfig.
+ *
+ * Output: `{ resolvedCompanyUid, resolvedMode }` — either may be undefined
+ * if the membership / sync-config call failed. Both undefined is a clean
+ * degradation — the caller pulls without a banner.
+ */
+export interface PerCompanyPullResolveClient {
+  listMyMemberships(): Promise<Array<{ companyUid: string; membershipKey: string }>>;
+  getMembershipSyncConfig(
+    membershipKey: string,
+  ): Promise<{ syncMode: MembershipSyncConfig["syncMode"] }>;
+  entity: { get(uid: string): Promise<{ slug?: string }> };
+}
+
+export interface PerCompanyPullResolveResult {
+  resolvedCompanyUid: string | undefined;
+  resolvedMode: MembershipSyncConfig["syncMode"] | undefined;
+}
+
+export async function resolvePerCompanyPullPlan(
+  client: PerCompanyPullResolveClient,
+  targetCompany: string | undefined,
+): Promise<PerCompanyPullResolveResult> {
+  if (!targetCompany) return { resolvedCompanyUid: undefined, resolvedMode: undefined };
+  try {
+    const memberships = await client.listMyMemberships();
+    // Direct UID / membershipKey match first (cheapest).
+    const direct = memberships.find(
+      (m) => m.companyUid === targetCompany || m.membershipKey === targetCompany,
+    );
+    if (direct) {
+      let mode: MembershipSyncConfig["syncMode"] | undefined;
+      try {
+        const cfg = await client.getMembershipSyncConfig(direct.membershipKey);
+        mode = cfg.syncMode;
+      } catch {
+        mode = undefined;
+      }
+      return { resolvedCompanyUid: direct.companyUid, resolvedMode: mode };
+    }
+    // Slug match — listMyMemberships returns companyUid only, so fan out
+    // entity.get to find the row whose slug matches the caller's input.
+    for (const m of memberships) {
+      try {
+        const entity = await client.entity.get(m.companyUid);
+        if (entity.slug === targetCompany) {
+          let mode: MembershipSyncConfig["syncMode"] | undefined;
+          try {
+            const cfg = await client.getMembershipSyncConfig(m.membershipKey);
+            mode = cfg.syncMode;
+          } catch {
+            mode = undefined;
+          }
+          return { resolvedCompanyUid: m.companyUid, resolvedMode: mode };
+        }
+      } catch {
+        // Entity not visible — skip and continue. Worst case the loop ends
+        // with no match and we return undefined for both — the pull still
+        // proceeds, banner just stays quiet.
+      }
+    }
+  } catch {
+    // listMyMemberships failed — degrade silently. Sync still works without
+    // the banner; this matches the runPullAll catch behavior.
+  }
+  return { resolvedCompanyUid: undefined, resolvedMode: undefined };
+}
+
 export function registerCloudCommands(program: Command): void {
   program
     .command("push")
@@ -817,10 +897,50 @@ export function registerCloudCommands(program: Command): void {
           console.log(`  Company:  ${options.company ?? "(from .hq/config.json)"}\n`);
 
           const accessToken = await ensureCognitoToken();
+          const vaultConfig = buildVaultConfig(accessToken);
+
+          // US-011 (2026-05-21 fix): resolve the caller's sync-config for
+          // the targeted membership BEFORE the pull, so we can (a) emit the
+          // narrow-hint banner after success if still on all-mode and
+          // (b) respect strict-mode refusal mirror of the --all + sync-now
+          // paths. Failure to resolve degrades silently — pull still works,
+          // banner just stays quiet (same as the catch in runPullAll).
+          const narrowHintLevel: BannerLevel = resolveBannerLevel();
+          const { resolvedCompanyUid, resolvedMode } =
+            await resolvePerCompanyPullPlan(
+              new VaultClient(vaultConfig),
+              options.company,
+            );
+
+          // Strict-mode refusal: matches runPullAll + runNowSingle behavior.
+          // Default banner level is 'hint' which never triggers refusal —
+          // wired now so future hq-core-staging releases can flip the
+          // default to 'strict' without re-touching this command.
+          if (
+            resolvedMode === "all" &&
+            isStrictRefusal(resolvedMode, narrowHintLevel) &&
+            options.modeAll !== true &&
+            resolvedCompanyUid
+          ) {
+            emitNarrowHint({
+              companyUid: resolvedCompanyUid,
+              syncMode: resolvedMode,
+              level: narrowHintLevel,
+            });
+            console.error(
+              chalk.red(
+                "\n✗ Pull refused: strict narrow-hint mode is on and this " +
+                  "membership still pulls everything. Run `hq sync narrow --apply` " +
+                  "to migrate, or re-run with --mode-all.",
+              ),
+            );
+            process.exit(1);
+          }
+
           const result = await sync({
             company: options.company,
             onConflict: options.onConflict,
-            vaultConfig: buildVaultConfig(accessToken),
+            vaultConfig,
             hqRoot: options.hqRoot,
           });
 
@@ -838,6 +958,17 @@ export function registerCloudCommands(program: Command): void {
               `\n✓ Pulled ${result.filesDownloaded} file(s) (${formatBytes(result.bytesDownloaded)}, ${result.filesSkipped} skipped, ${result.conflicts} conflicts)`,
             ),
           );
+
+          // US-011 (2026-05-21 fix): emit the hint banner after success
+          // so it appears alongside the summary line. Mirrors the wiring
+          // in runPullAll (cloud.ts:331) and runNowSingle (cloud.ts:1371).
+          if (resolvedMode === "all" && resolvedCompanyUid) {
+            emitNarrowHint({
+              companyUid: resolvedCompanyUid,
+              syncMode: resolvedMode,
+              level: narrowHintLevel,
+            });
+          }
         } catch (err) {
           console.error(
             chalk.red("\n✗ Pull failed:"),

package/src/commands/members.test.ts

@@ -246,13 +246,49 @@ describe("inviteMember", () => {
     expect(result.magicLink).toBe("hq://accept/tok_nested");
   });
 
-  it("throws instead of emitting hq://accept/undefined when no token is present", async () => {
+  it("schemaVersion 2: no inviteToken in response → success with undefined magicLink", async () => {
+    // 2026-05-21 fix: the server moved to email-keyed authoritative
+    // membership rows (schemaVersion 2) — the invite IS created, but
+    // there is no token to redeem. The CLI must NOT throw here; instead
+    // the action handler prints "sign in with the invited email"
+    // instructions. Previously this case threw "did not include an
+    // invite token" which produced false-failure UX on a working invite.
     fetchSpy.mockResolvedValueOnce(
-      jsonResponse(200, {
-        membership: { role: "admin", status: "pending" },
+      jsonResponse(201, {
+        membership: {
+          membershipKey: "email:alice@example.com#cmp_acme",
+          role: "member",
+          status: "pending",
+          inviteeEmail: "alice@example.com",
+          schemaVersion: 2,
+        },
       }),
     );
 
+    const result = await inviteMember({
+      target: "alice@example.com",
+      role: "member",
+      companyUid: "cmp_acme",
+      callerUid: "prs_admin",
+      token: "test-token",
+    });
+
+    expect(result.inviteToken).toBeUndefined();
+    expect(result.magicLink).toBeUndefined();
+    expect(result.membership.role).toBe("member");
+    expect(result.membership.status).toBe("pending");
+    expect(result.membership.membershipKey).toBe(
+      "email:alice@example.com#cmp_acme",
+    );
+    expect(result.membership.inviteeEmail).toBe("alice@example.com");
+  });
+
+  it("throws when the response has no membership row at all (server bug)", async () => {
+    // Belt-and-suspenders: a 2xx response with NO membership row is a
+    // server-side regression — surface it loudly so it doesn't silently
+    // succeed-but-do-nothing.
+    fetchSpy.mockResolvedValueOnce(jsonResponse(201, {}));
+
     await expect(
       inviteMember({
         target: "alice@example.com",
@@ -261,7 +297,7 @@ describe("inviteMember", () => {
         callerUid: "prs_admin",
         token: "test-token",
       }),
-    ).rejects.toThrow(/did not include an invite token/);
+    ).rejects.toThrow(/no membership row/);
   });
 });
 
@@ -313,6 +349,47 @@ describe("listPendingInvites", () => {
     fetchSpy.mockResolvedValueOnce(jsonResponse(200, {}));
     await expect(listPendingInvites("test-token", "cmp_acme")).resolves.toEqual([]);
   });
+
+  it("schemaVersion 2: reads `pending` key (the canonical server response)", async () => {
+    // 2026-05-21 fix: live server returns `{ pending: [...] }`, not
+    // `{ invites: [...] }`. The CLI must read `pending` as the primary
+    // and fall back to `invites` for older stages.
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        pending: [
+          {
+            membershipKey: "email:alice@example.com#cmp_acme",
+            inviteeEmail: "alice@example.com",
+            companyUid: "cmp_acme",
+            role: "member",
+            status: "pending",
+            invitedBy: "prs_admin",
+            invitedAt: "2026-05-21T12:00:00Z",
+            schemaVersion: 2,
+          },
+        ],
+      }),
+    );
+
+    const invites = await listPendingInvites("test-token", "cmp_acme");
+    expect(invites).toHaveLength(1);
+    expect(invites[0].membershipKey).toBe("email:alice@example.com#cmp_acme");
+    expect(invites[0].inviteeEmail).toBe("alice@example.com");
+  });
+
+  it("prefers `pending` over legacy `invites` when both present (server transition)", async () => {
+    // Defensive: an in-flight server deploy could briefly return BOTH
+    // fields. CLI takes the canonical `pending` key.
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        pending: [{ membershipKey: "k_pending" } as never],
+        invites: [{ membershipKey: "k_legacy" } as never],
+      }),
+    );
+    const invites = await listPendingInvites("test-token", "cmp_acme");
+    expect(invites).toHaveLength(1);
+    expect(invites[0].membershipKey).toBe("k_pending");
+  });
 });
 
 // ---------------------------------------------------------------------------

package/src/commands/members.ts

@@ -38,10 +38,30 @@ export interface InviteOptions {
   token: string;
 }
 
+/**
+ * Outcome of `hq members invite`. Two shapes depending on server schema:
+ *
+ *  - **schemaVersion ≤ 1** — server returns a random `inviteToken` the
+ *    invitee redeems via the `hq://accept/{token}` magic link. `magicLink`
+ *    is populated so the caller can print or paste it.
+ *  - **schemaVersion 2+** (current production) — membership row is
+ *    email-keyed and authoritative. There is no token; the invitee
+ *    accepts by signing into HQ with the same email. `inviteToken` +
+ *    `magicLink` are both `undefined`; the caller prints sign-in
+ *    instructions instead.
+ *
+ * `membership` is always populated when the server returned 2xx.
+ */
 export interface InviteResult {
-  inviteToken: string;
-  magicLink: string;
-  membership: { role: string; status: string; inviteToken?: string };
+  inviteToken?: string;
+  magicLink?: string;
+  membership: {
+    membershipKey?: string;
+    role: string;
+    status: string;
+    inviteToken?: string;
+    inviteeEmail?: string;
+  };
 }
 
 export interface DetectedTarget {
@@ -137,24 +157,38 @@ export async function inviteMember(
   }
 
   const data = (await res.json()) as {
-    membership?: { role: string; status: string; inviteToken?: string };
+    membership?: {
+      membershipKey?: string;
+      role: string;
+      status: string;
+      inviteToken?: string;
+      inviteeEmail?: string;
+      schemaVersion?: number;
+    };
     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) {
+  if (!data.membership) {
     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.",
+      `Invite endpoint returned 2xx with no membership row (response keys: ${keys}). ` +
+        "This is a server-side regression — file an issue.",
     );
   }
+  // Two server schemas in the wild:
+  //   - Legacy (schemaVersion ≤ 1): response carries a random `inviteToken`
+  //     the invitee redeems via `hq://accept/{token}`.
+  //   - Current (schemaVersion 2+): membership row is email-keyed and
+  //     authoritative — there is no token. The invitee accepts by signing
+  //     into HQ with the invited email. The CLI must NOT throw here
+  //     (previously did: "response did not include an invite token") — the
+  //     invite IS successfully created on the server; the caller just gets
+  //     undefined for inviteToken/magicLink and prints sign-in instructions.
+  const inviteToken = data.inviteToken ?? data.membership.inviteToken;
   return {
-    inviteToken,
-    magicLink: `hq://accept/${inviteToken}`,
-    membership: data.membership ?? { role: options.role, status: "pending" },
+    ...(inviteToken
+      ? { inviteToken, magicLink: `hq://accept/${inviteToken}` }
+      : {}),
+    membership: data.membership,
   };
 }
 
@@ -204,8 +238,14 @@ export async function listPendingInvites(
       err.code,
     );
   }
-  const data = (await res.json()) as { invites?: PendingInvite[] | null };
-  return data?.invites ?? [];
+  // Server schema: `{ pending: [...] }`. Earlier dev branches used
+  // `{ invites: [...] }` which the CLI still accepts as a fallback for
+  // operators running staging stages that haven't caught up yet.
+  const data = (await res.json()) as {
+    pending?: PendingInvite[] | null;
+    invites?: PendingInvite[] | null;
+  };
+  return data?.pending ?? data?.invites ?? [];
 }
 
 export async function revokeInvite(
@@ -275,14 +315,40 @@ export function registerMembersCommand(program: Command): void {
             ),
           );
           console.log();
-          console.log(chalk.bold("Magic link:"));
-          console.log(`  ${result.magicLink}`);
-          console.log();
-          console.log(
-            chalk.dim(
-              "Share this link with the invitee. They can run `hq onboard join --invite-token <token>` to accept.",
-            ),
-          );
+          if (result.magicLink) {
+            // Legacy server schema — magic-link redemption.
+            console.log(chalk.bold("Magic link:"));
+            console.log(`  ${result.magicLink}`);
+            console.log();
+            console.log(
+              chalk.dim(
+                "Share this link with the invitee. They can run `hq onboard join --invite-token <token>` to accept.",
+              ),
+            );
+          } else {
+            // schemaVersion 2+ — email-keyed authoritative membership row.
+            // No magic link to share; invitee accepts by signing into HQ.
+            const inviteeEmail =
+              result.membership.inviteeEmail ??
+              (typeof target === "string" && target.includes("@")
+                ? target
+                : undefined);
+            console.log(chalk.bold("Next step:"));
+            console.log(
+              `  Tell ${inviteeEmail ?? "the invitee"} to sign into HQ at https://hq.getindigo.ai with that email.`,
+            );
+            console.log(
+              chalk.dim(
+                "  The pending membership row claims itself on first sign-in — no separate token redemption.",
+              ),
+            );
+            if (result.membership.membershipKey) {
+              console.log();
+              console.log(
+                chalk.dim(`  Membership key: ${result.membership.membershipKey}`),
+              );
+            }
+          }
         } catch (err) {
           if (err instanceof InviteHttpError) {
             console.error(