@indigoai-us/hq-cli 5.205.0 → 5.206.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [5.206.0] — 2026-09-26
+
+### Fixed
+
+- Startup recovery no longer waits the full install deadline when an unchanged retired hq-cli package remains beside the install. Node 24 ESM loader file-read `ENOENT` errors also enter the existing recovery path and receive a report tag.
+
 ## [5.205.0] — 2026-09-26
 
 ### Added

package/dist/startup-registration.js

@@ -158,6 +158,7 @@ export async function registerCommandsWithRecovery(args) {
                 waitedMs: result.waitedMs,
                 sawLock: result.sawLock,
                 sawRetired: result.sawRetired,
+                retiredSiblingPresent: result.retiredSiblingPresent,
                 sawTreeChange: result.sawTreeChange,
                 lockHeldAtEnd: result.lockHeldAtEnd,
                 lockedMs: result.lockedMs,
@@ -188,6 +189,7 @@ export async function registerCommandsWithRecovery(args) {
                 waitedMs: result.waitedMs,
                 sawLock: result.sawLock,
                 sawRetired: result.sawRetired,
+                retiredSiblingPresent: result.retiredSiblingPresent,
                 sawTreeChange: result.sawTreeChange,
                 lockTool: result.lockTool,
             });

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

@@ -39,8 +39,9 @@
  */
 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):
+ * The closed set of resolution-failure dialects, verified on Node v22.23.1 and
+ * the observed Node 24 synchronous ESM loader shape (the @sentry/node
+ * import-in-the-middle hook does not change the stack transfer):
  *   - `esm-path`:    ESM importer, an absolute file (or legacyMainResolve dir)
  *                    target — `err.url` set, or `Cannot find package '<abs>'…`.
  *   - `esm-package`: ESM importer, a bare specifier — `Cannot find package
@@ -62,7 +63,7 @@ export type ModuleNotFoundCode = "ERR_MODULE_NOT_FOUND" | "MODULE_NOT_FOUND" | "
  *                    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`
+ *                    'open' and a cjs/loader frame but NO ESM source-read 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
@@ -179,6 +180,13 @@ export interface InstallTreeFs {
     existsSync(p: string): boolean;
     statSync(p: string): {
         isDirectory(): boolean;
+        isSymbolicLink?(): boolean;
+        size?: number;
+        mtimeMs?: number;
+    };
+    lstatSync?(p: string): {
+        isDirectory(): boolean;
+        isSymbolicLink?(): boolean;
         size?: number;
         mtimeMs?: number;
     };
@@ -264,6 +272,8 @@ export interface WaitForInstallTreeSettledResult {
     sawTreeChange?: boolean;
     /** True when the lock-free tree stayed unchanged for `staleProbeMs`. */
     staleTree?: boolean;
+    /** Presence on the final poll; null means the sibling directory was unreadable. */
+    retiredSiblingPresent?: boolean | null;
 }
 export declare const DEFAULT_INSTALL_TREE_STALE_PROBE_MS = 1500;
 /**
@@ -278,10 +288,11 @@ export declare const DEFAULT_INSTALL_TREE_STALE_PROBE_MS = 1500;
  * app, the box's update timer, another `hq`) cannot make a legitimately-in-progress
  * reinstall look stale:
  *   - UNLOCKED time — wall time observed with no fresh foreign lock — is bounded
- *     by `deadlineMs`. If the target is still missing, no lock or retired sibling
- *     is present, and the observed tree stays unchanged for `staleProbeMs`, the
- *     wait returns `staleTree` early. Any observed tree change keeps the ordinary
- *     settle deadline in force. `deadlineMs === 0` evaluates readiness once.
+ *     by `deadlineMs`. If the target is still missing and the observed tree,
+ *     including retired sibling names and mtimes, stays unchanged for
+ *     `staleProbeMs`, the wait returns `staleTree` early. Any observed tree
+ *     change keeps the ordinary settle deadline in force. `deadlineMs === 0`
+ *     evaluates readiness once.
  *   - LOCKED time — wall time observed under a fresh foreign lock held by a live
  *     pid — is bounded SEPARATELY by `lockWaitMs` (default the lock contract's own
  *     10-minute staleness window) and does NOT consume the settle budget. When
@@ -342,6 +353,8 @@ export type InstallTreeTornDiagnostics = {
     /** The bounded `tool` of the last fresh foreign lock seen, or "". */
     lockTool: string;
     node: string;
+    /** Presence on the final poll when the scope directory could be observed. */
+    retiredSiblingPresent?: boolean;
     /** The thrown error's `name` for the eval-throw dialect (HQ-CLI-1T), else "". */
     errorName: string;
 };
@@ -363,6 +376,8 @@ export interface InstallTreeTornInit {
     lockedMs?: number;
     /** The last fresh foreign lock's `tool`, bounded on construction (default ""). */
     lockTool?: string;
+    /** Final retired sibling presence, or null when the scope directory was unreadable. */
+    retiredSiblingPresent?: boolean | null;
 }
 /**
  * A torn-install failure that stays VISIBLE in Sentry with bounded, hq-derived

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

@@ -48,15 +48,33 @@ const ESM_PACKAGE_RE = /^Cannot find package '([^']+)' imported from (.+)$/s;
 const CJS_MODULE_RE = /^Cannot find module '([^']+)'/s;
 const ESM_MODULE_IMPORTED_RE = /^Cannot find module '([^']+)' imported from (.+)$/s;
 /**
- * The Node ESM loader's SOURCE-READ frame — `getSourceSync`/`defaultLoad` in
- * `node:internal/modules/esm/load`. Requiring the `esm/load` module frame (not
- * merely any frame under `modules/esm/`) is what proves the loader was READING
- * the module's source, so an ordinary `fs.openSync`/`readFileSync` ENOENT that
- * merely ESCAPES a module's EVALUATION — which runs under `esm/module_job`,
- * never `esm/load` — is NOT misclassified as a torn install and does not trigger
- * the settle wait. `load\b` also excludes the sibling `esm/loader` module.
+ * The Node ESM loader's SOURCE-READ helper in `node:internal/modules/esm/load`
+ * (Node 22) or `node:internal/modules/esm/loader` (Node 24's sync loader).
+ * `getSourceSync` must be the first non-`node:fs` caller after the source read;
+ * an ordinary fs ENOENT that escapes module evaluation therefore stays outside
+ * recovery even when an outer ModuleLoader frame exists.
  */
-const ESM_LOADER_FRAME = /node:internal[\\/]modules[\\/]esm[\\/]load\b/;
+const ESM_SOURCE_READ_FRAME = /^at getSourceSync \(node:internal[\\/]modules[\\/]esm[\\/](?:load|loader)\b/;
+const NODE_FS_FRAME = /^at .* \(node:fs\b/;
+/** True only when Node's ESM source-read helper called the failing fs read. */
+function hasEsmLoaderSourceReadFrame(stack) {
+    const frames = stack
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.startsWith("at "));
+    let sawFsRead = false;
+    for (const frame of frames) {
+        if (!sawFsRead) {
+            if (NODE_FS_READ_FRAME.test(frame))
+                sawFsRead = true;
+            continue;
+        }
+        if (NODE_FS_FRAME.test(frame))
+            continue;
+        return ESM_SOURCE_READ_FRAME.test(frame);
+    }
+    return false;
+}
 /**
  * The Node module RESOLVER frame — `finalizeResolution` in
  * `node:internal/modules/esm/resolve` (the observed HQ-CLI-1S route, where
@@ -85,12 +103,12 @@ function hasModuleEvalFrame(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
+ * {@link hasEsmLoaderSourceReadFrame}. A CJS require whose target was present at RESOLVE (its
  * filename cached in Module._pathCache) and gone at READ fails inside the loader's
  * source read: `readFileSync (node:fs)` called by `defaultLoadImpl`/`loadSource`
  * (Node ≥22) or, on older Node, the `Module._extensions..js` extension handler —
  * all frames in `node:internal/modules/cjs/loader`, and (unlike HQ-CLI-1M) with NO
- * `esm/load` frame.
+ * ESM source-read frame.
  *
  * The discriminator is POSITIONAL: the innermost `node:fs` read frame's
  * IMMEDIATELY-following (caller) frame must be a cjs/loader frame that is NOT a
@@ -251,7 +269,7 @@ export function classifyModuleNotFound(err) {
         if (record.syscall === "open" &&
             typeof record.path === "string" &&
             typeof record.stack === "string" &&
-            ESM_LOADER_FRAME.test(record.stack)) {
+            hasEsmLoaderSourceReadFrame(record.stack)) {
             return {
                 code,
                 dialect: "esm-enoent",
@@ -263,7 +281,7 @@ export function classifyModuleNotFound(err) {
         // 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
+        // ENOENT with syscall 'open' and a cjs/loader frame but NO ESM source-read frame
         // (which is why arm (0) missed it and classifyModuleNotFound returned null,
         // filing the bare HQ-CLI-20 capture). Gated on the FULL conjunction — code
         // ENOENT AND syscall 'open' AND a string path AND the POSITIONAL CJS
@@ -449,6 +467,7 @@ export function classifyEvalThrow(err, packageRoot) {
 const nodeInstallTreeFs = {
     existsSync: (p) => nodeFs.existsSync(p),
     statSync: (p) => nodeFs.statSync(p),
+    lstatSync: (p) => nodeFs.lstatSync(p),
     readFileSync: (p, encoding) => nodeFs.readFileSync(p, encoding),
     readdirSync: (p) => nodeFs.readdirSync(p),
 };
@@ -633,6 +652,56 @@ function retiredSiblingPresent(packageRoot, fs) {
     const entries = fs.readdirSync(parent); // caller treats a throw as "not ready"
     return entries.some((entry) => entry.startsWith(stagingPrefix));
 }
+/** Snapshot retired sibling trees so changes below their root stay observable. */
+function retiredSiblingActivitySignature(packageRoot, fs) {
+    const { leaf } = cliNameParts();
+    const stagingPrefix = `.${leaf}-`;
+    const parent = path.dirname(packageRoot);
+    const siblings = fs.readdirSync(parent).filter((entry) => entry.startsWith(stagingPrefix)).sort();
+    const snapshots = [["names", siblings]];
+    let observed = true;
+    let visited = 0;
+    const maxEntries = 20_000;
+    const maxDepth = 64;
+    const visit = (absolutePath, relativePath, depth) => {
+        visited += 1;
+        if (visited > maxEntries) {
+            observed = false;
+            return;
+        }
+        try {
+            const stat = fs.lstatSync ? fs.lstatSync(absolutePath) : fs.statSync(absolutePath);
+            const symbolicLink = stat.isSymbolicLink?.() ?? false;
+            const directory = !symbolicLink && stat.isDirectory();
+            const mtimeMs = stat.mtimeMs;
+            if (typeof mtimeMs !== "number" || !Number.isFinite(mtimeMs))
+                observed = false;
+            snapshots.push([
+                relativePath,
+                symbolicLink ? "symlink" : directory ? "directory" : "file",
+                stat.size ?? null,
+                typeof mtimeMs === "number" && Number.isFinite(mtimeMs) ? mtimeMs : null,
+            ]);
+            if (!directory)
+                return;
+            if (depth >= maxDepth) {
+                observed = false;
+                return;
+            }
+            for (const child of fs.readdirSync(absolutePath).sort()) {
+                visit(path.join(absolutePath, child), path.join(relativePath, child), depth + 1);
+            }
+        }
+        catch {
+            observed = false;
+            snapshots.push([relativePath, "unreadable"]);
+        }
+    };
+    for (const sibling of siblings) {
+        visit(path.join(parent, sibling), sibling, 0);
+    }
+    return { value: JSON.stringify(snapshots), observed };
+}
 /** Whether packageRoot's own manifest is healthy (`name === CLI_NAME`). */
 function packageRootHealthy(packageRoot, fs) {
     const manifest = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf-8"));
@@ -754,6 +823,18 @@ function installTreeActivitySignature(target, packageRoot, fs) {
             snapshots.push([directory, `entries-unreadable:${errorCode(err)}`]);
         }
     }
+    if (packageRoot) {
+        try {
+            const retired = retiredSiblingActivitySignature(packageRoot, fs);
+            snapshots.push(["retired-siblings", retired.value]);
+            if (!retired.observed)
+                observed = false;
+        }
+        catch (err) {
+            observed = false;
+            snapshots.push(["retired-siblings-unreadable", errorCode(err)]);
+        }
+    }
     return { value: JSON.stringify(snapshots), observed };
 }
 export const DEFAULT_INSTALL_TREE_STALE_PROBE_MS = 1_500;
@@ -769,10 +850,11 @@ export const DEFAULT_INSTALL_TREE_STALE_PROBE_MS = 1_500;
  * app, the box's update timer, another `hq`) cannot make a legitimately-in-progress
  * reinstall look stale:
  *   - UNLOCKED time — wall time observed with no fresh foreign lock — is bounded
- *     by `deadlineMs`. If the target is still missing, no lock or retired sibling
- *     is present, and the observed tree stays unchanged for `staleProbeMs`, the
- *     wait returns `staleTree` early. Any observed tree change keeps the ordinary
- *     settle deadline in force. `deadlineMs === 0` evaluates readiness once.
+ *     by `deadlineMs`. If the target is still missing and the observed tree,
+ *     including retired sibling names and mtimes, stays unchanged for
+ *     `staleProbeMs`, the wait returns `staleTree` early. Any observed tree
+ *     change keeps the ordinary settle deadline in force. `deadlineMs === 0`
+ *     evaluates readiness once.
  *   - LOCKED time — wall time observed under a fresh foreign lock held by a live
  *     pid — is bounded SEPARATELY by `lockWaitMs` (default the lock contract's own
  *     10-minute staleness window) and does NOT consume the settle budget. When
@@ -839,7 +921,7 @@ export async function waitForInstallTreeSettled(args) {
             }
             lastActivitySnapshot = activitySnapshot;
         }
-        let retiredPresent = false;
+        let retiredPresent = null;
         let retiredCheckFailed = false;
         if (args.packageRoot) {
             try {
@@ -848,6 +930,7 @@ export async function waitForInstallTreeSettled(args) {
                     sawRetired = true;
             }
             catch {
+                retiredPresent = null;
                 retiredCheckFailed = true;
             }
         }
@@ -883,14 +966,13 @@ export async function waitForInstallTreeSettled(args) {
                 lockTool,
                 sawTreeChange,
                 staleTree: false,
+                retiredSiblingPresent: retiredPresent,
             };
         }
         if (!ready &&
             !foreignLockHeld &&
-            !retiredPresent &&
             !retiredCheckFailed &&
             !sawLock &&
-            !sawRetired &&
             !sawTreeChange &&
             staleObservationStartedAt !== null &&
             t - staleObservationStartedAt >= staleProbeMs) {
@@ -904,6 +986,7 @@ export async function waitForInstallTreeSettled(args) {
                 lockTool,
                 sawTreeChange,
                 staleTree: true,
+                retiredSiblingPresent: retiredPresent,
             };
         }
         // Give up when the TREE has had a full unlocked budget with no writer visible,
@@ -925,6 +1008,7 @@ export async function waitForInstallTreeSettled(args) {
                 lockTool,
                 sawTreeChange,
                 staleTree: false,
+                retiredSiblingPresent: retiredPresent,
             };
         }
         // The first poll at which the wait has reached `deadlineMs` while a lock is
@@ -1007,7 +1091,7 @@ export class InstallTreeTornError extends Error {
         this.cause = init.cause;
         const sawTreeChange = init.sawTreeChange ?? false;
         const treeState = init.treeState ?? (init.outcome === "stale_tree" ? "stale" : "in_flight");
-        this.diagnostics = {
+        const diagnostics = {
             dialect: init.classified.dialect,
             code: init.classified.code,
             specifier: boundedDiagnosticValue(init.classified.specifier, SPECIFIER_BYTES),
@@ -1026,6 +1110,10 @@ export class InstallTreeTornError extends Error {
             node: process.version,
             errorName: boundedDiagnosticValue(init.classified.errorName ?? "", ERRORNAME_BYTES),
         };
+        if (typeof init.retiredSiblingPresent === "boolean") {
+            diagnostics.retiredSiblingPresent = init.retiredSiblingPresent;
+        }
+        this.diagnostics = diagnostics;
         Object.setPrototypeOf(this, new.target.prototype);
     }
 }

package/dist/utils/sentry-fingerprint.js

@@ -240,6 +240,15 @@ export function installTreeTornSentryTagsFor(err) {
         tree_state: installTreeStateTag(diagnostics.treeState),
         os: installTreeOsTag(process.platform),
     };
+    if (diagnostics.code === "ERR_MODULE_NOT_FOUND" || diagnostics.code === "MODULE_NOT_FOUND") {
+        tags.error_shape = "module_not_found";
+    }
+    else if (diagnostics.code === "ENOENT") {
+        tags.error_shape = "loader_enoent";
+    }
+    if (typeof diagnostics.retiredSiblingPresent === "boolean") {
+        tags.retired_sibling = diagnostics.retiredSiblingPresent ? "present" : "absent";
+    }
     if (recoveryOutcome)
         tags.recovery_outcome = recoveryOutcome;
     const lockTool = diagnostics.lockTool;

package/package.json

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