@link-assistant/hive-mind 2.8.8 → 2.8.10

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # @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
+
+- fd1789e: fix(development-log): collect a development log for every working session (#2090)
+
+  A run with `--auto-restart-until-mergeable` (implied by `--auto-merge`) starts a
+  new tool session with its own session UUID per restart iteration, but only the
+  first session ever reached the pull request:
+  `createDevelopmentLogFinalizer` memoized a single collection per process, no
+  restart path invoked the finalizer again, and several exit paths (usage limit,
+  tool failure, graceful shutdown, auto-continue) skipped finalization entirely.
+  The single collected `solve.log` was also truncated at collection time and was
+  committed twice, as a byte-identical duplicate under `<tool>-<sessionId>.log`.
+
+  The finalizer is now memoized per session id, every restart iteration finalizes
+  its own session at the shared `executeToolIteration` chokepoint, `safeExit`
+  forces a final collection on every exit path, and each session directory stores
+  only its own byte range of the process log (`metadata.json` schema version 3,
+  `artifacts.solveLogRange`) so the union of the sessions is the complete log
+  without duplication.
+
 ## 2.8.8
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-assistant/hive-mind",
-  "version": "2.8.8",
+  "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/development-log.finalize.lib.mjs

@@ -1,11 +1,105 @@
 /**
- * Build a once-only finalizer so both the normal and error completion paths can
- * preserve a development log without creating duplicate commits.
+ * Build a per-session finalizer so every completion path can preserve a
+ * development log without creating duplicate commits.
+ *
+ * Issue #1596 introduced a once-only finalizer: the first call collected the
+ * artifacts and every later call reused the memoized promise. Issue #2090
+ * showed that this silently drops every session after the first one — a run
+ * with `--auto-restart-until-mergeable` starts a brand new tool session (a new
+ * session UUID) per restart iteration, but only the very first session ever
+ * reached the repository.
+ *
+ * The finalizer is therefore memoized *per session id* instead of per process:
+ *
+ * - the same session id is collected only once (no duplicate commits),
+ * - a different session id is collected again into its own `sessions/<uuid>/`
+ *   directory,
+ * - each collection copies only the slice of the solve log that was produced
+ *   since the previous collection, so the union of all session directories is
+ *   the complete process log without duplicating megabytes per session.
  */
-export const createDevelopmentLogFinalizer = ({ collect, getParams }) => {
-  let resultPromise = null;
-  return () => {
-    if (!resultPromise) resultPromise = Promise.resolve().then(() => collect(getParams()));
+export const createDevelopmentLogFinalizer = ({ collect, getParams, register = true }) => {
+  // sessionKey -> promise of the collection result (dedupe per session).
+  const collections = new Map();
+  // sessionKey -> { startByte, sessionId } of an already collected session.
+  const sessionStartBytes = new Map();
+  // Byte offset in the solve log right after the last collected slice.
+  let nextLogStartByte = 0;
+  // Key of the session collected most recently, so a forced finalize at exit
+  // extends *that* session's log slice instead of re-collecting the first one.
+  let lastSessionKey = null;
+  // Serializes collections so their log slices never interleave.
+  let queue = Promise.resolve();
+
+  const toKey = sessionId => (sessionId ? String(sessionId) : '__no-session__');
+
+  const finalize = (options = {}) => {
+    const params = { ...getParams() };
+    if (options.sessionId !== undefined && options.sessionId !== null) params.sessionId = options.sessionId;
+
+    let sessionKey = toKey(params.sessionId);
+    if (options.force && options.sessionId === undefined && lastSessionKey) {
+      // Exit-time collection: the log tail belongs to the session collected
+      // most recently (which is a restart-iteration session, not the first one
+      // still referenced by the caller's `sessionId` variable).
+      sessionKey = lastSessionKey;
+      params.sessionId = sessionStartBytes.get(sessionKey)?.sessionId ?? params.sessionId;
+    }
+    const alreadyCollected = collections.has(sessionKey);
+
+    // Re-collecting the same session is only useful when the caller explicitly
+    // asks for it (process exit, to capture the log tail produced after the
+    // session finished). Otherwise reuse the memoized result.
+    if (alreadyCollected && !options.force) return collections.get(sessionKey);
+
+    lastSessionKey = sessionKey;
+
+    // Collections are serialized: each one commits and pushes, and the log
+    // slice boundaries only make sense when resolved sequentially.
+    const resultPromise = queue
+      .catch(() => {})
+      .then(() => {
+        const known = sessionStartBytes.get(sessionKey);
+        const logStartByte = known ? known.startByte : nextLogStartByte;
+        sessionStartBytes.set(sessionKey, { startByte: logStartByte, sessionId: params.sessionId ?? null });
+        return collect({ ...params, logStartByte });
+      })
+      .then(result => {
+        const endByte = result?.logEndByte;
+        if (typeof endByte === 'number' && endByte > nextLogStartByte) nextLogStartByte = endByte;
+        return result;
+      });
+
+    queue = resultPromise.catch(() => {});
+    collections.set(sessionKey, resultPromise);
     return resultPromise;
   };
+
+  finalize.getCollectedSessionKeys = () => [...collections.keys()];
+  // Publish the finalizer so restart iterations (watch mode,
+  // auto-restart-until-mergeable, keep-working, escalation, auto-ensure) and
+  // every exit path can collect the session they just finished.
+  if (register) setActiveDevelopmentLogFinalizer(finalize);
+  return finalize;
+};
+
+// Module-level registry so restart iterations deep in the call tree (watch
+// mode, auto-restart-until-mergeable, keep-working, escalation, auto-ensure)
+// can finalize the development log of the session they just finished without
+// threading the finalizer through every call signature.
+let activeFinalizer = null;
+
+export const setActiveDevelopmentLogFinalizer = finalizer => {
+  activeFinalizer = typeof finalizer === 'function' ? finalizer : null;
+};
+
+export const getActiveDevelopmentLogFinalizer = () => activeFinalizer;
+
+export const finalizeActiveDevelopmentLog = async (options = {}) => {
+  if (!activeFinalizer) return { skipped: 'no-active-finalizer' };
+  try {
+    return await activeFinalizer(options);
+  } catch (error) {
+    return { skipped: 'error', error };
+  }
 };

package/src/development-log.lib.mjs

@@ -1,6 +1,8 @@
 import fs from 'node:fs/promises';
+import { createReadStream, createWriteStream } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { pipeline } from 'node:stream/promises';
 
 const sanitizePathSegment = (value, fallback) => {
   const raw = value === null || value === undefined || value === '' ? fallback : String(value);
@@ -113,6 +115,23 @@ const findCodexSessionFile = async ({ sessionId, homeDir }) => {
   }
 };
 
+// Copy a byte range of the solve log into the session directory.
+// Issue #2090: each session stores only the slice of the process log that was
+// produced while that session was running, so the union of all session
+// directories is the complete log instead of N truncated copies of the same
+// prefix. Returns the byte offset right after the copied slice.
+const copyLogSlice = async ({ logFile, destinationPath, logStartByte = 0 }) => {
+  const stat = await fs.stat(logFile);
+  // The log was rotated/truncated since the previous collection: copy it whole.
+  const start = Number.isFinite(logStartByte) && logStartByte > 0 && logStartByte <= stat.size ? logStartByte : 0;
+  if (stat.size === 0 || start >= stat.size) {
+    await fs.writeFile(destinationPath, '');
+    return { logStartByte: start, logEndByte: stat.size };
+  }
+  await pipeline(createReadStream(logFile, { start, end: stat.size - 1 }), createWriteStream(destinationPath));
+  return { logStartByte: start, logEndByte: stat.size };
+};
+
 const copyKnownSessionFiles = async ({ repositoryPath, sessionRelativeDirectory, logFile, sessionId, tool, homeDir }) => {
   if (!sessionId) return [];
 
@@ -149,9 +168,16 @@ const copyKnownSessionFiles = async ({ repositoryPath, sessionRelativeDirectory,
 
   const copied = [];
   const seenSources = new Set();
+  // Issue #2090: when the tool renamed the running solve log to
+  // `<sessionId>.log`, this candidate resolves to the very log file that is
+  // already copied as solve.log — copying it again duplicated megabytes per
+  // session (PR link-assistant/formal-ai#809 stored two byte-identical 7 MB
+  // files). Skip it instead.
+  const resolvedLogFile = logFile ? path.resolve(logFile) : null;
   for (const candidate of candidates) {
     if (!candidate.sourcePath || seenSources.has(candidate.sourcePath)) continue;
     seenSources.add(candidate.sourcePath);
+    if (resolvedLogFile && path.resolve(candidate.sourcePath) === resolvedLogFile) continue;
 
     const relativePath = `${sessionRelativeDirectory}/${safeFileName(candidate.destinationName)}`;
     const copiedPath = path.join(sessionDirectory, safeFileName(candidate.destinationName));
@@ -163,7 +189,7 @@ const copyKnownSessionFiles = async ({ repositoryPath, sessionRelativeDirectory,
   return copied;
 };
 
-export const writeDevelopmentLogArtifacts = async ({ repositoryPath, logFile, issueNumber, prNumber, tool, sessionId, branchName, rawCommand, now = new Date(), homeDir = os.homedir() }) => {
+export const writeDevelopmentLogArtifacts = async ({ repositoryPath, logFile, issueNumber, prNumber, tool, sessionId, branchName, rawCommand, logStartByte = 0, now = new Date(), homeDir = os.homedir() }) => {
   if (!repositoryPath) {
     throw new Error('repositoryPath is required to write development-log artifacts');
   }
@@ -179,9 +205,14 @@ export const writeDevelopmentLogArtifacts = async ({ repositoryPath, logFile, is
   await fs.mkdir(sessionDirectory, { recursive: true });
 
   let copiedLogRelativePath = null;
+  let logSlice = { logStartByte: 0, logEndByte: 0 };
   if (logFile) {
     copiedLogRelativePath = `${sessionRelativeDirectory}/solve.log`;
-    await fs.copyFile(logFile, path.join(repositoryPath, copiedLogRelativePath));
+    logSlice = await copyLogSlice({
+      logFile,
+      destinationPath: path.join(repositoryPath, copiedLogRelativePath),
+      logStartByte,
+    });
   }
 
   const sessionFiles = await copyKnownSessionFiles({
@@ -195,7 +226,9 @@ export const writeDevelopmentLogArtifacts = async ({ repositoryPath, logFile, is
 
   const metadataRelativePath = `${sessionRelativeDirectory}/metadata.json`;
   const metadata = {
-    schemaVersion: 2,
+    // v3 (issue #2090): one directory per tool session, `solve.log` holds only
+    // this session's slice of the process log (see solveLogRange).
+    schemaVersion: 3,
     collectedAt: now.toISOString(),
     issueNumber: issueNumber ?? null,
     prNumber: prNumber ?? null,
@@ -207,6 +240,7 @@ export const writeDevelopmentLogArtifacts = async ({ repositoryPath, logFile, is
     caseStudyDirectory,
     artifacts: {
       solveLog: copiedLogRelativePath ? addDotSlash(toPosixPath(copiedLogRelativePath)) : null,
+      solveLogRange: copiedLogRelativePath ? { startByte: logSlice.logStartByte, endByte: logSlice.logEndByte } : null,
       sessionFiles,
     },
   };
@@ -221,12 +255,14 @@ export const writeDevelopmentLogArtifacts = async ({ repositoryPath, logFile, is
     copiedLogRelativePath: copiedLogRelativePath ? toPosixPath(copiedLogRelativePath) : null,
     metadataRelativePath: toPosixPath(metadataRelativePath),
     sessionFiles,
+    logStartByte: logSlice.logStartByte,
+    logEndByte: logSlice.logEndByte,
   };
 };
 
 const getCommandOutput = result => (result?.stderr?.toString?.() || result?.stdout?.toString?.() || '').trim();
 
-export const collectAndCommitDevelopmentLogArtifacts = async ({ enabled, repositoryPath, logFile, issueNumber, prNumber, tool, sessionId, branchName, rawCommand, $, log }) => {
+export const collectAndCommitDevelopmentLogArtifacts = async ({ enabled, repositoryPath, logFile, issueNumber, prNumber, tool, sessionId, branchName, rawCommand, logStartByte = 0, $, log }) => {
   if (!enabled) {
     return { skipped: 'disabled' };
   }
@@ -237,7 +273,7 @@ export const collectAndCommitDevelopmentLogArtifacts = async ({ enabled, reposit
   }
 
   // Issue #2048: verbose trace so the commit timing (relative to PR readiness signals) is diagnosable from logs.
-  await log?.(`🔍 Development log finalize: issue #${issueNumber ?? '?'}, PR #${prNumber ?? 'pending'}, branch ${branchName ?? 'none'}, session ${sessionId ?? 'none'}`, { verbose: true });
+  await log?.(`🔍 Development log finalize: issue #${issueNumber ?? '?'}, PR #${prNumber ?? 'pending'}, branch ${branchName ?? 'none'}, session ${sessionId ?? 'none'}, log slice from byte ${logStartByte}`, { verbose: true });
 
   try {
     const artifacts = await writeDevelopmentLogArtifacts({
@@ -249,8 +285,10 @@ export const collectAndCommitDevelopmentLogArtifacts = async ({ enabled, reposit
       sessionId,
       branchName,
       rawCommand,
+      logStartByte,
     });
 
+    await log?.(`🧾 Development log artifacts written to ${artifacts.sessionRelativeDirectory} (log bytes ${artifacts.logStartByte}-${artifacts.logEndByte})`, { verbose: true });
     await log?.(`🧾 Development log artifacts written to ${artifacts.developmentLogDirectory}`);
 
     if (!$) {

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/exit-handler.lib.mjs

@@ -9,6 +9,11 @@
 // Issue #1823: working-session guard for --do-not-shutdown-in-the-middle-of-working-session.
 // Static import is safe: working-session.lib.mjs has no heavy deps and does NOT import this module.
 import { isFlagEnabled as isWorkingSessionFlagEnabled, isWorkingSessionActive, requestShutdown as requestWorkingSessionShutdown, forceKillActiveChildren as forceKillWorkingSessionChildren } from './working-session.lib.mjs';
+// Issue #2090: preserve the development log on every exit path (usage limit
+// reached, tool failure, repository setup failure, graceful shutdown,
+// auto-continue hand-off). No-op unless solve registered a finalizer, so hive
+// and other consumers of this module are unaffected.
+import { finalizeActiveDevelopmentLog } from './development-log.finalize.lib.mjs';
 
 // Lazy-load Sentry to avoid keeping the event loop alive when not needed
 let Sentry = null;
@@ -241,6 +246,10 @@ export const logActiveHandles = async (log = null) => {
 export const safeExit = async (code = 0, reason = 'Process completed', { skipPreExit = false, failureActionSection = null } = {}) => {
   await showExitMessage(reason, code);
 
+  // Issue #2090: collect the working session that is still uncollected (and the
+  // log tail produced after it) before the process goes away.
+  await finalizeActiveDevelopmentLog({ force: true });
+
   if (!skipPreExit && code !== 0 && preExitFunction && !preExitHandlerRan) {
     preExitHandlerRan = true;
     try {

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/solve.restart-shared.lib.mjs

@@ -476,6 +476,18 @@ export const executeToolIteration = async params => {
     diskPath: '/',
     label: 'after AI restart iteration',
   });
+
+  // Issue #2090: every restart iteration starts a brand new tool session with
+  // its own session UUID. Collect its development log here — this is the single
+  // chokepoint shared by watch mode, auto-restart-until-mergeable,
+  // keep-working, escalation and auto-ensure — otherwise only the very first
+  // session of the process ever reached the pull request.
+  // When the tool did not report a session id there is nothing to key a new
+  // directory on, so extend the previously collected session instead of losing
+  // this iteration's part of the log.
+  const { finalizeActiveDevelopmentLog } = await import('./development-log.finalize.lib.mjs');
+  await (toolResult?.sessionId ? finalizeActiveDevelopmentLog({ sessionId: toolResult.sessionId }) : finalizeActiveDevelopmentLog({ force: true }));
+
   return toolResult;
 };
 

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;
+};