@link-assistant/hive-mind 2.8.9 → 2.8.11

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @link-assistant/hive-mind
 
+## 2.8.11
+
+### Patch Changes
+
+- 55a318d: Keep locally provisioned `openai-curated` plugins visible when Codex's authenticated remote plugin catalog is enabled. The repository-scoped `remote_plugin` override is written in place for every TOML spelling of the setting, so an operator config that uses a dotted key or an inline table cannot produce a duplicate key that Codex refuses to load.
+
+## 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.11",
   "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/codex-capability-preflight.lib.mjs

@@ -219,7 +219,7 @@ const checkModelVisibleSkills = async ({ command, env, runCommand, log, required
   return { status: missing.length === 0 ? 'satisfied' : 'missing', visible, missing };
 };
 
-const skillVisibilityError = ({ missing, visible, requirements, repairs = [] }) => new CodexCapabilityPreflightError(`Codex reports the required plugins as installed, but the model cannot see: ${missing.join(', ')}. ` + `Codex exposes a plugin's skills only while its payload is materialized under ` + `CODEX_HOME/plugins/cache/<marketplace>/<plugin>/<version>/skills. ` + `Visible skills were: ${visible ? [...visible].sort().join(', ') || 'none' : 'unknown'}.` + (repairs.length > 0 ? ` Attempted repairs: ${repairs.join(', ')}.` : ''), { missing, failClosed: missing.some(skill => isExplicitRequirement(requirements, skill)) });
+const skillVisibilityError = ({ missing, visible, requirements, repairs = [] }) => new CodexCapabilityPreflightError(`Codex reports the required plugins as installed, but the model cannot see: ${missing.join(', ')}. ` + `A plugin must survive Codex loader reconciliation and have a valid payload under ` + `CODEX_HOME/plugins/cache/<marketplace>/<plugin>/<version>/skills before its skills are exposed. ` + `Visible skills were: ${visible ? [...visible].sort().join(', ') || 'none' : 'unknown'}.` + (repairs.length > 0 ? ` Attempted repairs: ${repairs.join(', ')}.` : ''), { missing, failClosed: missing.some(skill => isExplicitRequirement(requirements, skill)) });
 
 const verifyModelVisibleSkills = async ({ command, env, runCommand, log, requiredSkills, requirements }) => {
   const outcome = await checkModelVisibleSkills({ command, env, runCommand, log, requiredSkills });
@@ -316,10 +316,10 @@ export async function resolveRequiredPlugins(options) {
   return (await resolveRequiredCapabilities(options)).plugins;
 }
 
-const readIssueRequirementText = async ({ owner, repo, issueNumber, runCommand }) => {
-  const issueResult = await runCommand({ command: 'gh', args: ['api', `repos/${owner}/${repo}/issues/${issueNumber}`], env: process.env });
+const readIssueRequirementText = async ({ owner, repo, issueNumber, runCommand, env }) => {
+  const issueResult = await runCommand({ command: 'gh', args: ['api', `repos/${owner}/${repo}/issues/${issueNumber}`], env });
   const issue = parseJsonCommand(issueResult, 'Codex capability issue discovery');
-  const commentsResult = await runCommand({ command: 'gh', args: ['api', `repos/${owner}/${repo}/issues/${issueNumber}/comments`, '--paginate'], env: process.env });
+  const commentsResult = await runCommand({ command: 'gh', args: ['api', `repos/${owner}/${repo}/issues/${issueNumber}/comments`, '--paginate'], env });
   const comments = parseJsonCommand(commentsResult, 'Codex capability comment discovery');
   return [issue?.title, issue?.body, ...(Array.isArray(comments) ? comments.map(comment => comment?.body) : [])].filter(Boolean).join('\n');
 };
@@ -358,6 +358,128 @@ const readIfPresent = async filePath => {
   }
 };
 
+const escapeRegExp = value => String(value).replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+
+// A line inside a multi-line string is data, not structure: `[plugins."x"]`
+// written inside `"""…"""` is a string, and treating it as a table header would
+// splice a key into the operator's value.
+const markStructuralLines = lines => {
+  const structural = [];
+  let openDelimiter = null;
+  for (const line of lines) {
+    structural.push(openDelimiter === null);
+    let rest = line;
+    for (;;) {
+      if (openDelimiter) {
+        const closeIndex = rest.indexOf(openDelimiter);
+        if (closeIndex === -1) break;
+        rest = rest.slice(closeIndex + openDelimiter.length);
+        openDelimiter = null;
+        continue;
+      }
+      const opened = /"""|'''/u.exec(rest);
+      if (!opened) break;
+      openDelimiter = opened[0];
+      rest = rest.slice(opened.index + opened[0].length);
+    }
+  }
+  return structural;
+};
+
+// TOML accepts the same setting as a header table, a dotted key, or an inline
+// table. Appending `[features]` next to any of the other two is a duplicate-key
+// document that Codex refuses to load, which would break every scoped
+// invocation for the repository — so each spelling is edited in place.
+export const setTomlTableBoolean = ({ config, table, key, value }) => {
+  const lines = String(config || '')
+    .replace(/\r\n/gu, '\n')
+    .split('\n');
+  const structural = markStructuralLines(lines);
+  const [escapedTable, escapedKey] = [escapeRegExp(table), escapeRegExp(key)];
+  const quoted = name => `(?:${name}|"${name}"|'${name}')`;
+  const tableHeaderPattern = new RegExp(`^\\s*\\[\\s*${quoted(escapedTable)}\\s*\\]\\s*(?:#.*)?$`, 'u');
+  const anyTableHeaderPattern = /^\s*\[\[?[^\]]*\]\]?\s*(?:#.*)?$/u;
+  // The value is everything before an optional trailing comment, so a comment
+  // an operator attached to the setting survives the rewrite.
+  const assignmentPattern = name => new RegExp(`^(\\s*${name}\\s*=\\s*)([^#]*?)(\\s*(?:#.*)?)$`, 'u');
+  const keyPattern = assignmentPattern(quoted(escapedKey));
+  const dottedPattern = assignmentPattern(`${quoted(escapedTable)}\\s*\\.\\s*${quoted(escapedKey)}`);
+  const inlineTablePattern = new RegExp(`^(\\s*${quoted(escapedTable)}\\s*=\\s*\\{)([^}]*)(\\}\\s*(?:#.*)?)$`, 'u');
+  const finish = () => `${lines.join('\n').trimEnd()}\n`;
+  const isStructural = index => structural[index];
+
+  const tableStart = lines.findIndex((line, index) => isStructural(index) && tableHeaderPattern.test(line));
+  if (tableStart !== -1) {
+    let tableEnd = lines.length;
+    for (let index = tableStart + 1; index < lines.length; index++) {
+      if (isStructural(index) && anyTableHeaderPattern.test(lines[index])) {
+        tableEnd = index;
+        break;
+      }
+    }
+    for (let index = tableStart + 1; index < tableEnd; index++) {
+      // Any existing value is replaced, not only a boolean literal: leaving a
+      // stale `remote_plugin = 1` behind and appending a second assignment is
+      // also a duplicate key.
+      if (isStructural(index) && keyPattern.test(lines[index])) {
+        lines[index] = lines[index].replace(keyPattern, `$1${value}$3`);
+        return finish();
+      }
+    }
+    // Insert after the table's last content line so the key is not separated
+    // from its own table by the blank lines that precede the next one.
+    let insertAt = tableEnd;
+    while (insertAt > tableStart + 1 && lines[insertAt - 1].trim() === '') insertAt--;
+    lines.splice(insertAt, 0, `${key} = ${value}`);
+    return finish();
+  }
+
+  // Outside any table header the operator may have used a dotted key or an
+  // inline table for the same setting.
+  const rootEnd = lines.findIndex((line, index) => isStructural(index) && anyTableHeaderPattern.test(line));
+  const rootLimit = rootEnd === -1 ? lines.length : rootEnd;
+  for (let index = 0; index < rootLimit; index++) {
+    if (!isStructural(index)) continue;
+    if (dottedPattern.test(lines[index])) {
+      lines[index] = lines[index].replace(dottedPattern, `$1${value}$3`);
+      return finish();
+    }
+    const inlineTable = inlineTablePattern.exec(lines[index]);
+    if (inlineTable) {
+      const [, prefix, contents, suffix] = inlineTable;
+      // The trailing separator is captured so the operator's spacing inside the
+      // braces survives the rewrite.
+      const inlineKeyPattern = new RegExp(`(^|,)(\\s*${quoted(escapedKey)}\\s*=\\s*)[^,]*?(\\s*)(,|$)`, 'u');
+      const nextContents = inlineKeyPattern.test(contents) ? contents.replace(inlineKeyPattern, `$1$2${value}$3$4`) : `${contents.trim() ? `${contents.trimEnd()}, ` : ' '}${key} = ${value} `;
+      lines[index] = `${prefix}${nextContents}${suffix}`;
+      return finish();
+    }
+  }
+
+  while (lines.length > 0 && lines.at(-1) === '') lines.pop();
+  if (lines.length > 0) lines.push('');
+  lines.push(`[${table}]`, `${key} = ${value}`, '');
+  return lines.join('\n');
+};
+
+// Codex's authenticated remote global catalog owns the reserved
+// `openai-curated` marketplace. In codex-rs 0.144.6 the prompt loader removes
+// every locally configured plugin from that marketplace before merging remote
+// installations. Hive provisions the local marketplace payload, so the scoped
+// home must select that local catalog or plugin list and prompt assembly report
+// contradictory states (issue #2094). This override is deliberately scoped to
+// runs that selected a local curated plugin; personal marketplaces retain the
+// operator's remote catalog setting.
+const configureScopedPluginLoader = async ({ codexHome, plugins, log }) => {
+  const localCurated = plugins.filter(plugin => pluginIdParts(plugin).marketplace === 'openai-curated');
+  if (localCurated.length === 0) return;
+  const configPath = path.join(codexHome, 'config.toml');
+  const config = await readIfPresent(configPath);
+  const nextConfig = setTomlTableBoolean({ config, table: 'features', key: 'remote_plugin', value: false });
+  if (nextConfig !== config) await fs.writeFile(configPath, nextConfig);
+  await log(`   🧭 Scoped Codex loader: remote_plugin=false for ${localCurated.join(', ')}; an authenticated remote catalog otherwise removes local @openai-curated entries before prompt assembly`, { verbose: true });
+};
+
 // Runtime settings follow the operator config while plugin enablement remains
 // persistent and isolated to this repository.
 const syncScopedConfig = async ({ baseConfigPath, scopedConfigPath }) => {
@@ -464,13 +586,13 @@ export async function runCodexCapabilityPreflight(options = {}) {
   }
 }
 
-async function provisionCodexCapabilities({ owner, repo, issueNumber, projectDir, baseCodexHome = process.env.HIVE_MIND_PARENT_CODEX_HOME || process.env.CODEX_HOME || path.join(os.homedir(), '.codex'), codexPath = 'codex', runCommand = defaultRunCommand, log = async () => {} } = {}) {
+async function provisionCodexCapabilities({ owner, repo, issueNumber, projectDir, env = process.env, baseCodexHome = env.HIVE_MIND_PARENT_CODEX_HOME || env.CODEX_HOME || path.join(os.homedir(), '.codex'), codexPath = 'codex', runCommand = defaultRunCommand, log = async () => {} } = {}) {
   if (!owner || !repo || !issueNumber) return { required: false, plugins: [], codexHome: null };
 
   // `executeToolWithBun` uses a shell expression for execution. Preflight uses
   // execFile and therefore selects the installed Codex binary directly.
   const command = /\s/u.test(codexPath) ? 'codex' : codexPath;
-  const requirementText = await readIssueRequirementText({ owner, repo, issueNumber, runCommand });
+  const requirementText = await readIssueRequirementText({ owner, repo, issueNumber, runCommand, env });
   const requirements = detectRequiredCodexCapabilities(requirementText);
   for (const { capability, line } of requirements.rejected || []) {
     await log(`   ⏭️  Ignored non-capability token '${capability}' from: ${line.slice(0, 160)}`, { verbose: true });
@@ -481,8 +603,13 @@ async function provisionCodexCapabilities({ owner, repo, issueNumber, projectDir
   for (const { capability, line } of requirements.evidence || []) {
     await log(`   🔎 '${capability}' detected from: ${line.slice(0, 160)}`, { verbose: true });
   }
-  const baseEnv = { ...process.env, CODEX_HOME: baseCodexHome, HIVE_MIND_PARENT_CODEX_HOME: baseCodexHome };
-  const baseCatalogResult = await runCommand({ command, args: ['plugin', 'list', '--available', '--json'], env: baseEnv });
+  // Every Codex-side preflight operation runs from the checkout that the
+  // solver will enter. Besides matching `codex exec`, this keeps any future
+  // repository-local discovery deterministic without relying on Hive's launch
+  // directory (issue #2094).
+  const runCodexCommand = invocation => runCommand({ ...invocation, cwd: projectDir });
+  const baseEnv = { ...env, CODEX_HOME: baseCodexHome, HIVE_MIND_PARENT_CODEX_HOME: baseCodexHome };
+  const baseCatalogResult = await runCodexCommand({ command, args: ['plugin', 'list', '--available', '--json'], env: baseEnv });
   const baseCatalog = parseJsonCommand(baseCatalogResult, 'Codex plugin catalog discovery');
   const skillDirectories = [path.join(os.homedir(), '.agents', 'skills'), projectDir && path.join(projectDir, '.agents', 'skills')].filter(Boolean);
   const { plugins, providers } = await resolveRequiredCapabilities({ requirements, catalog: baseCatalog, skillDirectories });
@@ -491,24 +618,25 @@ async function provisionCodexCapabilities({ owner, repo, issueNumber, projectDir
   }
   if (plugins.length === 0) {
     await log('   ✅ Required Agent Skills are already available from standard skill directories');
-    await verifyModelVisibleSkills({ command, env: baseEnv, runCommand, log, requiredSkills: requirements.skills, requirements });
+    await verifyModelVisibleSkills({ command, env: baseEnv, runCommand: runCodexCommand, log, requiredSkills: requirements.skills, requirements });
     return { required: true, plugins, skills: requirements.skills, codexHome: null, baseCodexHome };
   }
 
   const codexHome = buildCodexCapabilityStatePath({ baseCodexHome, owner, repo });
   await prepareScopedCodexHome({ baseCodexHome, codexHome });
-  const scopedEnv = { ...process.env, CODEX_HOME: codexHome, HIVE_MIND_PARENT_CODEX_HOME: baseCodexHome };
+  await configureScopedPluginLoader({ codexHome, plugins, log });
+  const scopedEnv = { ...env, CODEX_HOME: codexHome, HIVE_MIND_PARENT_CODEX_HOME: baseCodexHome };
 
   // Issue #2088: install *and repair*. Enablement recorded in the scoped
   // `config.toml` survives a container restart while the payload under
   // `plugins/cache` may not, and `codex plugin list` cannot tell those states
   // apart — so the payload itself is the thing that gets checked and rebuilt.
-  const repair = await repairScopedPluginPayloads({ command, env: scopedEnv, runCommand, log, codexHome, baseCodexHome, plugins, providers });
+  const repair = await repairScopedPluginPayloads({ command, env: scopedEnv, runCommand: runCodexCommand, log, codexHome, baseCodexHome, plugins, providers });
   for (const entry of repair.report) {
     if (entry.healthy) await log(`   ✅ Provisioned ${entry.pluginId} in repository-scoped Codex state`);
   }
 
-  const verifyResult = await runCommand({ command, args: ['plugin', 'list', '--json'], env: scopedEnv });
+  const verifyResult = await runCodexCommand({ command, args: ['plugin', 'list', '--json'], env: scopedEnv });
   const verifiedCatalog = parseJsonCommand(verifyResult, 'Codex capability verification');
   const verified = new Set((verifiedCatalog.installed || []).filter(plugin => plugin.installed && plugin.enabled).map(plugin => normalizePluginSelector(plugin.pluginId)));
   const unverified = plugins.filter(plugin => !verified.has(plugin));
@@ -525,14 +653,14 @@ async function provisionCodexCapabilities({ owner, repo, issueNumber, projectDir
   // the model saw zero `superpowers:*` skills, so the run proceeded and then
   // stalled on the repository's mandatory preflight. Confirm the requirement
   // against the catalog the model actually receives.
-  let visibility = await checkModelVisibleSkills({ command, env: scopedEnv, runCommand, log, requiredSkills: requirements.skills });
+  let visibility = await checkModelVisibleSkills({ command, env: scopedEnv, runCommand: runCodexCommand, log, requiredSkills: requirements.skills });
   if (visibility.status === 'missing') {
     // The payload looks materialized but the prompt disagrees: rebuild it from
     // scratch and re-probe before deciding (issue #2088).
     await log(`   🛠️  Model cannot see ${visibility.missing.join(', ')}; forcing a repository-scoped plugin payload rebuild`);
-    const forced = await repairScopedPluginPayloads({ command, env: scopedEnv, runCommand, log, codexHome, baseCodexHome, plugins, providers, strategies: PLUGIN_PAYLOAD_REPAIRS.slice(1), force: true });
+    const forced = await repairScopedPluginPayloads({ command, env: scopedEnv, runCommand: runCodexCommand, log, codexHome, baseCodexHome, plugins, providers, strategies: PLUGIN_PAYLOAD_REPAIRS.slice(1), force: true });
     repair.applied.push(...forced.applied);
-    visibility = await checkModelVisibleSkills({ command, env: scopedEnv, runCommand, log, requiredSkills: requirements.skills });
+    visibility = await checkModelVisibleSkills({ command, env: scopedEnv, runCommand: runCodexCommand, log, requiredSkills: requirements.skills });
   }
   if (visibility.status === 'missing') throw skillVisibilityError({ missing: visibility.missing, visible: visibility.visible, requirements, repairs: repair.applied });
   if (visibility.status === 'unknown' && repair.unhealthy.length > 0) {
@@ -556,4 +684,5 @@ export default {
   repairScopedPluginPayloads,
   resolveRequiredCapabilities,
   runCodexCapabilityPreflight,
+  setTomlTableBoolean,
 };

package/src/codex.lib.mjs

@@ -744,8 +744,8 @@ export const executeCodex = async params => {
   // Issue #1877: deploy the experimental HANDOFF.md Agent Skill so Codex loads
   // it natively from .agents/skills/handoff/SKILL.md (no-op unless --use-handoff).
   await deployHandoffSkill({ tempDir, argv, log, $ });
-
-  const capabilityPreflight = await runCodexCapabilityPreflight({ owner, repo, issueNumber, projectDir: tempDir, codexPath, log });
+  const codexBaseEnv = getCodexExecEnv(argv.verbose);
+  const capabilityPreflight = await runCodexCapabilityPreflight({ owner, repo, issueNumber, projectDir: tempDir, codexPath, log, env: codexBaseEnv });
   // Execute the Codex command
   return await executeCodexCommand({
     tempDir,
@@ -763,7 +763,7 @@ export const executeCodex = async params => {
     owner,
     repo,
     prNumber,
-    capabilityPreflight,
+    capabilityPreflight: { ...capabilityPreflight, codexBaseEnv },
   });
 };
 
@@ -809,7 +809,7 @@ export const executeCodexCommand = async params => {
     const mappedModel = mapModelToId(argv.model);
     const { reasoningEffort, source: reasoningEffortSource, rolloutTokenBudget } = resolveCodexReasoningEffort(argv);
     const isResumeMode = !!argv.resume;
-    const codexEnv = applyCodexCapabilityEnv(getCodexExecEnv(argv.verbose), {
+    const codexEnv = applyCodexCapabilityEnv(capabilityPreflight?.codexBaseEnv || getCodexExecEnv(argv.verbose), {
       codexHome: capabilityPreflight?.codexHome,
       baseCodexHome: capabilityPreflight?.baseCodexHome,
     });

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