@link-assistant/hive-mind 1.57.3 → 1.59.0

package/src/config.lib.mjs

@@ -18,7 +18,11 @@ if (typeof globalThis.use === 'undefined') {
   }
 }
 
-const getenvModule = await use('getenv');
+// Issue #1710: use-m occasionally hands back a truncated/corrupt global package
+// (npm install -g flake on hosted CI). useWithRetry deletes the broken install
+// dir and re-fetches when the failure is a SyntaxError mid-import.
+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;
 
@@ -413,9 +417,12 @@ export const supportsThinkingBudget = (version, minVersion = '2.1.12') => {
 // Supports model-specific max output tokens for Opus 4.6 (Issue #1221)
 // Sets CLAUDE_CODE_EFFORT_LEVEL for Opus 4.6 models (Issue #1238)
 // Supports planModel/executionModel for opusplan mode (Issue #1223)
-// See: https://code.claude.com/docs/en/model-config
+// Issue #1706: supports subSessionSize (parsed) + disable1mContext to cap
+// auto-compaction sub-session size and opt out of the 1M extended context.
+// See: https://code.claude.com/docs/en/env-vars and https://code.claude.com/docs/en/model-config
 //   ANTHROPIC_DEFAULT_OPUS_MODEL  → model used in plan mode (and for 'opus' alias)
 //   ANTHROPIC_DEFAULT_SONNET_MODEL → model used in execution mode (and for 'sonnet' alias)
+//   CLAUDE_CODE_DISABLE_1M_CONTEXT, CLAUDE_CODE_AUTO_COMPACT_WINDOW, CLAUDE_AUTOCOMPACT_PCT_OVERRIDE
 export const getClaudeEnv = (options = {}) => {
   // Get max output tokens based on model (Issue #1221)
   const maxOutputTokens = options.model ? getMaxOutputTokensForModel(options.model) : claudeCode.maxOutputTokens;
@@ -483,6 +490,36 @@ export const getClaudeEnv = (options = {}) => {
     env.ANTHROPIC_DEFAULT_SONNET_MODEL = String(options.executionModel);
   }
 
+  // Issue #1706: --disable-1m-context. Sets CLAUDE_CODE_DISABLE_1M_CONTEXT=1.
+  if (options.disable1mContext) {
+    env.CLAUDE_CODE_DISABLE_1M_CONTEXT = '1';
+  }
+
+  // Issue #1706: --sub-session-size. Caller passes a pre-parsed descriptor and the
+  // model context window so we can convert percentages to absolute tokens.
+  if (options.subSessionSize && options.subSessionSize.kind && options.subSessionSize.kind !== 'default') {
+    const window = Number.isFinite(options.contextWindowTokens) && options.contextWindowTokens > 0 ? options.contextWindowTokens : null;
+    if (options.subSessionSize.kind === 'tokens') {
+      const tokens = options.subSessionSize.tokens;
+      if (Number.isFinite(tokens) && tokens > 0) {
+        env.CLAUDE_CODE_AUTO_COMPACT_WINDOW = String(tokens);
+        // Compute percentage relative to the context window so the override stays
+        // within Claude Code's "lower-only" semantics. Default to 95 when unknown.
+        let pct = 95;
+        if (window) {
+          pct = Math.max(1, Math.min(95, Math.round((tokens / window) * 100)));
+        }
+        env.CLAUDE_AUTOCOMPACT_PCT_OVERRIDE = String(pct);
+      }
+    } else if (options.subSessionSize.kind === 'percent') {
+      const pct = Math.max(1, Math.min(95, Math.round(options.subSessionSize.percent)));
+      env.CLAUDE_AUTOCOMPACT_PCT_OVERRIDE = String(pct);
+      if (window) {
+        env.CLAUDE_CODE_AUTO_COMPACT_WINDOW = String(window);
+      }
+    }
+  }
+
   return env;
 };
 

package/src/github-cost-info.lib.mjs

@@ -30,7 +30,10 @@ export const buildCostInfoString = (totalCostUSD, anthropicTotalCostUSD, pricing
   if (!hasPublic && !hasAnthropic && !hasPricing && !hasOpencodeCost) return '';
   const publicDec = hasPublic ? new Decimal(totalCostUSD) : null;
   const anthropicDec = hasAnthropic ? new Decimal(anthropicTotalCostUSD) : null;
-  if (publicDec && anthropicDec && publicDec.toFixed(6) === anthropicDec.toFixed(6)) return `\n\n### 💰 Cost: **$${anthropicDec.toFixed(6)}**`;
+  // Issue #1703: collapse to short form when the rounded difference is below 6-decimal display precision.
+  // Without this, near-matching values like $11.219694 vs $11.219693 still printed the full breakdown
+  // even though "Difference: $-0.000000 (-0.00%)" carries no meaningful information.
+  if (publicDec && anthropicDec && anthropicDec.minus(publicDec).abs().toFixed(6) === '0.000000') return `\n\n### 💰 Cost: **$${anthropicDec.toFixed(6)}**`;
   let costInfo = '\n\n### 💰 **Cost estimation:**';
   if (pricingInfo?.modelName) {
     costInfo += `\n- Model: ${pricingInfo.modelName}`;

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/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('');

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.',
@@ -260,6 +269,16 @@ export const SOLVE_OPTION_DEFINITIONS = {
     description: 'Maximum thinking budget for calculating --think level mappings (default: 31999 for Claude Code). Values: off=0, low=max/4, medium=max/2, high=max*3/4, max=max.',
     default: 31999,
   },
+  'sub-session-size': {
+    type: 'string',
+    description: 'Cap on sub-session size between auto-compaction events. Accepts a token count (e.g. 150k, 1m, 200000), a percentage of the model context window (e.g. 50%), or "default" to keep the tool\'s built-in threshold. Default: 150k. For Claude this maps to CLAUDE_CODE_AUTO_COMPACT_WINDOW + CLAUDE_AUTOCOMPACT_PCT_OVERRIDE env vars. For Codex this maps to -c model_auto_compact_token_limit. (Issue #1706)',
+    default: '150k',
+  },
+  'disable-1m-context': {
+    type: 'boolean',
+    description: 'Disable 1M extended context window so the model uses its standard 200K-400K window. Helps preserve reasoning quality and reduces cost. Default: true. For Claude this sets CLAUDE_CODE_DISABLE_1M_CONTEXT=1 (also forbids the [1m] model-name suffix). For Codex this sets -c model_context_window=200000. Use --no-disable-1m-context to allow the 1M window. (Issue #1706)',
+    default: true,
+  },
   'fallback-model': {
     type: 'string',
     description: 'Fallback model to switch to on model capacity/overload errors. When supported, retries resume the same session with this model. Defaults: claude opus/opus-4-7 -> opus-4-6; codex gpt-5.5 -> gpt-5.4; all others unset.',
@@ -367,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/sub-session-size.lib.mjs

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+
+/**
+ * Sub-session size and 1M-context controls.
+ *
+ * Implements --sub-session-size and --disable-1m-context (issue #1706).
+ *
+ * --sub-session-size accepts:
+ *   - "default" / "auto"  → keep tool's built-in compaction threshold (no override)
+ *   - "off" / "0"         → keep tool's default (alias for "default")
+ *   - A token count       → "150k", "150K", "150000", "1.5m", "1M"
+ *   - A percentage        → "50%", "75%" (relative to model context window)
+ *
+ * --disable-1m-context (boolean, default true) opts out of the 1M extended
+ * context window so models fall back to their standard 200K-400K window.
+ *
+ * Claude Code controls (env vars only — no CLI flags exist):
+ *   - CLAUDE_CODE_DISABLE_1M_CONTEXT=1
+ *   - CLAUDE_CODE_AUTO_COMPACT_WINDOW=<tokens>     (basis for compaction math)
+ *   - CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=<1..100>     (only lowers; clamped to <= 95)
+ *
+ * Codex controls (via -c key=value, same mechanism as model_reasoning_effort):
+ *   - -c model_context_window=<tokens>             (forces 200K window)
+ *   - -c model_auto_compact_token_limit=<tokens>   (compaction threshold)
+ */
+
+const PARSE_ERROR_PREFIX = '--sub-session-size';
+
+const DEFAULT_TOKENS_VALUES = new Set(['default', 'auto', 'off', '0', 'none']);
+
+/**
+ * Parse a token count expression: "150k", "150K", "150000", "1.5m", "1M".
+ * Returns null if the input doesn't match the token-count format.
+ */
+const parseTokenCount = value => {
+  const match = String(value)
+    .trim()
+    .match(/^(\d+(?:\.\d+)?)\s*([kmKM]?)$/);
+  if (!match) return null;
+  const number = parseFloat(match[1]);
+  if (!Number.isFinite(number) || number < 0) return null;
+  const suffix = match[2].toLowerCase();
+  const multiplier = suffix === 'k' ? 1_000 : suffix === 'm' ? 1_000_000 : 1;
+  return Math.round(number * multiplier);
+};
+
+/**
+ * Parse a percentage expression: "50%", "75%".
+ * Returns null if the input doesn't match the percentage format.
+ */
+const parsePercent = value => {
+  const match = String(value)
+    .trim()
+    .match(/^(\d+(?:\.\d+)?)\s*%$/);
+  if (!match) return null;
+  const percent = parseFloat(match[1]);
+  if (!Number.isFinite(percent) || percent <= 0 || percent > 100) return null;
+  return percent;
+};
+
+/**
+ * Parse the --sub-session-size option value into a normalized descriptor.
+ *
+ * @param {string|undefined|null} rawValue - The raw option value.
+ * @param {Object} [options]
+ * @param {number|null} [options.contextWindow] - Model context window in tokens (used for percentage values).
+ * @returns {{ kind: 'default' | 'tokens' | 'percent', tokens: number | null, percent: number | null, raw: string }}
+ * @throws {Error} If the value cannot be parsed.
+ */
+export const parseSubSessionSize = (rawValue, { contextWindow = null } = {}) => {
+  if (rawValue === undefined || rawValue === null || rawValue === '') {
+    return { kind: 'default', tokens: null, percent: null, raw: '' };
+  }
+
+  const trimmed = String(rawValue).trim();
+  const lower = trimmed.toLowerCase();
+
+  if (DEFAULT_TOKENS_VALUES.has(lower)) {
+    return { kind: 'default', tokens: null, percent: null, raw: trimmed };
+  }
+
+  const percent = parsePercent(trimmed);
+  if (percent !== null) {
+    const tokens = Number.isFinite(contextWindow) && contextWindow > 0 ? Math.round((contextWindow * percent) / 100) : null;
+    return { kind: 'percent', percent, tokens, raw: trimmed };
+  }
+
+  const tokens = parseTokenCount(trimmed);
+  if (tokens !== null) {
+    return { kind: 'tokens', tokens, percent: null, raw: trimmed };
+  }
+
+  throw new Error(`${PARSE_ERROR_PREFIX}: invalid value "${rawValue}". Expected a token count (e.g. 150k, 1m), a percentage (e.g. 50%), or "default".`);
+};
+
+/**
+ * Apply --sub-session-size to a Claude Code env object.
+ *
+ * Claude Code uses CLAUDE_CODE_AUTO_COMPACT_WINDOW + CLAUDE_AUTOCOMPACT_PCT_OVERRIDE.
+ * The percentage override only *lowers* the default ~95% threshold (per upstream
+ * docs), so we clamp it at 95 to avoid silently being ignored.
+ *
+ * @param {Object} env - Mutable env object to update.
+ * @param {Object} parsed - Result of parseSubSessionSize.
+ * @param {Object} [options]
+ * @param {number|null} [options.contextWindow] - Model context window in tokens.
+ * @returns {{ applied: boolean, summary: string|null }}
+ */
+export const applySubSessionSizeToClaudeEnv = (env, parsed, { contextWindow = null } = {}) => {
+  if (!parsed || parsed.kind === 'default') {
+    return { applied: false, summary: null };
+  }
+
+  const window = Number.isFinite(contextWindow) && contextWindow > 0 ? contextWindow : null;
+
+  if (parsed.kind === 'tokens') {
+    const tokens = parsed.tokens;
+    if (!Number.isFinite(tokens) || tokens <= 0) return { applied: false, summary: null };
+
+    // Use the tokens value as the compaction window basis and apply 100%.
+    // Capped to the model's actual window by Claude Code itself.
+    env.CLAUDE_CODE_AUTO_COMPACT_WINDOW = String(tokens);
+    // Compute percentage relative to the model context window (if known) so the
+    // override stays within Claude Code's "lower-only" semantics. Default to 95.
+    let pct = 95;
+    if (window) {
+      pct = Math.max(1, Math.min(95, Math.round((tokens / window) * 100)));
+    }
+    env.CLAUDE_AUTOCOMPACT_PCT_OVERRIDE = String(pct);
+    return {
+      applied: true,
+      summary: `CLAUDE_CODE_AUTO_COMPACT_WINDOW=${tokens}, CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=${pct}`,
+    };
+  }
+
+  if (parsed.kind === 'percent') {
+    const pct = Math.max(1, Math.min(95, Math.round(parsed.percent)));
+    env.CLAUDE_AUTOCOMPACT_PCT_OVERRIDE = String(pct);
+    if (window) {
+      env.CLAUDE_CODE_AUTO_COMPACT_WINDOW = String(window);
+    }
+    return {
+      applied: true,
+      summary: `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=${pct}${window ? `, CLAUDE_CODE_AUTO_COMPACT_WINDOW=${window}` : ''}`,
+    };
+  }
+
+  return { applied: false, summary: null };
+};
+
+/**
+ * Apply --disable-1m-context to a Claude Code env object.
+ * Sets CLAUDE_CODE_DISABLE_1M_CONTEXT=1 when disabled is true.
+ */
+export const applyDisable1mContextToClaudeEnv = (env, disabled) => {
+  if (!disabled) return { applied: false };
+  env.CLAUDE_CODE_DISABLE_1M_CONTEXT = '1';
+  return { applied: true };
+};
+
+/**
+ * Build Codex `-c` config args for --sub-session-size.
+ * Returns an array like ['-c', 'model_auto_compact_token_limit=150000'] or [].
+ */
+export const buildCodexSubSessionSizeConfigArgs = (parsed, { contextWindow = null } = {}) => {
+  if (!parsed || parsed.kind === 'default') return [];
+
+  let tokens = null;
+  if (parsed.kind === 'tokens') {
+    tokens = parsed.tokens;
+  } else if (parsed.kind === 'percent') {
+    if (!Number.isFinite(contextWindow) || contextWindow <= 0) return [];
+    tokens = Math.round((contextWindow * parsed.percent) / 100);
+  }
+
+  if (!Number.isFinite(tokens) || tokens <= 0) return [];
+  return ['-c', `model_auto_compact_token_limit=${tokens}`];
+};
+
+/**
+ * Build Codex `-c` config args for --disable-1m-context.
+ *
+ * Codex doesn't have a 1M-specific opt-out flag, but setting
+ * `model_context_window=200000` forces the standard window.
+ *
+ * @param {boolean} disabled - True when --disable-1m-context is in effect.
+ * @param {Object} [options]
+ * @param {number} [options.fallbackTokens] - Tokens to set when disabling (default: 200_000).
+ * @returns {string[]} Codex `-c` args, possibly empty.
+ */
+export const buildCodexDisable1mContextConfigArgs = (disabled, { fallbackTokens = 200_000 } = {}) => {
+  if (!disabled) return [];
+  return ['-c', `model_context_window=${fallbackTokens}`];
+};
+
+/**
+ * Resolve --sub-session-size for a given tool, including fetching the model
+ * context window when a percentage is provided. Tolerates fetch failures.
+ *
+ * @param {Object} params
+ * @param {string|undefined|null} params.rawValue - The argv.subSessionSize value.
+ * @param {string} params.tool - 'claude' or 'codex'.
+ * @param {string} params.modelId - Model id (used for models.dev lookup when percent).
+ * @param {Function} [params.fetchModelInfo] - models.dev fetcher (injected for testability).
+ * @param {Function} [params.log] - log function (used for parse warnings).
+ * @returns {Promise<{ parsed: Object, contextWindowTokens: number|null }>}
+ */
+export const resolveSubSessionSize = async ({ rawValue, tool, modelId, fetchModelInfo, log }) => {
+  let parsed;
+  try {
+    parsed = parseSubSessionSize(rawValue);
+  } catch (parseError) {
+    if (log) await log(`⚠️  ${parseError.message}`, { level: 'warn' });
+    parsed = { kind: 'default', tokens: null, percent: null, raw: '' };
+  }
+
+  let contextWindowTokens = null;
+  if (parsed.kind === 'percent' && typeof fetchModelInfo === 'function') {
+    try {
+      const baseModelId = String(modelId || '').replace(/\[1m\]$/i, '');
+      const preferredProviderIds = tool === 'codex' ? ['openai'] : ['anthropic'];
+      const meta = await fetchModelInfo(baseModelId, { preferredProviderIds });
+      contextWindowTokens = meta?.limit?.context || null;
+    } catch {
+      contextWindowTokens = null;
+    }
+  }
+
+  return { parsed, contextWindowTokens };
+};
+
+export default {
+  parseSubSessionSize,
+  applySubSessionSizeToClaudeEnv,
+  applyDisable1mContextToClaudeEnv,
+  buildCodexSubSessionSizeConfigArgs,
+  buildCodexDisable1mContextConfigArgs,
+  resolveSubSessionSize,
+};

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

@@ -0,0 +1,91 @@
+#!/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>`. Two
+ * 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.
+ *
+ * The recovery is identical for both: 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 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 : '';
+  return /^Failed to resolve the path to /.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 '([^']+)'/);
+  return resolveMatch ? resolveMatch[1] : null;
+};
+
+const defaultCleanup = async path => {
+  const { rm } = await import('node:fs/promises');
+  await rm(path, { recursive: true, force: true });
+};