@indigoai-us/hq-cli 5.36.3 → 5.36.5

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/dist/utils/cognito-session.d.ts

@@ -22,47 +22,51 @@ import { type CognitoAuthConfig, type ClientInfo, type VaultServiceConfig } from
 export declare const DEFAULT_COGNITO: CognitoAuthConfig;
 export declare const DEFAULT_VAULT_API_URL: string;
 /**
- * Resolve the default HQ tree root for cloud-aware subcommands.
+ * Resolve the HQ tree root for cloud-aware subcommands (`hq sync`, `hq onboard`,
+ * `hq cloud …`, etc.).
  *
- * Priority order:
- *   1. `$HQ_ROOT` env var (explicit user override)
- *   2. Walk up from `process.cwd()` to the nearest dir containing BOTH a
- *      `core.yaml` file AND a `companies/` directory (root-unique marker
- *      pair — see note below).
- *   3. Fall back to `~/hq` (the historical default)
+ * Resolution order — mirrors the menubar/installer resolver
+ * (`hq-sync` `util/paths.rs::resolve_hq_folder`) so the CLI targets the SAME
+ * root the AppBar syncs, regardless of cwd:
+ *   1. `$HQ_ROOT` env var — explicit assertion by the caller; short-circuits all.
+ *   2. Walk up from `process.cwd()` to the nearest HQ root (working-tree wins:
+ *      if you're inside an HQ tree, operate on THAT tree). See {@link isHqRoot}.
+ *   3. `~/.hq/menubar.json` → `hqPath` — the canonical record written by the
+ *      installer (≥0.1.28) and the menubar's Settings re-tether. Same field HQ
+ *      Sync reads first.
+ *   4. `~/.hq/config.json` → `hqFolderPath` — legacy installer record.
+ *   5. Discovery: scan well-known locations (`~/HQ`, `~/hq`, `~/Documents/HQ`,
+ *      …) for a folder carrying a valid `core.yaml` signature. Safety net for
+ *      installs that never wrote the path back to menubar.json.
+ *   6. Fall back to `~/hq` (the historical CLI default) — or throw, per
+ *      `opts.onMissing`.
  *
- * Why both markers?
- *   The HQ root has `core.yaml` AND a sibling `companies/` directory. The
- *   synced `core/` subtree (which is itself part of the root's personal-vault
- *   scope) ALSO contains a `core.yaml` (the template's version-source-of-
- *   truth), but does NOT contain `companies/`. Single-marker `core.yaml`
- *   detection would stop at `<hqRoot>/core/` when the CLI is launched from
- *   somewhere inside that subtree, and downstream `companies/` lookups would
- *   silently miss the real content. Requiring `companies/` as well guarantees
- *   we resolve to the actual HQ root (Codex P2 on hq#146).
+ * Why tiers 3–5 exist:
+ *   Before this, the CLI only knew `$HQ_ROOT` and the cwd walk-up. Run from any
+ *   cwd OUTSIDE the HQ tree with `$HQ_ROOT` unset, it fell straight to `~/hq` —
+ *   so a user whose HQ lives anywhere else (e.g. `~/Desktop/HQ`, as the AppBar
+ *   syncs it) silently got a brand-new `~/hq` stub and a full re-sync into it
+ *   (split-brain). Reading the installer/menubar records the way HQ Sync does
+ *   closes that gap (feedback_3967e294).
  *
- * Evaluated once at module load — commander.js `.option()` callers pin the
- * value at registration time, which matches the user's actual cwd at process
- * start. Re-importable as a function for tests and command-time resolution.
- */
-/**
- * Resolve the HQ root directory.
- *
- * Resolution order:
- *   1. $HQ_ROOT env var (treated as an explicit assertion by the caller)
- *   2. Walk up from cwd looking for `core.yaml` AND `companies/` siblings
- *   3. Fall back to `~/hq` (or throw, per `opts.onMissing`)
+ * Why both markers in the walk-up (tier 2)?
+ *   An HQ root has a `core.yaml` (canonical `core/core.yaml` since hq-core v14,
+ *   legacy `<root>/core.yaml` before) AND a sibling `companies/` directory. The
+ *   synced `core/` subtree ALSO contains a `core.yaml` (the template version
+ *   source-of-truth) but NO `companies/`. Requiring `companies/` as well stops
+ *   the walk from latching onto `<hqRoot>/core/` (Codex P2 on hq#146).
  *
- * `opts.onMissing` controls the third arm:
- *   - `'fallback'` (default) — return `~/hq` if no HQ root is found above cwd.
- *     This preserves the module-load contract of `DEFAULT_HQ_ROOT`, which
- *     several commander.js `.option()` callers pin at registration time.
- *   - `'throw'` — throw with a user-actionable error. Used by module-management
- *     commands (pkg-install, pkg-remove, pkg-list, pkg-update, team-sync) where
- *     a silent default-path miss would silently target the wrong directory.
+ * `opts.onMissing` controls the final arm:
+ *   - `'fallback'` (default) — return `~/hq` if nothing resolves. Preserves the
+ *     module-load contract of `DEFAULT_HQ_ROOT`, pinned by commander.js
+ *     `.option()` callers at registration time.
+ *   - `'throw'` — throw a user-actionable error. Used by module-management
+ *     commands (pkg-*, team-sync) where a silent default-path miss would
+ *     target the wrong directory.
  *
- * `$HQ_ROOT` short-circuits both arms — if the env var is set, it's used
- * as-is regardless of `onMissing`.
+ * Evaluated once at module load for `DEFAULT_HQ_ROOT`; the installer/menubar
+ * records and cwd are both fixed at process start, so a one-shot read is sound.
+ * Re-importable as a function for command-time resolution and tests.
  */
 export declare function resolveDefaultHqRoot(opts?: {
     onMissing?: "throw" | "fallback";

package/dist/utils/cognito-session.js

@@ -19,10 +19,11 @@
  *   HQ_VAULT_API_URL           — vault-service API Gateway URL
  */
 
-!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]="cd9690e0-c7b0-5e26-a3ee-7f7bc98a0fe2")}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]="984bafe3-242a-5322-a2fe-65261b24ee0b")}catch(e){}}();
 import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
+import * as yaml from "js-yaml";
 import chalk from "chalk";
 import { loadCachedTokens, isExpiring, refreshTokens, browserLogin, detectHqCoreVersion, } from "@indigoai-us/hq-cloud";
 import { CLI_NAME, CLI_VERSION } from "../cli-version.js";
@@ -44,66 +45,174 @@ export const DEFAULT_COGNITO = {
 };
 export const DEFAULT_VAULT_API_URL = process.env.HQ_VAULT_API_URL ?? "https://hqapi.getindigo.ai";
 /**
- * Resolve the default HQ tree root for cloud-aware subcommands.
+ * Resolve the HQ tree root for cloud-aware subcommands (`hq sync`, `hq onboard`,
+ * `hq cloud …`, etc.).
  *
- * Priority order:
- *   1. `$HQ_ROOT` env var (explicit user override)
- *   2. Walk up from `process.cwd()` to the nearest dir containing BOTH a
- *      `core.yaml` file AND a `companies/` directory (root-unique marker
- *      pair — see note below).
- *   3. Fall back to `~/hq` (the historical default)
+ * Resolution order — mirrors the menubar/installer resolver
+ * (`hq-sync` `util/paths.rs::resolve_hq_folder`) so the CLI targets the SAME
+ * root the AppBar syncs, regardless of cwd:
+ *   1. `$HQ_ROOT` env var — explicit assertion by the caller; short-circuits all.
+ *   2. Walk up from `process.cwd()` to the nearest HQ root (working-tree wins:
+ *      if you're inside an HQ tree, operate on THAT tree). See {@link isHqRoot}.
+ *   3. `~/.hq/menubar.json` → `hqPath` — the canonical record written by the
+ *      installer (≥0.1.28) and the menubar's Settings re-tether. Same field HQ
+ *      Sync reads first.
+ *   4. `~/.hq/config.json` → `hqFolderPath` — legacy installer record.
+ *   5. Discovery: scan well-known locations (`~/HQ`, `~/hq`, `~/Documents/HQ`,
+ *      …) for a folder carrying a valid `core.yaml` signature. Safety net for
+ *      installs that never wrote the path back to menubar.json.
+ *   6. Fall back to `~/hq` (the historical CLI default) — or throw, per
+ *      `opts.onMissing`.
  *
- * Why both markers?
- *   The HQ root has `core.yaml` AND a sibling `companies/` directory. The
- *   synced `core/` subtree (which is itself part of the root's personal-vault
- *   scope) ALSO contains a `core.yaml` (the template's version-source-of-
- *   truth), but does NOT contain `companies/`. Single-marker `core.yaml`
- *   detection would stop at `<hqRoot>/core/` when the CLI is launched from
- *   somewhere inside that subtree, and downstream `companies/` lookups would
- *   silently miss the real content. Requiring `companies/` as well guarantees
- *   we resolve to the actual HQ root (Codex P2 on hq#146).
+ * Why tiers 3–5 exist:
+ *   Before this, the CLI only knew `$HQ_ROOT` and the cwd walk-up. Run from any
+ *   cwd OUTSIDE the HQ tree with `$HQ_ROOT` unset, it fell straight to `~/hq` —
+ *   so a user whose HQ lives anywhere else (e.g. `~/Desktop/HQ`, as the AppBar
+ *   syncs it) silently got a brand-new `~/hq` stub and a full re-sync into it
+ *   (split-brain). Reading the installer/menubar records the way HQ Sync does
+ *   closes that gap (feedback_3967e294).
  *
- * Evaluated once at module load — commander.js `.option()` callers pin the
- * value at registration time, which matches the user's actual cwd at process
- * start. Re-importable as a function for tests and command-time resolution.
- */
-/**
- * Resolve the HQ root directory.
+ * Why both markers in the walk-up (tier 2)?
+ *   An HQ root has a `core.yaml` (canonical `core/core.yaml` since hq-core v14,
+ *   legacy `<root>/core.yaml` before) AND a sibling `companies/` directory. The
+ *   synced `core/` subtree ALSO contains a `core.yaml` (the template version
+ *   source-of-truth) but NO `companies/`. Requiring `companies/` as well stops
+ *   the walk from latching onto `<hqRoot>/core/` (Codex P2 on hq#146).
  *
- * Resolution order:
- *   1. $HQ_ROOT env var (treated as an explicit assertion by the caller)
- *   2. Walk up from cwd looking for `core.yaml` AND `companies/` siblings
- *   3. Fall back to `~/hq` (or throw, per `opts.onMissing`)
+ * `opts.onMissing` controls the final arm:
+ *   - `'fallback'` (default) — return `~/hq` if nothing resolves. Preserves the
+ *     module-load contract of `DEFAULT_HQ_ROOT`, pinned by commander.js
+ *     `.option()` callers at registration time.
+ *   - `'throw'` — throw a user-actionable error. Used by module-management
+ *     commands (pkg-*, team-sync) where a silent default-path miss would
+ *     target the wrong directory.
  *
- * `opts.onMissing` controls the third arm:
- *   - `'fallback'` (default) — return `~/hq` if no HQ root is found above cwd.
- *     This preserves the module-load contract of `DEFAULT_HQ_ROOT`, which
- *     several commander.js `.option()` callers pin at registration time.
- *   - `'throw'` — throw with a user-actionable error. Used by module-management
- *     commands (pkg-install, pkg-remove, pkg-list, pkg-update, team-sync) where
- *     a silent default-path miss would silently target the wrong directory.
- *
- * `$HQ_ROOT` short-circuits both arms — if the env var is set, it's used
- * as-is regardless of `onMissing`.
+ * Evaluated once at module load for `DEFAULT_HQ_ROOT`; the installer/menubar
+ * records and cwd are both fixed at process start, so a one-shot read is sound.
+ * Re-importable as a function for command-time resolution and tests.
  */
 export function resolveDefaultHqRoot(opts = {}) {
+    // Tier 1: explicit override.
     if (process.env.HQ_ROOT)
         return path.resolve(process.env.HQ_ROOT);
+    // Tier 2: working-tree walk-up — operate on the HQ tree you're inside.
     let cur = path.resolve(process.cwd());
     while (cur !== path.dirname(cur)) {
         if (isHqRoot(cur))
             return cur;
         cur = path.dirname(cur);
     }
+    // Tiers 3–4: the installer/menubar's canonical "where is HQ" records.
+    const fromConfig = readHqRootFromHqConfig(path.join(os.homedir(), ".hq"));
+    if (fromConfig)
+        return path.resolve(fromConfig);
+    // Tier 5: discover a valid HQ root in the well-known locations.
+    const discovered = discoverHqRootViaCoreYaml();
+    if (discovered)
+        return discovered;
+    // Tier 6: nothing resolved.
     if (opts.onMissing === "throw") {
         throw new Error("Could not find HQ root. Run this command from within your HQ directory " +
-            "(must contain core.yaml AND a companies/ subdirectory), or set $HQ_ROOT.");
+            "(must contain core.yaml AND a companies/ subdirectory), set $HQ_ROOT, " +
+            "or install HQ via the installer/menubar so ~/.hq/menubar.json records " +
+            "its location.");
     }
     return path.join(os.homedir(), "hq");
 }
-/** True iff `dir` looks like an HQ root (has core.yaml + companies/ dir). */
+/**
+ * Read the configured HQ root from the installer/menubar records under
+ * `hqConfigDir` (`~/.hq`). Mirrors HQ Sync's precedence:
+ *   1. `menubar.json` → `hqPath` (canonical; written by installer ≥0.1.28 and
+ *      the menubar Settings re-tether)
+ *   2. `config.json` → `hqFolderPath` (legacy installer flows)
+ * Returns the first non-empty string, or undefined. Best-effort: a missing or
+ * malformed file is treated as "not configured" (never throws).
+ */
+function readHqRootFromHqConfig(hqConfigDir) {
+    const fromMenubar = readJsonStringField(path.join(hqConfigDir, "menubar.json"), "hqPath");
+    if (fromMenubar)
+        return fromMenubar;
+    return readJsonStringField(path.join(hqConfigDir, "config.json"), "hqFolderPath");
+}
+/** Read a top-level string field from a JSON file, or undefined on any miss. */
+function readJsonStringField(file, field) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf-8"));
+        const value = parsed[field];
+        return typeof value === "string" && value.length > 0 ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Well-known parent locations an HQ tree commonly lives in (mirrors hq-sync). */
+function hqDiscoveryCandidates() {
+    const home = os.homedir();
+    return [
+        path.join(home, "HQ"),
+        path.join(home, "hq"),
+        path.join(home, "Documents", "HQ"),
+        path.join(home, "Documents", "hq"),
+        path.join(home, "Desktop", "HQ"),
+        path.join(home, "Desktop", "hq"),
+    ];
+}
+/**
+ * Scan the well-known locations for a folder carrying a valid `core.yaml`
+ * signature. First match wins; returns undefined if none qualify. Cheap — a
+ * few stats plus one small YAML parse on a hit.
+ */
+function discoverHqRootViaCoreYaml() {
+    return hqDiscoveryCandidates().find(isValidHqRootSignature);
+}
+/**
+ * True iff `dir` carries a valid hq-core `core.yaml` — canonical
+ * (`<dir>/core/core.yaml`, hq-core ≥v14) or legacy (`<dir>/core.yaml`) — that
+ * parses as YAML and has BOTH the `version` and `hqVersion` fields. The dual
+ * field check (matching hq-sync's `is_valid_hq_root`) stops a stray `core.yaml`
+ * from another tool from false-matching.
+ */
+function isValidHqRootSignature(dir) {
+    const canonical = path.join(dir, "core", "core.yaml");
+    const legacy = path.join(dir, "core.yaml");
+    let file;
+    if (fileExists(canonical))
+        file = canonical;
+    else if (fileExists(legacy))
+        file = legacy;
+    else
+        return false;
+    try {
+        const parsed = yaml.load(fs.readFileSync(file, "utf-8"));
+        return (!!parsed &&
+            typeof parsed === "object" &&
+            "version" in parsed &&
+            "hqVersion" in parsed);
+    }
+    catch {
+        return false;
+    }
+}
+/** True iff `p` exists and is a regular file. */
+function fileExists(p) {
+    try {
+        return fs.statSync(p).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * True iff `dir` is an HQ root for the cwd walk-up: it has a `core.yaml`
+ * (canonical `core/core.yaml` since hq-core v14, or legacy `<dir>/core.yaml`)
+ * AND a sibling `companies/` directory. The `companies/` discriminator keeps
+ * the walk from latching onto the inner `core/` subtree, which carries its own
+ * `core.yaml` but no `companies/`.
+ */
 function isHqRoot(dir) {
-    if (!fs.existsSync(path.join(dir, "core.yaml")))
+    const hasCoreYaml = fileExists(path.join(dir, "core", "core.yaml")) ||
+        fileExists(path.join(dir, "core.yaml"));
+    if (!hasCoreYaml)
         return false;
     try {
         return fs.statSync(path.join(dir, "companies")).isDirectory();
@@ -193,4 +302,4 @@ export async function refreshCachedSession() {
     }
 }
 //# sourceMappingURL=cognito-session.js.map
-//# debugId=cd9690e0-c7b0-5e26-a3ee-7f7bc98a0fe2
+//# debugId=984bafe3-242a-5322-a2fe-65261b24ee0b

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.36.3",
+  "version": "5.36.5",
   "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),

package/src/utils/cognito-session.test.ts

@@ -19,12 +19,23 @@ describe("resolveDefaultHqRoot", () => {
   let tmpRoot: string;
   let origCwd: string;
   let origEnv: string | undefined;
+  let origHome: string | undefined;
+
+  // `~/.hq` records (menubar.json/config.json) + discovery candidates are all
+  // keyed off os.homedir(), which honors $HOME on POSIX/macOS. Pin HOME to a
+  // clean tmp dir so every tier is hermetic — the real machine's HQ install
+  // can't leak into the fallback/discovery assertions below.
+  let fakeHome: string;
 
   beforeEach(() => {
     tmpRoot = mkdtempSync(join(tmpdir(), "hq-cli-resolveroot-"));
+    fakeHome = join(tmpRoot, "home");
+    mkdirSync(fakeHome, { recursive: true });
     origCwd = process.cwd();
     origEnv = process.env.HQ_ROOT;
+    origHome = process.env.HOME;
     delete process.env.HQ_ROOT;
+    process.env.HOME = fakeHome;
   });
 
   afterEach(() => {
@@ -32,8 +43,17 @@ describe("resolveDefaultHqRoot", () => {
     rmSync(tmpRoot, { recursive: true, force: true });
     if (origEnv === undefined) delete process.env.HQ_ROOT;
     else process.env.HQ_ROOT = origEnv;
+    if (origHome === undefined) delete process.env.HOME;
+    else process.env.HOME = origHome;
   });
 
+  /** Write `~/.hq/<file>` (creating `~/.hq`) with the given JSON object. */
+  function writeHqConfig(file: string, obj: Record<string, unknown>): void {
+    const hqDir = join(fakeHome, ".hq");
+    mkdirSync(hqDir, { recursive: true });
+    writeFileSync(join(hqDir, file), JSON.stringify(obj));
+  }
+
   it("priority 1: honors $HQ_ROOT env var (resolved to absolute path)", () => {
     const explicit = join(tmpRoot, "explicit-target");
     mkdirSync(explicit, { recursive: true });
@@ -75,22 +95,21 @@ describe("resolveDefaultHqRoot", () => {
     expect(resolveDefaultHqRoot()).toBe(realpathSync(hqDir));
   });
 
-  it("priority 3: falls back when neither $HQ_ROOT nor an HQ-root marker pair are found", () => {
+  it("tier 6: falls back to ~/hq when nothing (env, cwd, ~/.hq records, discovery) resolves", () => {
     const stranded = join(tmpRoot, "stranded");
     mkdirSync(stranded, { recursive: true });
     process.chdir(stranded);
 
     const result = resolveDefaultHqRoot();
-    // Walks up to filesystem root, no core.yaml+companies/ pair found, falls
-    // back to ~/hq. We don't assert the exact value (depends on the test
-    // runner's $HOME) but the result should NOT be the stranded dir.
+    // No $HQ_ROOT, no core.yaml+companies/ above cwd, no ~/.hq records, no
+    // discoverable root under the (pinned) home → last-resort ~/hq.
     expect(result).not.toBe(stranded);
-    expect(result.endsWith("/hq")).toBe(true);
+    expect(result).toBe(join(fakeHome, "hq"));
   });
 
-  it("priority 3: a dir with only core.yaml (no companies/) is NOT a valid HQ root", () => {
-    // core.yaml present but no companies/ sibling → fall through to ~/hq.
-    // This is the synced core/ subtree's signature.
+  it("a dir with only core.yaml (no companies/) is NOT a valid HQ root (walk-up)", () => {
+    // core.yaml present but no companies/ sibling → not a root; with no other
+    // signal, fall through to ~/hq. This is the synced core/ subtree's shape.
     const lonelyCoreYaml = join(tmpRoot, "lonely");
     mkdirSync(lonelyCoreYaml, { recursive: true });
     writeFileSync(join(lonelyCoreYaml, "core.yaml"), "");
@@ -98,7 +117,7 @@ describe("resolveDefaultHqRoot", () => {
 
     const result = resolveDefaultHqRoot();
     expect(result).not.toBe(lonelyCoreYaml);
-    expect(result.endsWith("/hq")).toBe(true);
+    expect(result).toBe(join(fakeHome, "hq"));
   });
 
   it("$HQ_ROOT wins over walking-up resolution", () => {
@@ -115,6 +134,125 @@ describe("resolveDefaultHqRoot", () => {
     expect(resolveDefaultHqRoot()).toBe(explicit);
   });
 
+  // ── tiers 3–5: installer/menubar records + discovery (the feedback_3967e294
+  //    split-brain fix) ────────────────────────────────────────────────────
+  //
+  // REGRESSION: run from a cwd OUTSIDE any HQ tree with $HQ_ROOT unset. Before
+  // the fix the CLI fell straight to ~/hq and the sync engine created+filled a
+  // brand-new stub there, diverging from the AppBar's real root. It must now
+  // read ~/.hq/menubar.json → hqPath (the same record HQ Sync reads first).
+  it("tier 3: reads ~/.hq/menubar.json → hqPath from an unrelated cwd (feedback_3967e294)", () => {
+    const realRoot = join(tmpRoot, "Desktop", "HQ");
+    mkdirSync(realRoot, { recursive: true });
+    writeHqConfig("menubar.json", { machineId: "abc", hqPath: realRoot });
+
+    const stranded = join(tmpRoot, "some", "unrelated", "cwd");
+    mkdirSync(stranded, { recursive: true });
+    process.chdir(stranded);
+
+    expect(resolveDefaultHqRoot()).toBe(realRoot);
+  });
+
+  it("tier 4: reads ~/.hq/config.json → hqFolderPath when menubar.json is absent", () => {
+    const realRoot = join(tmpRoot, "Desktop", "HQ");
+    mkdirSync(realRoot, { recursive: true });
+    writeHqConfig("config.json", { hqFolderPath: realRoot });
+
+    const stranded = join(tmpRoot, "unrelated");
+    mkdirSync(stranded, { recursive: true });
+    process.chdir(stranded);
+
+    expect(resolveDefaultHqRoot()).toBe(realRoot);
+  });
+
+  it("tier 3 wins over tier 4: menubar.json hqPath beats config.json hqFolderPath", () => {
+    const fromMenubar = join(tmpRoot, "menubar-root");
+    const fromConfig = join(tmpRoot, "config-root");
+    mkdirSync(fromMenubar, { recursive: true });
+    mkdirSync(fromConfig, { recursive: true });
+    writeHqConfig("menubar.json", { hqPath: fromMenubar });
+    writeHqConfig("config.json", { hqFolderPath: fromConfig });
+
+    process.chdir(tmpRoot);
+    expect(resolveDefaultHqRoot()).toBe(fromMenubar);
+  });
+
+  it("an empty hqPath in menubar.json falls through to config.json (mirrors hq-sync)", () => {
+    const fromConfig = join(tmpRoot, "config-root");
+    mkdirSync(fromConfig, { recursive: true });
+    writeHqConfig("menubar.json", { hqPath: "" });
+    writeHqConfig("config.json", { hqFolderPath: fromConfig });
+
+    process.chdir(tmpRoot);
+    expect(resolveDefaultHqRoot()).toBe(fromConfig);
+  });
+
+  it("tier 2 (cwd walk-up) wins over tier 3 (menubar.json) — operate on the tree you're inside", () => {
+    // A user cd'd into a real HQ checkout must target THAT tree even when
+    // menubar.json points elsewhere — least-surprising for multi-checkout devs.
+    const insideRoot = join(tmpRoot, "checkout-a");
+    const nested = join(insideRoot, "companies", "acme");
+    mkdirSync(nested, { recursive: true });
+    mkdirSync(join(insideRoot, "core"), { recursive: true });
+    writeFileSync(
+      join(insideRoot, "core", "core.yaml"),
+      "version: 1\nhqVersion: \"15.0.0\"\n",
+    );
+    writeHqConfig("menubar.json", { hqPath: join(tmpRoot, "checkout-b") });
+
+    process.chdir(nested);
+    expect(resolveDefaultHqRoot()).toBe(realpathSync(insideRoot));
+  });
+
+  it("tier 2: walk-up detects a v14+/v15 root whose core.yaml lives at core/core.yaml", () => {
+    // hq-core v14 moved core.yaml from <root>/core.yaml to <root>/core/core.yaml.
+    // The walk-up must detect the modern layout (this was the second half of
+    // the bug — the CLI only checked the legacy root-level core.yaml).
+    const hqDir = join(tmpRoot, "Desktop", "HQ");
+    const nested = join(hqDir, "companies", "acme");
+    mkdirSync(nested, { recursive: true });
+    mkdirSync(join(hqDir, "core"), { recursive: true });
+    writeFileSync(
+      join(hqDir, "core", "core.yaml"),
+      "version: 1\nhqVersion: \"15.0.11\"\n",
+    );
+
+    process.chdir(nested);
+    expect(resolveDefaultHqRoot()).toBe(realpathSync(hqDir));
+  });
+
+  it("tier 5: discovers ~/HQ via a valid core/core.yaml signature when no ~/.hq records exist", () => {
+    // No $HQ_ROOT, no walk-up hit, no menubar/config records → discovery scans
+    // the well-known locations. ~/HQ with a schema-valid core/core.yaml wins.
+    const discovered = join(fakeHome, "HQ");
+    mkdirSync(join(discovered, "core"), { recursive: true });
+    writeFileSync(
+      join(discovered, "core", "core.yaml"),
+      "version: 1\nhqVersion: \"15.0.11\"\n",
+    );
+
+    const stranded = join(tmpRoot, "unrelated");
+    mkdirSync(stranded, { recursive: true });
+    process.chdir(stranded);
+
+    expect(resolveDefaultHqRoot()).toBe(discovered);
+  });
+
+  it("tier 5: discovery REJECTS a core.yaml lacking the version+hqVersion schema", () => {
+    // A stray core.yaml (from another tool) must not false-match — both fields
+    // are required, mirroring hq-sync's is_valid_hq_root.
+    const notHq = join(fakeHome, "HQ");
+    mkdirSync(join(notHq, "core"), { recursive: true });
+    writeFileSync(join(notHq, "core", "core.yaml"), "someOtherTool: true\n");
+
+    const stranded = join(tmpRoot, "unrelated");
+    mkdirSync(stranded, { recursive: true });
+    process.chdir(stranded);
+
+    // No valid discovery hit → tier 6 fallback.
+    expect(resolveDefaultHqRoot()).toBe(join(fakeHome, "hq"));
+  });
+
   // ── onMissing: throw vs fallback ──────────────────────────────────────
   //
   // Default behavior (no opts) is fallback to ~/hq — preserves the

package/src/utils/cognito-session.ts

@@ -22,6 +22,7 @@
 import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
+import * as yaml from "js-yaml";
 import chalk from "chalk";
 import {
   loadCachedTokens,
@@ -57,69 +58,193 @@ export const DEFAULT_VAULT_API_URL =
   process.env.HQ_VAULT_API_URL ?? "https://hqapi.getindigo.ai";
 
 /**
- * Resolve the default HQ tree root for cloud-aware subcommands.
+ * Resolve the HQ tree root for cloud-aware subcommands (`hq sync`, `hq onboard`,
+ * `hq cloud …`, etc.).
  *
- * Priority order:
- *   1. `$HQ_ROOT` env var (explicit user override)
- *   2. Walk up from `process.cwd()` to the nearest dir containing BOTH a
- *      `core.yaml` file AND a `companies/` directory (root-unique marker
- *      pair — see note below).
- *   3. Fall back to `~/hq` (the historical default)
+ * Resolution order — mirrors the menubar/installer resolver
+ * (`hq-sync` `util/paths.rs::resolve_hq_folder`) so the CLI targets the SAME
+ * root the AppBar syncs, regardless of cwd:
+ *   1. `$HQ_ROOT` env var — explicit assertion by the caller; short-circuits all.
+ *   2. Walk up from `process.cwd()` to the nearest HQ root (working-tree wins:
+ *      if you're inside an HQ tree, operate on THAT tree). See {@link isHqRoot}.
+ *   3. `~/.hq/menubar.json` → `hqPath` — the canonical record written by the
+ *      installer (≥0.1.28) and the menubar's Settings re-tether. Same field HQ
+ *      Sync reads first.
+ *   4. `~/.hq/config.json` → `hqFolderPath` — legacy installer record.
+ *   5. Discovery: scan well-known locations (`~/HQ`, `~/hq`, `~/Documents/HQ`,
+ *      …) for a folder carrying a valid `core.yaml` signature. Safety net for
+ *      installs that never wrote the path back to menubar.json.
+ *   6. Fall back to `~/hq` (the historical CLI default) — or throw, per
+ *      `opts.onMissing`.
  *
- * Why both markers?
- *   The HQ root has `core.yaml` AND a sibling `companies/` directory. The
- *   synced `core/` subtree (which is itself part of the root's personal-vault
- *   scope) ALSO contains a `core.yaml` (the template's version-source-of-
- *   truth), but does NOT contain `companies/`. Single-marker `core.yaml`
- *   detection would stop at `<hqRoot>/core/` when the CLI is launched from
- *   somewhere inside that subtree, and downstream `companies/` lookups would
- *   silently miss the real content. Requiring `companies/` as well guarantees
- *   we resolve to the actual HQ root (Codex P2 on hq#146).
+ * Why tiers 3–5 exist:
+ *   Before this, the CLI only knew `$HQ_ROOT` and the cwd walk-up. Run from any
+ *   cwd OUTSIDE the HQ tree with `$HQ_ROOT` unset, it fell straight to `~/hq` —
+ *   so a user whose HQ lives anywhere else (e.g. `~/Desktop/HQ`, as the AppBar
+ *   syncs it) silently got a brand-new `~/hq` stub and a full re-sync into it
+ *   (split-brain). Reading the installer/menubar records the way HQ Sync does
+ *   closes that gap (feedback_3967e294).
  *
- * Evaluated once at module load — commander.js `.option()` callers pin the
- * value at registration time, which matches the user's actual cwd at process
- * start. Re-importable as a function for tests and command-time resolution.
- */
-/**
- * Resolve the HQ root directory.
- *
- * Resolution order:
- *   1. $HQ_ROOT env var (treated as an explicit assertion by the caller)
- *   2. Walk up from cwd looking for `core.yaml` AND `companies/` siblings
- *   3. Fall back to `~/hq` (or throw, per `opts.onMissing`)
+ * Why both markers in the walk-up (tier 2)?
+ *   An HQ root has a `core.yaml` (canonical `core/core.yaml` since hq-core v14,
+ *   legacy `<root>/core.yaml` before) AND a sibling `companies/` directory. The
+ *   synced `core/` subtree ALSO contains a `core.yaml` (the template version
+ *   source-of-truth) but NO `companies/`. Requiring `companies/` as well stops
+ *   the walk from latching onto `<hqRoot>/core/` (Codex P2 on hq#146).
  *
- * `opts.onMissing` controls the third arm:
- *   - `'fallback'` (default) — return `~/hq` if no HQ root is found above cwd.
- *     This preserves the module-load contract of `DEFAULT_HQ_ROOT`, which
- *     several commander.js `.option()` callers pin at registration time.
- *   - `'throw'` — throw with a user-actionable error. Used by module-management
- *     commands (pkg-install, pkg-remove, pkg-list, pkg-update, team-sync) where
- *     a silent default-path miss would silently target the wrong directory.
+ * `opts.onMissing` controls the final arm:
+ *   - `'fallback'` (default) — return `~/hq` if nothing resolves. Preserves the
+ *     module-load contract of `DEFAULT_HQ_ROOT`, pinned by commander.js
+ *     `.option()` callers at registration time.
+ *   - `'throw'` — throw a user-actionable error. Used by module-management
+ *     commands (pkg-*, team-sync) where a silent default-path miss would
+ *     target the wrong directory.
  *
- * `$HQ_ROOT` short-circuits both arms — if the env var is set, it's used
- * as-is regardless of `onMissing`.
+ * Evaluated once at module load for `DEFAULT_HQ_ROOT`; the installer/menubar
+ * records and cwd are both fixed at process start, so a one-shot read is sound.
+ * Re-importable as a function for command-time resolution and tests.
  */
 export function resolveDefaultHqRoot(opts: {
   onMissing?: "throw" | "fallback";
 } = {}): string {
+  // Tier 1: explicit override.
   if (process.env.HQ_ROOT) return path.resolve(process.env.HQ_ROOT);
+
+  // Tier 2: working-tree walk-up — operate on the HQ tree you're inside.
   let cur = path.resolve(process.cwd());
   while (cur !== path.dirname(cur)) {
     if (isHqRoot(cur)) return cur;
     cur = path.dirname(cur);
   }
+
+  // Tiers 3–4: the installer/menubar's canonical "where is HQ" records.
+  const fromConfig = readHqRootFromHqConfig(path.join(os.homedir(), ".hq"));
+  if (fromConfig) return path.resolve(fromConfig);
+
+  // Tier 5: discover a valid HQ root in the well-known locations.
+  const discovered = discoverHqRootViaCoreYaml();
+  if (discovered) return discovered;
+
+  // Tier 6: nothing resolved.
   if (opts.onMissing === "throw") {
     throw new Error(
       "Could not find HQ root. Run this command from within your HQ directory " +
-        "(must contain core.yaml AND a companies/ subdirectory), or set $HQ_ROOT.",
+        "(must contain core.yaml AND a companies/ subdirectory), set $HQ_ROOT, " +
+        "or install HQ via the installer/menubar so ~/.hq/menubar.json records " +
+        "its location.",
     );
   }
   return path.join(os.homedir(), "hq");
 }
 
-/** True iff `dir` looks like an HQ root (has core.yaml + companies/ dir). */
+/**
+ * Read the configured HQ root from the installer/menubar records under
+ * `hqConfigDir` (`~/.hq`). Mirrors HQ Sync's precedence:
+ *   1. `menubar.json` → `hqPath` (canonical; written by installer ≥0.1.28 and
+ *      the menubar Settings re-tether)
+ *   2. `config.json` → `hqFolderPath` (legacy installer flows)
+ * Returns the first non-empty string, or undefined. Best-effort: a missing or
+ * malformed file is treated as "not configured" (never throws).
+ */
+function readHqRootFromHqConfig(hqConfigDir: string): string | undefined {
+  const fromMenubar = readJsonStringField(
+    path.join(hqConfigDir, "menubar.json"),
+    "hqPath",
+  );
+  if (fromMenubar) return fromMenubar;
+  return readJsonStringField(
+    path.join(hqConfigDir, "config.json"),
+    "hqFolderPath",
+  );
+}
+
+/** Read a top-level string field from a JSON file, or undefined on any miss. */
+function readJsonStringField(file: string, field: string): string | undefined {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, "utf-8")) as Record<
+      string,
+      unknown
+    >;
+    const value = parsed[field];
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Well-known parent locations an HQ tree commonly lives in (mirrors hq-sync). */
+function hqDiscoveryCandidates(): string[] {
+  const home = os.homedir();
+  return [
+    path.join(home, "HQ"),
+    path.join(home, "hq"),
+    path.join(home, "Documents", "HQ"),
+    path.join(home, "Documents", "hq"),
+    path.join(home, "Desktop", "HQ"),
+    path.join(home, "Desktop", "hq"),
+  ];
+}
+
+/**
+ * Scan the well-known locations for a folder carrying a valid `core.yaml`
+ * signature. First match wins; returns undefined if none qualify. Cheap — a
+ * few stats plus one small YAML parse on a hit.
+ */
+function discoverHqRootViaCoreYaml(): string | undefined {
+  return hqDiscoveryCandidates().find(isValidHqRootSignature);
+}
+
+/**
+ * True iff `dir` carries a valid hq-core `core.yaml` — canonical
+ * (`<dir>/core/core.yaml`, hq-core ≥v14) or legacy (`<dir>/core.yaml`) — that
+ * parses as YAML and has BOTH the `version` and `hqVersion` fields. The dual
+ * field check (matching hq-sync's `is_valid_hq_root`) stops a stray `core.yaml`
+ * from another tool from false-matching.
+ */
+function isValidHqRootSignature(dir: string): boolean {
+  const canonical = path.join(dir, "core", "core.yaml");
+  const legacy = path.join(dir, "core.yaml");
+  let file: string;
+  if (fileExists(canonical)) file = canonical;
+  else if (fileExists(legacy)) file = legacy;
+  else return false;
+  try {
+    const parsed = yaml.load(fs.readFileSync(file, "utf-8")) as
+      | Record<string, unknown>
+      | null
+      | undefined;
+    return (
+      !!parsed &&
+      typeof parsed === "object" &&
+      "version" in parsed &&
+      "hqVersion" in parsed
+    );
+  } catch {
+    return false;
+  }
+}
+
+/** True iff `p` exists and is a regular file. */
+function fileExists(p: string): boolean {
+  try {
+    return fs.statSync(p).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * True iff `dir` is an HQ root for the cwd walk-up: it has a `core.yaml`
+ * (canonical `core/core.yaml` since hq-core v14, or legacy `<dir>/core.yaml`)
+ * AND a sibling `companies/` directory. The `companies/` discriminator keeps
+ * the walk from latching onto the inner `core/` subtree, which carries its own
+ * `core.yaml` but no `companies/`.
+ */
 function isHqRoot(dir: string): boolean {
-  if (!fs.existsSync(path.join(dir, "core.yaml"))) return false;
+  const hasCoreYaml =
+    fileExists(path.join(dir, "core", "core.yaml")) ||
+    fileExists(path.join(dir, "core.yaml"));
+  if (!hasCoreYaml) return false;
   try {
     return fs.statSync(path.join(dir, "companies")).isDirectory();
   } catch {