@indigoai-us/hq-cli 5.109.10 → 5.109.12

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

@@ -34,11 +34,15 @@ 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;
+/** The eval-throw error name is a short closed-set token; the cap is only a belt. */
+const ERRORNAME_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;
@@ -52,6 +56,96 @@ const ESM_MODULE_IMPORTED_RE = /^Cannot find module '([^']+)' imported from (.+)
  * the settle wait. `load\b` also excludes the sibling `esm/loader` module.
  */
 const ESM_LOADER_FRAME = /node:internal[\\/]modules[\\/]esm[\\/]load\b/;
+/**
+ * The Node module RESOLVER frame — `finalizeResolution` in
+ * `node:internal/modules/esm/resolve` (the observed HQ-CLI-1S route, where
+ * realpathSync lstat's a component that vanished after the earlier stat), or the
+ * CJS `Module._findPath → toRealPath` route in `node:internal/modules/cjs/loader`
+ * (the same stat-then-lstat TOCTOU, accepted for symmetry). Requiring a resolver
+ * frame — alongside `syscall === 'lstat'` — is what proves the ENOENT came from
+ * the resolver's realpath step, so an ordinary `fs.lstatSync` ENOENT written by
+ * hq's own code (no resolver frame) is NOT misclassified as a torn install.
+ */
+const RESOLVER_FRAME = /node:internal[\\/]modules[\\/](?:esm[\\/]resolve|cjs[\\/]loader)\b/;
+/** The closed set of error `name`s the eval-throw dialect accepts (HQ-CLI-1T). */
+const EVAL_THROW_NAMES = new Set(["TypeError", "ReferenceError", "SyntaxError"]);
+/**
+ * A CJS module-EVALUATION frame — `Module._compile` / `wrapSafe` in
+ * `node:internal/modules/cjs/loader`, where a required module's top-level code
+ * runs (and where a SyntaxError is raised at compile). NOT the resolve frame
+ * `Module._resolveFilename`, so a resolution failure is never read as an eval.
+ */
+const CJS_EVAL_FRAME = /\bat (?:Module\._compile|wrapSafe) \(node:internal[\\/]modules[\\/]cjs[\\/]loader/;
+/** An ESM module-EVALUATION frame — `ModuleJob` run/evaluate in esm/module_job. */
+const ESM_EVAL_FRAME = /node:internal[\\/]modules[\\/]esm[\\/]module_job\b/;
+/** Whether `stack` carries a CJS or ESM module-EVALUATION loader frame. */
+function hasModuleEvalFrame(stack) {
+    return CJS_EVAL_FRAME.test(stack) || ESM_EVAL_FRAME.test(stack);
+}
+/**
+ * A stack LOCATION token — the absolute filesystem path in either an
+ * `at <fn> (<abs>:L:C)` frame or a bare `<abs>:L` header line (the source
+ * location a SyntaxError prepends). Anchored at line-start or an opening paren so
+ * a `node:internal/…` internal frame (never an absolute FS path) is skipped, and
+ * a Windows drive/UNC path is matched by shape so it classifies on any host.
+ */
+const STACK_LOCATION = /(?:^|\()((?:\/|[A-Za-z]:[\\/]|\\\\)[^():\n]*?):\d+(?::\d+)?(?:\)|$)/;
+/**
+ * A `file:` URL location in a stack frame — the form Node uses for an ESM module
+ * EVALUATION frame (`at file:///abs/mod.mjs:2:1`, or the same wrapped in parens).
+ * The whole non-space token is captured; the caller strips the trailing paren and
+ * `:line[:col]` and decodes it with fileURLToPath.
+ */
+function fileUrlFromFrame(line) {
+    const token = line.match(/file:\/\/\/\S+/);
+    if (!token)
+        return null;
+    const url = token[0].replace(/\)+$/, "").replace(/:\d+(?::\d+)?$/, "");
+    try {
+        return fileURLToPath(url);
+    }
+    catch {
+        return null; // not a decodable file URL
+    }
+}
+/**
+ * The eval-throw THROW SITE — the FIRST absolute filesystem path token in the
+ * stack, scanning top-down: for an ordinary error that is the throwing frame (a
+ * raw path for a CJS module, or a `file:` URL for an ESM one); for a SyntaxError
+ * it is the `<abs>:L` header line the stack carries before the `Error:` line.
+ * Returns null when no absolute path token is present.
+ */
+function evalThrowSite(stack) {
+    for (const rawLine of stack.split("\n")) {
+        const line = rawLine.trim();
+        const plain = STACK_LOCATION.exec(line);
+        if (plain)
+            return plain[1];
+        const fromUrl = fileUrlFromFrame(line);
+        if (fromUrl)
+            return fromUrl;
+    }
+    return null;
+}
+/**
+ * Lexical `<root>/node_modules/` containment for the eval-throw throw-site gate.
+ * Separator- and (Windows-shape-only) case-folded and anchored at a true
+ * directory boundary, so a sibling such as `<root>-old/node_modules/…` never
+ * matches. Mirrors incomplete-install-error.ts's isUnderNodeModules discipline;
+ * kept local because that module imports THIS one (a shared import would cycle).
+ */
+function looksWin32(p) {
+    return /^[a-zA-Z]:[\\/]/.test(p) || /^\\\\/.test(p);
+}
+function foldForCompare(p) {
+    const folded = p.replace(/[\\/]+/g, "/").replace(/\/+$/, "");
+    return looksWin32(p) ? folded.toLowerCase() : folded;
+}
+function isUnderNodeModules(candidate, root) {
+    if (!candidate || !root)
+        return false;
+    return foldForCompare(candidate).startsWith(`${foldForCompare(root)}/node_modules/`);
+}
 /**
  * A relative module specifier — `./x`, `../x`, `.\x`, `..\x`, or a bare `.`/`..`.
  * Mirrors the shape src/utils/incomplete-install-error.ts uses, extended with the
@@ -120,6 +214,28 @@ export function classifyModuleNotFound(err) {
                 target: { kind: "path", path: record.path },
             };
         }
+        // resolve-time ENOENT (HQ-CLI-1S): Node's resolver stat'ed a path OK, then
+        // realpathSync lstat'ed a component that a concurrent reinstall renamed away
+        // between the two, throwing ENOENT with syscall `lstat` from a RESOLVER frame
+        // (finalizeResolution / Module._findPath→toRealPath). Gated on the FULL
+        // conjunction so an ordinary fs.lstatSync ENOENT from hq's own code (no
+        // resolver frame) and a rename/unlink ENOENT (syscall not `lstat`) both stay
+        // null. The vanished component may be a package/scope DIRECTORY whose bare
+        // existence precedes its `package.json`, so the target is `exists` (presence
+        // only); readiness still rides the lock / manifest-health / retired-sibling /
+        // quiet guards. Structurally a loader race like esm-enoent — no writer gate.
+        if (record.syscall === "lstat" &&
+            typeof record.path === "string" &&
+            typeof record.stack === "string" &&
+            RESOLVER_FRAME.test(record.stack)) {
+            return {
+                code,
+                dialect: "resolve-enoent",
+                specifier: record.path,
+                importer: "",
+                target: { kind: "exists", path: record.path },
+            };
+        }
         return null;
     }
     if (code !== "ERR_MODULE_NOT_FOUND" && code !== "MODULE_NOT_FOUND")
@@ -204,6 +320,61 @@ export function classifyModuleNotFound(err) {
     // the lock / retired-dir / quiet signals only.
     return { code, dialect: "unknown", specifier: "", importer: "", target: { kind: "unknown" } };
 }
+/**
+ * Detect a module-EVALUATION throw STRUCTURALLY, WITHOUT the node_modules
+ * boundary gate: an error with NO `code`, a `name` in the closed set
+ * {TypeError, ReferenceError, SyntaxError}, a CJS/ESM module-evaluation loader
+ * frame, and a resolvable throw-site path. This is the shape a half-written
+ * dependency file produces — require() read an empty module and returned `{}`, so
+ * calling one of its exports throws a code-less TypeError while the module's own
+ * top-level code runs. No message text is ever parsed. The caller applies its own
+ * packageRoot gate ({@link classifyEvalThrow} for recovery, the boundary for
+ * capture context), so this stays pure and reusable. Returns null for anything
+ * that is not this shape — a coded error (ERR_REQUIRE_ESM etc.), an Error /
+ * RangeError name, a throw with no loader frame, or no absolute throw site.
+ */
+export function evalThrowShape(err) {
+    if (err === null || typeof err !== "object")
+        return null;
+    const record = err;
+    if (record.code !== undefined)
+        return null;
+    const name = typeof record.name === "string" ? record.name : "";
+    if (!EVAL_THROW_NAMES.has(name))
+        return null;
+    if (typeof record.stack !== "string" || !hasModuleEvalFrame(record.stack))
+        return null;
+    const throwSite = evalThrowSite(record.stack);
+    if (throwSite === null)
+        return null;
+    return { errorName: name, throwSite };
+}
+/**
+ * Classify a module-EVALUATION throw as a torn-install recovery candidate
+ * (HQ-CLI-1T) — the {@link evalThrowShape} fingerprint AND a throw site under
+ * `<packageRoot>/node_modules/`. A throw under the install's own `dist/` or
+ * `assets/`, outside the root, or with an unresolved root is NOT classified, so a
+ * genuine hq-cli code defect keeps its raw capture. Unlike the loader-race
+ * dialects the recovery seam gates this on a live writer signal before waiting.
+ * `packageRoot` comes from the seam's resolvePackageRoot (running-install → derived
+ * fallback). The target is `unknown` — an eval-throw carries no re-resolvable
+ * missing file, so recovery keys entirely on the writer signal + quiet window.
+ */
+export function classifyEvalThrow(err, packageRoot) {
+    const shape = evalThrowShape(err);
+    if (shape === null)
+        return null;
+    if (!packageRoot || !isUnderNodeModules(shape.throwSite, packageRoot))
+        return null;
+    return {
+        code: "EVAL_THROW",
+        dialect: "eval-throw",
+        specifier: shape.throwSite,
+        importer: "",
+        target: { kind: "unknown" },
+        errorName: shape.errorName,
+    };
+}
 const nodeInstallTreeFs = {
     existsSync: (p) => nodeFs.existsSync(p),
     statSync: (p) => nodeFs.statSync(p),
@@ -287,6 +458,8 @@ function relativeTargetResolvable(base, fs) {
  *                or a directory whose package.json `main` (or that main's index)
  *                or own `index.*` is a real file. A bare or partially-extracted
  *                directory is NOT loadable and reads as not-present.
+ *   - `exists`:  the path exists at all (any file type) — presence only, because
+ *                the vanished component may be a package/scope directory.
  *   - `unknown`: true (readiness turns on the other signals).
  * Any filesystem error reads as "not present" rather than throwing.
  */
@@ -294,6 +467,12 @@ export function installTargetPresent(target, fs = nodeInstallTreeFs) {
     try {
         if (target.kind === "unknown")
             return true;
+        // `exists` (resolve-enoent, HQ-CLI-1S): the lstat'ed component may be a
+        // package/scope DIRECTORY whose bare existence precedes its `package.json`, so
+        // presence alone is the signal here — the surrounding manifest-health /
+        // retired-sibling / quiet guards keep a premature re-exec bounded.
+        if (target.kind === "exists")
+            return fs.existsSync(target.path);
         if (target.kind === "path") {
             if (!fs.existsSync(target.path))
                 return false;
@@ -332,6 +511,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 +527,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 +569,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 +605,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,14 +660,83 @@ 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 };
         }
-        if (waitedMs >= deadlineMs) {
-            return { settled: false, waitedMs, sawLock, sawRetired };
+        // 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 };
         }
+        // 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);
     }
 }
+/**
+ * Whether packageRoot's own manifest is ABSENT (ENOENT) or name-mismatched — a
+ * mid-extraction rewrite signal (npm has renamed the dir aside and is re-writing
+ * package.json). A read error OTHER than ENOENT (EACCES/EPERM) is a benign
+ * permission fault, not a rewrite, so it returns false rather than a false signal.
+ */
+function manifestRewriteSignal(packageRoot, fs) {
+    let raw;
+    try {
+        raw = fs.readFileSync(path.join(packageRoot, "package.json"), "utf-8");
+    }
+    catch (err) {
+        return err?.code === "ENOENT";
+    }
+    try {
+        return JSON.parse(raw).name !== CLI_NAME;
+    }
+    catch {
+        return true; // present but unparseable → mid-write
+    }
+}
+/**
+ * Whether a global reinstall is PROVABLY rewriting the install tree right now —
+ * the positive writer signal the eval-throw gate requires before it will pay a
+ * settle wait. True iff (i) a fresh foreign update lock is held, (ii) packageRoot's
+ * manifest is absent or name-mismatched (mid-extraction), or (iii) a
+ * `.<leaf>-<hash>` retired sibling sits beside it. Crucially it is POSITIVE: a
+ * benign filesystem error that merely prevents READING the manifest or LISTING the
+ * parent (EACCES/EPERM) is NOT a signal, so a persistent third-party load-time
+ * defect on an otherwise-usable install never pays a spurious 90s wait. Every
+ * dependency is injectable so the recovery seam stays hermetic.
+ */
+export function installRewriteInProgress(args) {
+    const now = (args.now ?? Date.now)();
+    const fs = args.fs ?? nodeInstallTreeFs;
+    const isPidAlive = args.isPidAlive ?? defaultIsPidAlive;
+    // #570 renamed freshForeignLockHeld → freshForeignLock, which returns the lock
+    // info (or null) instead of a boolean; a fresh foreign lock is held iff non-null.
+    if (freshForeignLock(args.lockPath, now, isPidAlive, fs) !== null)
+        return true;
+    if (!args.packageRoot)
+        return false;
+    if (manifestRewriteSignal(args.packageRoot, fs))
+        return true;
+    try {
+        return retiredSiblingPresent(args.packageRoot, fs);
+    }
+    catch {
+        return false; // parent not listable — benign, not a rewrite signal
+    }
+}
 /** 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";
 /**
@@ -464,7 +763,11 @@ 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,
+            errorName: boundedDiagnosticValue(init.classified.errorName ?? "", ERRORNAME_BYTES),
         };
         Object.setPrototypeOf(this, new.target.prototype);
     }
@@ -486,15 +789,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.12",
   "description": "HQ by Indigo management CLI \u2014 modules and cloud sync",
   "main": "dist/index.js",
   "bin": {