@indigoai-us/hq-cli 5.36.2 → 5.36.4

package/dist/commands/cloud.js

@@ -13,11 +13,11 @@
  *   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]="94a293c9-eb80-5100-a3e0-d64c93f7165c")}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]="856084be-3bbb-50cd-8e3b-1e19ea13f4fb")}catch(e){}}();
 import chalk from "chalk";
 import * as fs from "fs";
 import * as path from "path";
-import { share, sync, readJournal, getJournalPath, loadCachedTokens, VaultClient, computePersonalVaultPaths, } from "@indigoai-us/hq-cloud";
+import { share, sync, readJournal, getJournalPath, loadCachedTokens, VaultClient, computePersonalVaultPaths, PERSONAL_VAULT_JOURNAL_SLUG, } from "@indigoai-us/hq-cloud";
 import { DEFAULT_HQ_ROOT, ensureCognitoToken, buildVaultConfig, } from "../utils/cognito-session.js";
 import { emitNarrowHint, isStrictRefusal, resolveBannerLevel, } from "../lib/narrow-hint-banner.js";
 /**
@@ -89,13 +89,18 @@ export async function pullAll(options, deps) {
     }
     const personal = options.skipPersonal ? null : pickCanonicalPerson(persons);
     if (personal) {
+        // Canonical slug, NOT the literal "personal": that legacy slug is the
+        // companies/personal company's journal. hq-sync-runner moved the vault
+        // slot to PERSONAL_VAULT_JOURNAL_SLUG; hq-cli journaling the same vault
+        // under the old slug split the bookkeeping across two files — every CLI
+        // sync re-flagged the menubar's already-synced files as conflicts.
         plan.push({
             slug: "personal",
             syncOptions: {
                 company: personal.uid,
                 hqRoot: options.hqRoot,
                 personalMode: true,
-                journalSlug: "personal",
+                journalSlug: PERSONAL_VAULT_JOURNAL_SLUG,
                 ...(options.onConflict ? { onConflict: options.onConflict } : {}),
             },
         });
@@ -213,7 +218,7 @@ export async function pushAll(options, deps) {
                 hqRoot: options.hqRoot,
                 paths: computePersonalVaultPaths(options.hqRoot),
                 personalMode: true,
-                journalSlug: "personal",
+                journalSlug: PERSONAL_VAULT_JOURNAL_SLUG,
                 skipUnchanged: true,
                 propagateDeletes: true,
                 propagateDeletePolicy: resolveDeletePolicy(),
@@ -481,7 +486,7 @@ export function registerCloudCommands(program) {
                     getEntity: async () => null,
                 });
                 personalMode = true;
-                journalSlug = "personal";
+                journalSlug = PERSONAL_VAULT_JOURNAL_SLUG;
             }
             // Default paths. For `--personal` with no explicit paths, default to
             // the canonical personal-vault top-level scope so re-runs from a
@@ -833,7 +838,7 @@ async function runPullPersonal(hqRoot, onConflict) {
             vaultConfig,
             hqRoot,
             personalMode: true,
-            journalSlug: "personal",
+            journalSlug: PERSONAL_VAULT_JOURNAL_SLUG,
         });
         if (result.aborted) {
             console.log(chalk.yellow(`\n⚠ Pull aborted (${result.filesDownloaded} downloaded, ${result.filesSkipped} skipped, ${result.conflicts} conflicts)`));
@@ -954,7 +959,7 @@ async function runNowSingle(hqRoot, company, personal, message, onConflict, mode
                 getEntity: async () => null,
             });
             personalMode = true;
-            journalSlug = "personal";
+            journalSlug = PERSONAL_VAULT_JOURNAL_SLUG;
             pushPaths = computePersonalVaultPaths(hqRoot);
         }
         else {
@@ -1163,4 +1168,4 @@ function resolveUploadAuthorFromCache() {
     }
 }
 //# sourceMappingURL=cloud.js.map
-//# debugId=94a293c9-eb80-5100-a3e0-d64c93f7165c
+//# debugId=856084be-3bbb-50cd-8e3b-1e19ea13f4fb

package/dist/commands/onboard-identity-guard.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Onboarding identity-link guard (DEV-1695 / DEV-1701 / DEV-1721).
+ *
+ * Failure mode this guards against:
+ *
+ *   The onboarding orchestrator's `create-person` step resolves the caller's
+ *   person entity by an email-derived slug GLOBALLY (not scoped to the caller's
+ *   Cognito identity). When a user signs back in under a DIFFERENT Cognito
+ *   `sub` — e.g. a new Google account, an email change, or a linked-IdP sub
+ *   swap — the slug lookup still finds the person row created under the ORIGINAL
+ *   sub and records it in the checkpoint's `personUid`. `create-person` is then
+ *   marked complete and is never re-validated against the live identity.
+ *
+ *   On every `hq onboard resume`, `create-person` is skipped as "already
+ *   complete" while the stale `personUid` is carried forward. The server
+ *   correctly refuses to bootstrap a company membership for a person the caller
+ *   does not own (it resolves the caller's person by the live Cognito sub), so
+ *   resume re-fails at `bootstrap-membership` every single time — an infinite
+ *   loop with a misleading downstream error.
+ *
+ * This module is the detection half of the fix: given the local checkpoint and
+ * the set of person entities ACTUALLY owned by the current caller (the server
+ * scopes `/entity/by-type/person` by the live Cognito sub), it reports whether
+ * the checkpoint adopted a person the caller no longer owns. The resume command
+ * uses it to surface a recoverable, actionable error instead of looping.
+ */
+import type { OnboardingCheckpoint } from "@indigoai-us/hq-onboarding";
+export type OnboardingIdentityCheck = {
+    kind: "ok";
+} | {
+    kind: "mismatch";
+    personUid: string;
+    message: string;
+};
+/**
+ * Detect the person-entity-vs-Cognito-sub mismatch that wedges
+ * `hq onboard resume` into an infinite loop.
+ *
+ * Returns `{ kind: "ok" }` whenever the flow should proceed normally:
+ *   - there is no checkpoint, or
+ *   - the checkpoint never recorded an adopted person (`personUid` unset, or
+ *     `create-person` not yet completed), or
+ *   - the adopted person is among those owned by the current caller.
+ *
+ * Returns `{ kind: "mismatch", ... }` only when the checkpoint completed
+ * `create-person` with a `personUid` that the current caller does NOT own —
+ * the exact state that loops forever at `bootstrap-membership`.
+ */
+export declare function detectOnboardingIdentityMismatch(input: {
+    checkpoint: OnboardingCheckpoint | null;
+    ownedPersonUids: readonly string[];
+}): OnboardingIdentityCheck;
+//# sourceMappingURL=onboard-identity-guard.d.ts.map

package/dist/commands/onboard-identity-guard.js

@@ -0,0 +1,94 @@
+/**
+ * Onboarding identity-link guard (DEV-1695 / DEV-1701 / DEV-1721).
+ *
+ * Failure mode this guards against:
+ *
+ *   The onboarding orchestrator's `create-person` step resolves the caller's
+ *   person entity by an email-derived slug GLOBALLY (not scoped to the caller's
+ *   Cognito identity). When a user signs back in under a DIFFERENT Cognito
+ *   `sub` — e.g. a new Google account, an email change, or a linked-IdP sub
+ *   swap — the slug lookup still finds the person row created under the ORIGINAL
+ *   sub and records it in the checkpoint's `personUid`. `create-person` is then
+ *   marked complete and is never re-validated against the live identity.
+ *
+ *   On every `hq onboard resume`, `create-person` is skipped as "already
+ *   complete" while the stale `personUid` is carried forward. The server
+ *   correctly refuses to bootstrap a company membership for a person the caller
+ *   does not own (it resolves the caller's person by the live Cognito sub), so
+ *   resume re-fails at `bootstrap-membership` every single time — an infinite
+ *   loop with a misleading downstream error.
+ *
+ * This module is the detection half of the fix: given the local checkpoint and
+ * the set of person entities ACTUALLY owned by the current caller (the server
+ * scopes `/entity/by-type/person` by the live Cognito sub), it reports whether
+ * the checkpoint adopted a person the caller no longer owns. The resume command
+ * uses it to surface a recoverable, actionable error instead of looping.
+ */
+/**
+ * Build the human-facing recovery message for a detected mismatch.
+ *
+ * Only the two recovery paths that ACTUALLY work are offered. Deleting the
+ * checkpoint and re-running `create-company` does NOT help: the email-derived
+ * slug would re-adopt the same other-owned person row, so it is deliberately
+ * not suggested.
+ */
+
+!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]="5e986156-276e-5583-a43d-74696c122d40")}catch(e){}}();
+function buildMismatchMessage(personUid) {
+    return [
+        `Onboarding can't continue — an identity-link mismatch is blocking resume.`,
+        ``,
+        `Your saved onboarding checkpoint is linked to person record ${personUid},`,
+        `but that record is owned by a different sign-in than the one you're using`,
+        `now. This usually means onboarding was started under one identity (one`,
+        `Google account / email) and later resumed under a different one.`,
+        ``,
+        `Because the person record belongs to the original sign-in, resume can't`,
+        `bootstrap your company membership and would otherwise retry forever.`,
+        ``,
+        `To recover, do ONE of the following:`,
+        `  1. Sign out and sign back in with your ORIGINAL onboarding identity,`,
+        `     then re-run 'hq onboard resume'.`,
+        `  2. Ask an HQ admin to relink person ${personUid} to your current`,
+        `     sign-in (reference Linear DEV-1695), then re-run 'hq onboard resume'.`,
+        ``,
+        `Nothing was changed — your data is safe.`,
+    ].join("\n");
+}
+/**
+ * Detect the person-entity-vs-Cognito-sub mismatch that wedges
+ * `hq onboard resume` into an infinite loop.
+ *
+ * Returns `{ kind: "ok" }` whenever the flow should proceed normally:
+ *   - there is no checkpoint, or
+ *   - the checkpoint never recorded an adopted person (`personUid` unset, or
+ *     `create-person` not yet completed), or
+ *   - the adopted person is among those owned by the current caller.
+ *
+ * Returns `{ kind: "mismatch", ... }` only when the checkpoint completed
+ * `create-person` with a `personUid` that the current caller does NOT own —
+ * the exact state that loops forever at `bootstrap-membership`.
+ */
+export function detectOnboardingIdentityMismatch(input) {
+    const { checkpoint, ownedPersonUids } = input;
+    if (!checkpoint)
+        return { kind: "ok" };
+    const adopted = checkpoint.personUid;
+    if (!adopted)
+        return { kind: "ok" };
+    // Mirror the orchestrator's `isStepComplete`: a personUid that predates the
+    // create-person step completing has not been committed as the adopted
+    // identity yet, so don't treat it as a mismatch.
+    if (!checkpoint.completedSteps?.includes("create-person")) {
+        return { kind: "ok" };
+    }
+    if (ownedPersonUids.includes(adopted))
+        return { kind: "ok" };
+    return {
+        kind: "mismatch",
+        personUid: adopted,
+        message: buildMismatchMessage(adopted),
+    };
+}
+//# sourceMappingURL=onboard-identity-guard.js.map
+//# debugId=5e986156-276e-5583-a43d-74696c122d40

package/dist/commands/onboard.js

@@ -19,10 +19,12 @@
  * 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]="38856701-42d8-587b-9969-8da51ede7cd4")}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]="8f6c7f48-0ce5-55f3-bfd9-b4a6040adb0b")}catch(e){}}();
 import chalk from "chalk";
-import { runOnboardCli } from "@indigoai-us/hq-onboarding";
-import { DEFAULT_HQ_ROOT, ensureCognitoToken, buildVaultConfig, } from "../utils/cognito-session.js";
+import { runOnboardCli, readCheckpoint } from "@indigoai-us/hq-onboarding";
+import { DEFAULT_HQ_ROOT, DEFAULT_VAULT_API_URL, ensureCognitoToken, buildVaultConfig, } from "../utils/cognito-session.js";
+import { createDefaultVaultClient } from "./cloud-provision.js";
+import { detectOnboardingIdentityMismatch } from "./onboard-identity-guard.js";
 // ---------------------------------------------------------------------------
 // Command registration
 // ---------------------------------------------------------------------------
@@ -102,6 +104,36 @@ export function registerOnboardCommand(program) {
         .action(async (options) => {
         try {
             const accessToken = await ensureCognitoToken();
+            // Identity-link pre-flight (DEV-1695 / DEV-1701 / DEV-1721): if the
+            // saved checkpoint adopted a person entity owned by a DIFFERENT Cognito
+            // sign-in than the current one, resume would skip the completed
+            // create-person step with that stale personUid and re-fail at
+            // bootstrap-membership forever. Detect it up front and surface a
+            // recoverable, actionable error instead of looping.
+            const checkpoint = await readCheckpoint(options.hqRoot);
+            if (checkpoint?.personUid) {
+                let ownedPersonUids = null;
+                try {
+                    const client = createDefaultVaultClient(DEFAULT_VAULT_API_URL, accessToken);
+                    const owned = await client.listMyPersonEntities();
+                    ownedPersonUids = owned.map((p) => p.uid);
+                }
+                catch (err) {
+                    // Best-effort guard: if the pre-flight lookup itself fails (network,
+                    // auth), don't block resume — but don't swallow it silently either.
+                    console.warn(chalk.yellow(`  (skipping identity pre-flight check: ${err instanceof Error ? err.message : String(err)})`));
+                }
+                if (ownedPersonUids) {
+                    const check = detectOnboardingIdentityMismatch({
+                        checkpoint,
+                        ownedPersonUids,
+                    });
+                    if (check.kind === "mismatch") {
+                        console.error(chalk.red(`\n✗ Resume blocked:\n\n${check.message}`));
+                        process.exit(1);
+                    }
+                }
+            }
             const result = await runOnboardCli({
                 mode: "resume",
                 vaultConfig: buildVaultConfig(accessToken),
@@ -142,4 +174,4 @@ export function registerOnboardCommand(program) {
     });
 }
 //# sourceMappingURL=onboard.js.map
-//# debugId=38856701-42d8-587b-9969-8da51ede7cd4
+//# debugId=8f6c7f48-0ce5-55f3-bfd9-b4a6040adb0b

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.36.2",
+  "version": "5.36.4",
   "description": "HQ by Indigo management CLI \u2014 modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -15,7 +15,7 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@indigoai-us/hq-cloud": "^6.2.2",
+    "@indigoai-us/hq-cloud": "^6.2.4",
     "@indigoai-us/hq-onboarding": "^0.1.0",
     "@sentry/node": "^10.49.0",
     "chalk": "^5.3.0",

package/src/commands/cloud.pull-all.test.ts

@@ -140,7 +140,7 @@ describe("pullAll", () => {
     expect(sync.calls[2]).toMatchObject({
       company: "psn_alice",
       personalMode: true,
-      journalSlug: "personal",
+      journalSlug: "__hq_personal_vault__",
     });
 
     expect(result.attempted).toBe(3);
@@ -300,7 +300,7 @@ describe("pullAll", () => {
     expect(sync.calls).toHaveLength(1);
     expect(sync.calls[0].company).toBe("psn_old");
     expect(sync.calls[0].personalMode).toBe(true);
-    expect(sync.calls[0].journalSlug).toBe("personal");
+    expect(sync.calls[0].journalSlug).toBe("__hq_personal_vault__");
   });
 
   // ── 8/9/10. US-011 narrow-hint banner ─────────────────────────────────────
@@ -565,7 +565,7 @@ describe("pullAll", () => {
       "psn_alice",
     ]);
     expect(sync.calls[1].personalMode).toBe(true);
-    expect(sync.calls[1].journalSlug).toBe("personal");
+    expect(sync.calls[1].journalSlug).toBe("__hq_personal_vault__");
   });
 
   it("skipPersonal=true with empty memberships produces zero sync calls", async () => {

package/src/commands/cloud.push-all.test.ts

@@ -176,7 +176,7 @@ describe("pushAll", () => {
     expect(share.calls[2]).toMatchObject({
       company: "psn_alice",
       personalMode: true,
-      journalSlug: "personal",
+      journalSlug: "__hq_personal_vault__",
       skipUnchanged: true,
       propagateDeletes: true,
     });
@@ -346,7 +346,7 @@ describe("pushAll", () => {
     expect(share.calls).toHaveLength(1);
     expect(share.calls[0].company).toBe("psn_old");
     expect(share.calls[0].personalMode).toBe(true);
-    expect(share.calls[0].journalSlug).toBe("personal");
+    expect(share.calls[0].journalSlug).toBe("__hq_personal_vault__");
   });
 
   // ── 7. Aggregate counts include deletes ───────────────────────────────────
@@ -451,6 +451,6 @@ describe("pushAll", () => {
       "psn_alice",
     ]);
     expect(share.calls[1].personalMode).toBe(true);
-    expect(share.calls[1].journalSlug).toBe("personal");
+    expect(share.calls[1].journalSlug).toBe("__hq_personal_vault__");
   });
 });

package/src/commands/cloud.ts

@@ -26,6 +26,7 @@ import {
   loadCachedTokens,
   VaultClient,
   computePersonalVaultPaths,
+  PERSONAL_VAULT_JOURNAL_SLUG,
   type ConflictStrategy,
   type EntityContext,
   type MembershipSyncConfig,
@@ -301,13 +302,18 @@ export async function pullAll(
 
   const personal = options.skipPersonal ? null : pickCanonicalPerson(persons);
   if (personal) {
+    // Canonical slug, NOT the literal "personal": that legacy slug is the
+    // companies/personal company's journal. hq-sync-runner moved the vault
+    // slot to PERSONAL_VAULT_JOURNAL_SLUG; hq-cli journaling the same vault
+    // under the old slug split the bookkeeping across two files — every CLI
+    // sync re-flagged the menubar's already-synced files as conflicts.
     plan.push({
       slug: "personal",
       syncOptions: {
         company: personal.uid,
         hqRoot: options.hqRoot,
         personalMode: true,
-        journalSlug: "personal",
+        journalSlug: PERSONAL_VAULT_JOURNAL_SLUG,
         ...(options.onConflict ? { onConflict: options.onConflict } : {}),
       },
     });
@@ -442,7 +448,7 @@ export async function pushAll(
         hqRoot: options.hqRoot,
         paths: computePersonalVaultPaths(options.hqRoot),
         personalMode: true,
-        journalSlug: "personal",
+        journalSlug: PERSONAL_VAULT_JOURNAL_SLUG,
         skipUnchanged: true,
         propagateDeletes: true,
         propagateDeletePolicy: resolveDeletePolicy(),
@@ -821,7 +827,7 @@ export function registerCloudCommands(program: Command): void {
               getEntity: async () => null,
             });
             personalMode = true;
-            journalSlug = "personal";
+            journalSlug = PERSONAL_VAULT_JOURNAL_SLUG;
           }
 
           // Default paths. For `--personal` with no explicit paths, default to
@@ -1349,7 +1355,7 @@ async function runPullPersonal(
       vaultConfig,
       hqRoot,
       personalMode: true,
-      journalSlug: "personal",
+      journalSlug: PERSONAL_VAULT_JOURNAL_SLUG,
     });
 
     if (result.aborted) {
@@ -1510,7 +1516,7 @@ async function runNowSingle(
         getEntity: async () => null,
       });
       personalMode = true;
-      journalSlug = "personal";
+      journalSlug = PERSONAL_VAULT_JOURNAL_SLUG;
       pushPaths = computePersonalVaultPaths(hqRoot);
     } else {
       // For company targets we need a concrete slug to compute the push path.

package/src/commands/onboard-identity-guard.test.ts

@@ -0,0 +1,99 @@
+/**
+ * Regression tests for the onboarding identity-link guard
+ * (DEV-1695 / DEV-1701 / DEV-1721).
+ *
+ * Covers the resume-with-mismatched-sub path: a checkpoint that completed
+ * `create-person` against a `personUid` the current caller does NOT own must
+ * be detected as a recoverable mismatch instead of being allowed to loop
+ * forever at bootstrap-membership. Also covers the no-false-positive cases
+ * (no checkpoint, no adopted person, create-person not complete, person owned).
+ *
+ * Pure function — no network, no VaultClient. The resume command supplies the
+ * owned-person UID set from the JWT-scoped `/entity/by-type/person` call.
+ */
+
+import { describe, expect, it } from "vitest";
+import type { OnboardingCheckpoint } from "@indigoai-us/hq-onboarding";
+
+import { detectOnboardingIdentityMismatch } from "./onboard-identity-guard.js";
+
+const OLD_PERSON = "prs_01KRGW9JQ4D2ZHD080B931ZT0J";
+const NEW_PERSON = "prs_01NEWOWNEDBYCURRENTSIGNIN00";
+
+function checkpoint(
+  overrides: Partial<OnboardingCheckpoint> = {},
+): OnboardingCheckpoint {
+  return {
+    mode: "create-company",
+    startedAt: "2026-05-13T14:36:45.668Z",
+    updatedAt: "2026-06-03T14:04:32.261Z",
+    personUid: OLD_PERSON,
+    companyUid: "cmp_01KT6WSNM6HGSH3JZGS8X1KXGS",
+    companySlug: "maximus",
+    completedSteps: ["create-person", "create-company", "provision-bucket"],
+    failedStep: "bootstrap-membership",
+    ...overrides,
+  };
+}
+
+describe("detectOnboardingIdentityMismatch", () => {
+  it("flags the mismatch when the checkpoint's person is owned by a different sign-in", () => {
+    // The Jacob Wuertz case: checkpoint adopted prs_OLD (owned by the original
+    // Cognito sub), but the current caller only owns prs_NEW.
+    const result = detectOnboardingIdentityMismatch({
+      checkpoint: checkpoint(),
+      ownedPersonUids: [NEW_PERSON],
+    });
+
+    expect(result.kind).toBe("mismatch");
+    if (result.kind !== "mismatch") throw new Error("expected mismatch");
+    expect(result.personUid).toBe(OLD_PERSON);
+    expect(result.message).toContain(OLD_PERSON);
+    // Actionable + references the recovery paths that actually work.
+    expect(result.message).toMatch(/DEV-1695/);
+    expect(result.message).toMatch(/original/i);
+    expect(result.message).toMatch(/relink/i);
+  });
+
+  it("also flags the mismatch when the caller owns NO person entities at all", () => {
+    const result = detectOnboardingIdentityMismatch({
+      checkpoint: checkpoint(),
+      ownedPersonUids: [],
+    });
+    expect(result.kind).toBe("mismatch");
+  });
+
+  it("passes when the adopted person IS owned by the current caller", () => {
+    const result = detectOnboardingIdentityMismatch({
+      checkpoint: checkpoint({ personUid: NEW_PERSON }),
+      ownedPersonUids: [NEW_PERSON, "prs_01ANOTHERONE0000000000000000"],
+    });
+    expect(result).toEqual({ kind: "ok" });
+  });
+
+  it("passes when there is no checkpoint", () => {
+    const result = detectOnboardingIdentityMismatch({
+      checkpoint: null,
+      ownedPersonUids: [NEW_PERSON],
+    });
+    expect(result).toEqual({ kind: "ok" });
+  });
+
+  it("passes when the checkpoint has not adopted a person yet (no personUid)", () => {
+    const result = detectOnboardingIdentityMismatch({
+      checkpoint: checkpoint({ personUid: undefined, completedSteps: [] }),
+      ownedPersonUids: [],
+    });
+    expect(result).toEqual({ kind: "ok" });
+  });
+
+  it("passes when create-person is not yet complete, even with a personUid present", () => {
+    // A personUid that predates the create-person step completing is not yet
+    // the committed identity — don't false-positive on it.
+    const result = detectOnboardingIdentityMismatch({
+      checkpoint: checkpoint({ completedSteps: ["create-company"] }),
+      ownedPersonUids: [NEW_PERSON],
+    });
+    expect(result).toEqual({ kind: "ok" });
+  });
+});

package/src/commands/onboard-identity-guard.ts

@@ -0,0 +1,103 @@
+/**
+ * Onboarding identity-link guard (DEV-1695 / DEV-1701 / DEV-1721).
+ *
+ * Failure mode this guards against:
+ *
+ *   The onboarding orchestrator's `create-person` step resolves the caller's
+ *   person entity by an email-derived slug GLOBALLY (not scoped to the caller's
+ *   Cognito identity). When a user signs back in under a DIFFERENT Cognito
+ *   `sub` — e.g. a new Google account, an email change, or a linked-IdP sub
+ *   swap — the slug lookup still finds the person row created under the ORIGINAL
+ *   sub and records it in the checkpoint's `personUid`. `create-person` is then
+ *   marked complete and is never re-validated against the live identity.
+ *
+ *   On every `hq onboard resume`, `create-person` is skipped as "already
+ *   complete" while the stale `personUid` is carried forward. The server
+ *   correctly refuses to bootstrap a company membership for a person the caller
+ *   does not own (it resolves the caller's person by the live Cognito sub), so
+ *   resume re-fails at `bootstrap-membership` every single time — an infinite
+ *   loop with a misleading downstream error.
+ *
+ * This module is the detection half of the fix: given the local checkpoint and
+ * the set of person entities ACTUALLY owned by the current caller (the server
+ * scopes `/entity/by-type/person` by the live Cognito sub), it reports whether
+ * the checkpoint adopted a person the caller no longer owns. The resume command
+ * uses it to surface a recoverable, actionable error instead of looping.
+ */
+
+import type { OnboardingCheckpoint } from "@indigoai-us/hq-onboarding";
+
+export type OnboardingIdentityCheck =
+  | { kind: "ok" }
+  | { kind: "mismatch"; personUid: string; message: string };
+
+/**
+ * Build the human-facing recovery message for a detected mismatch.
+ *
+ * Only the two recovery paths that ACTUALLY work are offered. Deleting the
+ * checkpoint and re-running `create-company` does NOT help: the email-derived
+ * slug would re-adopt the same other-owned person row, so it is deliberately
+ * not suggested.
+ */
+function buildMismatchMessage(personUid: string): string {
+  return [
+    `Onboarding can't continue — an identity-link mismatch is blocking resume.`,
+    ``,
+    `Your saved onboarding checkpoint is linked to person record ${personUid},`,
+    `but that record is owned by a different sign-in than the one you're using`,
+    `now. This usually means onboarding was started under one identity (one`,
+    `Google account / email) and later resumed under a different one.`,
+    ``,
+    `Because the person record belongs to the original sign-in, resume can't`,
+    `bootstrap your company membership and would otherwise retry forever.`,
+    ``,
+    `To recover, do ONE of the following:`,
+    `  1. Sign out and sign back in with your ORIGINAL onboarding identity,`,
+    `     then re-run 'hq onboard resume'.`,
+    `  2. Ask an HQ admin to relink person ${personUid} to your current`,
+    `     sign-in (reference Linear DEV-1695), then re-run 'hq onboard resume'.`,
+    ``,
+    `Nothing was changed — your data is safe.`,
+  ].join("\n");
+}
+
+/**
+ * Detect the person-entity-vs-Cognito-sub mismatch that wedges
+ * `hq onboard resume` into an infinite loop.
+ *
+ * Returns `{ kind: "ok" }` whenever the flow should proceed normally:
+ *   - there is no checkpoint, or
+ *   - the checkpoint never recorded an adopted person (`personUid` unset, or
+ *     `create-person` not yet completed), or
+ *   - the adopted person is among those owned by the current caller.
+ *
+ * Returns `{ kind: "mismatch", ... }` only when the checkpoint completed
+ * `create-person` with a `personUid` that the current caller does NOT own —
+ * the exact state that loops forever at `bootstrap-membership`.
+ */
+export function detectOnboardingIdentityMismatch(input: {
+  checkpoint: OnboardingCheckpoint | null;
+  ownedPersonUids: readonly string[];
+}): OnboardingIdentityCheck {
+  const { checkpoint, ownedPersonUids } = input;
+
+  if (!checkpoint) return { kind: "ok" };
+
+  const adopted = checkpoint.personUid;
+  if (!adopted) return { kind: "ok" };
+
+  // Mirror the orchestrator's `isStepComplete`: a personUid that predates the
+  // create-person step completing has not been committed as the adopted
+  // identity yet, so don't treat it as a mismatch.
+  if (!checkpoint.completedSteps?.includes("create-person")) {
+    return { kind: "ok" };
+  }
+
+  if (ownedPersonUids.includes(adopted)) return { kind: "ok" };
+
+  return {
+    kind: "mismatch",
+    personUid: adopted,
+    message: buildMismatchMessage(adopted),
+  };
+}

package/src/commands/onboard.ts

@@ -22,12 +22,15 @@
 import { Command } from "commander";
 import chalk from "chalk";
 
-import { runOnboardCli } from "@indigoai-us/hq-onboarding";
+import { runOnboardCli, readCheckpoint } from "@indigoai-us/hq-onboarding";
 import {
   DEFAULT_HQ_ROOT,
+  DEFAULT_VAULT_API_URL,
   ensureCognitoToken,
   buildVaultConfig,
 } from "../utils/cognito-session.js";
+import { createDefaultVaultClient } from "./cloud-provision.js";
+import { detectOnboardingIdentityMismatch } from "./onboard-identity-guard.js";
 
 // ---------------------------------------------------------------------------
 // Command registration
@@ -143,6 +146,46 @@ export function registerOnboardCommand(program: Command): void {
     .action(async (options: { hqRoot: string }) => {
       try {
         const accessToken = await ensureCognitoToken();
+
+        // Identity-link pre-flight (DEV-1695 / DEV-1701 / DEV-1721): if the
+        // saved checkpoint adopted a person entity owned by a DIFFERENT Cognito
+        // sign-in than the current one, resume would skip the completed
+        // create-person step with that stale personUid and re-fail at
+        // bootstrap-membership forever. Detect it up front and surface a
+        // recoverable, actionable error instead of looping.
+        const checkpoint = await readCheckpoint(options.hqRoot);
+        if (checkpoint?.personUid) {
+          let ownedPersonUids: string[] | null = null;
+          try {
+            const client = createDefaultVaultClient(
+              DEFAULT_VAULT_API_URL,
+              accessToken,
+            );
+            const owned = await client.listMyPersonEntities();
+            ownedPersonUids = owned.map((p) => p.uid);
+          } catch (err) {
+            // Best-effort guard: if the pre-flight lookup itself fails (network,
+            // auth), don't block resume — but don't swallow it silently either.
+            console.warn(
+              chalk.yellow(
+                `  (skipping identity pre-flight check: ${
+                  err instanceof Error ? err.message : String(err)
+                })`,
+              ),
+            );
+          }
+          if (ownedPersonUids) {
+            const check = detectOnboardingIdentityMismatch({
+              checkpoint,
+              ownedPersonUids,
+            });
+            if (check.kind === "mismatch") {
+              console.error(chalk.red(`\n✗ Resume blocked:\n\n${check.message}`));
+              process.exit(1);
+            }
+          }
+        }
+
         const result = await runOnboardCli({
           mode: "resume",
           vaultConfig: buildVaultConfig(accessToken),