@link-assistant/hive-mind 2.11.2 → 2.11.4

package/src/solve.results.lib.mjs

@@ -67,6 +67,10 @@ const { reportError } = sentryLib;
 const prIssueLinking = await import('./pr-issue-linking.lib.mjs');
 const { buildIssueReference, ensureIssueLinkInPullRequestBody } = prIssueLinking;
 
+// Issue #2119: the one place that decides whether a pull request changed anything.
+const { formatChangeSummary, getPullRequestChangeStats } = await import('./pull-request-changes.lib.mjs');
+const { buildNoChangesNotice, redactWorkspacePaths } = await import('./working-session-summary.lib.mjs');
+
 /**
  * Placeholder patterns used to detect auto-generated PR content that was not updated by the agent.
  * These patterns match the initial WIP PR created by solve.auto-pr.lib.mjs.
@@ -158,7 +162,7 @@ export const ensurePullRequestIssueLink = async ({ prNumber, issueNumber, owner,
   await writeSanitizedPublicationFile(tempBodyFile, linkResult.body);
 
   try {
-    const updateResult = await command`gh pr edit ${prNumber} --repo ${owner}/${repo} --body-file "${tempBodyFile}"`;
+    const updateResult = await command`gh pr edit ${prNumber} --repo ${owner}/${repo} --body-file ${tempBodyFile}`;
     await fs.unlink(tempBodyFile).catch(() => {});
 
     if (updateResult.code === 0) {
@@ -787,7 +791,7 @@ export const verifyResults = async (owner, repo, branchName, issueNumber, prNumb
           if (prTitleHasPlaceholder && !argv.autoRestartOnNonUpdatedPullRequestDescription) {
             const updatedTitle = await sanitizeForPublication(pr.title.replace(/^\[WIP\]\s*/, ''));
             await log(`  📝 Removing [WIP] prefix from PR title...`);
-            const titleResult = await $`gh pr edit ${pr.number} --repo ${owner}/${repo} --title "${updatedTitle}"`;
+            const titleResult = await $`gh pr edit ${pr.number} --repo ${owner}/${repo} --title ${updatedTitle}`;
             if (titleResult.code === 0) {
               await log(`  ✅ Updated PR title to: "${updatedTitle}"`);
             } else {
@@ -801,14 +805,14 @@ export const verifyResults = async (owner, repo, branchName, issueNumber, prNumb
           if (hasPlaceholder && !argv.autoRestartOnNonUpdatedPullRequestDescription) {
             await log(`  📝 Updating PR description to remove placeholder text...`);
 
-            // Build a summary of the changes from the PR diff
-            const diffResult = await $`gh pr diff ${pr.number} --repo ${owner}/${repo} 2>&1`;
-            const diffOutput = diffResult.code === 0 ? diffResult.stdout.toString() : '';
-
-            // Count files changed
-            const filesChanged = (diffOutput.match(/^diff --git/gm) || []).length;
-            const additions = (diffOutput.match(/^\+[^+]/gm) || []).length;
-            const deletions = (diffOutput.match(/^-[^-]/gm) || []).length;
+            // Issue #2119: measure the net diff. The reproduction PRs published
+            // "1 file(s) modified, 1 line(s) added" for a pull request that
+            // changed nothing, because the stats were never checked for being
+            // empty.
+            const changeStats = await getPullRequestChangeStats({ owner, repo, prNumber: pr.number, $ });
+            if (!changeStats.hasChanges) {
+              await log(`  ⚠️  PR #${pr.number} has an empty diff - the description will say so instead of claiming changes`, { level: 'warning' });
+            }
 
             // Get the issue title for context
             const issueTitleResult = await $`gh issue view ${issueNumber} --repo ${owner}/${repo} --json title --jq .title 2>&1`;
@@ -822,9 +826,7 @@ export const verifyResults = async (owner, repo, branchName, issueNumber, prNumb
 This pull request implements a solution for ${issueRef}: ${issueTitle}
 
 ### Changes
-- ${filesChanged} file(s) modified
-- ${additions} line(s) added
-- ${deletions} line(s) removed
+${formatChangeSummary(changeStats)}
 
 ### Issue Reference
 Fixes ${issueRef}
@@ -836,7 +838,7 @@ Fixes ${issueRef}
             await writeSanitizedPublicationFile(tempBodyFile, newDescription);
 
             try {
-              const descResult = await $`gh pr edit ${pr.number} --repo ${owner}/${repo} --body-file "${tempBodyFile}"`;
+              const descResult = await $`gh pr edit ${pr.number} --repo ${owner}/${repo} --body-file ${tempBodyFile}`;
               await fs.unlink(tempBodyFile).catch(() => {});
 
               if (descResult.code === 0) {
@@ -1269,7 +1271,7 @@ export const buildWorkingSessionSummaryDetails = ({ publicPricingEstimate = null
   return `${costInfo}${budgetStats}`.trim();
 };
 
-export const attachSolutionSummary = async ({ resultSummary, prNumber, issueNumber, owner, repo, publicPricingEstimate = null, anthropicTotalCostUSD = null, pricingInfo = null, budgetStatsData = null }) => {
+export const attachSolutionSummary = async ({ resultSummary, prNumber, issueNumber, owner, repo, publicPricingEstimate = null, anthropicTotalCostUSD = null, pricingInfo = null, budgetStatsData = null, changeStats = null }) => {
   if (!resultSummary || typeof resultSummary !== 'string') {
     await log('⚠️  No working session summary available to attach', { verbose: true });
     return false;
@@ -1290,10 +1292,16 @@ export const attachSolutionSummary = async ({ resultSummary, prNumber, issueNumb
       pricingInfo,
       budgetStatsData,
     });
+    // Issue #2119: publish what the session actually produced. The reported
+    // summary said "The `pwd` command completed" and printed the solver's own
+    // /tmp workspace, on a pull request that was still empty.
+    const noChangesNotice = buildNoChangesNotice(changeStats);
+    const summaryBody = redactWorkspacePaths(resultSummary);
+
     const comment = `${toolComments.WORKING_SESSION_SUMMARY_AUTOMATION_MARKER}
 ## ${toolComments.WORKING_SESSION_SUMMARY_MARKER}
 
-${resultSummary}${usageDetails ? `\n\n${usageDetails}` : ''}
+${summaryBody}${noChangesNotice ? `\n\n${noChangesNotice}` : ''}${usageDetails ? `\n\n${usageDetails}` : ''}
 
 ---
 *${toolComments.WORKING_SESSION_SUMMARY_AUTOMATED_FOOTER}*`;
@@ -1395,6 +1403,10 @@ export const maybeAttachWorkingSessionSummary = async ({ argv, resultSummary, wo
           ...sessionUsage,
         })
       : null);
+  // Issue #2119: a summary posted on a pull request that changed nothing must
+  // say so, instead of reading as a report of completed work.
+  const changeStats = prNumber ? await getPullRequestChangeStats({ owner, repo, prNumber, $ }) : null;
+
   const ok = await attachSolutionSummary({
     resultSummary,
     prNumber,
@@ -1405,6 +1417,7 @@ export const maybeAttachWorkingSessionSummary = async ({ argv, resultSummary, wo
     anthropicTotalCostUSD,
     pricingInfo,
     budgetStatsData: resolvedBudgetStatsData,
+    changeStats,
   });
   return { attached: !!ok, reason: ok ? 'attached' : 'post_failed', budgetStatsData: resolvedBudgetStatsData };
 };

package/src/solve.watch.lib.mjs

@@ -46,7 +46,12 @@ const { checkGitHubTerminalState } = terminalStateLib;
 
 // Issue #1574: Interruptible sleep so CTRL+C is never blocked by a lingering timer
 const { interruptibleSleep } = await import('./interruptible-sleep.lib.mjs');
-const { formatAutoIterationLimit, hasReachedAutoIterationLimit, normalizeAutoIterationLimit } = await import('./auto-iteration-limits.lib.mjs');
+// Issue #2119: one auto-restart budget shared with solve.auto-merge.lib.mjs, so
+// a limit of 5 means 5 AI sessions in total rather than 5 per subsystem, and
+// every label renders in the same `N/M` form.
+const autoRestartBudget = await import('./auto-restart-budget.lib.mjs');
+const { beginAutoRestartBudget, consumeAutoRestartIteration, formatAutoRestartLabel, formatAutoRestartLimit, getAutoRestartIterationsUsed, getRemainingAutoRestartIterations, hasExhaustedAutoRestartBudget } = autoRestartBudget;
+const { failOnAutoRestartBudgetExhausted } = await import('./auto-restart-exhaustion.lib.mjs');
 
 // Issue #1625: Central marker constants + tracked comment posting
 const toolComments = await import('./tool-comments.lib.mjs');
@@ -78,7 +83,9 @@ export const watchForFeedback = async params => {
 
   const watchInterval = argv.watchInterval || 60; // seconds
   const isTemporaryWatch = argv.temporaryWatch || false;
-  const maxAutoRestartIterations = normalizeAutoIterationLimit(argv.autoRestartMaxIterations);
+  // Issue #2119: claim the shared budget; the same limit is honoured by the
+  // auto-merge restart loop that solve.mjs runs afterwards.
+  const maxAutoRestartIterations = beginAutoRestartBudget({ maxIterations: argv.autoRestartMaxIterations });
 
   // Track latest session data across all iterations for accurate pricing
   // Issue #1056: Seed from the *initial* tool execution so the first auto-restart
@@ -105,7 +112,7 @@ export const watchForFeedback = async params => {
     await log(formatAligned('', 'Monitoring PR:', `#${prNumber}`, 2));
     await log(formatAligned('', 'Mode:', 'Auto-restart (NOT --watch mode)', 2));
     await log(formatAligned('', 'Stop conditions:', 'All changes committed OR PR merged OR max iterations reached', 2));
-    await log(formatAligned('', 'Max iterations:', formatAutoIterationLimit(maxAutoRestartIterations), 2));
+    await log(formatAligned('', 'Max iterations:', formatAutoRestartLimit(), 2));
     await log(formatAligned('', 'Note:', 'No wait time between iterations in auto-restart mode', 2));
   } else {
     await log(formatAligned('👁️', 'WATCH MODE ACTIVATED', ''));
@@ -118,8 +125,12 @@ export const watchForFeedback = async params => {
   await log('');
 
   let iteration = 0;
-  let autoRestartCount = 0;
+  // Issue #2119: mirrors the shared budget counter so every label in this loop
+  // reports the run-wide iteration number, not a per-subsystem one.
+  let autoRestartCount = getAutoRestartIterationsUsed();
   let firstIterationInTemporaryMode = isTemporaryWatch;
+  // Issue #2119: set when the budget runs out, so the caller learns the run failed.
+  let budgetExhaustion = null;
 
   while (true) {
     iteration++;
@@ -211,13 +222,25 @@ export const watchForFeedback = async params => {
         break;
       }
 
-      // Check if we've reached max iterations
-      if (hasReachedAutoIterationLimit(autoRestartCount, maxAutoRestartIterations)) {
-        await log('');
-        await log(formatAligned('⚠️', 'MAX ITERATIONS REACHED', `Exiting auto-restart mode after ${autoRestartCount} iterations`));
-        await log(formatAligned('', 'Some uncommitted changes may remain', '', 2));
-        await log(formatAligned('', 'Please review and commit manually if needed', '', 2));
-        await log('');
+      // Issue #2119: the shared budget is exhausted. Previously this logged a
+      // warning and broke out of the loop, leaving the very uncommitted changes
+      // that triggered every restart on a temporary clone that is then deleted.
+      // Now the run fails and the work is auto-committed first, so the result
+      // stays visible in the PR.
+      if (hasExhaustedAutoRestartBudget()) {
+        const changes = await getUncommittedChangesDetails(tempDir);
+        budgetExhaustion = await failOnAutoRestartBudgetExhausted({
+          owner,
+          repo,
+          prNumber,
+          tempDir,
+          branchName: prBranch || branchName,
+          $,
+          log,
+          formatAligned,
+          blocker: changes.length > 0 ? `uncommitted changes remained: ${changes.join(', ')}` : 'uncommitted changes remained',
+          subsystem: 'auto-restart on uncommitted changes',
+        });
         break;
       }
     }
@@ -274,17 +297,18 @@ export const watchForFeedback = async params => {
           }
           await log('');
 
-          // Increment auto-restart counter and log restart number
-          autoRestartCount++;
+          // Issue #2119: claim one iteration from the run-wide budget shared with
+          // the auto-merge restart loop.
+          autoRestartCount = consumeAutoRestartIteration();
           autoRestartIterationsRan = true; // Issue #1290: Mark that auto-restart iterations ran
           lastIterationLogUploaded = false; // Reset log upload tracking for new iteration
-          const restartLabel = firstIterationInTemporaryMode ? 'Initial restart' : `Restart ${autoRestartCount}/${maxAutoRestartIterations}`;
+          const restartLabel = `Restart ${formatAutoRestartLabel(autoRestartCount)}`;
           await log(formatAligned('🔄', `${restartLabel}:`, `Running ${argv.tool.toUpperCase()} to handle uncommitted changes...`));
 
           // Post a comment to PR about auto-restart
           if (prNumber) {
             try {
-              const remainingIterations = maxAutoRestartIterations === 0 ? null : maxAutoRestartIterations - autoRestartCount;
+              const remainingIterations = getRemainingAutoRestartIterations();
 
               // Get uncommitted files list for the comment
               let uncommittedFilesList = '';
@@ -292,7 +316,7 @@ export const watchForFeedback = async params => {
                 uncommittedFilesList = '\n\n**Uncommitted files:**\n```\n' + changes.join('\n') + '\n```';
               }
 
-              const iterationLabel = maxAutoRestartIterations === 0 ? `${autoRestartCount}` : `${autoRestartCount}/${maxAutoRestartIterations}`;
+              const iterationLabel = formatAutoRestartLabel(autoRestartCount);
               const stopText = remainingIterations === null ? 'Auto-restart is configured with no iteration limit.' : `Auto-restart will stop after changes are committed or discarded, or after ${remainingIterations} more iteration${remainingIterations !== 1 ? 's' : ''}.`;
               const commentBody = `## 🔄 ${AUTO_RESTART_MARKER} ${iterationLabel}\n\nDetected uncommitted changes from previous run. Starting new session to review and commit or discard them.${uncommittedFilesList}\n\n---\n*${stopText} Please wait until working session will end and give your feedback.*`;
               // Issue #1625: Track so this doesn't falsely count as AI-authored.
@@ -471,7 +495,7 @@ export const watchForFeedback = async params => {
               const logFile = getLogFile();
               if (logFile) {
                 // Use "Auto-restart X/Y Failure Log" format to distinguish from success logs
-                const iterationLabel = maxAutoRestartIterations === 0 ? `${autoRestartCount}` : `${autoRestartCount}/${maxAutoRestartIterations}`;
+                const iterationLabel = formatAutoRestartLabel(autoRestartCount);
                 const customTitle = `⚠️ Auto-restart ${iterationLabel} Failure Log`;
                 const logUploadSuccess = await attachLogToGitHub({
                   logFile,
@@ -607,7 +631,7 @@ export const watchForFeedback = async params => {
               const logFile = getLogFile();
               if (logFile) {
                 // Use "Auto-restart X/Y Log" format as requested in issue #1107
-                const iterationLabel = maxAutoRestartIterations === 0 ? `${autoRestartCount}` : `${autoRestartCount}/${maxAutoRestartIterations}`;
+                const iterationLabel = formatAutoRestartLabel(autoRestartCount);
                 const customTitle = `🔄 Auto-restart ${iterationLabel} Log`;
                 const logUploadSuccess = await attachLogToGitHub({
                   logFile,
@@ -733,6 +757,11 @@ export const watchForFeedback = async params => {
     latestAnthropicCost,
     autoRestartIterationsRan, // True if any auto-restart iterations actually ran
     lastIterationLogUploaded, // True if the last iteration's logs were uploaded
+    // Issue #2119: false when the shared auto-restart budget ran out, so the run
+    // is reported as failed instead of silently exiting with work still pending.
+    success: !budgetExhaustion,
+    reason: budgetExhaustion?.reason || null,
+    autoRestartLimitReached: Boolean(budgetExhaustion),
   };
 };
 

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

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 import { wrapUseWithRetry } from './use-with-retry.lib.mjs';
+import { wrapUseWithSingleFlight } from './use-m-single-flight.lib.mjs';
 
 export const USE_M_BOOTSTRAP_URL = 'https://unpkg.com/use-m/use.js';
 // Issue #2113: the fallback is only reached when unpkg cannot serve the `latest`
@@ -9,8 +10,13 @@ export const USE_M_BOOTSTRAP_URL = 'https://unpkg.com/use-m/use.js';
 // dependency import to the least resilient loader available. 8.14.4 is the first
 // release that both repairs corrupt aliases (8.14.3, use-m #66/#67) and removes
 // them with a retry budget (8.14.4, use-m #68), so the degraded path now keeps
-// upstream recovery instead of losing it.
-export const USE_M_BOOTSTRAP_FALLBACK_URL = 'https://unpkg.com/use-m@8.14.4/use.js';
+// upstream recovery instead of losing it. 8.15.0 (use-m #70, the report filed
+// from this issue) additionally serialises installs of one alias across
+// processes with its own `.use-m/<alias>.lock` plus a post-install marker, so
+// the pinned fallback now carries upstream prevention too — verified with the
+// standalone reproduction: 8.14.4 fails 22/24 concurrent loads, 8.15.0 fails
+// 0/24 (docs/case-studies/issue-2113/raw/experiment-upstream-use-m-8.15.0-fixed.log).
+export const USE_M_BOOTSTRAP_FALLBACK_URL = 'https://unpkg.com/use-m@8.15.0/use.js';
 
 const isMissingUseMBundle = code => /^Not found: \/use-m@[^/]+\/use\.js\s*$/.test(code.trim());
 
@@ -62,9 +68,22 @@ export const ensureUseM = async (options = {}) => {
     // 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);
+    //
+    // Issue #2113: retrying alone is not enough. use-m runs one
+    // `npm install -g <alias>@npm:<pkg>@<version>` per `use()` call with no
+    // in-flight dedup, and 38 modules under src/ load command-stream through
+    // use(), 31 of them with a top-level
+    // `await use('command-stream')`. Node evaluates sibling top-level-await
+    // subgraphs concurrently, so a cold container fires dozens of simultaneous
+    // global installs of the *same* alias directory; they delete and re-extract
+    // each other's trees, producing the ENOTEMPTY and half-extracted-package
+    // failures recorded in the issue. Every retry re-enters the same race, so
+    // the single-flight layer wraps the retry layer: identical loads collapse
+    // into one install, and installs of the same alias are serialised within
+    // and across processes.
+    globalThis.use = wrapUseWithSingleFlight(wrapUseWithRetry(rawUse));
   } else {
-    globalThis.use = wrapUseWithRetry(globalThis.use);
+    globalThis.use = wrapUseWithSingleFlight(wrapUseWithRetry(globalThis.use));
   }
   return globalThis.use;
 };

package/src/use-m-single-flight.lib.mjs

@@ -0,0 +1,350 @@
+#!/usr/bin/env node
+
+/**
+ * Single-flight layer for `use-m` package loading (issue #2113).
+ *
+ * Root cause this file addresses
+ * -----------------------------
+ * `use-m` installs every package it resolves with a *global* npm install:
+ *
+ *     npm install -g <pkg>-v-<version>@npm:<pkg>@<version>
+ *
+ * and it has no in-flight deduplication — every `use(specifier)` call runs the
+ * full `ensurePackageInstalled` → `installPackage` path. Hive Mind has 36
+ * modules under `src/` whose module body starts with a top-level
+ * `await use('command-stream')`, and Node evaluates sibling top-level-await
+ * subgraphs *concurrently*. On a cold container that means dozens of
+ * simultaneous `npm install -g command-stream-v-latest@npm:command-stream@latest`
+ * processes writing into the same global `node_modules` directory.
+ *
+ * npm has no cross-process locking for the global prefix, so those installs
+ * delete and re-extract each other's trees. The two symptoms recorded in the
+ * issue are exactly what that race produces (both reproduced in
+ * `experiments/issue-2113/reproduce-concurrent-install-race.mjs`):
+ *
+ *   * `npm error ENOTEMPTY: directory not empty, rmdir
+ *     '<...>/command-stream-v-latest/examples'` — one npm is removing the alias
+ *     while another is extracting into it, so the directory it just emptied is
+ *     repopulated before the `rmdir`;
+ *   * a half-extracted tree that imports fine at the entry point but throws
+ *     `ERR_MODULE_NOT_FOUND` for an arbitrary internal file
+ *     (`shell-parser.mjs`, `terminal-capture.mjs`, `$.trace.mjs`).
+ *
+ * Retrying cannot fix this, because every retry re-enters the same race with
+ * the same 30-odd competitors — which is why use-m's own 3 install attempts and
+ * `useWithRetry`'s backoff both failed in the logs attached to the issue.
+ *
+ * The fix
+ * -------
+ * Make the install happen **once**:
+ *
+ *   1. in-process memoisation per specifier — the 36 concurrent
+ *      `use('command-stream')` calls collapse into one load (this also removes
+ *      35 redundant `npm show command-stream version` network round-trips);
+ *   2. an in-process mutex per npm *alias* — different specifiers that map to
+ *      the same alias (`yargs@17.7.2` and `yargs@17.7.2/helpers`) are
+ *      serialised, because they install the same directory;
+ *   3. a cross-process advisory lock per alias — two Hive Mind processes
+ *      started at the same time (worker + monitor, CI matrix jobs) share one
+ *      global `node_modules`, so the lock has to outlive a single process.
+ *
+ * The lock is deliberately *advisory and self-healing*: it is an atomic
+ * `mkdir`, refreshed by a heartbeat, stolen when stale, and abandoned (with a
+ * diagnostic) after a timeout. A stuck lock therefore degrades to today's
+ * behaviour instead of hanging Hive Mind.
+ */
+
+import os from 'node:os';
+import path from 'node:path';
+import { isBuiltin } from 'node:module';
+import { USE_RETRY_WRAPPED } from './use-with-retry.lib.mjs';
+
+export const DEFAULT_HEARTBEAT_MS = 1000;
+export const DEFAULT_STALE_MS = 15000;
+export const DEFAULT_POLL_MS = 100;
+export const DEFAULT_TIMEOUT_MS = 300000;
+
+const USE_SINGLE_FLIGHT_WRAPPED = Symbol.for('hive-mind.use-m-single-flight.wrapped');
+
+// Mirrors use-m's own parser (`parseModuleSpecifier`) so the alias computed
+// here is byte-identical to the directory npm will create.
+const SPECIFIER_PATTERN = /^(?<packageName>(@[^@/]+\/)?[^@/]+)?(?:@(?<version>[^/]*))?(?<modulePath>(?:\/[^@]+)*)?$/;
+
+/**
+ * @param {string} specifier
+ * @returns {{ packageName: string, version: string, modulePath: string } | null}
+ *   `null` for anything that use-m will not install from npm (builtins,
+ *   relative/absolute paths, unparseable input).
+ */
+export const parseSpecifier = specifier => {
+  if (typeof specifier !== 'string' || specifier.trim() === '') return null;
+  if (specifier.startsWith('.') || specifier.startsWith('/') || specifier.startsWith('node:')) return null;
+  const match = specifier.match(SPECIFIER_PATTERN);
+  const packageName = match?.groups?.packageName;
+  if (typeof packageName !== 'string' || packageName.trim() === '') return null;
+  const version = typeof match.groups.version === 'string' && match.groups.version.trim() !== '' ? match.groups.version : 'latest';
+  const modulePath = typeof match.groups.modulePath === 'string' ? match.groups.modulePath : '';
+  return { packageName, version, modulePath };
+};
+
+/**
+ * The global `node_modules` directory name use-m installs into, e.g.
+ * `use('command-stream')` → `command-stream-v-latest`.
+ *
+ * @param {string} specifier
+ * @returns {string | null}
+ */
+export const aliasForSpecifier = specifier => {
+  const parsed = parseSpecifier(specifier);
+  if (!parsed) return null;
+  return `${parsed.packageName.replace('@', '').replace('/', '-')}-v-${parsed.version}`;
+};
+
+/**
+ * Does loading this specifier run `npm install -g`?
+ *
+ * `use('fs')`, `use('path')` and `use('os')` account for 57 of Hive Mind's 128
+ * `use()` call sites; use-m answers them from its built-in resolver without
+ * touching npm, so they must not pay for (or wait on) an install lock. They are
+ * still memoised — 26 identical `use('fs')` calls should resolve one promise.
+ *
+ * @param {string} specifier
+ * @returns {boolean}
+ */
+export const installsFromNpm = specifier => {
+  const parsed = parseSpecifier(specifier);
+  if (!parsed) return false;
+  return !isBuiltin(`${parsed.packageName}${parsed.modulePath}`);
+};
+
+export const defaultLockRoot = () => process.env.HIVE_MIND_USE_M_LOCK_DIR || path.join(os.tmpdir(), 'hive-mind-use-m-locks');
+
+const defaultSleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+
+const defaultLog = message => {
+  if (process.env.HIVE_MIND_USE_M_DEBUG || process.argv.includes('--verbose')) {
+    console.error(`[use-m] ${message}`);
+  }
+};
+
+// `/` and `@` never survive alias generation, but a caller may lock on an
+// arbitrary key in tests — keep the lock directory name filesystem-safe.
+const lockDirectoryFor = (lockRoot, key) => path.join(lockRoot, `${key.replace(/[^\w.@-]+/g, '_')}.lock`);
+
+const noopRelease = async () => {};
+
+/**
+ * Acquire a cross-process advisory lock for one npm alias.
+ *
+ * The lock is a directory: `mkdir` is atomic on every filesystem Hive Mind runs
+ * on (ext4, overlayfs, fuse-overlayfs in the DinD image, tmpfs, APFS), unlike
+ * `writeFile` with `flag: 'wx'` on network filesystems.
+ *
+ * @param {string} key - alias name.
+ * @param {object} [options]
+ * @param {string} [options.lockRoot]
+ * @param {number} [options.heartbeatMs] - how often the owner refreshes mtime.
+ * @param {number} [options.staleMs] - age after which a lock may be stolen.
+ * @param {number} [options.pollMs] - wait between acquisition attempts.
+ * @param {number} [options.timeoutMs] - give up (and proceed unlocked) after this.
+ * @param {object} [options.fs] - injectable `node:fs/promises`.
+ * @param {(ms: number) => Promise<void>} [options.sleep]
+ * @param {() => number} [options.now]
+ * @param {(message: string) => void} [options.log]
+ * @returns {Promise<{ acquired: boolean, path: string, release: () => Promise<void> }>}
+ */
+export const acquireAliasLock = async (key, options = {}) => {
+  const fs = options.fs ?? (await import('node:fs/promises'));
+  const sleep = options.sleep ?? defaultSleep;
+  const now = options.now ?? Date.now;
+  const log = options.log ?? defaultLog;
+  const lockRoot = options.lockRoot ?? defaultLockRoot();
+  const heartbeatMs = options.heartbeatMs ?? DEFAULT_HEARTBEAT_MS;
+  const staleMs = options.staleMs ?? DEFAULT_STALE_MS;
+  const pollMs = options.pollMs ?? DEFAULT_POLL_MS;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const lockPath = lockDirectoryFor(lockRoot, key);
+  const startedAt = now();
+
+  try {
+    await fs.mkdir(lockRoot, { recursive: true });
+  } catch (error) {
+    // A lock root we cannot create means no cross-process protection; the
+    // in-process layers still dedupe, so continue instead of failing the load.
+    log(`lock root ${lockRoot} is unusable (${error?.message}); continuing without a cross-process lock`);
+    return { acquired: false, path: lockPath, release: noopRelease };
+  }
+
+  for (;;) {
+    try {
+      await fs.mkdir(lockPath);
+      // Best-effort ownership breadcrumb: it makes a stuck lock diagnosable
+      // (`cat /tmp/hive-mind-use-m-locks/<alias>.lock/owner.json`) but nothing
+      // depends on it being readable.
+      await fs.writeFile(path.join(lockPath, 'owner.json'), `${JSON.stringify({ pid: process.pid, hostname: os.hostname(), key, startedAt: new Date(startedAt).toISOString() }, null, 2)}\n`).catch(() => {});
+      log(`acquired install lock for '${key}' at ${lockPath}`);
+
+      // Keep the mtime fresh so other processes do not mistake a slow install
+      // (a cold `npm install -g` can take a minute) for a crashed owner.
+      const heartbeat = setInterval(() => {
+        const stamp = new Date(now());
+        Promise.resolve(fs.utimes(lockPath, stamp, stamp)).catch(() => {});
+      }, heartbeatMs);
+      heartbeat.unref?.();
+
+      let released = false;
+      const release = async () => {
+        if (released) return;
+        released = true;
+        clearInterval(heartbeat);
+        try {
+          await fs.rm(lockPath, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
+        } catch (error) {
+          log(`failed to release install lock ${lockPath}: ${error?.message}`);
+        }
+      };
+      return { acquired: true, path: lockPath, release };
+    } catch (error) {
+      if (error?.code !== 'EEXIST') {
+        log(`could not create install lock ${lockPath} (${error?.message}); continuing without a cross-process lock`);
+        return { acquired: false, path: lockPath, release: noopRelease };
+      }
+    }
+
+    const stats = await fs.stat(lockPath).catch(() => null);
+    if (!stats) continue; // owner released between mkdir and stat — retry immediately.
+
+    const age = now() - stats.mtimeMs;
+    if (age > staleMs) {
+      log(`stealing stale install lock ${lockPath} (idle for ${Math.round(age)}ms)`);
+      await fs.rm(lockPath, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 }).catch(() => {});
+      continue;
+    }
+
+    if (now() - startedAt > timeoutMs) {
+      log(`timed out after ${timeoutMs}ms waiting for install lock ${lockPath}; proceeding without it`);
+      return { acquired: false, path: lockPath, release: noopRelease };
+    }
+
+    await sleep(pollMs);
+  }
+};
+
+/**
+ * Serialise `fn` against every other caller holding the same alias, in this
+ * process and across processes.
+ *
+ * @param {string} key
+ * @param {() => Promise<T>} fn
+ * @param {object} [options] - forwarded to {@link acquireAliasLock}.
+ * @returns {Promise<T>}
+ * @template T
+ */
+export const withAliasLock = async (key, fn, options = {}) => {
+  if (options.disabled) return fn();
+  const lock = await acquireAliasLock(key, options);
+  try {
+    return await fn();
+  } finally {
+    await lock.release();
+  }
+};
+
+const createState = () => ({ inflight: new Map(), chains: new Map() });
+
+let sharedState = createState();
+
+/** Drop memoised loads and alias chains (tests only). */
+export const resetSingleFlightState = () => {
+  sharedState = createState();
+};
+
+const runOnAliasChain = (state, alias, fn) => {
+  const previous = state.chains.get(alias) ?? Promise.resolve();
+  // `.then(fn, fn)` so a failed predecessor does not strand the queue.
+  const result = previous.then(fn, fn);
+  const tail = result.then(
+    () => {},
+    () => {}
+  );
+  state.chains.set(alias, tail);
+  tail.then(() => {
+    if (state.chains.get(alias) === tail) state.chains.delete(alias);
+  });
+  return result;
+};
+
+/**
+ * Wrap a `use` function so concurrent loads of the same package collapse into a
+ * single npm install.
+ *
+ * Composition order matters: single-flight must sit **outside**
+ * `wrapUseWithRetry`, so that the retry/repair logic (which deletes and
+ * reinstalls the alias directory) also runs under the lock. The wrapper carries
+ * both wrapper symbols, which keeps `ensureUseM()` idempotent — re-wrapping an
+ * already-protected `globalThis.use` returns it unchanged instead of nesting
+ * retries inside locks inside retries.
+ *
+ * @param {Function} use
+ * @param {object} [options]
+ * @param {boolean} [options.disabled] - skip the cross-process lock only.
+ * @param {object} [options.state] - injectable memo/chain state (tests).
+ * @returns {Function}
+ */
+export const wrapUseWithSingleFlight = (use, options = {}) => {
+  if (typeof use !== 'function' || use[USE_SINGLE_FLIGHT_WRAPPED]) return use;
+  const log = options.log ?? defaultLog;
+  const disabled = options.disabled ?? Boolean(process.env.HIVE_MIND_USE_M_NO_LOCK);
+
+  const wrapped = (specifier, ...args) => {
+    const state = options.state ?? sharedState;
+    const alias = aliasForSpecifier(specifier);
+    // Relative imports resolve against the *caller's* directory, so neither
+    // memoising nor serialising them is safe — pass them straight through.
+    if (!alias) return use(specifier, ...args);
+
+    // Issue #2113: both failing runs were started with `--verbose` and the log
+    // showed only the final crash. Tracing every load (specifier, alias,
+    // duration) is what makes the next incident diagnosable from the log alone.
+    const call = async () => {
+      const startedAt = Date.now();
+      log(`use('${specifier}') loading (alias ${alias})`);
+      try {
+        const module = await use(specifier, ...args);
+        log(`use('${specifier}') loaded in ${Date.now() - startedAt}ms`);
+        return module;
+      } catch (error) {
+        log(`use('${specifier}') failed after ${Date.now() - startedAt}ms: ${error?.message}`);
+        throw error;
+      }
+    };
+    // Only npm-backed specifiers need the alias mutex and the file lock; a
+    // built-in has no install step to protect.
+    const start = installsFromNpm(specifier) ? () => runOnAliasChain(state, alias, () => withAliasLock(alias, call, { ...options, disabled, log })) : call;
+
+    // Extra arguments select a different resolver/context, so results are not
+    // interchangeable; those calls skip the memo but still take the lock.
+    if (args.length > 0) return start();
+
+    const pending = state.inflight.get(specifier);
+    if (pending) {
+      log(`use('${specifier}') joined an in-flight load (alias ${alias})`);
+      return pending;
+    }
+
+    const promise = start();
+    state.inflight.set(specifier, promise);
+    // Successful loads stay memoised for the process lifetime (Node caches the
+    // module anyway); failures are evicted so a later call can retry.
+    promise.catch(() => {
+      if (state.inflight.get(specifier) === promise) state.inflight.delete(specifier);
+    });
+    return promise;
+  };
+
+  Object.defineProperty(wrapped, USE_SINGLE_FLIGHT_WRAPPED, { value: true });
+  // Claim the retry symbol too: `wrapUseWithRetry` is always applied first
+  // (see ensureUseM), so an outer re-wrap would invert the intended order.
+  Object.defineProperty(wrapped, USE_RETRY_WRAPPED, { value: true });
+  return wrapped;
+};