@indigoai-us/hq-cli 5.36.3 → 5.36.4

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.3",
+  "version": "5.36.4",
   "description": "HQ by Indigo management CLI \u2014 modules and cloud sync",
   "main": "dist/index.js",
   "bin": {

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),