@indigoai-us/hq-cli 5.314.0 → 5.315.0

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

@@ -30,18 +30,193 @@
  * 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";
 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;
+/**
+ * The Node ESM loader's SOURCE-READ helper in `node:internal/modules/esm/load`
+ * (Node 22) or `node:internal/modules/esm/loader` (Node 24's sync loader).
+ * `getSourceSync` must be the first non-`node:fs` caller after the source read;
+ * an ordinary fs ENOENT that escapes module evaluation therefore stays outside
+ * recovery even when an outer ModuleLoader frame exists.
+ */
+const ESM_SOURCE_READ_FRAME = /^at getSourceSync \(node:internal[\\/]modules[\\/]esm[\\/](?:load|loader)\b/;
+const NODE_FS_FRAME = /^at .* \(node:fs\b/;
+/** True only when Node's ESM source-read helper called the failing fs read. */
+function hasEsmLoaderSourceReadFrame(stack) {
+    const frames = stack
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.startsWith("at "));
+    let sawFsRead = false;
+    for (const frame of frames) {
+        if (!sawFsRead) {
+            if (NODE_FS_READ_FRAME.test(frame))
+                sawFsRead = true;
+            continue;
+        }
+        if (NODE_FS_FRAME.test(frame))
+            continue;
+        return ESM_SOURCE_READ_FRAME.test(frame);
+    }
+    return false;
+}
+/**
+ * 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);
+}
+/**
+ * The Node CJS loader's SOURCE-READ position (HQ-CLI-20) — the CJS twin of
+ * {@link hasEsmLoaderSourceReadFrame}. A CJS require whose target was present at RESOLVE (its
+ * filename cached in Module._pathCache) and gone at READ fails inside the loader's
+ * source read: `readFileSync (node:fs)` called by `defaultLoadImpl`/`loadSource`
+ * (Node ≥22) or, on older Node, the `Module._extensions..js` extension handler —
+ * all frames in `node:internal/modules/cjs/loader`, and (unlike HQ-CLI-1M) with NO
+ * ESM source-read frame.
+ *
+ * The discriminator is POSITIONAL: the innermost `node:fs` read frame's
+ * IMMEDIATELY-following (caller) frame must be a cjs/loader frame that is NOT a
+ * module-EVALUATION frame (Module._compile / wrapSafe). That is what proves the
+ * LOADER was reading the module's source. An ordinary `fs.readFileSync`/`openSync`
+ * ENOENT that merely ESCAPES a third-party module's own EVALUATION has the
+ * third-party FILE directly beneath `node:fs`, not a cjs/loader frame, so it stays
+ * captured (both shapes reproduced frame-for-frame on Node v22.23.1). The
+ * positional rule is the PRIMARY discriminator; the source-read helper NAMES are
+ * an accepted closed set, not the sole requirement, so a renamed helper still
+ * classifies.
+ *
+ * The whole-stack presence of Module._compile is deliberately NOT a rejection
+ * signal: under a raised Error.stackTraceLimit the torn shape ALSO carries the
+ * requiring module's own Module._compile frame — always at depth 11, past the
+ * default limit of 10 — so only the frame immediately beneath the node:fs read is
+ * consulted. Exported so incomplete-install-error.ts (which already imports from
+ * this module) shares the exact gate rather than duplicating the positional logic,
+ * mirroring how {@link evalThrowShape} and {@link packageNameOf} are shared.
+ */
+const NODE_FS_READ_FRAME = /^at (?:[\w$.]+\.)?(?:readFileSync|openSync) \(node:fs\b/;
+const CJS_LOADER_FRAME = /node:internal[\\/]modules[\\/]cjs[\\/]loader\b/;
+export function hasCjsLoaderSourceReadFrame(stack) {
+    const frames = stack
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.startsWith("at "));
+    for (let i = 0; i < frames.length; i++) {
+        if (!NODE_FS_READ_FRAME.test(frames[i]))
+            continue;
+        const caller = frames[i + 1];
+        if (caller === undefined)
+            return false;
+        return CJS_LOADER_FRAME.test(caller) && !CJS_EVAL_FRAME.test(caller);
+    }
+    return false;
+}
+/**
+ * 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
+ * bare-`.`/`..` case so a token that packageNameOf would reduce to the
+ * un-probeable name `.` is caught here and re-resolved instead.
+ */
+const RELATIVE_CJS_SPECIFIER = /^\.\.?([\\/]|$)/;
 /**
  * Reduce a bare specifier to its PACKAGE name: `@scope/name/sub` → `@scope/name`,
  * `name/sub` → `name`, `name` → `name`. This is the unit the readiness probe
@@ -54,19 +229,104 @@ export function packageNameOf(specifier) {
         return parts.slice(0, 2).join("/");
     return parts[0] ?? specifier;
 }
+/**
+ * Build a `package` target from an already-reduced name, UNLESS that name is not
+ * a plausible bare package: empty, a relative token reduced to `.`/`..`, or a
+ * subpath-imports token (`#internal`). Each of those reduces to a name whose
+ * `node_modules/<name>/package.json` ancestor probe can NEVER be true, so it
+ * falls back to `unknown` — readiness then turns on the lock / retired-dir /
+ * quiet signals rather than a probe that stays permanently false.
+ */
+function barePackageTarget(name, from) {
+    if (name.length === 0 || name.startsWith(".") || name.startsWith("#")) {
+        return { kind: "unknown" };
+    }
+    return { kind: "package", name, from };
+}
 /**
  * Classify a thrown value as a module-resolution failure and extract the missing
  * target, or return `null` for anything that is not one. The decision is
- * STRUCTURAL: `err.code` must be exactly `ERR_MODULE_NOT_FOUND` or
- * `MODULE_NOT_FOUND` — no argv, env, or free text is ever consulted, and any
- * other error (including an import-time throw of another class) returns `null`
- * so it is rethrown to the existing boundary unchanged.
+ * STRUCTURAL: `err.code` must be exactly `ERR_MODULE_NOT_FOUND`,
+ * `MODULE_NOT_FOUND`, or — for the esm-loader ENOENT dialect — `ENOENT` under
+ * the full conjunction below. No argv, env, or free text is ever consulted, and
+ * any other error (including an import-time throw of another class) returns
+ * `null` so it is rethrown to the existing boundary unchanged.
  */
 export function classifyModuleNotFound(err) {
     if (err === null || typeof err !== "object")
         return null;
     const record = err;
     const code = record.code;
+    // (0) esm-loader ENOENT (HQ-CLI-1M): a module present at RESOLVE and gone at
+    // READ, so Node's ESM loader raises ENOENT from getSourceSync/openSync rather
+    // than ERR_MODULE_NOT_FOUND at resolve. Gated on the FULL conjunction — code
+    // ENOENT AND syscall 'open' AND an esm-loader stack frame AND a string path —
+    // so an ordinary fs.readFileSync/openSync ENOENT written by hq's own code (no
+    // loader frame) cannot enter it. The vanished file IS the re-resolvable target
+    // the settle wait polls; recovery then waits and re-execs exactly as for the
+    // other dialects.
+    if (code === "ENOENT") {
+        if (record.syscall === "open" &&
+            typeof record.path === "string" &&
+            typeof record.stack === "string" &&
+            hasEsmLoaderSourceReadFrame(record.stack)) {
+            return {
+                code,
+                dialect: "esm-enoent",
+                specifier: record.path,
+                importer: "",
+                target: { kind: "path", path: record.path },
+            };
+        }
+        // cjs-loader source-read ENOENT (HQ-CLI-20): the CJS twin of esm-enoent — a
+        // require() whose target was present at RESOLVE (its filename held in
+        // Module._pathCache) and gone at READ, so the CJS loader's source read raises
+        // ENOENT with syscall 'open' and a cjs/loader frame but NO ESM source-read frame
+        // (which is why arm (0) missed it and classifyModuleNotFound returned null,
+        // filing the bare HQ-CLI-20 capture). Gated on the FULL conjunction — code
+        // ENOENT AND syscall 'open' AND a string path AND the POSITIONAL CJS
+        // source-read gate — so a third-party module's own top-level fs.readFileSync
+        // ENOENT (module EVALUATION, its own frame directly beneath node:fs) stays null
+        // and keeps its capture. Ordered AFTER the esm-enoent arm so HQ-CLI-1M keeps
+        // its byte-for-byte classification. Target 'path': the vanished file is a
+        // regular .js/.json file Node's CJS LOAD_AS_FILE step re-resolves, so the probe
+        // and settle wait reuse the same machinery as esm-enoent, unchanged.
+        if (record.syscall === "open" &&
+            typeof record.path === "string" &&
+            typeof record.stack === "string" &&
+            hasCjsLoaderSourceReadFrame(record.stack)) {
+            return {
+                code,
+                dialect: "cjs-enoent",
+                specifier: record.path,
+                importer: "",
+                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")
         return null;
     const message = typeof record.message === "string" ? record.message : "";
@@ -94,7 +354,7 @@ export function classifyModuleNotFound(err) {
             dialect: "esm-package",
             specifier: spec,
             importer,
-            target: { kind: "package", name: spec, from: path.dirname(importer) },
+            target: barePackageTarget(spec, path.dirname(importer)),
         };
     }
     // (c) CJS `Cannot find module '<spec>'` (+ Require stack). Absolute → a path
@@ -108,12 +368,32 @@ export function classifyModuleNotFound(err) {
             if (path.isAbsolute(spec)) {
                 return { code, dialect: "cjs-path", specifier: spec, importer, target: { kind: "path", path: spec } };
             }
+            // Relative specifier (`./x`, `../x`): Node reports the RAW token, so
+            // packageNameOf would reduce it to `.`/`..` and build a package target
+            // whose ancestor probe can never be true. Re-resolve it from the importer's
+            // directory, and report the RESOLVED path as the diagnostic specifier
+            // (actionable — the missing sibling's real location), mirroring esm-path.
+            if (RELATIVE_CJS_SPECIFIER.test(spec)) {
+                if (importer && path.isAbsolute(importer)) {
+                    const from = path.dirname(importer);
+                    return {
+                        code,
+                        dialect: "cjs-relative",
+                        specifier: path.resolve(from, spec),
+                        importer,
+                        target: { kind: "relative", specifier: spec, from },
+                    };
+                }
+                // No usable (absolute) importer survived — fall back to the lock /
+                // retired-dir / quiet signals rather than a probe that cannot be true.
+                return { code, dialect: "cjs-relative", specifier: spec, importer, target: { kind: "unknown" } };
+            }
             return {
                 code,
                 dialect: "cjs-package",
                 specifier: spec,
                 importer,
-                target: { kind: "package", name: packageNameOf(spec), from: path.dirname(importer) },
+                target: barePackageTarget(packageNameOf(spec), path.dirname(importer)),
             };
         }
     }
@@ -129,9 +409,65 @@ 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),
+    lstatSync: (p) => nodeFs.lstatSync(p),
     readFileSync: (p, encoding) => nodeFs.readFileSync(p, encoding),
     readdirSync: (p) => nodeFs.readdirSync(p),
 };
@@ -145,6 +481,58 @@ function defaultIsPidAlive(pid) {
         return err.code === "EPERM";
     }
 }
+/** CJS extensions Node's LOAD_AS_FILE / LOAD_INDEX try, in order. */
+const CJS_FILE_EXTENSIONS = [".js", ".json", ".node"];
+/** Whether `p` exists AND is a regular file (not a directory); any fs error → false. */
+function isResolvableFile(p, fs) {
+    try {
+        return fs.existsSync(p) && !fs.statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** Node's LOAD_AS_FILE(X): X itself, then X + each CJS extension — each must be a file. */
+function loadAsFile(base, fs) {
+    if (isResolvableFile(base, fs))
+        return true;
+    return CJS_FILE_EXTENSIONS.some((ext) => isResolvableFile(base + ext, fs));
+}
+/** Node's LOAD_INDEX(X): X/index.{js,json,node} — each must be a file. */
+function loadIndex(dir, fs) {
+    return CJS_FILE_EXTENSIONS.some((ext) => isResolvableFile(path.join(dir, `index${ext}`), fs));
+}
+/**
+ * Whether a relative target's resolved `base` is loadable exactly as Node's CJS
+ * require would load it: LOAD_AS_FILE(base), else LOAD_AS_DIRECTORY(base) — its
+ * package.json `main` resolved as a file (or that main's index), else
+ * base/index.*. A bare or partially-extracted directory — one that holds neither
+ * a resolvable `main` nor an index file — is deliberately NOT loadable, so it
+ * reads as not-present and the single re-exec cannot fire on a still-torn tree
+ * (mirrors the MODULE_NOT_FOUND Node would still throw for that state).
+ */
+function relativeTargetResolvable(base, fs) {
+    if (loadAsFile(base, fs))
+        return true;
+    const manifest = path.join(base, "package.json");
+    if (isResolvableFile(manifest, fs)) {
+        let main = null;
+        try {
+            const parsed = JSON.parse(fs.readFileSync(manifest, "utf-8"));
+            if (typeof parsed.main === "string" && parsed.main.trim() !== "")
+                main = parsed.main;
+        }
+        catch {
+            main = null; // unreadable / unparseable manifest — fall back to index.*
+        }
+        if (main !== null) {
+            const mainBase = path.resolve(base, main);
+            if (loadAsFile(mainBase, fs) || loadIndex(mainBase, fs))
+                return true;
+        }
+    }
+    return loadIndex(base, fs);
+}
 /**
  * Whether the missing target is now present on disk — the readiness signal the
  * settle wait polls. It re-resolves the SAME step Node's resolver took:
@@ -155,6 +543,13 @@ function defaultIsPidAlive(pid) {
  *                exact ancestor walk `getPackageJSONURL` performs, done WITHOUT
  *                `createRequire` so an ESM-only / export-conditioned package
  *                cannot false-negative.
+ *   - `relative`: re-resolve `path.resolve(from, specifier)` as Node's CJS
+ *                require would — a real file (exact / `.js` / `.json` / `.node`),
+ *                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.
  */
@@ -162,6 +557,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;
@@ -175,6 +576,15 @@ export function installTargetPresent(target, fs = nodeInstallTreeFs) {
             }
             return true;
         }
+        if (target.kind === "relative") {
+            // Re-resolve exactly as Node's CJS require would from `from`, so the probe
+            // turns true only when the missing module is ACTUALLY loadable again — a
+            // bare or partially-extracted directory must not read as present, or the
+            // single re-exec would fire on a still-torn tree. The extensionless case
+            // matters — a production sibling shape (`./Base/TreeIterator`, HQ-CLI-1N)
+            // carries no extension, so an exact-path-only probe would stay false for it.
+            return relativeTargetResolvable(path.resolve(target.from, target.specifier), fs);
+        }
         // package: ancestor walk from `from`.
         let dir = path.resolve(target.from);
         for (;;) {
@@ -191,6 +601,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).
+ */
+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("/");
@@ -198,26 +617,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) {
@@ -227,20 +652,302 @@ function retiredSiblingPresent(packageRoot, fs) {
     const entries = fs.readdirSync(parent); // caller treats a throw as "not ready"
     return entries.some((entry) => entry.startsWith(stagingPrefix));
 }
+/** Reduce an observed sibling basename to a closed kind without retaining it. */
+function retiredSiblingKind(packageRoot, fs) {
+    if (!packageRoot)
+        return "unknown";
+    try {
+        const { leaf } = cliNameParts();
+        const prefix = "." + leaf + "-";
+        const siblings = fs
+            .readdirSync(path.dirname(packageRoot))
+            .filter((entry) => entry.startsWith(prefix))
+            .sort();
+        if (siblings.length === 0)
+            return "unknown";
+        const name = siblings[0];
+        if (/^\.hq-cli-staging-[A-Za-z0-9-]+$/.test(name))
+            return "hq_staging";
+        if (/^\.hq-cli-backup-[A-Za-z0-9-]+$/.test(name))
+            return "hq_backup";
+        if (/^\.hq-cli-[A-Za-z0-9]{8}$/.test(name))
+            return "npm_hash_retired";
+        return "other";
+    }
+    catch {
+        return "unknown";
+    }
+}
+/** Classify current target/manifest state without retaining paths or file contents. */
+function installTargetState(target, packageRoot, fs) {
+    if (target.kind === "unknown")
+        return "unknown";
+    if (!installTargetPresent(target, fs))
+        return "missing";
+    if (!packageRoot)
+        return "unknown";
+    try {
+        const raw = fs.readFileSync(path.join(packageRoot, "package.json"), "utf-8");
+        let manifest;
+        try {
+            manifest = JSON.parse(raw);
+        }
+        catch {
+            return "manifest_invalid";
+        }
+        return manifest.name === CLI_NAME ? "manifest_valid" : "manifest_invalid";
+    }
+    catch (error) {
+        return error?.code === "ENOENT" ? "missing" : "unreadable";
+    }
+}
+/** Read only the lock's recorded owner PID; never retain or report the PID. */
+function updaterPidAlive(lockPath, fs, isPidAlive) {
+    try {
+        const lock = JSON.parse(fs.readFileSync(lockPath, "utf-8"));
+        if (typeof lock.pid !== "number" || !Number.isSafeInteger(lock.pid) || lock.pid <= 0) {
+            return "unknown";
+        }
+        return isPidAlive(lock.pid) ? "true" : "false";
+    }
+    catch {
+        return "unknown";
+    }
+}
+/** Snapshot retired sibling trees so changes below their root stay observable. */
+function retiredSiblingActivitySignature(packageRoot, fs) {
+    const { leaf } = cliNameParts();
+    const stagingPrefix = `.${leaf}-`;
+    const parent = path.dirname(packageRoot);
+    const siblings = fs.readdirSync(parent).filter((entry) => entry.startsWith(stagingPrefix)).sort();
+    const snapshots = [["names", siblings]];
+    let observed = true;
+    let visited = 0;
+    const maxEntries = 20_000;
+    const maxDepth = 64;
+    const visit = (absolutePath, relativePath, depth) => {
+        visited += 1;
+        if (visited > maxEntries) {
+            observed = false;
+            return;
+        }
+        try {
+            const stat = fs.lstatSync ? fs.lstatSync(absolutePath) : fs.statSync(absolutePath);
+            const symbolicLink = stat.isSymbolicLink?.() ?? false;
+            const directory = !symbolicLink && stat.isDirectory();
+            const mtimeMs = stat.mtimeMs;
+            if (typeof mtimeMs !== "number" || !Number.isFinite(mtimeMs))
+                observed = false;
+            snapshots.push([
+                relativePath,
+                symbolicLink ? "symlink" : directory ? "directory" : "file",
+                stat.size ?? null,
+                typeof mtimeMs === "number" && Number.isFinite(mtimeMs) ? mtimeMs : null,
+            ]);
+            if (!directory)
+                return;
+            if (depth >= maxDepth) {
+                observed = false;
+                return;
+            }
+            for (const child of fs.readdirSync(absolutePath).sort()) {
+                visit(path.join(absolutePath, child), path.join(relativePath, child), depth + 1);
+            }
+        }
+        catch {
+            observed = false;
+            snapshots.push([relativePath, "unreadable"]);
+        }
+    };
+    for (const sibling of siblings) {
+        visit(path.join(parent, sibling), sibling, 0);
+    }
+    return { value: JSON.stringify(snapshots), observed, present: siblings.length > 0 };
+}
 /** Whether packageRoot's own manifest is healthy (`name === CLI_NAME`). */
 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;
+    let nonRetiredObserved = true;
+    let retiredSiblingPresent = null;
+    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;
+            nonRetiredObserved = 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;
+            nonRetiredObserved = false;
+            snapshots.push([directory, `entries-unreadable:${errorCode(err)}`]);
+        }
+    }
+    if (packageRoot) {
+        try {
+            const retired = retiredSiblingActivitySignature(packageRoot, fs);
+            snapshots.push(["retired-siblings", retired.value]);
+            retiredSiblingPresent = retired.present;
+            if (!retired.observed)
+                observed = false;
+        }
+        catch (err) {
+            observed = false;
+            snapshots.push(["retired-siblings-unreadable", errorCode(err)]);
+        }
+    }
+    return { value: JSON.stringify(snapshots), observed, nonRetiredObserved, retiredSiblingPresent };
+}
+function canProbeUnsettledRetiredSibling(snapshot) {
+    // A very large or unreadable retired npm tree can exceed the bounded recursive
+    // activity scan. Its stable partial signature is still useful when the live
+    // install paths are observable and npm's named retired sibling is present.
+    // This only selects the existing stale-tree repair outcome; it never removes
+    // files, and any observed signature change still suppresses stale classification.
+    return snapshot.observed ||
+        (snapshot.nonRetiredObserved && snapshot.retiredSiblingPresent === true);
+}
+const DEFAULT_INSTALL_TREE_STALE_PROBE_MS = 1_500;
 /**
  * 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, 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`. If the target is still missing and the observable tree
+ *     signature stays unchanged for `staleProbeMs`, the wait returns `staleTree`
+ *     early. When only a named retired npm sibling's deep scan is incomplete,
+ *     a stable partial signature ends the wait early as `retiredSiblingUnverified`
+ *     instead. That outcome preserves uncertainty and tells the user to wait for
+ *     any installer before attempting a repair. Any observed signature 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
+ *     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`), 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;
@@ -250,16 +957,65 @@ 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 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 = canProbeUnsettledRetiredSibling(lastActivitySnapshot) ? start : null;
+    let sawTreeChange = false;
     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);
+        }
+        if (!sawTreeChange) {
+            const activitySnapshot = installTreeActivitySignature(args.target, args.packageRoot, fs);
+            const previousCanProbe = canProbeUnsettledRetiredSibling(lastActivitySnapshot);
+            const currentCanProbe = canProbeUnsettledRetiredSibling(activitySnapshot);
+            if (previousCanProbe && currentCanProbe && activitySnapshot.value !== lastActivitySnapshot.value) {
+                sawTreeChange = true;
+                staleObservationStartedAt = null;
+            }
+            else if (!currentCanProbe) {
+                staleObservationStartedAt = null;
+            }
+            else if (!previousCanProbe) {
+                staleObservationStartedAt = t;
+            }
+            lastActivitySnapshot = activitySnapshot;
+        }
+        let retiredPresent = null;
+        let retiredCheckFailed = false;
+        if (args.packageRoot) {
+            try {
+                retiredPresent = retiredSiblingPresent(args.packageRoot, fs);
+                if (retiredPresent)
+                    sawRetired = true;
+            }
+            catch {
+                retiredPresent = null;
+                retiredCheckFailed = true;
+            }
+        }
+        let ready = !foreignLockHeld && installTargetPresent(args.target, fs);
         if (ready && args.packageRoot) {
             try {
                 if (!packageRootHealthy(args.packageRoot, fs))
@@ -268,17 +1024,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)
@@ -289,16 +1036,137 @@ 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,
+                sawTreeChange,
+                staleTree: false,
+                retiredSiblingPresent: retiredPresent,
+                retiredSiblingKind: retiredSiblingKind(args.packageRoot, fs),
+                installTargetState: installTargetState(args.target, args.packageRoot, fs),
+                updaterPidAlive: updaterPidAlive(args.lockPath, fs, isPidAlive),
+            };
+        }
+        if (!ready &&
+            !foreignLockHeld &&
+            !retiredCheckFailed &&
+            !sawLock &&
+            !sawTreeChange &&
+            staleObservationStartedAt !== null &&
+            t - staleObservationStartedAt >= staleProbeMs) {
+            return {
+                settled: false,
+                waitedMs,
+                sawLock,
+                sawRetired,
+                lockHeldAtEnd: false,
+                lockedMs,
+                lockTool,
+                sawTreeChange,
+                staleTree: lastActivitySnapshot.observed,
+                retiredSiblingPresent: retiredPresent,
+                retiredSiblingUnverified: !lastActivitySnapshot.observed && lastActivitySnapshot.retiredSiblingPresent === true,
+                retiredSiblingKind: retiredSiblingKind(args.packageRoot, fs),
+                installTargetState: installTargetState(args.target, args.packageRoot, fs),
+                updaterPidAlive: updaterPidAlive(args.lockPath, fs, isPidAlive),
+            };
+        }
+        // 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,
+                sawTreeChange,
+                staleTree: false,
+                retiredSiblingPresent: retiredPresent,
+                retiredSiblingKind: retiredSiblingKind(args.packageRoot, fs),
+                installTargetState: installTargetState(args.target, args.packageRoot, fs),
+                updaterPidAlive: updaterPidAlive(args.lockPath, fs, isPidAlive),
+            };
         }
-        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);
     }
 }
+/**
+ * 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";
+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),
@@ -312,19 +1180,35 @@ export class InstallTreeTornError extends Error {
         super(INSTALL_TREE_TORN_MESSAGE);
         this.name = "InstallTreeTornError";
         this.cause = init.cause;
-        this.diagnostics = {
+        const sawTreeChange = init.sawTreeChange ?? false;
+        const treeState = init.treeState ?? (init.outcome === "stale_tree" ? "stale" : "in_flight");
+        const diagnostics = {
             dialect: init.classified.dialect,
             code: init.classified.code,
             specifier: boundedDiagnosticValue(init.classified.specifier, SPECIFIER_BYTES),
             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),
             node: process.version,
+            errorName: boundedDiagnosticValue(init.classified.errorName ?? "", ERRORNAME_BYTES),
+            retiredSiblingKind: init.retiredSiblingKind ?? "unknown",
+            installTargetState: init.installTargetState ?? "unknown",
+            versionGatePhase: init.versionGatePhase ?? "unknown",
+            updaterPidAlive: init.updaterPidAlive ?? "unknown",
         };
+        if (typeof init.retiredSiblingPresent === "boolean") {
+            diagnostics.retiredSiblingPresent = init.retiredSiblingPresent;
+        }
+        this.diagnostics = diagnostics;
         Object.setPrototypeOf(this, new.target.prototype);
     }
 }
@@ -332,8 +1216,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
@@ -341,19 +1262,45 @@ 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.";
+/** Guidance when a retired package sibling's activity could not be verified. */
+export const INSTALL_TREE_RETIRED_UNVERIFIED_REMEDY = "hq-cli found a retired install sibling but could not verify whether an installer is still using it. Wait for any npm or desktop CLI update to finish, then run the command again. If no install is running, repair 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).";
+/**
+ * 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
+        : err.diagnostics.outcome === "stale_tree"
+            ? INSTALL_TREE_STALE_REMEDY
+            : err.diagnostics.outcome === "retired_unverified"
+                ? INSTALL_TREE_RETIRED_UNVERIFIED_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