@indigoai-us/hq-cli 5.109.10 → 5.109.12

package/CHANGELOG.md

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

package/dist/startup-registration.d.ts

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

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

package/dist/utils/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,28 @@ 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;
     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 +106,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 +118,13 @@ 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) — where neither the exception
+ *     value nor node_system_error carried a `path` → { packageRoot,
+ *     packageJsonExists, nodeModulesExists, esmLoaderFrame, resolverFrame, 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

@@ -64,7 +64,7 @@
 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, 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 +95,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 +316,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 +335,25 @@ 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));
+}
+/**
+ * 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 +404,24 @@ 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;
+    }
+    return null;
 }
 /** A readFileSync surface, defaulting to the real fs when the caller injects none. */
 function readFileFrom(fileSystem) {
@@ -513,10 +549,13 @@ 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) — where neither the exception
+ *     value nor node_system_error carried a `path` → { packageRoot,
+ *     packageJsonExists, nodeModulesExists, esmLoaderFrame, resolverFrame, 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 +570,63 @@ 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 — the path-less loader/resolver ENOENT, 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)) {
+        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; either or both are recorded from the stack.
+                esmLoaderFrame: hasEsmLoaderFrame(record.stack),
+                resolverFrame: hasResolverFrame(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 +634,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) {