@indigoai-us/hq-cli 5.36.4 → 5.36.6

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.4",
+  "version": "5.36.6",
   "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.4",
+    "@indigoai-us/hq-cloud": "^6.2.6",
     "@indigoai-us/hq-onboarding": "^0.1.0",
     "@sentry/node": "^10.49.0",
     "chalk": "^5.3.0",

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 {