@link-assistant/hive-mind 2.8.9 → 2.8.10

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @link-assistant/hive-mind
 
+## 2.8.10
+
+### Patch Changes
+
+- b93ed64: fix(2092): make every `use-m` call site self-healing
+
+  `/fix --ci-cd` crashed on `await use('command-stream')` — once on a truncated
+  global install, once on a failed `npm install -g`. The existing corrupt-install
+  recovery was wired into 3 of 100 `use(...)` call sites, so the ~40 top-level
+  `command-stream` loads were unprotected.
+
+  - `ensureUseM()` now returns a retry-wrapped `use`, so every call site inherits
+    the recovery (idempotent, no per-call-site edits).
+  - New retry mode for `Failed to install <pkg> globally into '<dir>'`, with
+    exponential backoff.
+  - Cleanup deletes the whole `<pkg>-v-<version>` alias directory instead of the
+    entry file's parent directory.
+  - Retries bust Node's ESM cache, which otherwise replays the original
+    `SyntaxError` even after a healthy reinstall.
+  - `formatFatalError` restores cause chains (and stacks under `HIVE_MIND_VERBOSE`)
+    in `fix.mjs`/`cleanup.mjs`; `HIVE_MIND_USE_M_DEBUG=1` logs each loader attempt.
+
 ## 2.8.9
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-assistant/hive-mind",
-  "version": "2.8.9",
+  "version": "2.8.10",
   "description": "AI-powered issue solver and hive mind for collaborative problem solving",
   "main": "src/hive.mjs",
   "type": "module",

package/src/cleanup.mjs

@@ -438,6 +438,8 @@ async function main() {
 }
 
 main().catch(async error => {
-  await log(`❌ Error: ${error.message}`, { level: 'error' });
+  // Issue #2092: keep the cause chain so use-m load failures stay diagnosable.
+  const { formatFatalError } = await import('./error-formatting.lib.mjs');
+  await log(formatFatalError(error), { level: 'error' });
   process.exit(1);
 });

package/src/error-formatting.lib.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+
+/**
+ * Shared fatal-error formatting (issue #2092).
+ *
+ * The failing `/fix --ci-cd` runs printed exactly one line:
+ *
+ *   ❌ Failed to import module from '/home/box/.../command-stream-v-latest/src/$.mjs'.
+ *
+ * because the entry points did `console.error(\`❌ ${error.message}\`)`. Everything
+ * that would have identified the problem — the `SyntaxError` in `error.cause`,
+ * the stack showing which module triggered the load — was discarded, so the
+ * first investigation had to guess. This helper keeps the one-line summary but
+ * appends the cause chain, and the full stacks when verbose output is enabled.
+ */
+
+const MAX_CAUSE_DEPTH = 5;
+
+/**
+ * @param {unknown} error - the thrown value.
+ * @param {object} [options]
+ * @param {boolean} [options.verbose] - include stacks; defaults to the
+ *   `HIVE_MIND_VERBOSE` / `VERBOSE` environment variables.
+ * @returns {string} a multi-line, human-readable rendering of the error.
+ */
+export const formatFatalError = (error, options = {}) => {
+  const verbose = options.verbose ?? Boolean(process.env.HIVE_MIND_VERBOSE || process.env.VERBOSE);
+  const lines = [`❌ ${describe(error)}`];
+
+  let current = error?.cause;
+  for (let depth = 0; current && depth < MAX_CAUSE_DEPTH; depth++) {
+    lines.push(`   Caused by: ${describe(current)}`);
+    if (verbose && typeof current?.stack === 'string') lines.push(indent(current.stack));
+    current = current?.cause;
+  }
+
+  if (verbose && typeof error?.stack === 'string') lines.push(indent(error.stack));
+  return lines.join('\n');
+};
+
+const describe = value => {
+  if (value === null || value === undefined) return String(value);
+  if (typeof value !== 'object') return String(value);
+  const name = value.name || value.constructor?.name || 'Error';
+  const message = typeof value.message === 'string' && value.message ? value.message : JSON.stringify(value);
+  const code = value.code ? ` (code: ${value.code})` : '';
+  return `${name}: ${message}${code}`;
+};
+
+const indent = text =>
+  String(text)
+    .split('\n')
+    .map(line => `     ${line}`)
+    .join('\n');

package/src/fix.mjs

@@ -236,7 +236,10 @@ async function main() {
   });
 }
 
-main().catch(error => {
-  console.error(`❌ ${error.message}`);
+main().catch(async error => {
+  // Issue #2092: printing only error.message hid the SyntaxError cause of the
+  // use-m load failure, leaving the run log undiagnosable.
+  const { formatFatalError } = await import('./error-formatting.lib.mjs');
+  console.error(formatFatalError(error));
   process.exit(1);
 });

package/src/use-m-bootstrap.lib.mjs

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
 
+import { wrapUseWithRetry } from './use-with-retry.lib.mjs';
+
 export const USE_M_BOOTSTRAP_URL = 'https://unpkg.com/use-m/use.js';
 export const USE_M_BOOTSTRAP_FALLBACK_URL = 'https://unpkg.com/use-m@8.13.8/use.js';
 
@@ -41,12 +43,21 @@ const fallbackFetchUseMCode = () => fetchUseMCodeFromUrl(USE_M_BOOTSTRAP_FALLBAC
 export const ensureUseM = async (options = {}) => {
   const { fetchUseMCode = defaultFetchUseMCode, log = null } = options;
   if (typeof globalThis.use === 'undefined') {
+    let rawUse;
     try {
-      globalThis.use = (await eval(await fetchUseMCode())).use;
+      rawUse = (await eval(await fetchUseMCode())).use;
     } catch (error) {
       if (typeof log === 'function') log(`   use-m latest bootstrap failed (${error.message}); trying ${USE_M_BOOTSTRAP_FALLBACK_URL}`);
-      globalThis.use = (await eval(await fallbackFetchUseMCode())).use;
+      rawUse = (await eval(await fallbackFetchUseMCode())).use;
     }
+    // Issue #2092: a truncated global `npm install -g <pkg>` makes use-m throw
+    // `Failed to import module from '<...>/command-stream-v-latest/src/$.mjs'.`
+    // Only a few call sites used useWithRetry explicitly; wrapping here means
+    // every `await use(...)` in the codebase recovers by deleting the corrupt
+    // install directory and re-fetching.
+    globalThis.use = wrapUseWithRetry(rawUse);
+  } else {
+    globalThis.use = wrapUseWithRetry(globalThis.use);
   }
   return globalThis.use;
 };

package/src/use-with-retry.lib.mjs

@@ -30,20 +30,57 @@
  * @param {number} [options.attempts=3] - total attempts including the first try.
  * @param {(path: string) => Promise<void>} [options.cleanup] - injectable cleanup
  *   for the corrupted install directory (defaults to recursive `rm`).
+ * @param {(ms: number) => Promise<void>} [options.sleep] - injectable backoff used
+ *   between attempts when the global `npm install -g` itself failed.
+ * @param {number} [options.backoffMs=1000] - base backoff, doubled per attempt.
+ * @param {(message: string) => void} [options.log] - diagnostics sink; defaults to
+ *   `console.error` when `HIVE_MIND_USE_M_DEBUG` is set, otherwise silent.
  * @returns {Promise<unknown>} the module returned by use-m.
  */
 export const useWithRetry = async (use, specifier, options = {}) => {
   const attempts = options.attempts ?? 3;
   const cleanup = options.cleanup ?? defaultCleanup;
+  const sleep = options.sleep ?? defaultSleep;
+  const backoffMs = options.backoffMs ?? 1000;
+  const log = options.log ?? defaultLog;
+  const importModule = options.importModule ?? defaultImport;
+  const extraArgs = options.args ?? [];
   let lastError;
+  let cleanedImportPath = null;
   for (let attempt = 1; attempt <= attempts; attempt++) {
     try {
-      return await use(specifier);
+      return await use(specifier, ...extraArgs);
     } catch (error) {
       lastError = error;
-      if (attempt === attempts || !isCorruptInstallError(error)) {
+      // Node's ESM loader caches *failed* module evaluations by resolved URL.
+      // Once `<alias>/src/$.mjs` has thrown a SyntaxError, re-importing the very
+      // same path in this process replays that error even after the file on disk
+      // has been replaced by a healthy reinstall (verified against use-m@8.14.2 —
+      // see docs/case-studies/issue-2092). Deleting and reinstalling is therefore
+      // necessary but not sufficient: the retry must import through a
+      // cache-busting URL, which use-m has no way to do from the inside.
+      if (cleanedImportPath && extractCorruptedFilePath(error) === cleanedImportPath) {
+        try {
+          const recovered = await importModule(cleanedImportPath, attempt);
+          log(`use('${specifier}') recovered via a cache-busted import of ${cleanedImportPath}`);
+          return recovered;
+        } catch (reimportError) {
+          log(`cache-busted import of ${cleanedImportPath} also failed: ${reimportError?.message}`);
+        }
+      }
+      const retryable = isCorruptInstallError(error) || isTransientInstallError(error);
+      if (attempt === attempts || !retryable) {
+        log(`use('${specifier}') failed on attempt ${attempt}/${attempts} and will not be retried: ${error?.message}`);
         throw error;
       }
+      log(`use('${specifier}') failed on attempt ${attempt}/${attempts}: ${error?.message} — retrying`);
+      // Mode 4 (issue #2092): `npm install -g` itself failed (network blip,
+      // registry 5xx, DinD DNS not up yet). There is nothing to delete; just
+      // back off and let npm try again.
+      if (isTransientInstallError(error)) {
+        await sleep(backoffMs * 2 ** (attempt - 1));
+        continue;
+      }
       const corruptedPath = extractCorruptedFilePath(error);
       if (corruptedPath) {
         try {
@@ -53,9 +90,10 @@ export const useWithRetry = async (use, specifier, options = {}) => {
           //   * "Failed to resolve the path to 'pkg' from '<dir>'" — corruptedPath
           //     is the alias dir itself (e.g. /.../links-notation-v-latest).
           // For files, walk up to the alias dir; otherwise remove the dir as-is.
-          const { dirname } = await import('node:path');
-          const target = corruptedPath.endsWith('-v-latest') || /-v-\d/.test(corruptedPath) ? corruptedPath : dirname(corruptedPath);
-          await cleanup(target);
+          await cleanup(resolveAliasDir(corruptedPath));
+          // Remember the file so the next attempt can bypass Node's poisoned
+          // module cache if use-m hands us the same path again.
+          cleanedImportPath = /Failed to import module from '/.test(error?.message ?? '') ? corruptedPath : null;
         } catch {
           // Best-effort cleanup; fall through to retry regardless.
         }
@@ -66,6 +104,20 @@ export const useWithRetry = async (use, specifier, options = {}) => {
   throw lastError;
 };
 
+/**
+ * Mode 4 (issue #2092): use-m's own `npm install -g <pkg>` step failed, so no
+ * package tree exists yet — `Failed to install command-stream@latest globally
+ * into '/home/box/.nvm/.../node_modules'.` This is transient in Docker-in-Docker
+ * runs where the registry (or DNS) is briefly unreachable, so retry with backoff.
+ *
+ * @param {unknown} error
+ * @returns {boolean}
+ */
+export const isTransientInstallError = error => {
+  const message = typeof error?.message === 'string' ? error.message : '';
+  return /^Failed to install .+ globally into /.test(message);
+};
+
 export const isCorruptInstallError = error => {
   const cause = error?.cause;
   if (cause instanceof SyntaxError) return true;
@@ -101,7 +153,72 @@ export const extractCorruptedFilePath = error => {
   return invalidConfigMatch ? invalidConfigMatch[1] : null;
 };
 
+/**
+ * Walk a corrupted path up to the use-m alias install directory.
+ *
+ * Issue #2092: the failing file can be nested several levels deep inside the
+ * package (`.../command-stream-v-latest/src/$.mjs`). Removing only its parent
+ * directory (`.../src`) leaves a half-package on disk whose package.json still
+ * resolves, so the retry re-imports the same broken tree. Walking up to the
+ * `<pkg>-v-<version>` alias segment removes the whole install instead.
+ *
+ * Falls back to the immediate parent directory when no alias segment is found.
+ *
+ * @param {string} corruptedPath - file or directory path from the error message.
+ * @returns {string} directory to delete before retrying.
+ */
+export const resolveAliasDir = corruptedPath => {
+  const segments = corruptedPath.split('/');
+  const isAlias = segment => /-v-(latest|\d[^/]*)$/.test(segment);
+  for (let index = segments.length - 1; index >= 0; index--) {
+    if (isAlias(segments[index])) return segments.slice(0, index + 1).join('/');
+  }
+  return segments.slice(0, -1).join('/') || corruptedPath;
+};
+
 const defaultCleanup = async path => {
   const { rm } = await import('node:fs/promises');
   await rm(path, { recursive: true, force: true });
 };
+
+// Cache-busting import: a query string makes Node treat the URL as a distinct
+// module, so the freshly reinstalled file is evaluated instead of the cached
+// SyntaxError from the corrupt one.
+const defaultImport = async (filePath, attempt) => {
+  const { pathToFileURL } = await import('node:url');
+  return import(`${pathToFileURL(filePath).href}?use-m-retry=${attempt}`);
+};
+
+const defaultSleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+
+// Off by default so normal runs stay quiet; issue #2092 showed that when the
+// loader dies there is no trace of which specifier or attempt failed.
+const defaultLog = message => {
+  if (process.env.HIVE_MIND_USE_M_DEBUG) console.error(`[use-m] ${message}`);
+};
+
+const USE_RETRY_WRAPPED = Symbol.for('hive-mind.use-with-retry.wrapped');
+
+/**
+ * Wrap a raw use-m `use` function so that *every* call site inherits the
+ * corrupt-install recovery above (issue #2092).
+ *
+ * Before this, only the handful of call sites that explicitly imported
+ * `useWithRetry` (config/queue-config/lino) were protected, while ~40 other
+ * modules called `await use('command-stream')` directly and crashed with
+ * `Failed to import module from '.../command-stream-v-latest/src/$.mjs'.`
+ * whenever the global npm install was truncated.
+ *
+ * The wrapper is idempotent: wrapping an already-wrapped function returns it
+ * unchanged, so repeated `ensureUseM()` calls don't nest retries.
+ *
+ * @param {Function} use - raw use-m loader.
+ * @param {object} [options] - forwarded to useWithRetry (attempts, cleanup).
+ * @returns {Function} retry-wrapped loader.
+ */
+export const wrapUseWithRetry = (use, options = {}) => {
+  if (typeof use !== 'function' || use[USE_RETRY_WRAPPED]) return use;
+  const wrapped = (specifier, ...args) => useWithRetry(use, specifier, { ...options, args });
+  Object.defineProperty(wrapped, USE_RETRY_WRAPPED, { value: true });
+  return wrapped;
+};