@indigoai-us/hq-cli 5.204.0 → 5.206.0

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.204.0",
+  "version": "5.206.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {