@indigoai-us/hq-cli 5.109.11 → 5.109.13

package/CHANGELOG.md

@@ -2,6 +2,48 @@
 
 ## [Unreleased]
 
+## [5.109.13] — 2026-09-13
+
+### Fixed
+
+- A background reinstall no longer turns into a crash report in the CommonJS twin
+  of the shape 5.109.12 fixed for ES modules (HQ-CLI-20). When another program
+  reinstalls hq globally while a command is starting, it rewrites hq's files one
+  by one over a few seconds. If a bundled CommonJS dependency (here `ajv`, reached
+  while `hq core timeout-guard` registers its commands) had just resolved one of
+  its own files and that file vanished before Node read it, the low-level `ENOENT …
+  open` came from inside Node's CommonJS module loader — a shape the recovery only
+  recognized for ES modules, so it was still filed as a crash. It is now recognized
+  as "your install was mid-update, not an hq bug": the command waits for the
+  reinstall to settle and re-runs once on the healed tree, and the same noise is
+  dropped on the routes that bypass the top-level handler. The gate is deliberately
+  narrow — it fires only when Node's own loader was reading a module's source (the
+  frame directly beneath the file read is a `cjs/loader` frame, never the
+  dependency's own code) — so a third-party package whose own startup code reads a
+  missing file, or a fault in hq's own shipped files, still reports exactly once
+  (Sentry HQ-CLI-20).
+
+## [5.109.12] — 2026-09-12
+
+### Fixed
+
+- A background reinstall no longer turns into a crash report in two more shapes
+  it was still slipping through (HQ-CLI-1S, HQ-CLI-1T). When another program
+  reinstalls hq globally while a command is starting, it renames hq's files aside
+  and rewrites them file by file over a few seconds. Two failure shapes from that
+  window were still filed as crashes instead of being recovered: (1) a file that
+  Node checked a moment earlier vanished between its two resolve steps, surfacing
+  as a low-level `ENOENT … lstat` from inside the module resolver (HQ-CLI-1S);
+  and (2) a dependency file that was found but only half-written, so loading it
+  returned an empty module and its own code threw `TypeError: … is not a
+  function` (HQ-CLI-1T). Both are now recognized as "your install was mid-update,
+  not an hq bug": the command waits for the reinstall to settle and re-runs once
+  on the healed tree instead of reporting an error. The half-written-file case
+  only ever waits when a reinstall is actually in progress — a genuine, lasting
+  defect in a third-party dependency still reports exactly once and never pays a
+  wait, and a fault in hq's own shipped files is still reported. (The two related
+  shapes HQ-CLI-1V and HQ-CLI-1W are already covered by 5.109.8 and #561.)
+
 ## [5.109.11] — 2026-09-12
 
 ### Fixed

package/dist/main.js

@@ -565,8 +565,9 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         // install left a bundled file unwritten (HQ-CLI-1N, a CJS relative-sibling
         // MODULE_NOT_FOUND; HQ-CLI-1Q, a CJS BARE-specifier MODULE_NOT_FOUND for a
         // dependency the requiring third-party package's own manifest declares), or
-        // a concurrent global install rewrote the running tree so an ESM module
-        // present at resolve was gone at read (HQ-CLI-1M, an esm-loader ENOENT).
+        // a concurrent global install rewrote the running tree so a module present
+        // at resolve was gone at read (HQ-CLI-1M, an esm-loader ENOENT; HQ-CLI-20,
+        // its CJS loader-read twin).
         // All carry no hq-cli frames and reached the final else, filing a bare
         // crash and an unactionable line. An incomplete install is the caller's
         // machine, the disposition HQ-CLI-Y already established for the qmd CHILD —
@@ -574,11 +575,12 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         // environmental family (after the typed qmd carriers and the hq state-write
         // carrier, before environmentalFsErrorMessage): the signatures are disjoint
         // — ENVIRONMENTAL_FS_CODES is only ENOSPC/EDQUOT/EROFS (never
-        // ENOENT/MODULE_NOT_FOUND), no qmd carrier sets requireStack or an
-        // esm-loader frame, and the classified file must sit under
-        // <packageRoot>/node_modules — so ordering changes nothing that exists. The
+        // ENOENT/MODULE_NOT_FOUND), no qmd carrier sets requireStack or a loader
+        // source-read frame (esm/load or cjs/loader), and the classified file must
+        // sit under <packageRoot>/node_modules — so ordering changes nothing that
+        // exists. The
         // UNATTRIBUTABLE shapes are deliberately NOT suppressed and are captured
-        // WITH bounded context on the generic path below: an esm-loader ENOENT
+        // WITH bounded context on the generic path below: a loader/resolver ENOENT
         // whose path did not survive, and a bare miss the requirer does NOT declare
         // (a possible undeclared/peer dependency, now named in the context).
         const incompleteInstallMsg = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg || moduleMissingMsg || storeMissingMsg || storeUnopenableMsg || queryDocumentMsg || modelDownloadMsg || workdirMissingMsg || stateWriteMsg
@@ -679,9 +681,10 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
             // A genuinely unclassified fault is still captured exactly once. Two
             // shapes attach bounded, hq-derived context so the next occurrence
             // carries the evidence this one lacked: a qmd spawn-level failure the fix
-            // could not attribute (HQ-CLI-1A), and an esm-loader ENOENT whose path
-            // did not survive delivery (HQ-CLI-1M — the unattributable incomplete-
-            // install shape). Every other error captures bare, exactly as before.
+            // could not attribute (HQ-CLI-1A), and a loader/resolver ENOENT whose path
+            // did not survive delivery (HQ-CLI-1M esm-load, HQ-CLI-1S resolve-time,
+            // HQ-CLI-20 CJS load-time — the unattributable incomplete-install shape).
+            // Every other error captures bare, exactly as before.
             const spawnContext = qmdSpawnFailureCaptureContext(err);
             const installContext = incompleteInstallCaptureContext(err);
             if (spawnContext || installContext) {

package/dist/sentry.js

@@ -37,7 +37,9 @@ export function epipeAwareBeforeSend(event, hint) {
     // (HQ-CLI-1N, a CJS relative-sibling MODULE_NOT_FOUND under its bundled
     // node_modules; HQ-CLI-1Q, a CJS BARE-specifier MODULE_NOT_FOUND the requiring
     // third-party package's own manifest declares; HQ-CLI-1M, an esm-loader ENOENT
-    // for a file present at resolve and gone at read). handleTopLevelError already
+    // for a file present at resolve and gone at read; HQ-CLI-20, its CJS loader-read
+    // twin — a bundled CJS dep gone between resolve and the loader's source read).
+    // handleTopLevelError already
     // prints the reinstall remedy for the top-level route; dropping the event here
     // suppresses the fatal regardless of route — the unhandled-rejection boundary,
     // the command-level captureException sites, and bin/hq-auth-refresh —
@@ -50,7 +52,7 @@ export function epipeAwareBeforeSend(event, hint) {
     if (incompleteInstallMessage(hint?.originalException))
         return null;
     // An incomplete-install shape that is NOT suppressed (a bare miss the requirer
-    // does not declare, or a path-less esm-loader ENOENT) should still arrive
+    // does not declare, or a path-less loader/resolver ENOENT) should still arrive
     // ATTRIBUTABLE on every capture route, not only the top-level boundary:
     // handleTopLevelError in main.ts is the ONLY caller of
     // incompleteInstallCaptureContext, so events reaching this hook directly — the

package/dist/startup-registration.d.ts

@@ -16,7 +16,7 @@
  * style of handleTopLevelError so the whole seam is unit-testable without real
  * spawns, waits, or a real install tree.
  */
-import { type WaitForInstallTreeSettledArgs, type WaitForInstallTreeSettledResult } from "./utils/install-tree-torn.js";
+import { type InstallRewriteSignalArgs, type WaitForInstallTreeSettledArgs, type WaitForInstallTreeSettledResult } from "./utils/install-tree-torn.js";
 /**
  * Set on the re-exec'd child so it can NEVER wait or re-exec again — distinct
  * from self-update's HQ_RESCUE_SELF_UPDATED so the two recovery paths cannot
@@ -70,6 +70,8 @@ export interface RegisterRecoveryDeps {
     deriveInstallRoot?: () => string | null;
     lockPath?: () => string;
     waitForSettled?: (args: WaitForInstallTreeSettledArgs) => Promise<WaitForInstallTreeSettledResult>;
+    /** Positive writer-signal probe for the eval-throw gate (defaults to installRewriteInProgress). */
+    rewriteInProgress?: (args: InstallRewriteSignalArgs) => boolean;
     /** node flags to forward to the re-exec child (defaults to process.execArgv). */
     execArgv?: readonly string[];
 }

package/dist/startup-registration.js

@@ -20,7 +20,7 @@ import { spawnSync } from "node:child_process";
 import { resolveRunningInstall } from "./utils/version-gate.js";
 import { stringDerivedPackageRoot } from "./utils/hq-roots.js";
 import { updateLockPath, UPDATE_LOCK_STALE_MS } from "./utils/update-lock.js";
-import { classifyModuleNotFound, InstallTreeTornError, waitForInstallTreeSettled, } from "./utils/install-tree-torn.js";
+import { classifyEvalThrow, classifyModuleNotFound, installRewriteInProgress, 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
  * from self-update's HQ_RESCUE_SELF_UPDATED so the two recovery paths cannot
@@ -87,12 +87,32 @@ export async function registerCommandsWithRecovery(args) {
         return {};
     }
     catch (err) {
-        const classified = classifyModuleNotFound(err);
-        // Not a module-resolution failure — rethrow the SAME object to the existing
-        // boundary, preserving today's behaviour exactly.
+        // The packageRoot bounds the eval-throw classifier's throw site and feeds the
+        // settle wait's manifest-health / retired-sibling guards; resolved once here.
+        const packageRoot = resolvePackageRoot(deps);
+        // Classify the loader failure. classifyModuleNotFound covers the resolve/load
+        // dialects (incl. HQ-CLI-1S resolve-enoent); classifyEvalThrow covers a
+        // module-EVALUATION throw (HQ-CLI-1T). Anything unclassified is rethrown as the
+        // SAME object to the existing boundary, preserving today's behaviour exactly.
+        const classified = classifyModuleNotFound(err) ?? classifyEvalThrow(err, packageRoot);
         if (!classified)
             throw err;
-        const packageRoot = resolvePackageRoot(deps);
+        const lockPath = (deps.lockPath ?? updateLockPath)();
+        const waitFor = deps.waitForSettled ?? waitForInstallTreeSettled;
+        // Writer-signal gate for the eval-throw dialect ONLY. A module-evaluation
+        // throw is indistinguishable from a persistent third-party load-time defect
+        // unless a global reinstall is provably in progress, so require a POSITIVE
+        // writer signal — a fresh foreign lock, an absent/name-mismatched manifest, or
+        // a retired `.hq-cli-<hash>` sibling — before entering recovery. With no such
+        // signal the SAME error is rethrown raw (today's immediate capture) and never
+        // pays a settle wait; a benign fs error (an unreadable manifest or unlistable
+        // parent) is deliberately NOT read as a signal, so a real defect never waits.
+        // The loader-race dialects need no such gate. Injected for a hermetic seam.
+        if (classified.dialect === "eval-throw") {
+            const rewriteInProgress = deps.rewriteInProgress ?? installRewriteInProgress;
+            if (!rewriteInProgress({ packageRoot, lockPath }))
+                throw err;
+        }
         // A child that already recovered must never wait or re-exec again: report
         // once and let the boundary capture it.
         if (env[INSTALL_TREE_RECOVERY_GUARD_ENV] === "1") {
@@ -108,8 +128,6 @@ export async function registerCommandsWithRecovery(args) {
             });
         }
         stderr.write(`${INSTALL_TREE_WAIT_NOTICE}\n`);
-        const lockPath = (deps.lockPath ?? updateLockPath)();
-        const waitFor = deps.waitForSettled ?? waitForInstallTreeSettled;
         const result = await waitFor({
             target: classified.target,
             packageRoot,

package/dist/utils/incomplete-install-error.d.ts

@@ -13,10 +13,11 @@ export type PackageRootResolver = () => string | null;
 /** Which strategy produced the running install's root, recorded in diagnostics. */
 export type PackageRootResolverSource = "manifest-walk" | "string-derivation" | "unresolved" | "injected";
 /**
- * If `err` is an in-process incomplete-install module-load failure — either the
- * CJS relative-sibling shape (HQ-CLI-1N) or the ESM vanished-file shape
- * (HQ-CLI-1M), with the failing file confirmed under `<packageRoot>/node_modules/`
- * — return the actionable, input-free reinstall remedy; otherwise return null.
+ * If `err` is an in-process incomplete-install module-load failure — the CJS
+ * relative-sibling shape (HQ-CLI-1N), the ESM vanished-at-read shape (HQ-CLI-1M),
+ * or the resolve-time lstat shape (HQ-CLI-1S), with the failing file confirmed
+ * under `<packageRoot>/node_modules/` — return the actionable, input-free reinstall
+ * remedy; otherwise return null.
  *
  * Mirrors qmdModuleMissingMessage so the top-level handler and beforeSend branch
  * the same way: a non-null result means print-the-remedy-and-skip-Sentry, null
@@ -24,7 +25,11 @@ export type PackageRootResolverSource = "manifest-walk" | "string-derivation" |
  * fails yields null.
  */
 export declare function incompleteInstallMessage(err: unknown, resolvePackageRoot?: PackageRootResolver, fileSystem?: Pick<typeof fs, "readFileSync">): string | null;
-/** Bounded, scrubber-safe diagnostics for an unattributable esm-loader ENOENT (HQ-CLI-1M). */
+/**
+ * Bounded, scrubber-safe diagnostics for an unattributable loader/resolver ENOENT
+ * whose `path` did not survive delivery — the esm-loader open shape (HQ-CLI-1M) or
+ * the resolve-time lstat shape (HQ-CLI-1S). The two frame booleans say which.
+ */
 export type IncompleteInstallEsmDiagnostics = {
     /** The resolved install root, or the literal `<unresolved>` when none was found. */
     packageRoot: string;
@@ -41,9 +46,30 @@ export type IncompleteInstallEsmDiagnostics = {
      */
     packageJsonExists?: boolean;
     nodeModulesExists?: boolean;
+    /** The stack carried an esm-loader (source-read) frame — the HQ-CLI-1M route. */
     esmLoaderFrame: boolean;
+    /** The stack carried a module-resolver frame — the HQ-CLI-1S resolve-time route. */
+    resolverFrame: boolean;
+    /** The stack carried a CJS loader (source-read) frame — the HQ-CLI-20 route. */
+    cjsLoaderFrame: boolean;
     code: string;
 };
+/**
+ * Bounded, scrubber-safe diagnostics for a module-EVALUATION throw that reached
+ * the boundary raw (HQ-CLI-1T) — a code-less TypeError/ReferenceError/SyntaxError
+ * whose throw site sits under the running install's node_modules, so the next
+ * occurrence names the offending third-party package instead of filing bare. Only
+ * the closed error name and the bounded package name are recorded; never the
+ * message, argv, or a full path.
+ */
+export type IncompleteInstallEvalThrowDiagnostics = {
+    evalThrow: true;
+    errorName: string;
+    throwSitePackage: string;
+    packageRoot: string;
+    packageRootResolved: boolean;
+    resolver: PackageRootResolverSource;
+};
 /**
  * Bounded, scrubber-safe diagnostics for a NOT-suppressed third-party bare miss
  * (HQ-CLI-1Q): a possible undeclared / peer-only dependency defect, made
@@ -82,7 +108,7 @@ export type IncompleteInstallRelativeDiagnostics = {
  * exactly one of the strict shapes above; the looseness is only at the read
  * boundary.
  */
-export type IncompleteInstallDiagnostics = Partial<IncompleteInstallEsmDiagnostics & IncompleteInstallBareDiagnostics & IncompleteInstallRelativeDiagnostics>;
+export type IncompleteInstallDiagnostics = Partial<IncompleteInstallEsmDiagnostics & IncompleteInstallBareDiagnostics & IncompleteInstallRelativeDiagnostics & IncompleteInstallEvalThrowDiagnostics>;
 /**
  * When an incomplete-install failure reaches the capture path WITHOUT being
  * suppressed, return a bounded `contexts.incomplete_install` block so the next
@@ -94,10 +120,14 @@ export type IncompleteInstallDiagnostics = Partial<IncompleteInstallEsmDiagnosti
  *     dist/ or assets/, outside the install, or under an unresolved root
  *     (HQ-CLI-1N) → { code, relativeSpecifier:true, packageRoot,
  *     packageRootResolved, resolver, requirerScope };
- *   - an esm-loader ENOENT whose path did not survive delivery (HQ-CLI-1M) — the
- *     shape the delivered payload arrived in, where neither the exception value
- *     nor node_system_error carried a `path` → { packageRoot, packageJsonExists,
- *     nodeModulesExists, esmLoaderFrame, code }.
+ *   - a loader/resolver ENOENT whose path did not survive delivery (HQ-CLI-1M
+ *     esm-load open, HQ-CLI-1S resolve-time lstat, HQ-CLI-20 CJS load-time open) —
+ *     where neither the exception value nor node_system_error carried a `path` →
+ *     { packageRoot, packageJsonExists, nodeModulesExists, esmLoaderFrame,
+ *     resolverFrame, cjsLoaderFrame, code };
+ *   - a module-EVALUATION throw that reached the boundary raw (HQ-CLI-1T) →
+ *     { evalThrow, errorName, throwSitePackage, packageRoot, packageRootResolved,
+ *     resolver }.
  * Built with the byte-capped, scrubber-safe discipline of
  * package-root-diagnostics.ts — never a caller argv, query, or user-minted
  * value. Never throws. main.ts attaches this on the generic capture path

package/dist/utils/incomplete-install-error.js

@@ -7,7 +7,7 @@
 // failure inside THIS process rather than a qmd child's captured stderr, which
 // is the gap HQ-CLI-Y's classifier cannot cover.
 //
-// Three shapes, one cause — a partial/interrupted global install left a file
+// Four shapes, one cause — a partial/interrupted global install left a file
 // unwritten, or a concurrent global install rewrote the running tree
 // underneath a command:
 //
@@ -36,6 +36,14 @@
 //   ERR_MODULE_NOT_FOUND at resolve, never ENOENT at load; an ENOENT at load
 //   proves the file vanished between resolve and read.
 //
+//   HQ-CLI-20 (Sentry 7724280783) — CJS load, in-process. The CJS twin of
+//   HQ-CLI-1M: `hq core timeout-guard` registers the full command graph, which
+//   reaches a bundled CommonJS dependency (ajv) whose internal require() resolved
+//   a sibling from Module._pathCache and then read its source after a concurrent
+//   reinstall had vanished it. Node raised `ENOENT` with syscall 'open' from the
+//   CJS loader's source read (defaultLoadImpl/loadSource) — a cjs/loader frame but
+//   NO esm/load frame, so the esm-loader gate missed it and it filed a bare crash.
+//
 // All shapes carry no hq-cli frames, reach the boundary's final `else`, and —
 // before this classifier — filed a bare captureException plus an unactionable
 // `hq: <fallback>` line. The disposition is the one HQ-CLI-Y already
@@ -59,12 +67,15 @@
 //      optional-dependency miss (not guaranteed installed), and an undeclared or
 //      peer-only miss (`Cannot find module 'mqtt'` from a requirer that does not
 //      declare it) all stay loud — the last two enriched with both package names.
-//   3. The ESM shape additionally requires an esm-loader frame — an ordinary
-//      `fs.readFileSync` ENOENT written by hq's own code stays captured.
+//   3. The loader shapes additionally require a loader SOURCE-READ frame — the ESM
+//      shape an `esm/load` frame, the CJS shape (HQ-CLI-20) a cjs/loader frame
+//      immediately beneath the node:fs read. An ordinary `fs.readFileSync` ENOENT
+//      written by hq's own code, or one escaping a third-party module's own
+//      EVALUATION, carries no such frame and stays captured.
 import * as fs from "fs";
 import * as path from "path";
 import { packageRoot, stringDerivedPackageRoot } from "./hq-roots.js";
-import { packageNameOf } from "./install-tree-torn.js";
+import { evalThrowShape, hasCjsLoaderSourceReadFrame, packageNameOf } from "./install-tree-torn.js";
 import { boundedDiagnosticValue } from "./package-root-diagnostics.js";
 /**
  * The actionable remedy shown to the operator. Input-free — nothing from the
@@ -95,6 +106,16 @@ const RELATIVE_SPECIFIER = /^\.\.?[\\/]/;
  * `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`, or the CJS `Module._findPath → toRealPath`
+ * route in `node:internal/modules/cjs/loader`. Alongside `syscall === 'lstat'`
+ * this proves a resolve-time ENOENT (HQ-CLI-1S) — a path component that vanished
+ * between the resolver's stat and its realpathSync lstat — so an ordinary
+ * `fs.lstatSync` ENOENT from hq's own code stays captured. Mirrors the frame
+ * matcher in install-tree-torn.ts (duplicated exactly as ESM_LOADER_FRAME is).
+ */
+const RESOLVER_FRAME = /node:internal[\\/]modules[\\/](?:esm[\\/]resolve|cjs[\\/]loader)\b/;
 const ROOT_DIAGNOSTIC_BYTES = 256;
 const CODE_DIAGNOSTIC_BYTES = 32;
 // Package names live inside hq-cli's own dependency graph, so their universe is
@@ -306,6 +327,10 @@ function requirerDeclaresDependency(requiringFile, packageName, fileSystem) {
 function hasEsmLoaderFrame(stack) {
     return typeof stack === "string" && ESM_LOADER_FRAME.test(stack);
 }
+/** True when `stack` carries a Node module RESOLVER frame. */
+function hasResolverFrame(stack) {
+    return typeof stack === "string" && RESOLVER_FRAME.test(stack);
+}
 /**
  * The ESM-loader ENOENT SIGNATURE, independent of whether a usable `path`
  * survived: `code === 'ENOENT'`, `syscall === 'open'`, and an esm-loader frame
@@ -321,10 +346,44 @@ function isEsmLoaderEnoent(err) {
         hasEsmLoaderFrame(record.stack));
 }
 /**
- * If `err` is an in-process incomplete-install module-load failure — either the
- * CJS relative-sibling shape (HQ-CLI-1N) or the ESM vanished-file shape
- * (HQ-CLI-1M), with the failing file confirmed under `<packageRoot>/node_modules/`
- * — return the actionable, input-free reinstall remedy; otherwise return null.
+ * The resolve-time ENOENT SIGNATURE (HQ-CLI-1S): `code === 'ENOENT'`,
+ * `syscall === 'lstat'`, and a resolver frame — independent of whether a usable
+ * `path` survived delivery. Sibling of {@link isEsmLoaderEnoent}; the message
+ * classifier additionally requires a `path` under node_modules.
+ */
+function isResolveEnoent(err) {
+    if (err === null || typeof err !== "object")
+        return false;
+    const record = err;
+    return (record.code === "ENOENT" &&
+        record.syscall === "lstat" &&
+        hasResolverFrame(record.stack));
+}
+/** True when `stack` is a CJS loader SOURCE-READ stack (HQ-CLI-20). */
+function hasCjsLoaderFrame(stack) {
+    return typeof stack === "string" && hasCjsLoaderSourceReadFrame(stack);
+}
+/**
+ * The CJS loader-read ENOENT SIGNATURE (HQ-CLI-20): `code === 'ENOENT'`,
+ * `syscall === 'open'`, and a CJS loader SOURCE-READ stack (the positional gate
+ * shared from install-tree-torn.ts) — the CJS twin of {@link isEsmLoaderEnoent},
+ * independent of whether a usable `path` survived. The message classifier
+ * additionally requires a `path` under node_modules.
+ */
+function isCjsLoaderEnoent(err) {
+    if (err === null || typeof err !== "object")
+        return false;
+    const record = err;
+    return (record.code === "ENOENT" &&
+        record.syscall === "open" &&
+        hasCjsLoaderFrame(record.stack));
+}
+/**
+ * If `err` is an in-process incomplete-install module-load failure — the CJS
+ * relative-sibling shape (HQ-CLI-1N), the ESM vanished-at-read shape (HQ-CLI-1M),
+ * or the resolve-time lstat shape (HQ-CLI-1S), with the failing file confirmed
+ * under `<packageRoot>/node_modules/` — return the actionable, input-free reinstall
+ * remedy; otherwise return null.
  *
  * Mirrors qmdModuleMissingMessage so the top-level handler and beforeSend branch
  * the same way: a non-null result means print-the-remedy-and-skip-Sentry, null
@@ -375,17 +434,35 @@ export function incompleteInstallMessage(err, resolvePackageRoot = safePackageRo
             ? INCOMPLETE_INSTALL_REMEDY
             : null;
     }
-    // Shape B (ESM load, HQ-CLI-1M): an ENOENT from the module loader for a file
-    // that was present at resolve and gone at read.
-    if (record.syscall !== "open")
-        return null;
-    if (typeof record.path !== "string")
-        return null;
-    if (!hasEsmLoaderFrame(record.stack))
-        return null;
-    return isUnderNodeModules(record.path, root)
-        ? INCOMPLETE_INSTALL_REMEDY
-        : null;
+    // Shape B (ESM load, HQ-CLI-1M): an ENOENT from the module LOADER for a file
+    // present at resolve and gone at read (syscall 'open' + an esm-loader frame).
+    if (record.syscall === "open" &&
+        typeof record.path === "string" &&
+        hasEsmLoaderFrame(record.stack)) {
+        return isUnderNodeModules(record.path, root) ? INCOMPLETE_INSTALL_REMEDY : null;
+    }
+    // Shape B' (RESOLVE time, HQ-CLI-1S): an ENOENT from the resolver's realpath
+    // step (syscall 'lstat' + a resolver frame) — a path component that a concurrent
+    // reinstall renamed away between the resolver's stat and its lstat. Same
+    // disposition as B: a vanished component under the running install's
+    // node_modules is a torn install, so print the remedy and skip capture.
+    if (record.syscall === "lstat" &&
+        typeof record.path === "string" &&
+        hasResolverFrame(record.stack)) {
+        return isUnderNodeModules(record.path, root) ? INCOMPLETE_INSTALL_REMEDY : null;
+    }
+    // Shape B'' (CJS load-time, HQ-CLI-20): the CJS twin of Shape B — an ENOENT from
+    // the CJS loader's source read (syscall 'open' + a CJS loader SOURCE-READ stack,
+    // NO esm/load frame) for a bundled dependency file present at resolve and gone at
+    // read. Same disposition as B: a vanished file under the running install's
+    // node_modules is a torn install, so print the remedy and skip capture; a miss
+    // under the install's own dist/ or assets/ stays captured.
+    if (record.syscall === "open" &&
+        typeof record.path === "string" &&
+        hasCjsLoaderFrame(record.stack)) {
+        return isUnderNodeModules(record.path, root) ? INCOMPLETE_INSTALL_REMEDY : null;
+    }
+    return null;
 }
 /** A readFileSync surface, defaulting to the real fs when the caller injects none. */
 function readFileFrom(fileSystem) {
@@ -513,10 +590,14 @@ function relativeSpecifierCaptureContext(err, resolvePackageRoot, fileSystem) {
  *     dist/ or assets/, outside the install, or under an unresolved root
  *     (HQ-CLI-1N) → { code, relativeSpecifier:true, packageRoot,
  *     packageRootResolved, resolver, requirerScope };
- *   - an esm-loader ENOENT whose path did not survive delivery (HQ-CLI-1M) — the
- *     shape the delivered payload arrived in, where neither the exception value
- *     nor node_system_error carried a `path` → { packageRoot, packageJsonExists,
- *     nodeModulesExists, esmLoaderFrame, code }.
+ *   - a loader/resolver ENOENT whose path did not survive delivery (HQ-CLI-1M
+ *     esm-load open, HQ-CLI-1S resolve-time lstat, HQ-CLI-20 CJS load-time open) —
+ *     where neither the exception value nor node_system_error carried a `path` →
+ *     { packageRoot, packageJsonExists, nodeModulesExists, esmLoaderFrame,
+ *     resolverFrame, cjsLoaderFrame, code };
+ *   - a module-EVALUATION throw that reached the boundary raw (HQ-CLI-1T) →
+ *     { evalThrow, errorName, throwSitePackage, packageRoot, packageRootResolved,
+ *     resolver }.
  * Built with the byte-capped, scrubber-safe discipline of
  * package-root-diagnostics.ts — never a caller argv, query, or user-minted
  * value. Never throws. main.ts attaches this on the generic capture path
@@ -531,19 +612,66 @@ export function incompleteInstallCaptureContext(err, resolvePackageRoot = safePa
     const relative = relativeSpecifierCaptureContext(err, resolvePackageRoot, fileSystem);
     if (relative)
         return relative;
-    // (C) HQ-CLI-1M — the path-less esm-loader ENOENT, unchanged.
-    if (!isEsmLoaderEnoent(err))
-        return undefined;
-    // Only instrument what we did NOT already confidently suppress: a path under
-    // node_modules is classified and printed above, never captured.
-    if (incompleteInstallMessage(err, resolvePackageRoot, readFileFrom(fileSystem)) !== null) {
-        return undefined;
+    // (C) HQ-CLI-1M / HQ-CLI-1S / HQ-CLI-20 — the path-less loader/resolver ENOENT
+    // (esm-load open, resolve-time lstat, or CJS load-time open), made attributable.
+    // An ENOENT whose `path` survived and sits under node_modules is classified and
+    // printed above, never captured; only the unattributable shape (no usable path,
+    // or a path outside node_modules) reaches here.
+    if (isEsmLoaderEnoent(err) || isResolveEnoent(err) || isCjsLoaderEnoent(err)) {
+        if (incompleteInstallMessage(err, resolvePackageRoot, readFileFrom(fileSystem)) === null) {
+            const record = err;
+            const code = typeof record.code === "string" ? record.code : "";
+            // The default resolver knows which strategy answered (manifest walk vs the
+            // string derivation that survives a torn tree); an injected resolver is
+            // opaque, so it is recorded as "injected" and its return used as the root.
+            const resolution = resolvePackageRoot === safePackageRoot
+                ? resolvePackageRootWithSource()
+                : {
+                    root: resolveRootSafely(resolvePackageRoot),
+                    source: "injected",
+                };
+            const root = resolution.root;
+            const diagnostics = {
+                packageRoot: boundedDiagnosticValue(root ?? "<unresolved>", ROOT_DIAGNOSTIC_BYTES),
+                packageRootResolved: root !== null,
+                resolver: resolution.source,
+                // Which route raised it — the esm-loader (source-read) frame for 1M, the
+                // resolver frame for 1S, the CJS loader source-read frame for HQ-CLI-20;
+                // any are recorded from the stack.
+                esmLoaderFrame: hasEsmLoaderFrame(record.stack),
+                resolverFrame: hasResolverFrame(record.stack),
+                cjsLoaderFrame: hasCjsLoaderFrame(record.stack),
+                code: boundedDiagnosticValue(code, CODE_DIAGNOSTIC_BYTES),
+            };
+            // Report the existence booleans ONLY when a root was resolved. Reported for
+            // an unresolved root they were uninitialised `false`s indistinguishable from
+            // "resolved but missing" — the instrumentation defect the prior fix shipped.
+            if (root !== null) {
+                diagnostics.packageJsonExists = safeExistsSync(fileSystem, path.join(root, "package.json"));
+                diagnostics.nodeModulesExists = safeExistsSync(fileSystem, path.join(root, "node_modules"));
+            }
+            return { incomplete_install: diagnostics };
+        }
     }
-    const record = err;
-    const code = typeof record.code === "string" ? record.code : "";
-    // The default resolver knows which strategy answered (manifest walk vs the
-    // string derivation that survives a torn tree); an injected resolver is
-    // opaque, so it is recorded as "injected" and its return used as the root.
+    // (D) HQ-CLI-1T — a module-EVALUATION throw that reached the boundary raw (the
+    // writer-signal gate found no reinstall in progress), made attributable.
+    return evalThrowCaptureContext(err, resolvePackageRoot);
+}
+/**
+ * When a module-EVALUATION throw (HQ-CLI-1T) reached the capture path raw — a
+ * code-less TypeError/ReferenceError/SyntaxError whose top-level code ran while a
+ * half-written dependency file returned an empty module — return a bounded
+ * `incomplete_install` block naming the offending third-party package so the next
+ * occurrence is attributable instead of bare; otherwise undefined. When the root
+ * resolves, the throw site MUST sit under its node_modules (an hq-cli `dist/` or
+ * `assets/` eval throw is hq's OWN defect and stays a bare capture); when the root
+ * is unresolved the block is still attached with `packageRootResolved:false`.
+ * Never throws; never emits the message, argv, or a full path.
+ */
+function evalThrowCaptureContext(err, resolvePackageRoot) {
+    const shape = evalThrowShape(err);
+    if (!shape)
+        return undefined;
     const resolution = resolvePackageRoot === safePackageRoot
         ? resolvePackageRootWithSource()
         : {
@@ -551,21 +679,18 @@ export function incompleteInstallCaptureContext(err, resolvePackageRoot = safePa
             source: "injected",
         };
     const root = resolution.root;
-    const diagnostics = {
-        packageRoot: boundedDiagnosticValue(root ?? "<unresolved>", ROOT_DIAGNOSTIC_BYTES),
-        packageRootResolved: root !== null,
-        resolver: resolution.source,
-        esmLoaderFrame: true,
-        code: boundedDiagnosticValue(code, CODE_DIAGNOSTIC_BYTES),
+    if (root !== null && !isUnderNodeModules(shape.throwSite, root))
+        return undefined;
+    return {
+        incomplete_install: {
+            evalThrow: true,
+            errorName: boundedDiagnosticValue(shape.errorName, CODE_DIAGNOSTIC_BYTES),
+            throwSitePackage: boundedDiagnosticValue(requiringPackage(shape.throwSite)?.name ?? "<unresolved>", PACKAGE_NAME_DIAGNOSTIC_BYTES),
+            packageRoot: boundedDiagnosticValue(root ?? "<unresolved>", ROOT_DIAGNOSTIC_BYTES),
+            packageRootResolved: root !== null,
+            resolver: resolution.source,
+        },
     };
-    // Report the existence booleans ONLY when a root was resolved. Reported for an
-    // unresolved root they were uninitialised `false`s indistinguishable from
-    // "resolved but missing" — the instrumentation defect the prior fix shipped.
-    if (root !== null) {
-        diagnostics.packageJsonExists = safeExistsSync(fileSystem, path.join(root, "package.json"));
-        diagnostics.nodeModulesExists = safeExistsSync(fileSystem, path.join(root, "node_modules"));
-    }
-    return { incomplete_install: diagnostics };
 }
 /** existsSync that never throws — any filesystem error reads as "absent". */
 function safeExistsSync(fileSystem, target) {

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

@@ -31,10 +31,13 @@
  */
 /**
  * The loader-error `code`s recovery classifies. The first two mean "a module
- * could not be resolved"; `ENOENT` is the esm-loader dialect where a module was
- * present at resolve and gone at read (HQ-CLI-1M) — see {@link ModuleErrorDialect}.
+ * could not be resolved"; `ENOENT` is the loader/resolver dialect where a module
+ * was present at one step and gone at the next (HQ-CLI-1M esm-load open, HQ-CLI-20
+ * cjs-load open, HQ-CLI-1S resolve-time lstat); `EVAL_THROW` is the synthetic code
+ * for a module-EVALUATION throw that carries NO real `code` (HQ-CLI-1T) — see
+ * {@link ModuleErrorDialect}.
  */
-export type ModuleNotFoundCode = "ERR_MODULE_NOT_FOUND" | "MODULE_NOT_FOUND" | "ENOENT";
+export type ModuleNotFoundCode = "ERR_MODULE_NOT_FOUND" | "MODULE_NOT_FOUND" | "ENOENT" | "EVAL_THROW";
 /**
  * The closed set of resolution-failure dialects, verified on Node v22.23.1 (the
  * @sentry/node import-in-the-middle hook does not change the shapes):
@@ -54,10 +57,27 @@ export type ModuleNotFoundCode = "ERR_MODULE_NOT_FOUND" | "MODULE_NOT_FOUND" | "
  *   - `esm-enoent`:  ESM loader ENOENT (HQ-CLI-1M) — a module present at RESOLVE
  *                    and gone at READ, so getSourceSync/openSync raises ENOENT
  *                    (not ERR_MODULE_NOT_FOUND). `err.path` is the vanished file.
+ *   - `cjs-enoent`:  CJS loader 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 (defaultLoadImpl/loadSource, or the older
+ *                    Module._extensions..js handler) raises ENOENT with syscall
+ *                    'open' and a cjs/loader frame but NO esm/load frame. `err.path`
+ *                    is the vanished file.
+ *   - `resolve-enoent`: ESM/CJS RESOLVE-time ENOENT (HQ-CLI-1S) — a path component
+ *                    stat'ed OK, then vanished before realpathSync's lstat, so the
+ *                    resolver (finalizeResolution / Module._findPath→toRealPath)
+ *                    raises ENOENT with syscall `lstat`. `err.path` is the vanished
+ *                    component (which may be a package/scope directory).
+ *   - `eval-throw`:  a module-EVALUATION throw (HQ-CLI-1T) — a dependency file was
+ *                    found but still half-written, so require() returned an empty
+ *                    module and its top-level code threw a code-LESS TypeError /
+ *                    ReferenceError / SyntaxError under Module._compile /
+ *                    esm/module_job. The specifier is the bounded throw-site path.
  *   - `unknown`:     a module-not-found whose message did not parse; recovery
  *                    still waits on the lock / retired-dir / quiet signals.
  */
-export type ModuleErrorDialect = "esm-path" | "esm-package" | "cjs-path" | "cjs-package" | "cjs-relative" | "esm-enoent" | "unknown";
+export type ModuleErrorDialect = "esm-path" | "esm-package" | "cjs-path" | "cjs-package" | "cjs-relative" | "esm-enoent" | "cjs-enoent" | "resolve-enoent" | "eval-throw" | "unknown";
 /**
  * The missing thing, re-resolvable by the readiness probe:
  *   - `path`:     an absolute filesystem path (a `.js` file, or a package dir).
@@ -66,6 +86,12 @@ export type ModuleErrorDialect = "esm-path" | "esm-package" | "cjs-path" | "cjs-
  *                 Node's CJS resolver does from directory `from` —
  *                 `path.resolve(from, specifier)` plus the `.js`/`.json`/`.node`
  *                 and directory forms.
+ *   - `exists`:   an absolute path whose bare EXISTENCE is the readiness signal
+ *                 (HQ-CLI-1S) — the resolver lstat'ed this component, which may be
+ *                 a package/scope DIRECTORY whose contents precede a `package.json`,
+ *                 so the `path` kind's directory rule could stay false forever.
+ *                 Readiness still rides the lock / manifest-health / retired-sibling
+ *                 / quiet guards, exactly as for the loader-race dialects.
  *   - `unknown`:  the message did not parse; treated as "present" by the probe so
  *                 readiness turns only on the lock / retired-dir / quiet signals.
  */
@@ -80,6 +106,9 @@ export type ModuleErrorTarget = {
     kind: "relative";
     specifier: string;
     from: string;
+} | {
+    kind: "exists";
+    path: string;
 } | {
     kind: "unknown";
 };
@@ -91,7 +120,10 @@ export interface ClassifiedModuleError {
     /** The importer the message named (from-clause or requireStack[0]), or "". */
     importer: string;
     target: ModuleErrorTarget;
+    /** The thrown error's `name` for the eval-throw dialect (HQ-CLI-1T), else absent. */
+    errorName?: string;
 }
+export declare function hasCjsLoaderSourceReadFrame(stack: string): boolean;
 /**
  * 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
@@ -109,6 +141,39 @@ export declare function packageNameOf(specifier: string): string;
  * `null` so it is rethrown to the existing boundary unchanged.
  */
 export declare function classifyModuleNotFound(err: unknown): ClassifiedModuleError | null;
+/** The structural fingerprint of a module-EVALUATION throw (HQ-CLI-1T). */
+export interface EvalThrowShape {
+    /** The thrown error's `name`, in {@link EVAL_THROW_NAMES}. */
+    errorName: string;
+    /** The absolute throw-site path (first path token in the stack). */
+    throwSite: string;
+}
+/**
+ * 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 declare function evalThrowShape(err: unknown): EvalThrowShape | null;
+/**
+ * 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 declare function classifyEvalThrow(err: unknown, packageRoot: string | null): ClassifiedModuleError | null;
 /** The filesystem surface the probe and wait use, injectable for hermetic tests. */
 export interface InstallTreeFs {
     existsSync(p: string): boolean;
@@ -133,6 +198,8 @@ export interface InstallTreeFs {
  *                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.
  */
@@ -221,6 +288,27 @@ export interface WaitForInstallTreeSettledResult {
  * lockWaitMs`), so the caller can never hang.
  */
 export declare function waitForInstallTreeSettled(args: WaitForInstallTreeSettledArgs): Promise<WaitForInstallTreeSettledResult>;
+export interface InstallRewriteSignalArgs {
+    /** The running install's package dir (from resolveRunningInstall), or null. */
+    packageRoot: string | null;
+    /** The shared update-lock path ($HOME/.hq/locks/cli-update.lock). */
+    lockPath: string;
+    now?: () => number;
+    fs?: InstallTreeFs;
+    isPidAlive?: (pid: number) => boolean;
+}
+/**
+ * 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 declare function installRewriteInProgress(args: InstallRewriteSignalArgs): boolean;
 /** The recovery OUTCOME, which — not the dialect — decides capture. */
 export type InstallTreeTornOutcome = "guarded" | "unsettled" | "reexec-failed" | "lock-held";
 export type InstallTreeTornDiagnostics = {
@@ -241,6 +329,8 @@ export type InstallTreeTornDiagnostics = {
     /** The bounded `tool` of the last fresh foreign lock seen, or "". */
     lockTool: string;
     node: string;
+    /** The thrown error's `name` for the eval-throw dialect (HQ-CLI-1T), else "". */
+    errorName: string;
 };
 export interface InstallTreeTornInit {
     /** The original loader error, carried unchanged as `cause`. */

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

@@ -41,6 +41,8 @@ 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;
@@ -54,6 +56,141 @@ 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);
+}
+/**
+ * The Node CJS loader's SOURCE-READ position (HQ-CLI-20) — the CJS twin of
+ * {@link ESM_LOADER_FRAME}. 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/load` 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
@@ -122,6 +259,53 @@ export function classifyModuleNotFound(err) {
                 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/load 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")
@@ -206,6 +390,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),
@@ -289,6 +528,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.
  */
@@ -296,6 +537,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;
@@ -509,6 +756,57 @@ export async function waitForInstallTreeSettled(args) {
         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";
 /**
@@ -539,6 +837,7 @@ export class InstallTreeTornError extends Error {
             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);
     }

package/package.json

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