@indigoai-us/hq-cli 5.345.187 → 5.345.189

package/dist/lib/index-render/session-scope.d.ts

@@ -60,9 +60,9 @@ export interface PlanOptions {
  * - Unbound session: an explicit company is used as given; otherwise every
  *   company is rebuilt, with a warning unless --all-companies was passed.
  * - Indeterminate session state: refused.
- * - `companies` for one company needs cli.rebuild-index-company-scope, whether
- *   the company came from the caller or from the bound set. Under `all` the
- *   companies child is skipped instead when the flag is off.
+ * - Bound isolation is not optional. The kill switch may restore every-company
+ *   writes only for an unbound session (automation). A bound session never
+ *   writes another company's INDEX.md (feedback_31a4e992).
  * - Every company is checked to be a real directory before anything runs.
  */
 export declare function planScopedRebuild(target: IndexTarget, args: readonly string[], root: string, env: NodeJS.ProcessEnv, options: PlanOptions): RebuildPlan;

package/dist/lib/index-render/session-scope.js

@@ -196,9 +196,9 @@ function companyArgs(target, slug) {
  * - Unbound session: an explicit company is used as given; otherwise every
  *   company is rebuilt, with a warning unless --all-companies was passed.
  * - Indeterminate session state: refused.
- * - `companies` for one company needs cli.rebuild-index-company-scope, whether
- *   the company came from the caller or from the bound set. Under `all` the
- *   companies child is skipped instead when the flag is off.
+ * - Bound isolation is not optional. The kill switch may restore every-company
+ *   writes only for an unbound session (automation). A bound session never
+ *   writes another company's INDEX.md (feedback_31a4e992).
  * - Every company is checked to be a real directory before anything runs.
  */
 export function planScopedRebuild(target, args, root, env, options) {
@@ -261,17 +261,19 @@ export function planScopedRebuild(target, args, root, env, options) {
             }
         }
     }
-    // cli.rebuild-index-company-scope is a kill switch (default on). Off, the
-    // companies root-index rebuild goes back to its pre-scoping behavior
-    // (every company) with a warning, instead of being refused or skipped.
+    // cli.rebuild-index-company-scope is a kill switch (default on). Off, an
+    // unbound `companies` rebuild goes back to every company (automation). A
+    // bound session still rebuilds only its bound companies.
     const gateOff = !options.companyIndexScopeEnabled;
-    if (target === "companies" && gateOff && explicit.length === 0) {
+    const bound = state.kind === "bound";
+    if (target === "companies" && gateOff && explicit.length === 0 && !bound) {
         return { runs: [{ target, args: [] }], warning: COMPANY_SCOPE_FLAG_OFF_WARNING };
     }
     if (target === "all") {
+        const unscoped = gateOff && !bound;
         return {
-            runs: [{ target, args: [...companies.flatMap((slug) => ["--company", slug]), ...(gateOff ? [UNSCOPED_COMPANIES_INDEX] : [])] }],
-            warning: gateOff ? COMPANY_SCOPE_FLAG_OFF_WARNING : warning,
+            runs: [{ target, args: [...companies.flatMap((slug) => ["--company", slug]), ...(unscoped ? [UNSCOPED_COMPANIES_INDEX] : [])] }],
+            warning: unscoped ? COMPANY_SCOPE_FLAG_OFF_WARNING : warning,
         };
     }
     return { runs: companies.map((slug) => ({ target, args: companyArgs(target, slug) })), warning };

package/dist/lib/index-render/shared.d.ts

@@ -54,10 +54,12 @@ export declare function generatedStamp(content: string): string | undefined;
 export declare function log(context: RenderContext, message: string): void;
 export declare function projectStatus(root: string, project: string, prdPath: string, fallback: string, expectedStatePrdPath?: string): string;
 /**
- * Project status from prd.json alone: "complete" when every story passes,
- * otherwise `fallback`. Unlike `projectStatus`, this never reads the
- * machine-local `workspace/orchestrator/<project>/state.json`, so synced
- * output renders the same on every machine.
+ * Project status from files that sync with the company: sibling `state.json`
+ * (status written by skills such as demand-test), then prd.json `status` /
+ * `metadata.status`, then "complete" when every story passes, otherwise
+ * `fallback`. Unlike `projectStatus`, this never reads the machine-local
+ * `workspace/orchestrator/<project>/state.json`, so synced output renders
+ * the same on every machine.
  */
 export declare function prdProjectStatus(prdPath: string, fallback: string): string;
 export declare function basename(file: string): string;

package/dist/lib/index-render/shared.js

@@ -166,14 +166,43 @@ export function projectStatus(root, project, prdPath, fallback, expectedStatePrd
     }
     return prdProjectStatus(prdPath, fallback);
 }
+function normalizeProjectStatus(raw) {
+    if (["completed", "complete"].includes(raw))
+        return "complete";
+    if (["in_progress", "active", "started"].includes(raw))
+        return "active";
+    return raw;
+}
+function explicitProjectStatus(record) {
+    if (!record)
+        return undefined;
+    if (typeof record.status === "string" && record.status.trim()) {
+        return normalizeProjectStatus(record.status.trim());
+    }
+    const metadata = record.metadata;
+    if (metadata && typeof metadata === "object" && !Array.isArray(metadata)) {
+        const nested = metadata.status;
+        if (typeof nested === "string" && nested.trim())
+            return normalizeProjectStatus(nested.trim());
+    }
+    return undefined;
+}
 /**
- * Project status from prd.json alone: "complete" when every story passes,
- * otherwise `fallback`. Unlike `projectStatus`, this never reads the
- * machine-local `workspace/orchestrator/<project>/state.json`, so synced
- * output renders the same on every machine.
+ * Project status from files that sync with the company: sibling `state.json`
+ * (status written by skills such as demand-test), then prd.json `status` /
+ * `metadata.status`, then "complete" when every story passes, otherwise
+ * `fallback`. Unlike `projectStatus`, this never reads the machine-local
+ * `workspace/orchestrator/<project>/state.json`, so synced output renders
+ * the same on every machine.
  */
 export function prdProjectStatus(prdPath, fallback) {
+    const localState = explicitProjectStatus(readJson(path.join(path.dirname(prdPath), "state.json")));
+    if (localState)
+        return localState;
     const prd = readJson(prdPath);
+    const declared = explicitProjectStatus(prd);
+    if (declared)
+        return declared;
     if (prd && Array.isArray(prd.userStories) && prd.userStories.length > 0 && prd.userStories.every((story) => Boolean(story.passes)))
         return "complete";
     return fallback;

package/dist/utils/cognito-session.d.ts

@@ -52,7 +52,7 @@ export declare const DEFAULT_VAULT_API_URL: string;
  *   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
+ *   6. Fall back to `~/hq` (`C:\hq` on Windows) — or throw, per
  *      `opts.onMissing`.
  *
  * Why tiers 3–5 exist:
@@ -71,7 +71,7 @@ export declare const DEFAULT_VAULT_API_URL: string;
  *   the walk from latching onto `<hqRoot>/core/` (Codex P2 on hq#146).
  *
  * `opts.onMissing` controls the final arm:
- *   - `'fallback'` (default) — return `~/hq` if nothing resolves. Preserves the
+ *   - `'fallback'` (default) — return `~/hq` (`C:\hq` on Windows) 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
@@ -88,6 +88,8 @@ export declare function resolveDefaultHqRoot(opts?: {
     env?: NodeJS.ProcessEnv;
     cwd?: string;
     home?: string;
+    /** Defaults to process.platform; injectable so tests can exercise win32. */
+    platform?: NodeJS.Platform;
 }): string;
 export declare const DEFAULT_HQ_ROOT: string;
 /**
@@ -267,7 +269,7 @@ export declare function buildVaultConfig(authToken: string): VaultServiceConfig;
  * means no valid session could be ensured non-interactively; the caller gets a
  * reason string and can decide what to do next. Never opens a browser.
  */
-type MachineRefreshOptions = Pick<EnsureCognitoTokenOptions, "tokenSource"> & MachineTokenValidityOptions & {
+type MachineRefreshOptions = Pick<EnsureCognitoTokenOptions, "tokenSource" | "signal"> & MachineTokenValidityOptions & {
     /** Refresh the person session even when the cached token is still valid. */
     force?: boolean;
 };

package/dist/utils/cognito-session.js

@@ -30,6 +30,7 @@ import { hasPersonCachedSession, isMachineCredsFileEnvSet, probeMachineIdentity,
 import { CLI_NAME, CLI_VERSION } from "../cli-version.js";
 import { daemonDir } from "../lib/mesh/live/daemon/paths.js";
 import { workMeshRoot } from "../lib/mesh/live/paths.js";
+import { defaultHqRootFallback, hqDiscoveryCandidates, pathForPlatform, } from "./hq-root-resolver.js";
 import { acquireLockFileExclusively } from "./exclusive-lock.js";
 import { reportNoninteractivePersonRefreshRejection } from "./cognito-refresh-sentry.js";
 import { decodeJwtPayload, loadCachedTokens, personTokenCacheFile, readPersonTokenFile, readTokenFile, } from "./person-token-cache.js";
@@ -78,7 +79,7 @@ export const DEFAULT_VAULT_API_URL = process.env.HQ_VAULT_API_URL ?? "https://hq
  *   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
+ *   6. Fall back to `~/hq` (`C:\hq` on Windows) — or throw, per
  *      `opts.onMissing`.
  *
  * Why tiers 3–5 exist:
@@ -97,7 +98,7 @@ export const DEFAULT_VAULT_API_URL = process.env.HQ_VAULT_API_URL ?? "https://hq
  *   the walk from latching onto `<hqRoot>/core/` (Codex P2 on hq#146).
  *
  * `opts.onMissing` controls the final arm:
- *   - `'fallback'` (default) — return `~/hq` if nothing resolves. Preserves the
+ *   - `'fallback'` (default) — return `~/hq` (`C:\hq` on Windows) 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
@@ -111,32 +112,35 @@ export const DEFAULT_VAULT_API_URL = process.env.HQ_VAULT_API_URL ?? "https://hq
 export function resolveDefaultHqRoot(opts = {}) {
     const env = opts.env ?? process.env;
     const home = opts.home ?? os.homedir();
+    const platform = opts.platform ?? process.platform;
+    const p = pathForPlatform(platform);
     // Tier 1: explicit override.
     if (env.HQ_ROOT)
-        return path.resolve(env.HQ_ROOT);
+        return p.resolve(env.HQ_ROOT);
     // Tier 2: working-tree walk-up — operate on the HQ tree you're inside.
-    let cur = path.resolve(opts.cwd ?? process.cwd());
-    while (cur !== path.dirname(cur)) {
-        if (isHqRoot(cur))
+    let cur = p.resolve(opts.cwd ?? process.cwd());
+    while (cur !== p.dirname(cur)) {
+        if (isHqRoot(cur, p))
             return cur;
-        cur = path.dirname(cur);
+        cur = p.dirname(cur);
     }
     // Tiers 3–4: the installer/menubar's canonical "where is HQ" records.
-    const fromConfig = readHqRootFromHqConfig(path.join(home, ".hq"));
+    const fromConfig = readHqRootFromHqConfig(p.join(home, ".hq"), p);
     if (fromConfig)
-        return path.resolve(fromConfig);
-    // Tier 5: discover a valid HQ root in the well-known locations.
-    const discovered = discoverHqRootViaCoreYaml(home);
+        return p.resolve(fromConfig);
+    // Tier 5: discover a valid HQ root in the well-known locations (on Windows
+    // the home-relative ones first, then %SystemDrive%\hq and %LOCALAPPDATA%\hq).
+    const discovered = hqDiscoveryCandidates({ platform, env, home }).find((dir) => isValidHqRootSignature(dir, p));
     if (discovered)
         return discovered;
-    // Tier 6: nothing resolved.
+    // Tier 6: nothing resolved. Fallback is ~/hq, or %SystemDrive%\hq on Windows.
     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), set $HQ_ROOT, " +
             "or install HQ via the installer/menubar so ~/.hq/menubar.json records " +
             "its location.");
     }
-    return path.join(home, "hq");
+    return defaultHqRootFallback({ platform, env, home });
 }
 /**
  * Read the configured HQ root from the installer/menubar records under
@@ -147,11 +151,11 @@ export function resolveDefaultHqRoot(opts = {}) {
  * 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");
+function readHqRootFromHqConfig(hqConfigDir, p = path) {
+    const fromMenubar = readJsonStringField(p.join(hqConfigDir, "menubar.json"), "hqPath");
     if (fromMenubar)
         return fromMenubar;
-    return readJsonStringField(path.join(hqConfigDir, "config.json"), "hqFolderPath");
+    return readJsonStringField(p.join(hqConfigDir, "config.json"), "hqFolderPath");
 }
 /** Read a top-level string field from a JSON file, or undefined on any miss. */
 function readJsonStringField(file, field) {
@@ -164,25 +168,6 @@ function readJsonStringField(file, field) {
         return undefined;
     }
 }
-/** Well-known parent locations an HQ tree commonly lives in (mirrors hq-sync). */
-function hqDiscoveryCandidates(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(home) {
-    return hqDiscoveryCandidates(home).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
@@ -190,9 +175,9 @@ function discoverHqRootViaCoreYaml(home) {
  * 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");
+function isValidHqRootSignature(dir, p = path) {
+    const canonical = p.join(dir, "core", "core.yaml");
+    const legacy = p.join(dir, "core.yaml");
     let file;
     if (fileExists(canonical))
         file = canonical;
@@ -227,13 +212,13 @@ function fileExists(p) {
  * the walk from latching onto the inner `core/` subtree, which carries its own
  * `core.yaml` but no `companies/`.
  */
-function isHqRoot(dir) {
-    const hasCoreYaml = fileExists(path.join(dir, "core", "core.yaml")) ||
-        fileExists(path.join(dir, "core.yaml"));
+function isHqRoot(dir, p = path) {
+    const hasCoreYaml = fileExists(p.join(dir, "core", "core.yaml")) ||
+        fileExists(p.join(dir, "core.yaml"));
     if (!hasCoreYaml)
         return false;
     try {
-        return fs.statSync(path.join(dir, "companies")).isDirectory();
+        return fs.statSync(p.join(dir, "companies")).isDirectory();
     }
     catch {
         return false;
@@ -780,11 +765,21 @@ function withTokenStateDirSection(fn) {
     return run;
 }
 const MAX_MACHINE_TOKEN_MIN_VALIDITY_SECONDS = 1800;
-async function ensureMachineTokens(minValiditySeconds) {
+/**
+ * `signal` cancels only this caller's wait inside hq-cloud (a mint shared with
+ * other callers keeps running). Without it a bounded caller such as `hq agent
+ * inbox` timed out, retried, and its retry queued behind the orphaned first
+ * mint, which still held the lock.
+ */
+async function ensureMachineTokens(minValiditySeconds, signal) {
     const resolverMinimum = minValiditySeconds === undefined
         ? undefined
         : Math.min(minValiditySeconds, MAX_MACHINE_TOKEN_MIN_VALIDITY_SECONDS);
-    return withMachineTokenStateDir(() => getValidMachineTokens(DEFAULT_COGNITO, resolverMinimum === undefined ? undefined : { minValiditySeconds: resolverMinimum }));
+    const resolverOptions = {
+        ...(resolverMinimum === undefined ? {} : { minValiditySeconds: resolverMinimum }),
+        ...(signal ? { signal } : {}),
+    };
+    return withMachineTokenStateDir(() => getValidMachineTokens(DEFAULT_COGNITO, Object.keys(resolverOptions).length === 0 ? undefined : resolverOptions));
 }
 /**
  * Ensure the current machine identity has a valid session and return only the
@@ -803,7 +798,7 @@ async function ensureMachineTokensMaybeFallback(options = {}) {
     if (isDefaultMachineCredsFallback(options)) {
         logDefaultMachineCredsFallback();
     }
-    return ensureMachineTokens(options.minValiditySeconds);
+    return ensureMachineTokens(options.minValiditySeconds, options.signal);
 }
 /**
  * After a person-cache miss or refresh failure: if the default machine-creds
@@ -818,7 +813,7 @@ async function tryDefaultMachineCredsFallback(options = {}) {
     if (!isMachineIdentity())
         return null;
     logDefaultMachineCredsFallback();
-    return ensureMachineTokens(options.minValiditySeconds);
+    return ensureMachineTokens(options.minValiditySeconds, options.signal);
 }
 /**
  * True when a person-token refresh failed with a definitive Cognito auth
@@ -880,6 +875,8 @@ function resolvePersonSessionAfterRefreshRejection(cached) {
  * a browser.
  */
 export async function ensureCognitoToken(options = {}) {
+    if (options.signal?.aborted)
+        throw options.signal.reason ?? new Error("Token acquisition was aborted");
     if (wantsMachineCognitoTokens(options))
         return ensureCognitoTokenUnserialized(options);
     return withTokenStateDirSection(() => ensureCognitoTokenUnserialized(options));

package/dist/utils/hq-root-resolver.d.ts

@@ -1,13 +1,39 @@
 /** Lightweight HQ-root resolver shared by cloud commands and fast flag scope. */
+import * as path from "node:path";
+/** Path module matching the target platform's path shapes. */
+export declare function pathForPlatform(platform?: NodeJS.Platform): path.PlatformPath;
+/**
+ * The last-resort HQ root when nothing else resolves: `C:\hq` on Windows
+ * (`%SystemDrive%\hq`), `~/hq` elsewhere. Pure; all inputs injectable.
+ */
+export declare function defaultHqRootFallback(opts?: {
+    platform?: NodeJS.Platform;
+    env?: NodeJS.ProcessEnv;
+    home?: string;
+}): string;
+/**
+ * Well-known locations an HQ tree commonly lives in (mirrors hq-sync). On
+ * Windows `%SystemDrive%\hq` then `%LOCALAPPDATA%\hq` come AFTER the
+ * home-relative candidates, so an existing unrecorded `%USERPROFILE%\hq`
+ * install keeps winning over a stray `C:\hq` (avoids a split root).
+ */
+export declare function hqDiscoveryCandidates(opts?: {
+    platform?: NodeJS.Platform;
+    env?: NodeJS.ProcessEnv;
+    home?: string;
+}): string[];
 /**
  * Resolve the HQ tree root using the same precedence as the Cognito helpers:
  * explicit HQ_ROOT, nearest cwd root, installer records, known locations, then
- * the historical ~/hq fallback (or an error when requested).
+ * the platform fallback (`~/hq`, or `C:\hq` on Windows), or an error when
+ * requested.
  */
 export declare function resolveDefaultHqRoot(opts?: {
     onMissing?: "throw" | "fallback";
     env?: NodeJS.ProcessEnv;
     cwd?: string;
     home?: string;
+    platform?: NodeJS.Platform;
 }): string;
+export declare function isValidHqRootSignature(dir: string, p?: path.PlatformPath): boolean;
 //# sourceMappingURL=hq-root-resolver.d.ts.map

package/dist/utils/hq-root-resolver.js

@@ -3,26 +3,71 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import * as yaml from "js-yaml";
+/** Path module matching the target platform's path shapes. */
+export function pathForPlatform(platform = process.platform) {
+    return platform === "win32" ? path.win32 : path.posix;
+}
+/** `%SystemDrive%` (for example `C:`), defaulting to `C:` when unset. */
+function windowsSystemDrive(env) {
+    const drive = env.SystemDrive ?? env.SYSTEMDRIVE;
+    return drive && drive.trim().length > 0 ? drive.trim() : "C:";
+}
+/**
+ * The last-resort HQ root when nothing else resolves: `C:\hq` on Windows
+ * (`%SystemDrive%\hq`), `~/hq` elsewhere. Pure; all inputs injectable.
+ */
+export function defaultHqRootFallback(opts = {}) {
+    const platform = opts.platform ?? process.platform;
+    const env = opts.env ?? process.env;
+    if (platform === "win32") {
+        return path.win32.join(`${windowsSystemDrive(env)}\\`, "hq");
+    }
+    return path.posix.join(opts.home ?? os.homedir(), "hq");
+}
+/**
+ * Well-known locations an HQ tree commonly lives in (mirrors hq-sync). On
+ * Windows `%SystemDrive%\hq` then `%LOCALAPPDATA%\hq` come AFTER the
+ * home-relative candidates, so an existing unrecorded `%USERPROFILE%\hq`
+ * install keeps winning over a stray `C:\hq` (avoids a split root).
+ */
+export function hqDiscoveryCandidates(opts = {}) {
+    const platform = opts.platform ?? process.platform;
+    const env = opts.env ?? process.env;
+    const home = opts.home ?? os.homedir();
+    const p = pathForPlatform(platform);
+    const candidates = [];
+    candidates.push(p.join(home, "HQ"), p.join(home, "hq"), p.join(home, "Documents", "HQ"), p.join(home, "Documents", "hq"), p.join(home, "Desktop", "HQ"), p.join(home, "Desktop", "hq"));
+    if (platform === "win32") {
+        candidates.push(defaultHqRootFallback({ platform, env, home }));
+        const localAppData = env.LOCALAPPDATA?.trim();
+        if (localAppData)
+            candidates.push(p.join(localAppData, "hq"));
+    }
+    return [...new Set(candidates)];
+}
 /**
  * Resolve the HQ tree root using the same precedence as the Cognito helpers:
  * explicit HQ_ROOT, nearest cwd root, installer records, known locations, then
- * the historical ~/hq fallback (or an error when requested).
+ * the platform fallback (`~/hq`, or `C:\hq` on Windows), or an error when
+ * requested.
  */
 export function resolveDefaultHqRoot(opts = {}) {
     const env = opts.env ?? process.env;
     const home = opts.home ?? os.homedir();
+    const platform = opts.platform ?? process.platform;
+    const p = pathForPlatform(platform);
     if (env.HQ_ROOT)
-        return path.resolve(env.HQ_ROOT);
-    let cur = path.resolve(opts.cwd ?? process.cwd());
-    while (cur !== path.dirname(cur)) {
-        if (isHqRoot(cur))
+        return p.resolve(env.HQ_ROOT);
+    let cur = p.resolve(opts.cwd ?? process.cwd());
+    while (cur !== p.dirname(cur)) {
+        if (isHqRoot(cur, p))
             return cur;
-        cur = path.dirname(cur);
+        cur = p.dirname(cur);
     }
-    const fromConfig = readHqRootFromHqConfig(path.join(home, ".hq"));
+    const fromConfig = readHqRootFromHqConfig(p.join(home, ".hq"), p);
     if (fromConfig)
-        return path.resolve(fromConfig);
-    const discovered = discoverHqRootViaCoreYaml(home);
+        return p.resolve(fromConfig);
+    const discovered = hqDiscoveryCandidates({ platform, env, home }).find((dir) => isValidHqRootSignature(dir, p));
     if (discovered)
         return discovered;
     if (opts.onMissing === "throw") {
@@ -31,13 +76,13 @@ export function resolveDefaultHqRoot(opts = {}) {
             "or install HQ via the installer/menubar so ~/.hq/menubar.json records " +
             "its location.");
     }
-    return path.join(home, "hq");
+    return defaultHqRootFallback({ platform, env, home });
 }
-function readHqRootFromHqConfig(hqConfigDir) {
-    const fromMenubar = readJsonStringField(path.join(hqConfigDir, "menubar.json"), "hqPath");
+function readHqRootFromHqConfig(hqConfigDir, p = path) {
+    const fromMenubar = readJsonStringField(p.join(hqConfigDir, "menubar.json"), "hqPath");
     if (fromMenubar)
         return fromMenubar;
-    return readJsonStringField(path.join(hqConfigDir, "config.json"), "hqFolderPath");
+    return readJsonStringField(p.join(hqConfigDir, "config.json"), "hqFolderPath");
 }
 function readJsonStringField(file, field) {
     try {
@@ -49,22 +94,9 @@ function readJsonStringField(file, field) {
         return undefined;
     }
 }
-function hqDiscoveryCandidates(home) {
-    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"),
-    ];
-}
-function discoverHqRootViaCoreYaml(home) {
-    return hqDiscoveryCandidates(home).find(isValidHqRootSignature);
-}
-function isValidHqRootSignature(dir) {
-    const canonical = path.join(dir, "core", "core.yaml");
-    const legacy = path.join(dir, "core.yaml");
+export function isValidHqRootSignature(dir, p = path) {
+    const canonical = p.join(dir, "core", "core.yaml");
+    const legacy = p.join(dir, "core.yaml");
     let file;
     if (fileExists(canonical))
         file = canonical;
@@ -88,13 +120,13 @@ function fileExists(file) {
         return false;
     }
 }
-function isHqRoot(dir) {
-    const hasCoreYaml = fileExists(path.join(dir, "core", "core.yaml")) ||
-        fileExists(path.join(dir, "core.yaml"));
+function isHqRoot(dir, p = path) {
+    const hasCoreYaml = fileExists(p.join(dir, "core", "core.yaml")) ||
+        fileExists(p.join(dir, "core.yaml"));
     if (!hasCoreYaml)
         return false;
     try {
-        return fs.statSync(path.join(dir, "companies")).isDirectory();
+        return fs.statSync(p.join(dir, "companies")).isDirectory();
     }
     catch {
         return false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.345.187",
+  "version": "5.345.189",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -52,9 +52,9 @@
     "@aws-sdk/client-iot-data-plane": "^3.1096.0",
     "@aws-sdk/client-s3": "^3.1049.0",
     "@aws-sdk/dsql-signer": "^3.1146.0",
-    "@indigoai-us/hq-cloud": "6.18.106",
-    "@indigoai-us/hq-flags-client": "^0.1.2",
-    "@modelcontextprotocol/sdk": "1.29.0",
+    "@indigoai-us/hq-cloud": "6.18.107",
+    "@indigoai-us/hq-flags-client": "^0.2.0",
+    "@modelcontextprotocol/sdk": "1.32.2",
     "@sentry/node": "^10.49.0",
     "@tobilu/qmd": "2.5.3",
     "ajv": "^8.20.0",
@@ -62,13 +62,13 @@
     "chalk": "^5.3.0",
     "commander": "^12.1.0",
     "js-yaml": "^4.1.0",
-    "mqtt": "5.15.2",
+    "mqtt": "5.16.1",
     "open": "^10.1.0",
     "pg": "^8.23.1",
     "semver": "^7.8.5",
     "simple-git": "^3.27.0",
-    "smol-toml": "1.6.1",
-    "varlock": "1.21.1"
+    "smol-toml": "1.9.1",
+    "varlock": "1.23.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
@@ -77,8 +77,8 @@
     "@types/node": "^22.0.0",
     "@types/pg": "^8.23.1",
     "@types/semver": "^7.8.0",
-    "@vitest/coverage-v8": "4.1.6",
-    "aedes": "1.1.2",
+    "@vitest/coverage-v8": "4.1.12",
+    "aedes": "1.2.0",
     "aws-sdk-client-mock": "^4.1.0",
     "esbuild": "0.28.2",
     "eslint": "^10.5.0",
@@ -114,11 +114,11 @@
     "*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}": "eslint --cache --no-error-on-unmatched-pattern"
   },
   "optionalDependencies": {
-    "@indigoai-us/hq-hook-win32-x64": "5.345.187",
-    "@indigoai-us/hq-hook-win32-arm64": "5.345.187",
-    "@indigoai-us/hq-hook-darwin-x64": "5.345.187",
-    "@indigoai-us/hq-hook-darwin-arm64": "5.345.187",
-    "@indigoai-us/hq-hook-linux-x64": "5.345.187",
-    "@indigoai-us/hq-hook-linux-arm64": "5.345.187"
+    "@indigoai-us/hq-hook-win32-x64": "5.345.189",
+    "@indigoai-us/hq-hook-win32-arm64": "5.345.189",
+    "@indigoai-us/hq-hook-darwin-x64": "5.345.189",
+    "@indigoai-us/hq-hook-darwin-arm64": "5.345.189",
+    "@indigoai-us/hq-hook-linux-x64": "5.345.189",
+    "@indigoai-us/hq-hook-linux-arm64": "5.345.189"
   }
 }