@indigoai-us/hq-cli 5.162.0 → 5.164.0

package/dist/startup-registration.js

@@ -27,6 +27,8 @@ import { classifyEvalThrow, classifyModuleNotFound, installRewriteInProgress, In
  * shadow each other.
  */
 export const INSTALL_TREE_RECOVERY_GUARD_ENV = "HQ_INSTALL_TREE_RECOVERED";
+/** Carries the writer-state observed by the parent into the guarded re-exec. */
+export const INSTALL_TREE_RECOVERY_TREE_STATE_ENV = "HQ_INSTALL_TREE_RECOVERY_TREE_STATE";
 /** Operator override for the settle wait's deadline. */
 export const INSTALL_SETTLE_TIMEOUT_ENV = "HQ_INSTALL_SETTLE_TIMEOUT_MS";
 /** Default settle deadline (ms). Overridable by {@link INSTALL_SETTLE_TIMEOUT_ENV}. */
@@ -36,7 +38,7 @@ export const DEFAULT_INSTALL_SETTLE_TIMEOUT_MS = 90_000;
  * actually happens. It tells a human why the command paused and is the e2e's
  * synchronization point; it is never a remedy and never sets an error exit code.
  */
-export const INSTALL_TREE_WAIT_NOTICE = "hq: the hq-cli install is being updated underneath this command; waiting for it to finish…";
+export const INSTALL_TREE_WAIT_NOTICE = "hq: checking whether the hq-cli install tree is still changing before retrying…";
 /** Resolve the settle deadline from the environment (0 = evaluate once; default on invalid). */
 export function resolveSettleTimeoutMs(env) {
     const raw = env[INSTALL_SETTLE_TIMEOUT_ENV];
@@ -121,10 +123,12 @@ export async function registerCommandsWithRecovery(args) {
                 classified,
                 packageRoot,
                 outcome: "guarded",
+                treeState: env[INSTALL_TREE_RECOVERY_TREE_STATE_ENV] === "stale" ? "stale" : "in_flight",
                 attempt: 2,
                 waitedMs: 0,
                 sawLock: false,
                 sawRetired: false,
+                sawTreeChange: false,
             });
         }
         stderr.write(`${INSTALL_TREE_WAIT_NOTICE}\n`);
@@ -137,6 +141,7 @@ export async function registerCommandsWithRecovery(args) {
             onLockExtended: () => stderr.write(`${INSTALL_TREE_LOCK_WAIT_NOTICE}\n`),
         });
         if (!result.settled) {
+            const treeState = result.staleTree === true ? "stale" : "in_flight";
             throw new InstallTreeTornError({
                 cause: err,
                 classified,
@@ -145,12 +150,15 @@ export async function registerCommandsWithRecovery(args) {
                 // writer held the shared lock past its own ceiling — report 'lock-held'
                 // (its remedy tells the user to let the update finish, never to reinstall
                 // over it). Otherwise the tree genuinely never settled with no writer
-                // visible, which keeps meaning 'unsettled'.
-                outcome: result.lockHeldAtEnd ? "lock-held" : "unsettled",
+                // visible. The settle probe only uses `stale_tree` when it could observe
+                // an unchanged tree with no active writer or retired sibling.
+                outcome: result.lockHeldAtEnd ? "lock-held" : result.staleTree ? "stale_tree" : "unsettled",
+                treeState,
                 attempt: 1,
                 waitedMs: result.waitedMs,
                 sawLock: result.sawLock,
                 sawRetired: result.sawRetired,
+                sawTreeChange: result.sawTreeChange,
                 lockHeldAtEnd: result.lockHeldAtEnd,
                 lockedMs: result.lockedMs,
                 lockTool: result.lockTool,
@@ -158,17 +166,30 @@ export async function registerCommandsWithRecovery(args) {
         }
         const spawn = deps.spawn ?? spawnSync;
         const execArgv = deps.execArgv ?? process.execArgv;
-        const child = spawn(process.execPath, [...execArgv, entryPath, ...argv.slice(2)], { stdio: "inherit", env: { ...env, [INSTALL_TREE_RECOVERY_GUARD_ENV]: "1" } });
+        const treeState = result.sawLock || result.sawRetired || result.sawTreeChange
+            ? "in_flight"
+            : "stale";
+        const child = spawn(process.execPath, [...execArgv, entryPath, ...argv.slice(2)], {
+            stdio: "inherit",
+            env: {
+                ...env,
+                [INSTALL_TREE_RECOVERY_GUARD_ENV]: "1",
+                [INSTALL_TREE_RECOVERY_TREE_STATE_ENV]: treeState,
+            },
+        });
         if (child.error) {
             throw new InstallTreeTornError({
                 cause: err,
                 classified,
                 packageRoot,
                 outcome: "reexec-failed",
+                treeState,
                 attempt: 1,
                 waitedMs: result.waitedMs,
                 sawLock: result.sawLock,
                 sawRetired: result.sawRetired,
+                sawTreeChange: result.sawTreeChange,
+                lockTool: result.lockTool,
             });
         }
         // A signal-killed child has status null; surface it as a failure exit rather

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

@@ -81,6 +81,10 @@ export declare const DEFAULT_VAULT_API_URL: string;
  */
 export declare function resolveDefaultHqRoot(opts?: {
     onMissing?: "throw" | "fallback";
+    /** Defaults to process.env, process.cwd() and os.homedir(). */
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+    home?: string;
 }): string;
 export declare const DEFAULT_HQ_ROOT: string;
 /**

package/dist/utils/cognito-session.js

@@ -102,22 +102,24 @@ export const DEFAULT_VAULT_API_URL = process.env.HQ_VAULT_API_URL ?? "https://hq
  * Re-importable as a function for command-time resolution and tests.
  */
 export function resolveDefaultHqRoot(opts = {}) {
+    const env = opts.env ?? process.env;
+    const home = opts.home ?? os.homedir();
     // Tier 1: explicit override.
-    if (process.env.HQ_ROOT)
-        return path.resolve(process.env.HQ_ROOT);
+    if (env.HQ_ROOT)
+        return path.resolve(env.HQ_ROOT);
     // Tier 2: working-tree walk-up — operate on the HQ tree you're inside.
-    let cur = path.resolve(process.cwd());
+    let cur = path.resolve(opts.cwd ?? 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"));
+    const fromConfig = readHqRootFromHqConfig(path.join(home, ".hq"));
     if (fromConfig)
         return path.resolve(fromConfig);
     // Tier 5: discover a valid HQ root in the well-known locations.
-    const discovered = discoverHqRootViaCoreYaml();
+    const discovered = discoverHqRootViaCoreYaml(home);
     if (discovered)
         return discovered;
     // Tier 6: nothing resolved.
@@ -127,7 +129,7 @@ export function resolveDefaultHqRoot(opts = {}) {
             "or install HQ via the installer/menubar so ~/.hq/menubar.json records " +
             "its location.");
     }
-    return path.join(os.homedir(), "hq");
+    return path.join(home, "hq");
 }
 /**
  * Read the configured HQ root from the installer/menubar records under
@@ -156,8 +158,7 @@ function readJsonStringField(file, field) {
     }
 }
 /** Well-known parent locations an HQ tree commonly lives in (mirrors hq-sync). */
-function hqDiscoveryCandidates() {
-    const home = os.homedir();
+function hqDiscoveryCandidates(home = os.homedir()) {
     return [
         path.join(home, "HQ"),
         path.join(home, "hq"),
@@ -172,8 +173,8 @@ function hqDiscoveryCandidates() {
  * 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);
+function discoverHqRootViaCoreYaml(home) {
+    return hqDiscoveryCandidates(home).find(isValidHqRootSignature);
 }
 /**
  * True iff `dir` carries a valid hq-core `core.yaml` — canonical

package/dist/utils/install-tree-torn.d.ts

@@ -179,6 +179,8 @@ export interface InstallTreeFs {
     existsSync(p: string): boolean;
     statSync(p: string): {
         isDirectory(): boolean;
+        size?: number;
+        mtimeMs?: number;
     };
     readFileSync(p: string, encoding: "utf-8"): string;
     readdirSync(p: string): string[];
@@ -225,6 +227,8 @@ export interface WaitForInstallTreeSettledArgs {
     isPidAlive?: (pid: number) => boolean;
     pollMs?: number;
     quietMs?: number;
+    /** Short observation window for an unchanged, lock-free broken tree. */
+    staleProbeMs?: number;
     deadlineMs: number;
     /**
      * Ceiling on the CUMULATIVE time observed under a FRESH foreign lock held by a
@@ -256,7 +260,12 @@ export interface WaitForInstallTreeSettledResult {
     lockedMs: number;
     /** The bounded `tool` of the last fresh foreign lock seen, or "" if none. */
     lockTool: string;
+    /** Whether a relevant install-tree path changed during this wait. */
+    sawTreeChange?: boolean;
+    /** True when the lock-free tree stayed unchanged for `staleProbeMs`. */
+    staleTree?: boolean;
 }
+export declare const DEFAULT_INSTALL_TREE_STALE_PROBE_MS = 1500;
 /**
  * Poll until the install tree has been continuously READY for `quietMs`, or the
  * wait exhausts its bounds. READY means: (i) no FRESH update lock held by another
@@ -265,14 +274,14 @@ export interface WaitForInstallTreeSettledResult {
  * `.<leaf>-<rand>` retired sibling remains beside it. Every filesystem error makes
  * its condition "not ready" rather than throwing.
  *
- * The wait is LOCK-AWARE and bounded on TWO independent axes, so a live
- * cooperating writer (the desktop app, the box's update timer, another `hq`)
- * cannot make a legitimately-in-progress reinstall look like a torn install:
+ * The wait is LOCK-AWARE and bounded, so a live cooperating writer (the desktop
+ * app, the box's update timer, another `hq`) cannot make a legitimately-in-progress
+ * reinstall look stale:
  *   - UNLOCKED time — wall time observed with no fresh foreign lock — is bounded
- *     by `deadlineMs`. That is the budget for the TREE to settle once no writer is
- *     visible; with no lock ever seen, unlocked time equals total wait time and
- *     the behaviour is byte-for-byte the pre-lock-aware one (unsettled at exactly
- *     `deadlineMs`, and `deadlineMs === 0` evaluates readiness exactly once).
+ *     by `deadlineMs`. If the target is still missing, no lock or retired sibling
+ *     is present, and the observed tree stays unchanged for `staleProbeMs`, the
+ *     wait returns `staleTree` early. Any observed tree change keeps the ordinary
+ *     settle deadline in force. `deadlineMs === 0` evaluates readiness once.
  *   - LOCKED time — wall time observed under a fresh foreign lock held by a live
  *     pid — is bounded SEPARATELY by `lockWaitMs` (default the lock contract's own
  *     10-minute staleness window) and does NOT consume the settle budget. When
@@ -285,7 +294,8 @@ export interface WaitForInstallTreeSettledResult {
  * began, so a starved event loop only makes the wait coarser, never unbounded. A
  * stale lock (dead pid, older than the staleness window, unparseable) or our own
  * pid never extends anything. The whole wait is bounded (≤ `deadlineMs +
- * lockWaitMs`), so the caller can never hang.
+ * lockWaitMs`), and the unchanged-tree path normally returns after the much
+ * shorter `staleProbeMs` observation window.
  */
 export declare function waitForInstallTreeSettled(args: WaitForInstallTreeSettledArgs): Promise<WaitForInstallTreeSettledResult>;
 export interface InstallRewriteSignalArgs {
@@ -310,7 +320,8 @@ export interface InstallRewriteSignalArgs {
  */
 export declare function installRewriteInProgress(args: InstallRewriteSignalArgs): boolean;
 /** The recovery OUTCOME, which — not the dialect — decides capture. */
-export type InstallTreeTornOutcome = "guarded" | "unsettled" | "reexec-failed" | "lock-held";
+export type InstallTreeTornOutcome = "guarded" | "unsettled" | "reexec-failed" | "lock-held" | "stale_tree";
+export type InstallTreeState = "in_flight" | "stale";
 export type InstallTreeTornDiagnostics = {
     dialect: ModuleErrorDialect;
     code: ModuleNotFoundCode;
@@ -318,10 +329,12 @@ export type InstallTreeTornDiagnostics = {
     importer: string;
     packageRoot: string;
     outcome: InstallTreeTornOutcome;
+    treeState: InstallTreeState;
     attempt: 1 | 2;
     waitedMs: number;
     sawLock: boolean;
     sawRetired: boolean;
+    sawTreeChange: boolean;
     /** A fresh foreign lock was still held when the wait gave up (→ 'lock-held'). */
     lockHeldAtEnd: boolean;
     /** Cumulative wall time the wait spent under a fresh foreign lock. */
@@ -342,6 +355,8 @@ export interface InstallTreeTornInit {
     waitedMs: number;
     sawLock: boolean;
     sawRetired: boolean;
+    sawTreeChange?: boolean;
+    treeState?: InstallTreeState;
     /** Whether a fresh foreign lock was held when the wait gave up (default false). */
     lockHeldAtEnd?: boolean;
     /** Cumulative time under a fresh foreign lock (default 0). */
@@ -362,11 +377,13 @@ export declare class InstallTreeTornError extends Error {
 }
 export declare function isInstallTreeTornError(err: unknown): err is InstallTreeTornError;
 /** The exact Sentry `contexts` payload for a captured torn-install failure. */
-export declare function installTreeTornCaptureContext(err: InstallTreeTornError): {
+export declare function installTreeTornCaptureContext(err: InstallTreeTornError, homeDirectory?: string): {
     contexts: {
         install_tree_torn: InstallTreeTornDiagnostics;
     };
 };
+/** Replace a home-directory prefix without matching similarly-named sibling folders. */
+export declare function scrubHomeDirectoryPrefix(value: string, homeDirectory?: string): string;
 /**
  * The fixed, input-free operator remedy. It names the likely writers (so a
  * human knows this was not their command's fault) and the reinstall commands,
@@ -374,6 +391,8 @@ export declare function installTreeTornCaptureContext(err: InstallTreeTornError)
  * appended by {@link installTreeTornStderrLine}.
  */
 export declare const INSTALL_TREE_TORN_REMEDY: string;
+/** Fixed repair guidance for an unchanged tree with no active updater signal. */
+export declare const INSTALL_TREE_STALE_REMEDY: string;
 /**
  * The fixed, input-free remedy for the 'lock-held' outcome: a cooperating writer
  * held the shared update lock past its own staleness ceiling. Telling the user to