@indigoai-us/hq-cli 5.163.0 → 5.165.0

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 ## [Unreleased]
 
+## [5.165.0] — 2026-09-24
+
+### Fixed
+
+- Codex lane starts and resumes now pass the assigned worker policy directory to
+  policy hooks.
+
+## [5.164.0] — 2026-09-24
+
+### Fixed
+
+- When a startup import fails, hq-cli checks for an update lock, a retired package
+  directory, or install-tree changes for 1.5 seconds. If none appears, it exits
+  with `npm install -g @indigoai-us/hq-cli@latest` instead of waiting 90 seconds.
+  Sentry context replaces the home-directory prefix with `~`.
+- Sentry keeps the `guarded`, `unsettled`, `reexec-failed`, and `lock-held`
+  outcomes, adds `stale_tree` and `tree_state`, and tags `updater_source` when
+  known. The fingerprint remains `["InstallTreeTornError", "outcome:<token>"]`,
+  so the four existing outcome groups keep their keys.
+
 ## [5.163.0] — 2026-09-24
 
 - Workforce plan refusals in the CLI keep direct checkout for eligible companies.

package/dist/lib/lanes/spawn.d.ts

@@ -222,6 +222,8 @@ export declare function buildProviderCommand(provider: LaneProvider, input: {
     fastMode?: boolean;
     /** Per-spawn worker profile instructions and materialized settings. */
     profile?: ProviderProfileLaunch;
+    /** Worker profile path, forwarded to Codex hook subprocesses when supported. */
+    workerPolicyDir?: string;
     /** Continue a recorded session. Only providers in PROVIDER_SESSION_RESUME accept this. */
     resume?: ProviderResumeInput;
     /**

package/dist/lib/lanes/spawn.js

@@ -522,6 +522,19 @@ function appendProviderProfileFlags(provider, args, profile) {
         }
     }
 }
+/** Make the worker policy directory available to Codex hook subprocesses. */
+function appendCodexWorkerPolicyDirFlag(provider, args, workerPolicyDir) {
+    if (provider !== "codex" || workerPolicyDir === undefined)
+        return args;
+    if (!workerPolicyDir.trim()) {
+        throw new LanesError("invalid_worker_policy_dir", "Worker policy directory must not be empty");
+    }
+    const setting = `shell_environment_policy.set.HQ_POLICY_WORKER_DIR=${JSON.stringify(workerPolicyDir)}`;
+    const separator = args.indexOf("--");
+    if (separator === -1)
+        return [...args, "-c", setting];
+    return [...args.slice(0, separator), "-c", setting, ...args.slice(separator)];
+}
 export const PID_LIVENESS_DECISIONS = [
     "esrch",
     "starttime_mismatch",
@@ -1138,7 +1151,7 @@ export function buildProviderCommand(provider, input) {
     }
     return {
         command,
-        args: appendFastModeFlags(parsed, appendEffortFlag(parsed, appendModelFlag(parsed, appendProviderProfileFlags(parsed, args, input.profile), input.model), input.effort), input.fastMode),
+        args: appendFastModeFlags(parsed, appendEffortFlag(parsed, appendModelFlag(parsed, appendCodexWorkerPolicyDirFlag(parsed, appendProviderProfileFlags(parsed, args, input.profile), input.workerPolicyDir), input.model), input.effort), input.fastMode),
     };
 }
 export function workerEnv(base, resolved, laneId, hqRoot, autoCompactTokens, meshCompany, workerPolicyDir) {
@@ -1757,6 +1770,7 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
         effort: effort.effort,
         fastMode,
         profile: profileLaunch,
+        workerPolicyDir,
         resume,
     });
     // A systemd PATH mismatch is an environment defect, not a lane failure.
@@ -1806,6 +1820,7 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
                 effort: effort.effort,
                 fastMode,
                 profile: profileLaunch,
+                workerPolicyDir,
                 resume: { session_id: resume.session_id, prompt: COMPACTION_PROMPT },
             });
             compaction = compactLaneSession({
@@ -2128,6 +2143,7 @@ export function spawnEnvelopeRepair(hqRoot, lane, input, deps = {}) {
         effort: effort.effort,
         fastMode,
         profile: profileLaunch,
+        workerPolicyDir,
         ...(mode === "resume" && sessionId !== null
             ? { resume: { session_id: sessionId, prompt: repairPrompt } }
             : { freshTurnPrompt: repairPrompt }),

package/dist/sentry.js

@@ -7,7 +7,7 @@ import { getCachedSentryUser } from "./utils/sentry-identity.js";
 import { isEpipe } from "./utils/epipe.js";
 import { environmentalFsErrorMessage } from "./utils/environmental-error.js";
 import { incompleteInstallCaptureContext, incompleteInstallMessage, } from "./utils/incomplete-install-error.js";
-import { sentryFingerprintFor, sentryMcpCollisionContextFor, } from "./utils/sentry-fingerprint.js";
+import { installTreeTornSentryTagsFor, sentryFingerprintFor, sentryMcpCollisionContextFor, } from "./utils/sentry-fingerprint.js";
 /**
  * Drop broken-pipe (EPIPE) crashes before scrubbing/send. A closed downstream
  * reader (`hq … | head`, `source <(hq …)`, a parent that exited) is normal
@@ -84,6 +84,10 @@ export function epipeAwareBeforeSend(event, hint) {
         if (fingerprint)
             event.fingerprint = fingerprint;
     }
+    const installTreeTags = installTreeTornSentryTagsFor(hint?.originalException);
+    if (installTreeTags) {
+        event.tags = { ...event.tags, ...installTreeTags };
+    }
     return beforeSend(event, hint);
 }
 /**

package/dist/startup-registration.d.ts

@@ -23,6 +23,8 @@ import { type InstallRewriteSignalArgs, type WaitForInstallTreeSettledArgs, type
  * shadow each other.
  */
 export declare const INSTALL_TREE_RECOVERY_GUARD_ENV = "HQ_INSTALL_TREE_RECOVERED";
+/** Carries the writer-state observed by the parent into the guarded re-exec. */
+export declare const INSTALL_TREE_RECOVERY_TREE_STATE_ENV = "HQ_INSTALL_TREE_RECOVERY_TREE_STATE";
 /** Operator override for the settle wait's deadline. */
 export declare const INSTALL_SETTLE_TIMEOUT_ENV = "HQ_INSTALL_SETTLE_TIMEOUT_MS";
 /** Default settle deadline (ms). Overridable by {@link INSTALL_SETTLE_TIMEOUT_ENV}. */
@@ -32,7 +34,7 @@ export declare const DEFAULT_INSTALL_SETTLE_TIMEOUT_MS = 90000;
  * 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 declare const INSTALL_TREE_WAIT_NOTICE = "hq: the hq-cli install is being updated underneath this command; waiting for it to finish\u2026";
+export declare const INSTALL_TREE_WAIT_NOTICE = "hq: checking whether the hq-cli install tree is still changing before retrying\u2026";
 /** Resolve the settle deadline from the environment (0 = evaluate once; default on invalid). */
 export declare function resolveSettleTimeoutMs(env: NodeJS.ProcessEnv): number;
 /** Operator override for the settle wait's LOCK ceiling (time under a live writer). */

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/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

package/dist/utils/install-tree-torn.js

@@ -30,6 +30,7 @@
  * are only READ (their exported symbols), never modified.
  */
 import * as nodeFs from "node:fs";
+import { homedir } from "node:os";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { CLI_NAME } from "../cli-version.js";
@@ -637,6 +638,125 @@ function packageRootHealthy(packageRoot, fs) {
     const manifest = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf-8"));
     return manifest.name === CLI_NAME;
 }
+function isWithinPath(candidate, root) {
+    const relative = path.relative(root, candidate);
+    return relative === "" ||
+        (!path.isAbsolute(relative) && relative !== ".." && !relative.startsWith(`..${path.sep}`));
+}
+/** Paths whose presence, metadata, or immediate entries show activity for this import. */
+function installTreeActivityPaths(target, packageRoot) {
+    const root = packageRoot ? path.resolve(packageRoot) : null;
+    const paths = new Set();
+    const directories = new Set();
+    const addPath = (candidate) => {
+        const resolved = path.resolve(candidate);
+        paths.add(resolved);
+        directories.add(path.dirname(resolved));
+        if (!root || !isWithinPath(resolved, root))
+            return;
+        let current = path.dirname(resolved);
+        for (;;) {
+            paths.add(current);
+            directories.add(current);
+            if (current === root)
+                break;
+            const parent = path.dirname(current);
+            if (parent === current || !isWithinPath(parent, root))
+                break;
+            current = parent;
+        }
+    };
+    if (root) {
+        for (const candidate of [
+            root,
+            path.join(root, "package.json"),
+            path.join(root, "dist"),
+            path.join(root, "node_modules"),
+        ]) {
+            addPath(candidate);
+            directories.add(candidate);
+        }
+    }
+    if (target.kind === "path" || target.kind === "exists") {
+        addPath(target.path);
+    }
+    else if (target.kind === "relative") {
+        const base = path.resolve(target.from, target.specifier);
+        const candidates = [
+            base,
+            ...CJS_FILE_EXTENSIONS.map((ext) => base + ext),
+            ...CJS_FILE_EXTENSIONS.map((ext) => path.join(base, `index${ext}`)),
+        ];
+        for (const candidate of candidates)
+            addPath(candidate);
+    }
+    else if (target.kind === "package") {
+        let from = path.resolve(target.from);
+        let ancestorCount = 0;
+        for (;;) {
+            if (root && !isWithinPath(from, root))
+                break;
+            addPath(path.join(from, "node_modules", target.name));
+            if (from === root)
+                break;
+            ancestorCount += 1;
+            if (!root && ancestorCount >= 12)
+                break;
+            const parent = path.dirname(from);
+            if (parent === from)
+                break;
+            from = parent;
+        }
+    }
+    return {
+        paths: [...paths].sort(),
+        directories: [...directories].sort(),
+    };
+}
+/** A local-only snapshot of the missing target and directories an installer may change. */
+function installTreeActivitySignature(target, packageRoot, fs) {
+    const activity = installTreeActivityPaths(target, packageRoot);
+    const snapshots = [];
+    let observed = true;
+    const errorCode = (err) => {
+        if (err !== null && typeof err === "object" && "code" in err && typeof err.code === "string") {
+            return err.code;
+        }
+        return "error";
+    };
+    for (const candidate of activity.paths) {
+        try {
+            if (!fs.existsSync(candidate)) {
+                snapshots.push([candidate, "missing"]);
+                continue;
+            }
+            const stat = fs.statSync(candidate);
+            snapshots.push([
+                candidate,
+                stat.isDirectory() ? "directory" : "file",
+                stat.size ?? null,
+                stat.mtimeMs ?? null,
+            ]);
+        }
+        catch (err) {
+            observed = false;
+            snapshots.push([candidate, `unreadable:${errorCode(err)}`]);
+        }
+    }
+    for (const directory of activity.directories) {
+        try {
+            if (!fs.existsSync(directory) || !fs.statSync(directory).isDirectory())
+                continue;
+            snapshots.push([directory, "entries", fs.readdirSync(directory).sort()]);
+        }
+        catch (err) {
+            observed = false;
+            snapshots.push([directory, `entries-unreadable:${errorCode(err)}`]);
+        }
+    }
+    return { value: JSON.stringify(snapshots), observed };
+}
+export const DEFAULT_INSTALL_TREE_STALE_PROBE_MS = 1_500;
 /**
  * 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
@@ -645,14 +765,14 @@ function packageRootHealthy(packageRoot, fs) {
  * `.<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
@@ -665,7 +785,8 @@ function packageRootHealthy(packageRoot, fs) {
  * 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 async function waitForInstallTreeSettled(args) {
     const now = args.now ?? Date.now;
@@ -676,7 +797,11 @@ export async function waitForInstallTreeSettled(args) {
     const quietMs = args.quietMs ?? 1500;
     const deadlineMs = args.deadlineMs;
     const lockWaitMs = args.lockWaitMs ?? DEFAULT_INSTALL_SETTLE_LOCK_WAIT_MS;
+    const staleProbeMs = Math.max(0, args.staleProbeMs ?? DEFAULT_INSTALL_TREE_STALE_PROBE_MS);
     const start = now();
+    let lastActivitySnapshot = installTreeActivitySignature(args.target, args.packageRoot, fs);
+    let staleObservationStartedAt = lastActivitySnapshot.observed ? start : null;
+    let sawTreeChange = false;
     let readySince = null;
     let sawLock = false;
     let sawRetired = false;
@@ -700,6 +825,32 @@ export async function waitForInstallTreeSettled(args) {
             sawLock = true;
             lockTool = boundedDiagnosticValue(lock.tool, LOCK_TOOL_BYTES);
         }
+        if (!sawTreeChange) {
+            const activitySnapshot = installTreeActivitySignature(args.target, args.packageRoot, fs);
+            if (!activitySnapshot.observed) {
+                staleObservationStartedAt = null;
+            }
+            else if (!lastActivitySnapshot.observed) {
+                staleObservationStartedAt = t;
+            }
+            else if (activitySnapshot.value !== lastActivitySnapshot.value) {
+                sawTreeChange = true;
+                staleObservationStartedAt = null;
+            }
+            lastActivitySnapshot = activitySnapshot;
+        }
+        let retiredPresent = false;
+        let retiredCheckFailed = false;
+        if (args.packageRoot) {
+            try {
+                retiredPresent = retiredSiblingPresent(args.packageRoot, fs);
+                if (retiredPresent)
+                    sawRetired = true;
+            }
+            catch {
+                retiredCheckFailed = true;
+            }
+        }
         let ready = !foreignLockHeld && installTargetPresent(args.target, fs);
         if (ready && args.packageRoot) {
             try {
@@ -709,17 +860,8 @@ export async function waitForInstallTreeSettled(args) {
             catch {
                 ready = false;
             }
-            if (ready) {
-                try {
-                    if (retiredSiblingPresent(args.packageRoot, fs)) {
-                        sawRetired = true;
-                        ready = false;
-                    }
-                }
-                catch {
-                    ready = false;
-                }
-            }
+            if (ready && (retiredPresent || retiredCheckFailed))
+                ready = false;
         }
         if (ready) {
             if (readySince === null)
@@ -731,7 +873,38 @@ export async function waitForInstallTreeSettled(args) {
         const waitedMs = t - start;
         if (ready && (deadlineMs === 0 || t - readySince >= quietMs)) {
             // Settling requires no foreign lock, so it is never held at the end here.
-            return { settled: true, waitedMs, sawLock, sawRetired, lockHeldAtEnd: false, lockedMs, lockTool };
+            return {
+                settled: true,
+                waitedMs,
+                sawLock,
+                sawRetired,
+                lockHeldAtEnd: false,
+                lockedMs,
+                lockTool,
+                sawTreeChange,
+                staleTree: false,
+            };
+        }
+        if (!ready &&
+            !foreignLockHeld &&
+            !retiredPresent &&
+            !retiredCheckFailed &&
+            !sawLock &&
+            !sawRetired &&
+            !sawTreeChange &&
+            staleObservationStartedAt !== null &&
+            t - staleObservationStartedAt >= staleProbeMs) {
+            return {
+                settled: false,
+                waitedMs,
+                sawLock,
+                sawRetired,
+                lockHeldAtEnd: false,
+                lockedMs,
+                lockTool,
+                sawTreeChange,
+                staleTree: true,
+            };
         }
         // Give up when the TREE has had a full unlocked budget with no writer visible,
         // OR a writer is STILL holding the lock and has held it past its own staleness
@@ -742,7 +915,17 @@ export async function waitForInstallTreeSettled(args) {
         // `deadlineMs` 0 makes the unlocked test fire on the first poll (evaluate-once),
         // matching the pre-lock-aware contract; `lockHeldAtEnd` distinguishes the causes.
         if (unlockedMs >= deadlineMs || (foreignLockHeld && lockedMs >= lockWaitMs)) {
-            return { settled: false, waitedMs, sawLock, sawRetired, lockHeldAtEnd: foreignLockHeld, lockedMs, lockTool };
+            return {
+                settled: false,
+                waitedMs,
+                sawLock,
+                sawRetired,
+                lockHeldAtEnd: foreignLockHeld,
+                lockedMs,
+                lockTool,
+                sawTreeChange,
+                staleTree: false,
+            };
         }
         // The first poll at which the wait has reached `deadlineMs` while a lock is
         // still held is exactly where the pre-lock-aware wait gave up — announce the
@@ -808,7 +991,7 @@ export function installRewriteInProgress(args) {
     }
 }
 /** The fixed, input-free carrier message (grouping cardinality stays bounded). */
-const INSTALL_TREE_TORN_MESSAGE = "hq-cli install tree was being rewritten while this command started";
+const INSTALL_TREE_TORN_MESSAGE = "hq-cli could not load a module from its install tree and automatic recovery did not complete";
 /**
  * A torn-install failure that stays VISIBLE in Sentry with bounded, hq-derived
  * diagnostics. Fixed `name`/`message` (no argv, path, or free text in either),
@@ -822,6 +1005,8 @@ export class InstallTreeTornError extends Error {
         super(INSTALL_TREE_TORN_MESSAGE);
         this.name = "InstallTreeTornError";
         this.cause = init.cause;
+        const sawTreeChange = init.sawTreeChange ?? false;
+        const treeState = init.treeState ?? (init.outcome === "stale_tree" ? "stale" : "in_flight");
         this.diagnostics = {
             dialect: init.classified.dialect,
             code: init.classified.code,
@@ -829,10 +1014,12 @@ export class InstallTreeTornError extends Error {
             importer: boundedDiagnosticValue(init.classified.importer, IMPORTER_BYTES),
             packageRoot: boundedDiagnosticValue(init.packageRoot ?? "", PACKAGE_ROOT_BYTES),
             outcome: init.outcome,
+            treeState,
             attempt: init.attempt,
             waitedMs: init.waitedMs,
             sawLock: init.sawLock,
             sawRetired: init.sawRetired,
+            sawTreeChange,
             lockHeldAtEnd: init.lockHeldAtEnd ?? false,
             lockedMs: init.lockedMs ?? 0,
             lockTool: boundedDiagnosticValue(init.lockTool ?? "", LOCK_TOOL_BYTES),
@@ -846,8 +1033,45 @@ export function isInstallTreeTornError(err) {
     return err instanceof InstallTreeTornError;
 }
 /** The exact Sentry `contexts` payload for a captured torn-install failure. */
-export function installTreeTornCaptureContext(err) {
-    return { contexts: { install_tree_torn: err.diagnostics } };
+export function installTreeTornCaptureContext(err, homeDirectory = homedir()) {
+    const diagnostics = err.diagnostics;
+    return {
+        contexts: {
+            install_tree_torn: {
+                ...diagnostics,
+                specifier: scrubHomeDirectoryPrefix(diagnostics.specifier, homeDirectory),
+                importer: scrubHomeDirectoryPrefix(diagnostics.importer, homeDirectory),
+                packageRoot: scrubHomeDirectoryPrefix(diagnostics.packageRoot, homeDirectory),
+            },
+        },
+    };
+}
+function looksLikeWindowsPath(value) {
+    return /^[a-zA-Z]:[\\/]/.test(value) || /^\\\\/.test(value);
+}
+/** Replace a home-directory prefix without matching similarly-named sibling folders. */
+export function scrubHomeDirectoryPrefix(value, homeDirectory = homedir()) {
+    if (!value || !homeDirectory)
+        return value;
+    if (looksLikeWindowsPath(value) || looksLikeWindowsPath(homeDirectory)) {
+        const home = path.win32.normalize(homeDirectory).replace(/[\\/]+$/, "");
+        const normalized = path.win32.normalize(value);
+        const foldedHome = home.toLowerCase();
+        const foldedValue = normalized.toLowerCase();
+        if (foldedValue === foldedHome)
+            return "~";
+        const prefix = `${foldedHome}\\`;
+        if (foldedValue.startsWith(prefix))
+            return `~\\${normalized.slice(home.length + 1)}`;
+        return value;
+    }
+    const home = path.posix.normalize(homeDirectory).replace(/\/+$/, "");
+    const normalized = path.posix.normalize(value);
+    if (normalized === home)
+        return "~";
+    if (normalized.startsWith(`${home}/`))
+        return `~/${normalized.slice(home.length + 1)}`;
+    return value;
 }
 /**
  * The fixed, input-free operator remedy. It names the likely writers (so a
@@ -855,10 +1079,15 @@ export function installTreeTornCaptureContext(err) {
  * and interpolates NOTHING — the only per-event value is the bounded specifier
  * appended by {@link installTreeTornStderrLine}.
  */
-export const INSTALL_TREE_TORN_REMEDY = "the hq-cli install was being updated by another process (the box's hq-cli-update " +
-    "timer, the desktop app, or another hq command) while this command started. " +
-    "Re-run your command; if it keeps failing, reinstall with " +
-    "`npm i -g @indigoai-us/hq-cli` (or `pnpm add -g @indigoai-us/hq-cli`).";
+export const INSTALL_TREE_TORN_REMEDY = "hq-cli could not finish automatic install-tree recovery. Re-run your command; " +
+    "if it still fails, reinstall with `npm install -g @indigoai-us/hq-cli@latest` " +
+    "(or `pnpm add -g @indigoai-us/hq-cli@latest` / `bun add -g @indigoai-us/hq-cli@latest` " +
+    "when that manager owns your install).";
+/** Fixed repair guidance for an unchanged tree with no active updater signal. */
+export const INSTALL_TREE_STALE_REMEDY = "hq-cli's install tree is incomplete and no active updater was detected. " +
+    "Reinstall with `npm install -g @indigoai-us/hq-cli@latest` " +
+    "(or `pnpm add -g @indigoai-us/hq-cli@latest` / `bun add -g @indigoai-us/hq-cli@latest` " +
+    "when that manager owns your install), then run the command again.";
 /**
  * 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
@@ -877,7 +1106,11 @@ export const INSTALL_TREE_LOCK_HELD_REMEDY = "another hq updater (the desktop ap
  * {@link INSTALL_TREE_TORN_REMEDY} byte-for-byte.
  */
 export function installTreeTornStderrLine(err) {
-    const remedy = err.diagnostics.outcome === "lock-held" ? INSTALL_TREE_LOCK_HELD_REMEDY : INSTALL_TREE_TORN_REMEDY;
+    const remedy = err.diagnostics.outcome === "lock-held"
+        ? INSTALL_TREE_LOCK_HELD_REMEDY
+        : err.diagnostics.outcome === "stale_tree"
+            ? INSTALL_TREE_STALE_REMEDY
+            : INSTALL_TREE_TORN_REMEDY;
     const specifier = err.diagnostics.specifier;
     return specifier ? `${remedy} (missing: ${specifier})` : remedy;
 }

package/dist/utils/sentry-fingerprint.d.ts

@@ -9,6 +9,12 @@ export interface SentryMcpCollisionContext {
 }
 /** Return bounded, value-free Sentry context for an instrumented Codex name collision. */
 export declare function sentryMcpCollisionContextFor(err: unknown): SentryMcpCollisionContext | null;
+/**
+ * Bounded, aggregatable tags for an unrecovered install-tree failure. Phase,
+ * outcome, state, and OS are closed values. Paths and raw lock-tool strings stay
+ * in context; only a known updater source becomes a tag.
+ */
+export declare function installTreeTornSentryTagsFor(err: unknown): Record<string, string> | null;
 /**
  * Return a bounded `event.fingerprint` array for `err`, or `null` when `err`
  * carries no discriminator from the closed allowlist (in which case the caller
@@ -23,7 +29,7 @@ export declare function sentryMcpCollisionContextFor(err: unknown): SentryMcpCol
  * The InstallTreeTornError branch is the deliberate exception: it returns a
  * fully explicit `["InstallTreeTornError", "outcome:<token>"]` with NO
  * DEFAULT_GROUPING lead, because its chained loader cause makes the default
- * component unbounded (see the module header — HQ-CLI-21/22/23).
+ * component unbounded.
  *
  * `rpcCode` is checked first so a gateway JSON-RPC fault groups by its protocol
  * code; the two carriers are disjoint in practice (the JSON-RPC throw site sets

package/dist/utils/sentry-fingerprint.js

@@ -38,7 +38,9 @@
 //     in three different groups (hashes a4289a5e530e166ebdedea9d34dcad0a,
 //     b563c1b891bd975bdc605efc86034b44, b4ee254473ea249758617de1a98848fa —
 //     HQ-CLI-21/22/23). So that branch returns a FULLY EXPLICIT key with no
-//     default lead: ["InstallTreeTornError", "outcome:<token>"].
+//     default lead: ["InstallTreeTornError", "outcome:<token>"]. This PR keeps
+//     the existing explicit key so the new stale-tree outcome extends the current
+//     groups without splitting them.
 //
 // Genuinely different failure classes therefore form distinct, PREDICTABLE
 // groups, and everything with no bounded discriminator is left to default
@@ -156,17 +158,96 @@ const KNOWN_ERROR_NAMES = new Set([
     "QmdWorkdirMissingError",
     // A torn-install failure the bounded settle-wait + single re-exec could not
     // recover (HQ-CLI-1G/1H/1J/1K, HQ-CLI-1Y). Fingerprinted on its own branch below
-    // by the bounded `diagnostics.outcome`, so the whole family groups into ≤4 issues.
+    // by the normalized recovery result, so the family groups into two stable buckets.
     "InstallTreeTornError",
 ]);
 /**
- * The CLOSED set of InstallTreeTornError recovery outcomes worth their own
- * group. Anything else collapses to `outcome:other`, so the axis stays finite;
- * the carrier's message is fixed, so this outcome IS the only discriminator.
+ * The closed loader dialects accepted for the install_tree_phase tag. Anything
+ * outside this set collapses to unknown, so tags stay safe to aggregate.
  */
+const INSTALL_TREE_PHASES = new Set([
+    "cjs-enoent",
+    "cjs-package",
+    "cjs-path",
+    "cjs-relative",
+    "esm-enoent",
+    "esm-package",
+    "esm-path",
+    "eval-throw",
+    "resolve-enoent",
+    "unknown",
+]);
+const KNOWN_INSTALL_TREE_UPDATERS = new Map([
+    ["hq-cli-self-update", "cli-self-update"],
+    ["hq-cli-update", "box-timer"],
+    ["hq-cli-version-gate", "cli-version-gate"],
+    ["hq-desktop-app-cli-update", "desktop-app"],
+]);
 const KNOWN_INSTALL_TREE_OUTCOMES = new Set([
-    "guarded", "unsettled", "reexec-failed", "lock-held",
+    "guarded",
+    "unsettled",
+    "reexec-failed",
+    "lock-held",
+    "stale_tree",
 ]);
+function installTreeRecoveryOutcomeTag(value) {
+    return typeof value === "string" && KNOWN_INSTALL_TREE_OUTCOMES.has(value)
+        ? value
+        : null;
+}
+function installTreeStateTag(value) {
+    return value === "stale" ? "stale" : "in_flight";
+}
+function installTreePhaseTag(value) {
+    if (typeof value !== "string" || !INSTALL_TREE_PHASES.has(value))
+        return "unknown";
+    if (value === "esm-enoent" || value === "cjs-enoent")
+        return "loader_read";
+    if (value === "eval-throw")
+        return "module_evaluation";
+    if (value === "esm-package" || value === "cjs-package")
+        return "package_resolution";
+    if (value === "unknown")
+        return "unknown";
+    return "path_resolution";
+}
+function installTreeOsTag(platform) {
+    if (platform === "win32")
+        return "windows";
+    if (platform === "darwin")
+        return "macos";
+    if (platform === "linux")
+        return "linux";
+    return "other";
+}
+/**
+ * Bounded, aggregatable tags for an unrecovered install-tree failure. Phase,
+ * outcome, state, and OS are closed values. Paths and raw lock-tool strings stay
+ * in context; only a known updater source becomes a tag.
+ */
+export function installTreeTornSentryTagsFor(err) {
+    if (err === null || typeof err !== "object")
+        return null;
+    const record = err;
+    if (record.name !== "InstallTreeTornError")
+        return null;
+    const diagnostics = record.diagnostics !== null && typeof record.diagnostics === "object"
+        ? record.diagnostics
+        : {};
+    const recoveryOutcome = installTreeRecoveryOutcomeTag(diagnostics.outcome);
+    const tags = {
+        install_tree_phase: installTreePhaseTag(diagnostics.dialect),
+        tree_state: installTreeStateTag(diagnostics.treeState),
+        os: installTreeOsTag(process.platform),
+    };
+    if (recoveryOutcome)
+        tags.recovery_outcome = recoveryOutcome;
+    const lockTool = diagnostics.lockTool;
+    const updaterSource = typeof lockTool === "string" ? KNOWN_INSTALL_TREE_UPDATERS.get(lockTool) : undefined;
+    if (updaterSource)
+        tags.updater_source = updaterSource;
+    return tags;
+}
 /** Fixed bucket for any error name outside the closed allowlist. */
 const FALLBACK_ERROR_NAME = "other";
 /**
@@ -241,7 +322,7 @@ function qmdDispositionToken(status, signal) {
  * The InstallTreeTornError branch is the deliberate exception: it returns a
  * fully explicit `["InstallTreeTornError", "outcome:<token>"]` with NO
  * DEFAULT_GROUPING lead, because its chained loader cause makes the default
- * component unbounded (see the module header — HQ-CLI-21/22/23).
+ * component unbounded.
  *
  * `rpcCode` is checked first so a gateway JSON-RPC fault groups by its protocol
  * code; the two carriers are disjoint in practice (the JSON-RPC throw site sets
@@ -284,10 +365,9 @@ export function sentryFingerprintFor(err) {
         ];
     }
     // A torn-install failure carries neither an rpcCode nor an HTTP status; its
-    // only bounded discriminator is the recovery `diagnostics.outcome`. Keyed
+    // only bounded discriminator is the existing recovery outcome. Keyed
     // BEFORE the rpc/status branches so the family groups into a bounded set of
-    // predictable issues (guarded / unsettled / reexec-failed / lock-held, plus the
-    // `outcome:other` fallback) rather than one fungible bucket.
+    // predictable issues rather than one fungible bucket.
     //
     // The key is FULLY EXPLICIT — it does NOT lead with DEFAULT_GROUPING. Leading
     // with the placeholder salts the appended tokens with Sentry's default grouping
@@ -300,16 +380,16 @@ export function sentryFingerprintFor(err) {
     // a4289a5e530e166ebdedea9d34dcad0a, b563c1b891bd975bdc605efc86034b44 and
     // b4ee254473ea249758617de1a98848fa (HQ-CLI-21/22/23) — defeating the very bound
     // this branch exists to enforce. The explicit key collapses them to one stable
-    // group per outcome, independent of machine, install path and which module tore.
+    // group per recovery outcome, independent of machine, install path and module.
     if (rawName === "InstallTreeTornError") {
         const diagnostics = record.diagnostics;
         const outcome = diagnostics !== null && typeof diagnostics === "object"
             ? diagnostics.outcome
             : undefined;
-        const token = typeof outcome === "string" && KNOWN_INSTALL_TREE_OUTCOMES.has(outcome)
-            ? `outcome:${outcome}`
-            : "outcome:other";
-        return ["InstallTreeTornError", token];
+        return [
+            "InstallTreeTornError",
+            `outcome:${installTreeRecoveryOutcomeTag(outcome) ?? "other"}`,
+        ];
     }
     const name = KNOWN_ERROR_NAMES.has(rawName) ? rawName : FALLBACK_ERROR_NAME;
     const rpcCode = record.rpcCode;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.163.0",
+  "version": "5.165.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {