@indigoai-us/hq-cli 5.109.10 → 5.109.11

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## [Unreleased]
 
+## [5.109.11] — 2026-09-12
+
+### Fixed
+
+- A torn-install recovery no longer gives up after 90 seconds while another hq
+  updater is still legitimately installing hq-cli. When a command starts just as
+  the desktop app (or the box's `hq-cli-update` timer, or another `hq`) is
+  rewriting the install, the recovery waits for that writer to finish — bounded by
+  the shared install lock's own 10-minute staleness window rather than the 90-second
+  settle deadline — and then re-runs once on the healed tree, so the common case
+  (an install that finishes within the window) no longer fails at all. A short
+  second line explains the pause while it waits. If a writer holds the lock past
+  that ceiling, the command still fails once, but with a "let the update finish,
+  then re-run — do not reinstall while it is running" remedy and a distinct
+  `lock-held` outcome, instead of advice to reinstall over a live installer
+  (Sentry HQ-CLI-1Y, HQ-CLI-23). The ceiling is overridable with
+  `HQ_INSTALL_SETTLE_LOCK_TIMEOUT_MS`.
+
 ## [5.109.10] — 2026-09-12
 
 ### Fixed

package/dist/startup-registration.d.ts

@@ -35,6 +35,24 @@ export declare const DEFAULT_INSTALL_SETTLE_TIMEOUT_MS = 90000;
 export declare const INSTALL_TREE_WAIT_NOTICE = "hq: the hq-cli install is being updated underneath this command; waiting for it to finish\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). */
+export declare const INSTALL_SETTLE_LOCK_TIMEOUT_ENV = "HQ_INSTALL_SETTLE_LOCK_TIMEOUT_MS";
+/**
+ * Default ceiling (ms) on the time the settle wait spends under a fresh foreign
+ * lock held by a live cooperating writer — the update-lock contract's own
+ * staleness window. Overridable by {@link INSTALL_SETTLE_LOCK_TIMEOUT_ENV}.
+ */
+export declare const DEFAULT_INSTALL_SETTLE_LOCK_TIMEOUT_MS: number;
+/**
+ * The single dim line emitted once when the wait continues PAST the settle
+ * deadline because a live updater still holds the shared install lock — so a human
+ * knows the pause is a running update, not a hang. Never a remedy, never an exit
+ * code; worded distinctly from {@link INSTALL_TREE_WAIT_NOTICE} so the e2e can
+ * synchronize on it.
+ */
+export declare const INSTALL_TREE_LOCK_WAIT_NOTICE = "hq: another hq updater is still installing hq-cli; waiting for it to finish\u2026";
+/** Resolve the lock ceiling from the environment (0 = do not extend; default on invalid). */
+export declare function resolveSettleLockTimeoutMs(env: NodeJS.ProcessEnv): number;
 /** Minimal view of a `spawnSync` result the seam relies on. */
 export interface RecoverySpawnResult {
     status: number | null;

package/dist/startup-registration.js

@@ -19,7 +19,7 @@
 import { spawnSync } from "node:child_process";
 import { resolveRunningInstall } from "./utils/version-gate.js";
 import { stringDerivedPackageRoot } from "./utils/hq-roots.js";
-import { updateLockPath } from "./utils/update-lock.js";
+import { updateLockPath, UPDATE_LOCK_STALE_MS } from "./utils/update-lock.js";
 import { classifyModuleNotFound, InstallTreeTornError, waitForInstallTreeSettled, } from "./utils/install-tree-torn.js";
 /**
  * Set on the re-exec'd child so it can NEVER wait or re-exec again — distinct
@@ -46,6 +46,31 @@ export function resolveSettleTimeoutMs(env) {
         return DEFAULT_INSTALL_SETTLE_TIMEOUT_MS;
     return Number.parseInt(raw.trim(), 10);
 }
+/** Operator override for the settle wait's LOCK ceiling (time under a live writer). */
+export const INSTALL_SETTLE_LOCK_TIMEOUT_ENV = "HQ_INSTALL_SETTLE_LOCK_TIMEOUT_MS";
+/**
+ * Default ceiling (ms) on the time the settle wait spends under a fresh foreign
+ * lock held by a live cooperating writer — the update-lock contract's own
+ * staleness window. Overridable by {@link INSTALL_SETTLE_LOCK_TIMEOUT_ENV}.
+ */
+export const DEFAULT_INSTALL_SETTLE_LOCK_TIMEOUT_MS = UPDATE_LOCK_STALE_MS;
+/**
+ * The single dim line emitted once when the wait continues PAST the settle
+ * deadline because a live updater still holds the shared install lock — so a human
+ * knows the pause is a running update, not a hang. Never a remedy, never an exit
+ * code; worded distinctly from {@link INSTALL_TREE_WAIT_NOTICE} so the e2e can
+ * synchronize on it.
+ */
+export const INSTALL_TREE_LOCK_WAIT_NOTICE = "hq: another hq updater is still installing hq-cli; waiting for it to finish…";
+/** Resolve the lock ceiling from the environment (0 = do not extend; default on invalid). */
+export function resolveSettleLockTimeoutMs(env) {
+    const raw = env[INSTALL_SETTLE_LOCK_TIMEOUT_ENV];
+    if (typeof raw !== "string" || raw.trim() === "")
+        return DEFAULT_INSTALL_SETTLE_LOCK_TIMEOUT_MS;
+    if (!/^\d+$/.test(raw.trim()))
+        return DEFAULT_INSTALL_SETTLE_LOCK_TIMEOUT_MS;
+    return Number.parseInt(raw.trim(), 10);
+}
 /**
  * Register commands, recovering once from a torn-install module-resolution
  * failure. On a clean registration this returns `{}` and touches nothing else.
@@ -90,17 +115,27 @@ export async function registerCommandsWithRecovery(args) {
             packageRoot,
             lockPath,
             deadlineMs: resolveSettleTimeoutMs(env),
+            lockWaitMs: resolveSettleLockTimeoutMs(env),
+            onLockExtended: () => stderr.write(`${INSTALL_TREE_LOCK_WAIT_NOTICE}\n`),
         });
         if (!result.settled) {
             throw new InstallTreeTornError({
                 cause: err,
                 classified,
                 packageRoot,
-                outcome: "unsettled",
+                // A fresh foreign lock still held at the end means a live cooperating
+                // 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",
                 attempt: 1,
                 waitedMs: result.waitedMs,
                 sawLock: result.sawLock,
                 sawRetired: result.sawRetired,
+                lockHeldAtEnd: result.lockHeldAtEnd,
+                lockedMs: result.lockedMs,
+                lockTool: result.lockTool,
             });
         }
         const spawn = deps.spawn ?? spawnSync;

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

@@ -137,6 +137,15 @@ export interface InstallTreeFs {
  * Any filesystem error reads as "not present" rather than throwing.
  */
 export declare function installTargetPresent(target: ModuleErrorTarget, fs?: InstallTreeFs): boolean;
+/**
+ * Default ceiling on the CUMULATIVE time the wait may spend observing a FRESH
+ * foreign lock held by a live pid. Equal to the shared update-lock contract's own
+ * staleness window ({@link UPDATE_LOCK_STALE_MS} — "no healthy npm install -g of
+ * this package runs 10 minutes"), so the wait trusts a live cooperating writer for
+ * exactly as long as the contract legitimises holding the lock, and never longer.
+ * Overridable by the seam (env HQ_INSTALL_SETTLE_LOCK_TIMEOUT_MS).
+ */
+export declare const DEFAULT_INSTALL_SETTLE_LOCK_WAIT_MS: number;
 export interface WaitForInstallTreeSettledArgs {
     target: ModuleErrorTarget;
     /** The running install's package dir (from resolveRunningInstall), or null. */
@@ -150,6 +159,22 @@ export interface WaitForInstallTreeSettledArgs {
     pollMs?: number;
     quietMs?: number;
     deadlineMs: number;
+    /**
+     * Ceiling on the CUMULATIVE time observed under a FRESH foreign lock held by a
+     * live pid. Locked time does NOT consume `deadlineMs` (the budget for the tree
+     * to settle once no cooperating writer is visible); it is bounded separately by
+     * this ceiling so the wait can never hang. Defaults to
+     * {@link DEFAULT_INSTALL_SETTLE_LOCK_WAIT_MS}.
+     */
+    lockWaitMs?: number;
+    /**
+     * Invoked exactly once — at the first poll where the total wait has reached
+     * `deadlineMs` while a fresh foreign lock is still held (the moment the
+     * pre-lock-aware wait would have given up). Lets the seam print a one-line
+     * notice that the pause is a live updater, not a hang. Never invoked when no
+     * lock is seen or the lock clears before the deadline.
+     */
+    onLockExtended?: () => void;
 }
 export interface WaitForInstallTreeSettledResult {
     settled: boolean;
@@ -158,20 +183,46 @@ export interface WaitForInstallTreeSettledResult {
     sawLock: boolean;
     /** An npm retired/staging sibling (`.hq-cli-<rand>`) was observed at least once. */
     sawRetired: boolean;
+    /** A fresh foreign lock was held on the FINAL poll of an unsettled wait. */
+    lockHeldAtEnd: boolean;
+    /** Cumulative wall time observed under a fresh foreign lock held by a live pid. */
+    lockedMs: number;
+    /** The bounded `tool` of the last fresh foreign lock seen, or "" if none. */
+    lockTool: string;
 }
 /**
  * Poll until the install tree has been continuously READY for `quietMs`, or the
- * `deadlineMs` passes. READY means: (i) no FRESH update lock held by another pid,
- * (ii) the missing target is present, and — when `packageRoot` is known —
- * (iii) `<packageRoot>/package.json` parses with `name === CLI_NAME` and
- * (iv) no `.<leaf>-<rand>` retired sibling remains beside it. Every filesystem
- * error makes its condition "not ready" rather than throwing. `deadlineMs === 0`
- * evaluates readiness exactly once (no waiting); otherwise the whole wait is
- * bounded, so the caller can never hang.
+ * wait exhausts its bounds. READY means: (i) no FRESH update lock held by another
+ * pid, (ii) the missing target is present, and — when `packageRoot` is known —
+ * (iii) `<packageRoot>/package.json` parses with `name === CLI_NAME` and (iv) no
+ * `.<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:
+ *   - 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).
+ *   - 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
+ *     that ceiling is reached with the lock still held, the result is unsettled
+ *     with `lockHeldAtEnd` true so the seam can report a distinct `lock-held`
+ *     outcome and remedy rather than telling the user to reinstall over a live
+ *     writer.
+ * Each poll's REAL elapsed interval (now() deltas) is attributed to the locked or
+ * unlocked bucket by whether a fresh foreign lock was held when the interval
+ * 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.
  */
 export declare function waitForInstallTreeSettled(args: WaitForInstallTreeSettledArgs): Promise<WaitForInstallTreeSettledResult>;
 /** The recovery OUTCOME, which — not the dialect — decides capture. */
-export type InstallTreeTornOutcome = "guarded" | "unsettled" | "reexec-failed";
+export type InstallTreeTornOutcome = "guarded" | "unsettled" | "reexec-failed" | "lock-held";
 export type InstallTreeTornDiagnostics = {
     dialect: ModuleErrorDialect;
     code: ModuleNotFoundCode;
@@ -183,6 +234,12 @@ export type InstallTreeTornDiagnostics = {
     waitedMs: number;
     sawLock: boolean;
     sawRetired: 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. */
+    lockedMs: number;
+    /** The bounded `tool` of the last fresh foreign lock seen, or "". */
+    lockTool: string;
     node: string;
 };
 export interface InstallTreeTornInit {
@@ -195,6 +252,12 @@ export interface InstallTreeTornInit {
     waitedMs: number;
     sawLock: boolean;
     sawRetired: boolean;
+    /** 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). */
+    lockedMs?: number;
+    /** The last fresh foreign lock's `tool`, bounded on construction (default ""). */
+    lockTool?: string;
 }
 /**
  * A torn-install failure that stays VISIBLE in Sentry with bounded, hq-derived
@@ -221,10 +284,20 @@ export declare function installTreeTornCaptureContext(err: InstallTreeTornError)
  * appended by {@link installTreeTornStderrLine}.
  */
 export declare const INSTALL_TREE_TORN_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
+ * `npm i -g` here would collide with a live installer mid-rename — the exact race
+ * update-lock.ts exists to prevent — so this remedy tells them to let the running
+ * update finish and NEVER to reinstall over it. Interpolates NOTHING.
+ */
+export declare const INSTALL_TREE_LOCK_HELD_REMEDY: string;
 /**
  * The single actionable stderr line for a captured torn-install failure: the
- * fixed remedy plus the bounded, hq-derived missing specifier — the only
- * interpolated value, never argv.
+ * outcome's fixed remedy plus the bounded, hq-derived missing specifier — the only
+ * interpolated value, never argv. A 'lock-held' outcome selects the "let the
+ * update finish" remedy (never the reinstall advice); every other outcome keeps
+ * {@link INSTALL_TREE_TORN_REMEDY} byte-for-byte.
  */
 export declare function installTreeTornStderrLine(err: InstallTreeTornError): string;
 //# sourceMappingURL=install-tree-torn.d.ts.map

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

@@ -34,11 +34,13 @@ import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { CLI_NAME } from "../cli-version.js";
 import { boundedDiagnosticValue } from "./package-root-diagnostics.js";
-import { isLockStale } from "./update-lock.js";
+import { isLockStale, UPDATE_LOCK_STALE_MS } from "./update-lock.js";
 /** Byte caps for the (hq-derived, path-shaped) diagnostic strings. */
 const SPECIFIER_BYTES = 256;
 const IMPORTER_BYTES = 256;
 const PACKAGE_ROOT_BYTES = 256;
+/** Byte cap for the lock holder's `tool` (the only foreign string this reads). */
+const LOCK_TOOL_BYTES = 64;
 const ESM_PACKAGE_RE = /^Cannot find package '([^']+)' imported from (.+)$/s;
 const CJS_MODULE_RE = /^Cannot find module '([^']+)'/s;
 const ESM_MODULE_IMPORTED_RE = /^Cannot find module '([^']+)' imported from (.+)$/s;
@@ -332,6 +334,15 @@ export function installTargetPresent(target, fs = nodeInstallTreeFs) {
         return false;
     }
 }
+/**
+ * Default ceiling on the CUMULATIVE time the wait may spend observing a FRESH
+ * foreign lock held by a live pid. Equal to the shared update-lock contract's own
+ * staleness window ({@link UPDATE_LOCK_STALE_MS} — "no healthy npm install -g of
+ * this package runs 10 minutes"), so the wait trusts a live cooperating writer for
+ * exactly as long as the contract legitimises holding the lock, and never longer.
+ * Overridable by the seam (env HQ_INSTALL_SETTLE_LOCK_TIMEOUT_MS).
+ */
+export const DEFAULT_INSTALL_SETTLE_LOCK_WAIT_MS = UPDATE_LOCK_STALE_MS;
 /** The scope/leaf split of CLI_NAME, e.g. `@indigoai-us` / `hq-cli`. */
 function cliNameParts() {
     const slash = CLI_NAME.indexOf("/");
@@ -339,26 +350,32 @@ function cliNameParts() {
         return { scope: null, leaf: CLI_NAME };
     return { scope: CLI_NAME.slice(0, slash), leaf: CLI_NAME.slice(slash + 1) };
 }
-/** Whether a FRESH update lock is held by a DIFFERENT live pid (blocks readiness). */
-function freshForeignLockHeld(lockPath, nowMs, isPidAlive, fs) {
+/**
+ * The FRESH update lock held by a DIFFERENT live pid, or null. A non-null result
+ * blocks readiness AND extends the wait under the lock ceiling; the lock file is
+ * only ever READ. Freshness is decided by {@link isLockStale} exactly as before
+ * (parseable, `startedAt` younger than {@link UPDATE_LOCK_STALE_MS}, pid alive),
+ * and our own pid never counts.
+ */
+function freshForeignLock(lockPath, nowMs, isPidAlive, fs) {
     let raw;
     try {
         raw = fs.readFileSync(lockPath, "utf-8");
     }
     catch {
-        return false; // no lock (ENOENT) or unreadable — not a fresh foreign holder
+        return null; // no lock (ENOENT) or unreadable — not a fresh foreign holder
     }
     if (isLockStale(raw, nowMs, isPidAlive))
-        return false;
+        return null;
     try {
         const info = JSON.parse(raw);
         if (info.pid === process.pid)
-            return false; // our own lock never blocks us
+            return null; // our own lock never blocks us
+        return info;
     }
     catch {
-        return false; // isLockStale already treats unparseable as stale, unreachable
+        return null; // isLockStale already treats unparseable as stale, unreachable
     }
-    return true;
 }
 /** Whether an npm retired/staging sibling (`.<leaf>-*`) sits beside packageRoot. */
 function retiredSiblingPresent(packageRoot, fs) {
@@ -375,13 +392,33 @@ function packageRootHealthy(packageRoot, fs) {
 }
 /**
  * Poll until the install tree has been continuously READY for `quietMs`, or the
- * `deadlineMs` passes. READY means: (i) no FRESH update lock held by another pid,
- * (ii) the missing target is present, and — when `packageRoot` is known —
- * (iii) `<packageRoot>/package.json` parses with `name === CLI_NAME` and
- * (iv) no `.<leaf>-<rand>` retired sibling remains beside it. Every filesystem
- * error makes its condition "not ready" rather than throwing. `deadlineMs === 0`
- * evaluates readiness exactly once (no waiting); otherwise the whole wait is
- * bounded, so the caller can never hang.
+ * wait exhausts its bounds. READY means: (i) no FRESH update lock held by another
+ * pid, (ii) the missing target is present, and — when `packageRoot` is known —
+ * (iii) `<packageRoot>/package.json` parses with `name === CLI_NAME` and (iv) no
+ * `.<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:
+ *   - 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).
+ *   - 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
+ *     that ceiling is reached with the lock still held, the result is unsettled
+ *     with `lockHeldAtEnd` true so the seam can report a distinct `lock-held`
+ *     outcome and remedy rather than telling the user to reinstall over a live
+ *     writer.
+ * Each poll's REAL elapsed interval (now() deltas) is attributed to the locked or
+ * unlocked bucket by whether a fresh foreign lock was held when the interval
+ * 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.
  */
 export async function waitForInstallTreeSettled(args) {
     const now = args.now ?? Date.now;
@@ -391,16 +428,32 @@ export async function waitForInstallTreeSettled(args) {
     const pollMs = args.pollMs ?? 250;
     const quietMs = args.quietMs ?? 1500;
     const deadlineMs = args.deadlineMs;
+    const lockWaitMs = args.lockWaitMs ?? DEFAULT_INSTALL_SETTLE_LOCK_WAIT_MS;
     const start = now();
     let readySince = null;
     let sawLock = false;
     let sawRetired = false;
+    let lockedMs = 0;
+    let unlockedMs = 0;
+    let lockTool = "";
+    let prevT = start;
+    let prevForeignLockHeld = false;
+    let lockExtendedFired = false;
     for (;;) {
         const t = now();
-        const foreignLock = freshForeignLockHeld(args.lockPath, t, isPidAlive, fs);
-        if (foreignLock)
+        // Attribute the interval that just elapsed [prevT, t) to the bucket for the
+        // lock state that held when it BEGAN (real now() deltas, never nominal pollMs).
+        if (prevForeignLockHeld)
+            lockedMs += t - prevT;
+        else
+            unlockedMs += t - prevT;
+        const lock = freshForeignLock(args.lockPath, t, isPidAlive, fs);
+        const foreignLockHeld = lock !== null;
+        if (foreignLockHeld) {
             sawLock = true;
-        let ready = !foreignLock && installTargetPresent(args.target, fs);
+            lockTool = boundedDiagnosticValue(lock.tool, LOCK_TOOL_BYTES);
+        }
+        let ready = !foreignLockHeld && installTargetPresent(args.target, fs);
         if (ready && args.packageRoot) {
             try {
                 if (!packageRootHealthy(args.packageRoot, fs))
@@ -430,11 +483,29 @@ export async function waitForInstallTreeSettled(args) {
         }
         const waitedMs = t - start;
         if (ready && (deadlineMs === 0 || t - readySince >= quietMs)) {
-            return { settled: true, waitedMs, sawLock, sawRetired };
+            // Settling requires no foreign lock, so it is never held at the end here.
+            return { settled: true, waitedMs, sawLock, sawRetired, lockHeldAtEnd: false, lockedMs, lockTool };
+        }
+        // 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
+        // ceiling. The lock ceiling is gated on a lock being held RIGHT NOW so that a
+        // ceiling of 0 (HQ_INSTALL_SETTLE_LOCK_TIMEOUT_MS=0, "do not extend under a
+        // lock") disables only the extension and does not collapse the ordinary
+        // deadlineMs settle when no lock exists — `lockedMs` is 0 ≥ 0 on every poll.
+        // `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 };
         }
-        if (waitedMs >= deadlineMs) {
-            return { settled: false, waitedMs, sawLock, sawRetired };
+        // 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
+        // extension once, and only when we are genuinely going to keep waiting.
+        if (!lockExtendedFired && foreignLockHeld && waitedMs >= deadlineMs) {
+            lockExtendedFired = true;
+            args.onLockExtended?.();
         }
+        prevT = t;
+        prevForeignLockHeld = foreignLockHeld;
         await sleep(pollMs);
     }
 }
@@ -464,6 +535,9 @@ export class InstallTreeTornError extends Error {
             waitedMs: init.waitedMs,
             sawLock: init.sawLock,
             sawRetired: init.sawRetired,
+            lockHeldAtEnd: init.lockHeldAtEnd ?? false,
+            lockedMs: init.lockedMs ?? 0,
+            lockTool: boundedDiagnosticValue(init.lockTool ?? "", LOCK_TOOL_BYTES),
             node: process.version,
         };
         Object.setPrototypeOf(this, new.target.prototype);
@@ -486,15 +560,26 @@ export const INSTALL_TREE_TORN_REMEDY = "the hq-cli install was being updated by
     "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`).";
+/**
+ * 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
+ * `npm i -g` here would collide with a live installer mid-rename — the exact race
+ * update-lock.ts exists to prevent — so this remedy tells them to let the running
+ * update finish and NEVER to reinstall over it. Interpolates NOTHING.
+ */
+export const INSTALL_TREE_LOCK_HELD_REMEDY = "another hq updater (the desktop app, the box's hq-cli-update timer, or another " +
+    "hq command) was still installing hq-cli when this command stopped waiting. Let " +
+    "that update finish, then re-run your command; do not reinstall while it is running.";
 /**
  * The single actionable stderr line for a captured torn-install failure: the
- * fixed remedy plus the bounded, hq-derived missing specifier — the only
- * interpolated value, never argv.
+ * outcome's fixed remedy plus the bounded, hq-derived missing specifier — the only
+ * interpolated value, never argv. A 'lock-held' outcome selects the "let the
+ * update finish" remedy (never the reinstall advice); every other outcome keeps
+ * {@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 specifier = err.diagnostics.specifier;
-    return specifier
-        ? `${INSTALL_TREE_TORN_REMEDY} (missing: ${specifier})`
-        : INSTALL_TREE_TORN_REMEDY;
+    return specifier ? `${remedy} (missing: ${specifier})` : remedy;
 }
 //# sourceMappingURL=install-tree-torn.js.map

package/dist/utils/sentry-fingerprint.js

@@ -92,8 +92,8 @@ const KNOWN_ERROR_NAMES = new Set([
     // (HQ-CLI-1A).
     "QmdWorkdirMissingError",
     // A torn-install failure the bounded settle-wait + single re-exec could not
-    // recover (HQ-CLI-1G/1H/1J/1K). Fingerprinted on its own branch below by the
-    // bounded `diagnostics.outcome`, so the whole family groups into ≤3 issues.
+    // 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.
     "InstallTreeTornError",
 ]);
 /**
@@ -102,7 +102,7 @@ const KNOWN_ERROR_NAMES = new Set([
  * the carrier's message is fixed, so this outcome IS the only discriminator.
  */
 const KNOWN_INSTALL_TREE_OUTCOMES = new Set([
-    "guarded", "unsettled", "reexec-failed",
+    "guarded", "unsettled", "reexec-failed", "lock-held",
 ]);
 /** Fixed bucket for any error name outside the closed allowlist. */
 const FALLBACK_ERROR_NAME = "other";
@@ -214,8 +214,8 @@ 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
-    // BEFORE the rpc/status branches so the family groups into ≤3 predictable
-    // issues (guarded / unsettled / reexec-failed) rather than one fungible bucket.
+    // BEFORE the rpc/status branches so the family groups into ≤4 predictable issues
+    // (guarded / unsettled / reexec-failed / lock-held) rather than one fungible bucket.
     if (rawName === "InstallTreeTornError") {
         const diagnostics = record.diagnostics;
         const outcome = diagnostics !== null && typeof diagnostics === "object"

package/package.json

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