@link-assistant/hive-mind 1.58.0 → 1.59.1

package/src/github-merge.lib.mjs

@@ -342,7 +342,9 @@ export async function checkPRCIStatus(owner, repo, prNumber, verbose = false) {
     // ([].every(fn) returns true for any fn).
     if (allChecks.length === 0) {
       if (verbose) {
-        console.log(`[VERBOSE] /merge: PR #${prNumber} has no CI checks yet - treating as pending`);
+        // Issue #1712: Reword for clarity — empty check-runs API response, not "no CI configured".
+        const commitUrl = `https://github.com/${owner}/${repo}/commit/${sha}`;
+        console.log(`[VERBOSE] /merge: PR #${prNumber} HEAD ${commitUrl} has no check-runs/statuses registered yet — treating as pending`);
       }
       return {
         status: 'pending',
@@ -1070,6 +1072,8 @@ export async function getDetailedCIStatus(owner, repo, prNumber, verbose = false
     const statuses = JSON.parse(statusJson.trim() || '[]');
 
     // Build detailed checks list
+    // Issue #1712: Include html_url so the user-facing waiting message can include
+    // a clickable link for each pending/failing check.
     const allChecks = [
       ...checkRuns.map(check => ({
         name: check.name,
@@ -1077,6 +1081,7 @@ export async function getDetailedCIStatus(owner, repo, prNumber, verbose = false
         conclusion: check.conclusion, // success, failure, cancelled, timed_out, skipped, neutral, action_required, stale, null
         type: 'check_run',
         id: check.id,
+        html_url: check.html_url || check.details_url || null,
       })),
       ...statuses.map(status => ({
         name: status.context,
@@ -1084,13 +1089,20 @@ export async function getDetailedCIStatus(owner, repo, prNumber, verbose = false
         conclusion: status.state === 'pending' ? null : status.state === 'success' ? 'success' : status.state === 'failure' ? 'failure' : status.state,
         type: 'status',
         id: null,
+        html_url: status.target_url || null,
       })),
     ];
 
     // No checks yet
     if (allChecks.length === 0) {
       if (verbose) {
-        console.log(`[VERBOSE] /merge: PR #${prNumber} has no CI checks yet - treating as no_checks`);
+        // Issue #1712: Reword to avoid "no CI checks" sounding like "no CI configured".
+        // We are inspecting the GitHub `/commits/{sha}/check-runs` and `/commits/{sha}/status` endpoints;
+        // an empty result means no check-runs/statuses are registered yet for this commit, NOT that the
+        // repository has no CI/CD workflows. The caller (`getMergeBlockers`) decides between race
+        // condition vs. "no CI configured" based on additional API calls.
+        const commitUrl = `https://github.com/${owner}/${repo}/commit/${sha}`;
+        console.log(`[VERBOSE] /merge: PR #${prNumber} HEAD ${commitUrl} has no check-runs or commit statuses registered yet (status=no_checks; race vs. no-CI distinction is decided downstream)`);
       }
       return {
         status: 'no_checks',
@@ -1213,9 +1225,14 @@ export async function getWorkflowRunsForSha(owner, repo, sha, verbose = false) {
       .map(run => ({ id: run.id, status: run.status, conclusion: run.conclusion, name: run.name, html_url: run.html_url, path: run.path }));
 
     if (verbose) {
-      console.log(`[VERBOSE] /merge: Found ${runs.length} workflow runs for SHA ${sha.substring(0, 7)}`);
+      // Issue #1712: Include the commit URL (not just SHA) and the workflow run html_url
+      // so the user can click through to GitHub instead of pasting IDs into a URL by hand.
+      // The run html_url already encodes the run ID, so we don't repeat it as a separate field.
+      const commitUrl = `https://github.com/${owner}/${repo}/commit/${sha}`;
+      console.log(`[VERBOSE] /merge: Found ${runs.length} workflow run(s) for ${commitUrl}`);
       for (const run of runs) {
-        console.log(`[VERBOSE] /merge:   - ${run.name} (${run.id}): status=${run.status}, conclusion=${run.conclusion}`);
+        const concPart = run.conclusion ? `/${run.conclusion}` : '';
+        console.log(`[VERBOSE] /merge:   - ${run.name} [${run.status}${concPart}]: ${run.html_url}`);
       }
     }
 
@@ -1333,8 +1350,8 @@ export { getCommitDate, checkPreviousPRCommitsHadCI, checkWorkflowsHavePRTrigger
 import { waitForCommitCI, checkBranchCIHealth, getMergeCommitSha } from './github-merge-ci.lib.mjs';
 export { waitForCommitCI, checkBranchCIHealth, getMergeCommitSha };
 
-import { getAllActiveRepoRuns, waitForAllRepoActions, checkCIConsensus, checkAllPRCommitsCI, getPRCommitShas } from './github-merge-repo-actions.lib.mjs'; // Issue #1503
-export { getAllActiveRepoRuns, waitForAllRepoActions, checkCIConsensus, checkAllPRCommitsCI, getPRCommitShas };
+import { getAllActiveRepoRuns, waitForAllRepoActions, checkCIConsensus, checkAllPRCommitsCI, getPRCommitShas, getActivePRWorkflowRuns } from './github-merge-repo-actions.lib.mjs'; // Issue #1503, #1712
+export { getAllActiveRepoRuns, waitForAllRepoActions, checkCIConsensus, checkAllPRCommitsCI, getPRCommitShas, getActivePRWorkflowRuns };
 
 export default {
   READY_LABEL,
@@ -1376,4 +1393,5 @@ export default {
   getAllActiveRepoRuns,
   waitForAllRepoActions,
   checkCIConsensus, // Issue #1503
+  getActivePRWorkflowRuns, // Issue #1712: list active runs across ALL PR commits
 };

package/src/lino.lib.mjs

@@ -2,7 +2,9 @@ if (typeof use === 'undefined') {
   globalThis.use = (await eval(await (await fetch('https://unpkg.com/use-m/use.js')).text())).use;
 }
 
-const linoModule = await use('links-notation');
+// Issue #1710: hosted CI npm-install flake — retry once on a corrupt install.
+const { useWithRetry } = await import('./use-with-retry.lib.mjs');
+const linoModule = await useWithRetry(globalThis.use, 'links-notation');
 const LinoParser = linoModule.Parser || linoModule.default?.Parser;
 
 const fs = await import('fs');

package/src/queue-config.lib.mjs

@@ -36,10 +36,15 @@ if (typeof globalThis.use === 'undefined') {
   }
 }
 
-const getenvModule = await use('getenv');
+// Issue #1710 / #1712: use-m occasionally hands back a truncated/corrupt global
+// package on hosted CI (npm install -g flake — manifests as ERR_INVALID_PACKAGE_CONFIG,
+// "Failed to resolve the path", or SyntaxError mid-import). useWithRetry deletes
+// the broken install dir and re-fetches.
+const { useWithRetry } = await import('./use-with-retry.lib.mjs');
+const getenvModule = await useWithRetry(globalThis.use, 'getenv');
 // Node 24 CJS/ESM interop may return the whole module object instead of the function directly
 const getenv = typeof getenvModule === 'function' ? getenvModule : getenvModule.default || getenvModule;
-const linoModule = await use('links-notation');
+const linoModule = await useWithRetry(globalThis.use, 'links-notation');
 const LinoParser = linoModule.Parser || linoModule.default?.Parser;
 
 /**

package/src/solve.auto-merge-helpers.lib.mjs

@@ -33,7 +33,43 @@ const { reportError } = sentryLib;
 
 // Import GitHub merge functions
 const githubMergeLib = await import('./github-merge.lib.mjs');
-const { checkPRMergeable, checkForBillingLimitError, getDetailedCIStatus, getWorkflowRunsForSha, getWorkflowRunJobsCount, getActiveRepoWorkflows, getCommitDate, checkWorkflowsHavePRTriggers, checkPreviousPRCommitsHadCI } = githubMergeLib;
+const { checkPRMergeable, checkForBillingLimitError, getDetailedCIStatus, getWorkflowRunsForSha, getWorkflowRunJobsCount, getActiveRepoWorkflows, getCommitDate, checkWorkflowsHavePRTriggers, checkPreviousPRCommitsHadCI, getActivePRWorkflowRuns } = githubMergeLib;
+
+/**
+ * Issue #1712: Plain-English meaning of GitHub Actions / check-run statuses, so the
+ * verbose log explains itself instead of forcing the user to look up GitHub docs.
+ * Returns the same status string suffixed with a parenthetical hint, e.g.
+ * "in_progress (currently executing)". Unknown statuses are returned unchanged.
+ */
+const STATUS_HINTS = {
+  in_progress: 'currently executing',
+  queued: 'waiting for a runner',
+  pending: 'waiting to start',
+  waiting: 'blocked on a deployment / approval gate',
+  requested: 'requested but not yet picked up',
+  completed: 'finished',
+};
+const CONCLUSION_HINTS = {
+  success: 'passed',
+  failure: 'failed',
+  cancelled: 'cancelled (will be re-triggered if applicable)',
+  timed_out: 'timed out',
+  skipped: 'skipped (e.g. paths-ignore matched)',
+  neutral: 'neutral / informational',
+  action_required: 'manual approval required',
+  stale: 'stale — superseded by a newer run',
+  startup_failure: 'workflow failed to start (likely invalid YAML)',
+};
+const explainStatus = (status, conclusion) => {
+  const statusPart = status ? `${status}${STATUS_HINTS[status] ? ` (${STATUS_HINTS[status]})` : ''}` : 'unknown';
+  if (!conclusion) return statusPart;
+  const concPart = `${conclusion}${CONCLUSION_HINTS[conclusion] ? ` (${CONCLUSION_HINTS[conclusion]})` : ''}`;
+  return `${statusPart} → ${concPart}`;
+};
+const formatRunLine = run => {
+  const status = run.conclusion ? `${run.status}/${run.conclusion}` : run.status;
+  return `${run.name} [${status}] — ${run.html_url}`;
+};
 
 // Issue #1625: Import centralized session-ending markers so the duplicate-
 // search scope for checkForExistingComment() stays in lock-step with the
@@ -343,13 +379,38 @@ export const getMergeBlockers = async (owner, repo, prNumber, verbose = false, c
           }
 
           // Some workflow runs are still in progress or produced results — genuine race condition
+          // Issue #1712: User-facing blocker `details` carry the run URL + status so the
+          // top-level "⏳ Waiting for CI:" line is self-explanatory. Verbose listing is
+          // produced by `getWorkflowRunsForSha(..., verbose=true)` above — do NOT print the
+          // same run list twice. Here we only emit the one-line summary that explains
+          // *why* we're still waiting (race vs. real run).
+          const commitUrl = `https://github.com/${owner}/${repo}/pull/${prNumber}/commits/${ciStatus.sha}`;
           if (verbose) {
-            await log(`[VERBOSE] /merge: PR #${prNumber} has no CI check-runs yet, but ${workflowRuns.length} workflow run(s) were triggered for SHA ${ciStatus.sha.substring(0, 7)} - genuine race condition (waiting for check-runs to appear)`);
+            await log(`[VERBOSE] /merge: ${workflowRuns.length} workflow run(s) registered for PR #${prNumber} HEAD ${commitUrl} — waiting for them to publish check-runs (race condition between workflow_run and check_runs APIs, typically ~30–120 s)`);
           }
+
+          // Also surface any active workflow runs on OLDER PR commits, so the user's view of
+          // the GitHub Actions tab (which shows yellow dots for every commit) reconciles
+          // with the log. These are NOT blockers — GitHub's concurrency group cancels them
+          // when a new commit is pushed — but listing them stops the user from worrying that
+          // the watcher is missing them.
+          const activeAcrossCommits = await getActivePRWorkflowRuns(owner, repo, prNumber, ciStatus.sha, verbose, getWorkflowRunsForSha);
+          if (verbose && activeAcrossCommits.otherActive > 0) {
+            await log(`[VERBOSE] /merge: ${activeAcrossCommits.otherActive} additional active workflow run(s) on older commits of PR #${prNumber} (these are not blockers — GitHub's concurrency group will cancel them):`);
+            for (const group of activeAcrossCommits.groups) {
+              if (group.isHead) continue;
+              const olderCommitUrl = `https://github.com/${owner}/${repo}/pull/${prNumber}/commits/${group.sha}`;
+              await log(`[VERBOSE] /merge:   on ${olderCommitUrl}:`);
+              for (const run of group.runs) {
+                await log(`[VERBOSE] /merge:     - ${formatRunLine(run)} — ${explainStatus(run.status, run.conclusion)}`);
+              }
+            }
+          }
+
           blockers.push({
             type: 'ci_pending',
-            message: `CI/CD checks have not started yet (${workflowRuns.length} workflow run(s) triggered, waiting for check-runs to appear)`,
-            details: workflowRuns.map(r => r.name),
+            message: `Waiting for ${workflowRuns.length} workflow run(s) on HEAD ${commitUrl} to publish check-runs`,
+            details: workflowRuns.map(formatRunLine),
           });
         } else {
           // No workflow runs for this SHA — but this could be a race condition!
@@ -519,11 +580,27 @@ export const getMergeBlockers = async (owner, repo, prNumber, verbose = false, c
     }
   } else if (ciStatus.status === 'pending') {
     // CI is still running or queued - wait for completion
-    const pendingNames = [...ciStatus.pendingChecks, ...ciStatus.queuedChecks].map(c => c.name);
+    const pendingChecks = [...ciStatus.pendingChecks, ...ciStatus.queuedChecks];
+    const pendingDetails = pendingChecks.map(c => {
+      const statusPart = c.status ? ` [${c.status}]` : '';
+      const urlPart = c.html_url ? ` — ${c.html_url}` : '';
+      return `${c.name}${statusPart}${urlPart}`;
+    });
+    if (verbose) {
+      // Issue #1712: One concise line + a per-check entry that includes a plain-English
+      // explanation of the status. We do NOT also call getWorkflowRunsForSha here — the
+      // detailed CI status already covers the same data via check-runs.
+      const commitUrl = `https://github.com/${owner}/${repo}/pull/${prNumber}/commits/${ciStatus.sha}`;
+      await log(`[VERBOSE] /merge: ${pendingChecks.length} check-run(s) still running/queued on PR #${prNumber} HEAD ${commitUrl}:`);
+      for (const c of pendingChecks) {
+        const url = c.html_url ? ` — ${c.html_url}` : '';
+        await log(`[VERBOSE] /merge:   - ${c.name}: ${explainStatus(c.status, c.conclusion)}${url}`);
+      }
+    }
     blockers.push({
       type: 'ci_pending',
       message: 'CI/CD checks are still running or queued',
-      details: pendingNames,
+      details: pendingDetails,
     });
   } else if (ciStatus.status === 'cancelled') {
     // All non-passed checks are cancelled or stale (no genuine failures)
@@ -540,10 +617,15 @@ export const getMergeBlockers = async (owner, repo, prNumber, verbose = false, c
     } else {
       // These need to be re-triggered, NOT treated as AI-fixable failures
       const cancelledOrStaleChecks = [...ciStatus.cancelledChecks, ...(ciStatus.staleChecks || [])];
+      const cancelledDetails = cancelledOrStaleChecks.map(c => {
+        const concPart = c.conclusion ? ` [${c.conclusion}]` : '';
+        const urlPart = c.html_url ? ` — ${c.html_url}` : '';
+        return `${c.name}${concPart}${urlPart}`;
+      });
       blockers.push({
         type: 'ci_cancelled',
         message: 'CI/CD checks were cancelled or became stale',
-        details: cancelledOrStaleChecks.map(c => c.name),
+        details: cancelledDetails,
         sha: ciStatus.sha,
       });
     }

package/src/solve.auto-merge.lib.mjs

@@ -111,6 +111,11 @@ export const watchUntilMergeable = async params => {
   await log(formatAligned('', 'Wait for all repo actions:', waitForAllRepoActionsFlag ? 'Yes (strict repo-wide safety)' : 'No (PR-scoped CI only)', 2));
   await log(formatAligned('', 'Stop conditions:', 'PR merged, PR closed, or becomes mergeable', 2));
   await log(formatAligned('', 'Restart triggers:', 'New non-bot comments, CI failures, merge conflicts', 2));
+  // Issue #1708: Surface that --auto-input-until-mergeable streamed feedback
+  // into the prior session, so any restart triggered here is a fallback.
+  if (argv.autoInputUntilMergeable) {
+    await log(formatAligned('', 'Streaming-first:', '--auto-input-until-mergeable was active; this loop is the fallback', 2));
+  }
   await log('');
   await log('Press Ctrl+C to stop watching manually');
   await log('');
@@ -898,10 +903,30 @@ No further AI sessions will be started automatically for this run. Please review
         const cancelledOnly = blockers.every(b => b.type === 'ci_cancelled' || b.type === 'ci_pending');
         const cancelledBlocker = blockers.find(b => b.type === 'ci_cancelled');
 
+        // Issue #1712: When `details` contain URLs (which they now always do for ci_pending /
+        // ci_cancelled blockers), comma-joining them produces an unreadable single-line wall
+        // of text. Render the first detail inline (with the message as the header) and any
+        // additional details on their own indented lines. Each detail is already
+        // self-explanatory: "<name> [<status>] — <url>".
+        const renderBlocker = (icon, header, blocker) => {
+          if (!blocker.details || blocker.details.length === 0) {
+            return log(formatAligned(icon, header, blocker.message, 2));
+          }
+          if (blocker.details.length === 1) {
+            return log(formatAligned(icon, header, blocker.details[0], 2));
+          }
+          return (async () => {
+            await log(formatAligned(icon, header, blocker.message, 2));
+            for (const detail of blocker.details) {
+              await log(formatAligned('', '', detail, 4));
+            }
+          })();
+        };
+
         if (cancelledOnly && cancelledBlocker) {
-          await log(formatAligned('🔄', 'Waiting for re-triggered CI:', cancelledBlocker.details.join(', '), 2));
+          await renderBlocker('🔄', 'Waiting for re-triggered CI:', cancelledBlocker);
         } else if (pendingBlocker) {
-          await log(formatAligned('⏳', 'Waiting for CI:', pendingBlocker.details.length > 0 ? pendingBlocker.details.join(', ') : pendingBlocker.message, 2));
+          await renderBlocker('⏳', 'Waiting for CI:', pendingBlocker);
         } else {
           await log(formatAligned('⏳', 'Waiting for:', blockers.map(b => b.message).join(', '), 2));
         }

package/src/solve.config.lib.mjs

@@ -198,6 +198,15 @@ export const SOLVE_OPTION_DEFINITIONS = {
     description: 'Auto-restart until PR becomes mergeable (no iteration limit). Restarts on new comments from non-bot users, CI failures, merge conflicts, or other issues. Does NOT auto-merge.',
     default: true,
   },
+  // Issue #1708: Stage 1 introduces this flag inert — it parses, appears in
+  // --help, and is read by validateAutoInputUntilMergeable below, but does not
+  // change the runtime loop yet. Stages 2-6 will wire it into watchUntilMergeable
+  // and the bidirectional NDJSON pipe (see docs/case-studies/issue-1708/).
+  'auto-input-until-mergeable': {
+    type: 'boolean',
+    description: '[EXPERIMENTAL] Extend a single AI tool session as long as possible by streaming new input (uncommitted changes, CI/CD failures, PR/issue comments, issue title/body updates) directly into the running session, instead of restarting it. Implies --accept-incomming-comments-as-input and --queue-comments-to-input by default (comments are deferred until the AI finishes the current step and is waiting for input). Existing auto-restart/auto-resume loops remain enabled as a fallback, but the goal is to keep them dormant. The full streaming-aware watchUntilMergeable replacement and per-tool wiring is staged in subsequent PRs (see docs/case-studies/issue-1708/). Falls back gracefully on non-Claude tools and on streaming errors. Disabled by default.',
+    default: false,
+  },
   'wait-for-all-actions-in-repository-before-mergeable': {
     type: 'boolean',
     description: 'Wait for ALL active GitHub Actions workflow runs in the entire repository to complete before declaring PR mergeable. When enabled, blocks merge if ANY CI/CD run in the repository is active, regardless of branch — this is a strict safety mode for repositories with cross-branch CI/CD coupling. Disabled by default.',
@@ -377,6 +386,26 @@ export const SOLVE_OPTION_DEFINITIONS = {
     description: '[EXPERIMENTAL] Convenience flag that enables --interactive-mode, --accept-incomming-comments-as-input and --exclude-all-own-incomming-comments-from-input together. Only supported for --tool claude.',
     default: false,
   },
+  // Issue #1708: Comment delivery mode for --accept-incomming-comments-as-input.
+  // --stream-comments-to-input: forward comments immediately as they arrive
+  //   (the default for --accept-incomming-comments-as-input on its own; matches
+  //   the existing #817 behavior of pushing comments to Claude as soon as
+  //   pollIncomingComments sees them).
+  // --queue-comments-to-input: hold comments until the AI signals it is idle
+  //   (waiting for input), then flush the queue. Used by
+  //   --auto-input-until-mergeable so the model finishes the current step
+  //   before getting interrupted with new instructions.
+  // The two flags are mutually exclusive; if both are set, queue mode wins.
+  'stream-comments-to-input': {
+    type: 'boolean',
+    description: '[EXPERIMENTAL] When --accept-incomming-comments-as-input is enabled, forward each new PR/issue comment to the AI immediately as it arrives (real-time streaming). This is the default behavior for --accept-incomming-comments-as-input on its own. Mutually exclusive with --queue-comments-to-input; queue mode wins if both are set. Only supported for --tool claude.',
+    default: false,
+  },
+  'queue-comments-to-input': {
+    type: 'boolean',
+    description: '[EXPERIMENTAL] When --accept-incomming-comments-as-input is enabled, queue new PR/issue comments and only flush them once the AI signals it is idle (waiting for input). This is the default mode implied by --auto-input-until-mergeable so the AI completes the current step before being interrupted with new instructions. Mutually exclusive with --stream-comments-to-input; queue mode wins if both are set. Only supported for --tool claude.',
+    default: false,
+  },
   'prompt-explore-sub-agent': {
     type: 'boolean',
     description: 'Encourage AI to use Explore-style sub-agent workflow for codebase exploration. Supported for --tool claude and --tool codex.',

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

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+
+/**
+ * Retry wrapper for `use-m` package loading.
+ *
+ * Issue #1710: Hosted CI runners occasionally hand back a truncated or
+ * partially-installed global package after `npm install -g <pkg>`. Three
+ * surface symptoms have been observed:
+ *
+ *   1. `import` throws a SyntaxError ("Unexpected end of input") wrapped
+ *      in use-m's `Failed to import module from '<path>'.` — the file on
+ *      disk is cut off mid-line.
+ *   2. use-m throws `Failed to resolve the path to '<pkg>' from '<dir>'`
+ *      — the install completed without error but the package tree is
+ *      missing files that the `main`/`exports` entry depends on.
+ *   3. Node throws `Invalid package config <dir>/package.json.` with
+ *      `code: 'ERR_INVALID_PACKAGE_CONFIG'` — the package.json itself
+ *      is corrupt/truncated and cannot even be parsed (issue #1712).
+ *
+ * The recovery is identical for all three: delete the broken alias install
+ * directory and ask use-m to re-fetch. A clean reinstall almost always
+ * succeeds. This helper centralises that retry so every call site picks
+ * it up.
+ */
+
+/**
+ * @param {(specifier: string) => Promise<unknown>} use - the use-m loader.
+ * @param {string} specifier - the npm specifier to load (e.g. `'getenv'`).
+ * @param {object} [options]
+ * @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`).
+ * @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;
+  let lastError;
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    try {
+      return await use(specifier);
+    } catch (error) {
+      lastError = error;
+      if (attempt === attempts || !isCorruptInstallError(error)) {
+        throw error;
+      }
+      const corruptedPath = extractCorruptedFilePath(error);
+      if (corruptedPath) {
+        try {
+          // Two failure modes:
+          //   * "Failed to import module from '<file>'" — corruptedPath is a file
+          //     inside the use-m alias dir (e.g. /.../getenv-v-latest/index.js).
+          //   * "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);
+        } catch {
+          // Best-effort cleanup; fall through to retry regardless.
+        }
+      }
+    }
+  }
+  // Unreachable — the loop either returns or throws.
+  throw lastError;
+};
+
+export const isCorruptInstallError = error => {
+  const cause = error?.cause;
+  if (cause instanceof SyntaxError) return true;
+  const causeMessage = typeof cause?.message === 'string' ? cause.message : '';
+  if (/Unexpected end of input|Unexpected token/.test(causeMessage)) return true;
+  // Mode 3 (issue #1712): package.json itself is corrupt — Node refuses to
+  // even parse it and throws ERR_INVALID_PACKAGE_CONFIG before use-m's own
+  // resolve/import logic gets a chance to run.
+  if (error?.code === 'ERR_INVALID_PACKAGE_CONFIG') return true;
+  if (cause?.code === 'ERR_INVALID_PACKAGE_CONFIG') return true;
+  // Mode 2 (also seen on hosted CI): npm install completes but the package
+  // tree is incomplete, so use-m can't resolve the entry point.
+  const message = typeof error?.message === 'string' ? error.message : '';
+  if (/^Failed to resolve the path to /.test(message)) return true;
+  // Fallback string match for ERR_INVALID_PACKAGE_CONFIG (in case the error
+  // bubbles through use-m without preserving the `code` property).
+  return /^Invalid package config /.test(message);
+};
+
+export const extractCorruptedFilePath = error => {
+  const message = typeof error?.message === 'string' ? error.message : '';
+  const importMatch = message.match(/Failed to import module from '([^']+)'/);
+  if (importMatch) return importMatch[1];
+  // For "Failed to resolve the path to 'pkg' from '<dir>'" the second path
+  // is already the alias install directory — return it directly so callers
+  // can clean it up (cleanup() handles both files and directories).
+  const resolveMatch = message.match(/Failed to resolve the path to '[^']+' from '([^']+)'/);
+  if (resolveMatch) return resolveMatch[1];
+  // Mode 3 (issue #1712): "Invalid package config <dir>/package.json." —
+  // extract the package.json path so the caller's cleanup() walks up to
+  // the alias dir.
+  const invalidConfigMatch = message.match(/Invalid package config (\S+?package\.json)/);
+  return invalidConfigMatch ? invalidConfigMatch[1] : null;
+};
+
+const defaultCleanup = async path => {
+  const { rm } = await import('node:fs/promises');
+  await rm(path, { recursive: true, force: true });
+};