@link-assistant/hive-mind 2.13.2 → 2.13.4

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @link-assistant/hive-mind
 
+## 2.13.4
+
+### Patch Changes
+
+- 36b0ff9: Stop `solve` from crashing with `TypeError: A GitHub pull request URL requires owner, repo, and a positive integer number` when `--auto-continue` resumes an `issue-<n>-<hash>` branch that has no pull request yet. Continue mode has always had two shapes — resume an existing pull request, or reuse a leftover branch from an interrupted run (`prNumber: null`) — and since #2158 the "Your prepared Pull Request" URL was built from `prNumber` unconditionally, so the second shape aborted the run right after branch checkout, one step before `handleAutoPrCreation()` would have created the missing pull request. The URL is now built through a nullable `buildGitHubPullRequestUrlOrNull()` helper, the run logs that the pull request is still pending, and the strict builder reports the values it received so a bare stack trace is actionable. Full analysis in `docs/case-studies/issue-2170/`.
+
+## 2.13.3
+
+### Patch Changes
+
+- bf38253: Stop losing hours (and money) to retries of runs that already succeeded, and keep retrying a real provider outage for up to 12 hours. A gateway-error check matched any standalone `520`–`524` anywhere in the final message, so a solve run on issue #523 / PR #524 had each of its eleven _successful_ results re-classified as "Gateway error (502/504/52x)" and re-run — $7.65 and 3 h 55 min before `❌ Transient API error persisted after 10 retries`. HTTP status codes are now only recognised next to an error context (`API Error: 502`, `error code: 522`, `HTTP 504`) or a canonical gateway phrase, a run that Claude reported as successful is never retried (the near-miss is logged in verbose mode), and every tool's transient-retry loop is now driven by a wall-clock budget — 12 hours by default (`HIVE_MIND_TRANSIENT_ERROR_RETRY_BUDGET_MS`, `0` disables) with a 3-minute minimum delay (`HIVE_MIND_MIN_TRANSIENT_ERROR_DELAY_MS`) and a `3 → 30` min exponential backoff — instead of a fixed attempt count that gave up after ~3.5 hours. Full analysis in `docs/case-studies/issue-2169`.
+
 ## 2.13.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-assistant/hive-mind",
-  "version": "2.13.2",
+  "version": "2.13.4",
   "description": "AI-powered issue solver and hive mind for collaborative problem solving",
   "main": "src/hive.mjs",
   "type": "module",

package/src/agent.lib.mjs

@@ -28,7 +28,7 @@ import { checkPlaywrightMcpPackageAvailability, getAgentPlaywrightMcpDisableEnv
 import { createAgentTokenUsage, accumulateAgentStepFinishUsage, parseAgentTokenUsage } from './agent-token-usage.lib.mjs';
 import { createJsonStreamScanner, parseJsonRecords } from './json-stream.lib.mjs';
 import { firstErrorText, stringifyErrorValue } from './error-text.lib.mjs';
-import { classifyRetryableError, prepareRetryAfterError, waitWithCountdown } from './tool-retry.lib.mjs';
+import { classifyRetryableError, createTransientRetryBudget, prepareRetryAfterError, waitWithCountdown } from './tool-retry.lib.mjs';
 import { attachStreamingInput, finalizeBidirectionalHandler, setupBidirectionalHandler } from './bidirectional-interactive.lib.mjs';
 import { ensureAiToolScratchIgnored, filterAiToolScratchFromStatus } from './ai-tool-scratch.lib.mjs';
 import { buildAgentArgs, detectFormalAiAgentRoutingMismatch, formatAgentArgsForDisplay, isAgentIdleEvent, isAgentStrongCompletionEvent } from './agent-command.lib.mjs';
@@ -571,13 +571,16 @@ export const executeAgentCommand = async params => {
 
   // Retry configuration
   let retryCount = 0;
+  // Issue #2169: retries are bounded by a wall-clock budget (12 h by default, configurable via
+  // HIVE_MIND_TRANSIENT_ERROR_RETRY_BUDGET_MS) instead of a low attempt count.
+  const transientRetryBudget = createTransientRetryBudget();
 
   const executeWithRetry = async () => {
     // Execute agent command from the cloned repository directory
     if (retryCount === 0) {
       await log(`\n${formatAligned('🤖', 'Executing Agent:', argv.model.toUpperCase())}`);
     } else {
-      await log(`\n${formatAligned('🔄', 'Retry attempt:', `${retryCount}/${retryLimits.maxTransientErrorRetries}`)}`);
+      await log(`\n${formatAligned('🔄', 'Retry attempt:', `${retryCount} (${transientRetryBudget.describeProgress()})`)}`);
     }
 
     if (argv.verbose) {
@@ -986,7 +989,17 @@ export const executeAgentCommand = async params => {
         if (retryableError.isRetryable) {
           const isRequestTimeoutRetry = retryableError.label === 'Request timeout';
           const maxRetries = isRequestTimeoutRetry ? retryLimits.maxRequestTimeoutRetries : retryLimits.maxTransientErrorRetries;
-          if (retryCount < maxRetries) {
+          // Issue #2169: the attempt count is only a runaway backstop — the 12-hour wall-clock budget
+          // (configurable) decides when to stop, and every wait honours the 3-minute minimum.
+          const retryDecision = transientRetryBudget.evaluate({
+            retryCount,
+            maxRetries,
+            initialDelayMs: isRequestTimeoutRetry ? retryLimits.initialRequestTimeoutDelayMs : retryLimits.initialTransientErrorDelayMs,
+            maxDelayMs: isRequestTimeoutRetry ? retryLimits.maxRequestTimeoutDelayMs : retryLimits.maxTransientErrorDelayMs,
+            minDelayMs: retryLimits.minTransientErrorDelayMs,
+          });
+          if (retryDecision.allowed) {
+            transientRetryBudget.grant();
             if (sessionId && !argv.resume) argv.resume = sessionId;
             // Issue #2037: retry the same model on capacity errors before falling back;
             // after a capacity-driven model switch, retry quickly instead of waiting the
@@ -999,17 +1012,18 @@ export const executeAgentCommand = async params => {
               retryCount,
               initialDelayMs: isRequestTimeoutRetry ? retryLimits.initialRequestTimeoutDelayMs : retryLimits.initialTransientErrorDelayMs,
               maxDelayMs: isRequestTimeoutRetry ? retryLimits.maxRequestTimeoutDelayMs : retryLimits.maxTransientErrorDelayMs,
+              minDelayMs: retryLimits.minTransientErrorDelayMs,
             });
             const delay = retryPlan.delay;
             const delayLabel = delay >= 60000 ? `${Math.round(delay / 60000)} min` : `${Math.round(delay / 1000)}s`;
-            await log(`\n⚠️ ${retryableError.label} detected. Retry ${retryCount + 1}/${maxRetries} in ${delayLabel}${sessionId ? ' (session preserved)' : ''}...`, { level: 'warning' });
+            await log(`\n⚠️ ${retryableError.label} detected. Retry ${retryCount + 1} in ${delayLabel}${sessionId ? ' (session preserved)' : ''} (${transientRetryBudget.describeProgress()})...`, { level: 'warning' });
             await finalizeAgentBidirectionalHandler();
             await waitForRetryDelay(delay, log);
             await log('\n🔄 Retrying now...');
             retryCount++;
             return await executeWithRetry();
           }
-          await log(`\n\n❌ ${retryableError.label} persisted after ${maxRetries} retries`, { level: 'error' });
+          await log(`\n\n❌ ${retryableError.label} persisted: ${transientRetryBudget.describeExhaustion(retryDecision)}`, { level: 'error' });
         }
 
         // Build JSON error structure for consistent error reporting

package/src/claude.connection.lib.mjs

@@ -5,7 +5,8 @@ if (typeof globalThis.use === 'undefined') {
 const { $ } = await use('command-stream');
 import { log } from './lib.mjs';
 import { reportError } from './sentry.lib.mjs';
-import { timeouts, getThinkingLevelToTokens, getTokensToThinkingLevel, supportsThinkingBudget, DEFAULT_MAX_THINKING_BUDGET } from './config.lib.mjs';
+import { timeouts, retryLimits, getThinkingLevelToTokens, getTokensToThinkingLevel, supportsThinkingBudget, DEFAULT_MAX_THINKING_BUDGET } from './config.lib.mjs';
+import { createTransientRetryBudget, waitWithCountdown } from './tool-retry.lib.mjs';
 import { buildAuthRemedyLines } from './formal-ai.lib.mjs';
 import { stringifyErrorValue } from './error-text.lib.mjs';
 import { mapModelToId } from './claude.model-utils.lib.mjs';
@@ -14,15 +15,39 @@ export const validateClaudeConnection = async (model = 'haiku') => {
   const mappedModel = mapModelToId(model);
   // Issue #2130: "run claude login" is wrong advice for a Formal-AI-served model.
   const authRemedyLines = buildAuthRemedyLines({ model, vendorRemedy: 'Please run: claude login' });
-  const maxRetries = 3;
-  const baseDelay = timeouts.retryBaseDelay;
+  // Issue #2169: a provider outage during validation used to abort the whole run after 3 quick
+  // retries (~seconds). Validation now shares the same wall-clock retry budget as execution —
+  // 12 h by default, 3-minute minimum wait, all configurable through HIVE_MIND_* env vars.
+  const maxRetries = retryLimits.maxTransientErrorRetries;
   let retryCount = 0;
+  const transientRetryBudget = createTransientRetryBudget();
+  // Returns true when a retry was performed (caller should recurse), false when the budget is spent.
+  const retryAfterOverload = async context => {
+    const retryDecision = transientRetryBudget.evaluate({
+      retryCount,
+      maxRetries,
+      initialDelayMs: retryLimits.initialTransientErrorDelayMs,
+      maxDelayMs: retryLimits.maxTransientErrorDelayMs,
+      minDelayMs: retryLimits.minTransientErrorDelayMs,
+    });
+    if (!retryDecision.allowed) {
+      await log(`❌ API overload error persisted: ${transientRetryBudget.describeExhaustion(retryDecision)}`, { level: 'error' });
+      await log('   The API appears to be heavily loaded. Please try again later.', { level: 'error' });
+      return false;
+    }
+    transientRetryBudget.grant();
+    const delayLabel = retryDecision.delayMs >= 60000 ? `${Math.round(retryDecision.delayMs / 60000)} min` : `${Math.round(retryDecision.delayMs / 1000)}s`;
+    await log(`⚠️ API overload error ${context}. Retrying in ${delayLabel} (${transientRetryBudget.describeProgress()})...`, { level: 'warning' });
+    await waitWithCountdown(retryDecision.delayMs, log);
+    retryCount++;
+    return true;
+  };
   const attemptValidation = async () => {
     try {
       if (retryCount === 0) {
         await log('🔍 Validating Claude CLI connection...');
       } else {
-        await log(`🔄 Retry attempt ${retryCount}/${maxRetries} for Claude CLI validation...`);
+        await log(`🔄 Retry attempt ${retryCount} for Claude CLI validation (${transientRetryBudget.describeProgress()})...`);
       }
       try {
         const versionResult = await $`timeout ${Math.floor(timeouts.claudeCli / 6000)} claude --version`;
@@ -83,21 +108,8 @@ export const validateClaudeConnection = async (model = 'haiku') => {
       const jsonError = checkForJsonError(stdout) || checkForJsonError(stderr);
       const isOverloadError = (stdout.includes('API Error: 500') && stdout.includes('Overloaded')) || (stdout.includes('API Error: 529') && stdout.includes('Overloaded')) || (stderr.includes('API Error: 500') && stderr.includes('Overloaded')) || (stderr.includes('API Error: 529') && stderr.includes('Overloaded')) || (jsonError && (jsonError.type === 'api_error' || jsonError.type === 'overloaded_error') && jsonError.message === 'Overloaded');
       if (isOverloadError) {
-        if (retryCount < maxRetries) {
-          const delay = baseDelay * Math.pow(2, retryCount);
-          await log(`⚠️ API overload error during validation. Retrying in ${delay / 1000} seconds...`, {
-            level: 'warning',
-          });
-          await new Promise(resolve => setTimeout(resolve, delay));
-          retryCount++;
-          return await attemptValidation();
-        } else {
-          await log(`❌ API overload error persisted after ${maxRetries} retries during validation`, {
-            level: 'error',
-          });
-          await log('   The API appears to be heavily loaded. Please try again later.', { level: 'error' });
-          return false;
-        }
+        if (await retryAfterOverload('during validation')) return await attemptValidation();
+        return false;
       }
       const exitCode = result.code ?? result.exitCode ?? 0; // Bun shell compat
       if (exitCode !== 0) {
@@ -116,18 +128,8 @@ export const validateClaudeConnection = async (model = 'haiku') => {
       }
       if (jsonError) {
         if ((jsonError.type === 'api_error' || jsonError.type === 'overloaded_error') && jsonError.message === 'Overloaded') {
-          if (retryCount < maxRetries) {
-            const delay = baseDelay * Math.pow(2, retryCount);
-            await log(`⚠️ API overload error in response. Retrying in ${delay / 1000} seconds...`, {
-              level: 'warning',
-            });
-            await new Promise(resolve => setTimeout(resolve, delay));
-            retryCount++;
-            return await attemptValidation();
-          } else {
-            await log(`❌ API overload error persisted after ${maxRetries} retries`, { level: 'error' });
-            return false;
-          }
+          if (await retryAfterOverload('in response')) return await attemptValidation();
+          return false;
         }
         await log(`❌ Claude CLI returned error: ${jsonError.type} - ${jsonError.message}`, { level: 'error' });
         if (jsonError.type === 'forbidden') {
@@ -140,18 +142,8 @@ export const validateClaudeConnection = async (model = 'haiku') => {
     } catch (error) {
       const errorStr = error.message || error.toString();
       if ((errorStr.includes('API Error: 500') && errorStr.includes('Overloaded')) || (errorStr.includes('API Error: 529') && errorStr.includes('Overloaded')) || (errorStr.includes('api_error') && errorStr.includes('Overloaded')) || (errorStr.includes('overloaded_error') && errorStr.includes('Overloaded'))) {
-        if (retryCount < maxRetries) {
-          const delay = baseDelay * Math.pow(2, retryCount);
-          await log(`⚠️ API overload error during validation. Retrying in ${delay / 1000} seconds...`, {
-            level: 'warning',
-          });
-          await new Promise(resolve => setTimeout(resolve, delay));
-          retryCount++;
-          return await attemptValidation();
-        } else {
-          await log(`❌ API overload error persisted after ${maxRetries} retries`, { level: 'error' });
-          return false;
-        }
+        if (await retryAfterOverload('during validation')) return await attemptValidation();
+        return false;
       }
       await log(`❌ Failed to validate Claude CLI connection: ${error.message}`, { level: 'error' });
       await log('   💡 Make sure Claude CLI is installed and accessible', { level: 'error' });

package/src/claude.lib.mjs

@@ -28,7 +28,7 @@ import { buildMcpConfigWithoutPlaywright, ensureClaudePlaywrightMcpServer } from
 import { resolveClaudeSessionToolFlags } from './useless-tools.lib.mjs';
 import { ensureClaudeQuietConfig } from './claude-quiet-config.lib.mjs';
 import { fetchModelInfo } from './model-info.lib.mjs';
-import { classifyRetryableError, logExecutionContext, prepareRetryAfterError, waitWithCountdown } from './tool-retry.lib.mjs';
+import { classifyRetryableError, createTransientRetryBudget, describeClassificationEvidence, logExecutionContext, prepareRetryAfterError, waitWithCountdown } from './tool-retry.lib.mjs';
 import { resolveSubSessionSize } from './sub-session-size.lib.mjs'; // Issue #1706
 import { withAgentsMdAsClaudeMd } from './agents-md-claude-support.lib.mjs';
 import { deployHandoffSkill } from './handoff-skill.lib.mjs'; // Issue #1877
@@ -341,6 +341,9 @@ export const executeClaudeCommand = async params => {
   const escapePromptForShell = promptText => String(promptText).replace(/"/g, '\\"').replace(/\$/g, '\\$');
   await validateBidirectionalModeConfig(argv, log);
   let retryCount = 0;
+  // Issue #2169: total-time budget shared by every transient-error retry of this run (default
+  // 12 h). Created outside executeWithRetry so the elapsed clock survives the recursive calls.
+  const transientRetryBudget = createTransientRetryBudget();
   let baseBranchInterventionPrompt = null;
   let baseBranchInterventionResumeCount = 0;
   // Issue #1834 (PR #1835 feedback): corrupted-thinking-block recovery — resume the session first,
@@ -353,7 +356,8 @@ export const executeClaudeCommand = async params => {
     if (retryCount === 0) {
       await log(`\n${formatAligned('🤖', 'Executing Claude:', argv.model.toUpperCase())}`);
     } else {
-      await log(`\n${formatAligned('🔄', 'Retry attempt:', `${retryCount}/${retryLimits.maxTransientErrorRetries}`)}`);
+      // Issue #2169: the count cap is a backstop now, so report the retry budget instead.
+      await log(`\n${formatAligned('🔄', 'Retry attempt:', `${retryCount} (${transientRetryBudget.describeProgress()})`)}`);
     }
     if (argv.verbose) {
       // Issue #1949: logExecutionContext shows the requested alias with its resolved
@@ -1035,17 +1039,32 @@ export const executeClaudeCommand = async params => {
       }
       // Issues #1331, #1353, #1472/#1475: Unified transient error retry (exponential backoff, session preservation)
       const isTransientError = isStartupTimeout || isActivityTimeout || isOverloadError || isInternalServerError || is503Error || isRequestTimeout || isRateLimitError || retryableLastError.isRetryable || (lastMessage.includes('API Error: 500') && (lastMessage.includes('Overloaded') || lastMessage.includes('Internal server error'))) || (lastMessage.includes('API Error: 529') && (lastMessage.includes('overloaded_error') || lastMessage.includes('Overloaded'))) || (lastMessage.includes('api_error') && lastMessage.includes('Overloaded')) || (lastMessage.includes('overloaded_error') && lastMessage.includes('Overloaded')) || lastMessage.includes('API Error: 503') || (lastMessage.includes('503') && (lastMessage.includes('upstream connect error') || lastMessage.includes('remote connection failure'))) || lastMessage === 'Request timed out' || lastMessage.includes('Request timed out');
+      // Issue #2169: a run that ended in a *successful* result event must never be retried.
+      // `lastMessage` holds the agent's own last text, so any prose that merely looks like an API
+      // error ("PR #524", "API Error: 503" quoted while working on an issue about it) used to flip
+      // `isTransientError` on and send a finished session into the retry loop. In the reported run
+      // all 11 attempts succeeded and were retried anyway, burning 3 h 54 min before the process
+      // exited 1 with the summary text presented as the error.
+      const runProducedSuccess = resultSuccessReceived && !commandFailed && !errorDuringExecution && exitCode === 0;
+      if (runProducedSuccess && isTransientError) {
+        await log(`🔍 Transient-error pattern seen in a successful run — not retrying (Issue #2169). Pattern: ${retryableLastError.label || 'flagged by stream detector'}; last message: ${JSON.stringify(lastMessage.substring(0, 200))}`, { verbose: true });
+        await log(`   Classification evidence: ${describeClassificationEvidence(lastMessage, retryableLastError.label)}`, { verbose: true });
+      }
       // Issue #2161: an account/subscription block short-circuits every retry
       // path. Stale transient flags from earlier in the run (an overload at hour
       // one, say) must not schedule a retry that is guaranteed to fail the same
       // way — and each retry would burn another full startup against a provider
       // that has already refused the credentials.
-      if ((commandFailed || isTransientError) && isTransientError && !subscriptionError) {
-        // Issue #1472/#1475: Startup/activity timeout → 30s–2min backoff; #1353: Request timeout → 5min–1hr; general → 2min–30min
+      if (!runProducedSuccess && isTransientError && !subscriptionError) {
+        // Issue #1472/#1475: Startup/activity timeout → 30s–2min backoff; #1353: Request timeout → 5min–1hr; general → 3min–30min
         const isTimeoutRetry = isStartupTimeout || isActivityTimeout;
-        const maxRetries = isTimeoutRetry ? retryLimits.maxTransientErrorRetries : isRequestTimeout ? retryLimits.maxRequestTimeoutRetries : retryLimits.maxTransientErrorRetries;
+        // Issue #2169: stream timeouts keep their own short count cap; API errors are governed by
+        // the 12-hour budget with a 3-minute floor on every wait.
+        const maxRetries = isTimeoutRetry ? retryLimits.maxStreamTimeoutRetries : isRequestTimeout ? retryLimits.maxRequestTimeoutRetries : retryLimits.maxTransientErrorRetries;
         const initialDelay = isTimeoutRetry ? 30000 : isRequestTimeout ? retryLimits.initialRequestTimeoutDelayMs : retryLimits.initialTransientErrorDelayMs;
         const maxDelay = isTimeoutRetry ? 120000 : isRequestTimeout ? retryLimits.maxRequestTimeoutDelayMs : retryLimits.maxTransientErrorDelayMs;
+        const minDelay = isTimeoutRetry ? 0 : retryLimits.minTransientErrorDelayMs;
+        const retryDecision = transientRetryBudget.evaluate({ retryCount, maxRetries, initialDelayMs: initialDelay, maxDelayMs: maxDelay, minDelayMs: minDelay });
         // Issue #1437: Fail fast when API signals x-should-retry: false AND session made no progress
         const isStuckRetry = apiMarkedNotRetryable && retryCount >= retryLimits.maxNotRetryableAttempts && resultNumTurns <= 1;
         if (isStuckRetry) {
@@ -1072,18 +1091,22 @@ export const executeClaudeCommand = async params => {
             queuedFeedback, // Issue #817: Bidirectional mode feedback
           };
         }
-        if (retryCount < maxRetries) {
+        if (retryDecision.allowed) {
+          transientRetryBudget.grant();
           // Activity timeout preserves session (work was started), startup timeout does not (no session created)
           if (!isStartupTimeout && sessionId && !argv.resume) argv.resume = sessionId;
           // Issue #2037: retry same model on capacity errors before falling back; a switch retries fast.
-          const retryPlan = await prepareRetryAfterError({ tool: 'claude', argv, log, errorMessage: retryableLastError.message || lastMessage, retryCount, initialDelayMs: initialDelay, maxDelayMs: maxDelay });
+          const retryPlan = await prepareRetryAfterError({ tool: 'claude', argv, log, errorMessage: retryableLastError.message || lastMessage, retryCount, initialDelayMs: initialDelay, maxDelayMs: maxDelay, minDelayMs: minDelay });
           const delay = retryPlan.delay;
           const errorLabel = isStartupTimeout ? 'Stream startup timeout (Issue #1472/#1475)' : isActivityTimeout ? 'Stream activity timeout (Issue #1472)' : isRequestTimeout ? 'Request timeout' : retryableLastError.label || (isOverloadError || (lastMessage.includes('API Error: 500') && lastMessage.includes('Overloaded')) || (lastMessage.includes('API Error: 529') && lastMessage.includes('Overloaded')) ? `API overload (${lastMessage.includes('529') ? '529' : '500'})` : isInternalServerError || lastMessage.includes('Internal server error') ? 'Internal server error (500)' : isRateLimitError ? 'Server rate limited (429)' : '503 network error');
           const notRetryableHint = apiMarkedNotRetryable ? ' (API says not retryable — will stop early if no progress)' : '';
           const delayLabel = delay >= 60000 ? `${Math.round(delay / 60000)} min` : `${Math.round(delay / 1000)}s`;
           const retryMode = isStartupTimeout ? ' (fresh start)' : ' (session preserved)';
-          await log(`\n⚠️ ${errorLabel} detected. Retry ${retryCount + 1}/${maxRetries} in ${delayLabel}${retryMode}${notRetryableHint}...`, { level: 'warning' });
+          await log(`\n⚠️ ${errorLabel} detected. Retry ${retryCount + 1} in ${delayLabel}${retryMode}${notRetryableHint} (${transientRetryBudget.describeProgress()})...`, { level: 'warning' });
           await log(`   Error: ${isStartupTimeout ? `No output from Claude CLI within ${timeouts.streamStartupMs / 1000}s` : isActivityTimeout ? `No output for ${timeouts.streamActivityMs / 1000}s after previous activity` : lastMessage.substring(0, 200)}`, { verbose: true });
+          // Issue #2169: the 200-character excerpt above hid the token that actually triggered the
+          // classifier in the reported run, so also log where every status-looking token sits.
+          await log(`   Classification evidence: ${describeClassificationEvidence(retryableLastError.message || lastMessage, errorLabel)}`, { verbose: true });
           // Issue #1510: Post PR comment when force-killing and auto-resuming so reviewers can follow the session lifecycle
           if ((isActivityTimeout || isStartupTimeout) && owner && repo && prNumber && $) {
             try {
@@ -1102,7 +1125,10 @@ export const executeClaudeCommand = async params => {
           retryCount++;
           return await executeWithRetry();
         } else {
-          await log(`\n\n❌ Transient API error persisted after ${maxRetries} retries\n   Please try again later or check https://status.anthropic.com/`, { level: 'error' });
+          // Issue #2169: report *why* we stopped — count backstop vs 12-hour budget — and how long
+          // the run actually spent retrying, so an exhausted window is diagnosable from one line.
+          const exhaustionReason = transientRetryBudget.describeExhaustion(retryDecision);
+          await log(`\n\n❌ Transient API error persisted: ${exhaustionReason}\n   Please try again later or check https://status.anthropic.com/\n   Raise HIVE_MIND_TRANSIENT_ERROR_RETRY_BUDGET_MS to keep retrying for longer.`, { level: 'error' });
           // Issue #1886: fold captured cost so the carried-forward cost survives this retries-exhausted path.
           seedCumulativeAnthropicCost(argv.previousAnthropicCost);
           const cumulativeAnthropicCostUSDOnRetriesExhausted = addAnthropicRunCost(anthropicTotalCostUSD ?? anthropicCostFromAnyResult);
@@ -1118,7 +1144,7 @@ export const executeClaudeCommand = async params => {
             anthropicTotalCostUSD: cumulativeAnthropicCostUSDOnRetriesExhausted, // Issue #1104/#1886: Include cumulative cost even on failure
             resultSummary, // Issue #1263: Include result summary
             // Issue #1845/#1941: surface the actual error, rejecting meaningless fragments (e.g. a lone "}")
-            errorInfo: { message: buildToolErrorMessage({ lastMessage, exitCode, fallback: `Transient API error persisted after ${maxRetries} retries`, toolLabel: 'Claude' }), exitCode },
+            errorInfo: { message: buildToolErrorMessage({ lastMessage, exitCode, fallback: `Transient API error persisted: ${transientRetryBudget.describeExhaustion(retryDecision)}`, toolLabel: 'Claude' }), exitCode },
             subscriptionError, // Issue #2161
             queuedFeedback, // Issue #817: Bidirectional mode feedback
           };
@@ -1253,19 +1279,24 @@ export const executeClaudeCommand = async params => {
         const maxRetries = isTimeoutException ? retryLimits.maxRequestTimeoutRetries : retryLimits.maxTransientErrorRetries;
         const initialDelay = isTimeoutException ? retryLimits.initialRequestTimeoutDelayMs : retryLimits.initialTransientErrorDelayMs;
         const maxDelay = isTimeoutException ? retryLimits.maxRequestTimeoutDelayMs : retryLimits.maxTransientErrorDelayMs;
-        if (retryCount < maxRetries) {
+        // Issue #2169: the same 12-hour budget with a 3-minute floor governs the exception path.
+        const minDelay = retryLimits.minTransientErrorDelayMs;
+        const retryDecision = transientRetryBudget.evaluate({ retryCount, maxRetries, initialDelayMs: initialDelay, maxDelayMs: maxDelay, minDelayMs: minDelay });
+        if (retryDecision.allowed) {
+          transientRetryBudget.grant();
           if (sessionId && !argv.resume) argv.resume = sessionId;
           // Issue #2037: retry same model on capacity errors before falling back; a switch retries fast.
-          const retryPlan = await prepareRetryAfterError({ tool: 'claude', argv, log, errorMessage: errorStr, retryCount, initialDelayMs: initialDelay, maxDelayMs: maxDelay });
+          const retryPlan = await prepareRetryAfterError({ tool: 'claude', argv, log, errorMessage: errorStr, retryCount, initialDelayMs: initialDelay, maxDelayMs: maxDelay, minDelayMs: minDelay });
           const delay = retryPlan.delay;
           const errorLabel = isTimeoutException ? 'Request timeout' : retryableException.label || (errorStr.includes('Overloaded') ? `API overload (${errorStr.includes('529') ? '529' : '500'})` : errorStr.includes('Internal server error') ? 'Internal server error (500)' : '503 network error');
           const delayLabel = delay >= 60000 ? `${Math.round(delay / 60000)} min` : `${Math.round(delay / 1000)}s`;
-          await log(`\n⚠️ ${errorLabel} in exception. Retry ${retryCount + 1}/${maxRetries} in ${delayLabel} (session preserved)...`, { level: 'warning' });
+          await log(`\n⚠️ ${errorLabel} in exception. Retry ${retryCount + 1} in ${delayLabel} (session preserved, ${transientRetryBudget.describeProgress()})...`, { level: 'warning' });
           await waitWithCountdown(delay, log);
           await log('\n🔄 Retrying now...');
           retryCount++;
           return await executeWithRetry();
         }
+        await log(`\n⏹️ Stopped retrying: ${transientRetryBudget.describeExhaustion(retryDecision)}`, { level: 'warning' });
       }
       await log(`\n\n❌ Error executing Claude command: ${error.message}`, { level: 'error' });
       // Issue #1886: fold captured cost so the carried-forward cost survives this exception path too.

package/src/codex.lib.mjs

@@ -34,7 +34,7 @@ import { fetchModelInfo } from './model-info.lib.mjs';
 import { defaultModels, isFormalAiModel } from './models/index.mjs';
 import { buildAuthRemedyLines, buildFormalAiEnvExports, isPrepareOnly, logPreparedToolCommand, resolveFormalAiToolExecution } from './formal-ai.lib.mjs';
 import { buildFormalAiPricingInfo } from './formal-ai-pricing.lib.mjs'; // Issue #2119
-import { classifyRetryableError, prepareRetryAfterError, waitWithCountdown } from './tool-retry.lib.mjs';
+import { classifyRetryableError, createTransientRetryBudget, prepareRetryAfterError, waitWithCountdown } from './tool-retry.lib.mjs';
 import { parseSubSessionSize, buildCodexSubSessionSizeConfigArgs, buildCodexDisable1mContextConfigArgs } from './sub-session-size.lib.mjs'; // Issue #1706
 import { getCumulativeContextInputTokens } from './context-fill.lib.mjs';
 import { deployHandoffSkill } from './handoff-skill.lib.mjs'; // Issue #1877
@@ -720,6 +720,9 @@ export const executeCodexCommand = async params => {
   const expectedBaseBranch = String(argv?.baseBranch || '').trim();
   // Retry configuration
   let retryCount = 0;
+  // Issue #2169: retries are bounded by a wall-clock budget (12 h by default, configurable via
+  // HIVE_MIND_TRANSIENT_ERROR_RETRY_BUDGET_MS) instead of a low attempt count.
+  const transientRetryBudget = createTransientRetryBudget();
   let baseBranchInterventionPrompt = null;
   let baseBranchInterventionResumeCount = 0;
   const executeWithRetry = async () => {
@@ -727,7 +730,7 @@ export const executeCodexCommand = async params => {
     if (retryCount === 0) {
       await log(`\n${formatAligned('🤖', 'Executing Codex:', argv.model.toUpperCase())}`);
     } else {
-      await log(`\n${formatAligned('🔄', 'Retry attempt:', `${retryCount}/${retryLimits.maxTransientErrorRetries}`)}`);
+      await log(`\n${formatAligned('🔄', 'Retry attempt:', `${retryCount} (${transientRetryBudget.describeProgress()})`)}`);
     }
     if (argv.verbose) {
       await log(`   Model: ${argv.model}`, { verbose: true });
@@ -1103,20 +1106,30 @@ export const executeCodexCommand = async params => {
         } else if (retryableError.isRetryable) {
           const isRequestTimeoutRetry = retryableError.label === 'Request timeout';
           const maxRetries = isRequestTimeoutRetry ? retryLimits.maxRequestTimeoutRetries : retryLimits.maxTransientErrorRetries;
-          if (retryCount < maxRetries) {
+          // Issue #2169: the attempt count is only a runaway backstop — the 12-hour wall-clock budget
+          // (configurable) decides when to stop, and every wait honours the 3-minute minimum.
+          const retryDecision = transientRetryBudget.evaluate({
+            retryCount,
+            maxRetries,
+            initialDelayMs: isRequestTimeoutRetry ? retryLimits.initialRequestTimeoutDelayMs : retryLimits.initialTransientErrorDelayMs,
+            maxDelayMs: isRequestTimeoutRetry ? retryLimits.maxRequestTimeoutDelayMs : retryLimits.maxTransientErrorDelayMs,
+            minDelayMs: retryLimits.minTransientErrorDelayMs,
+          });
+          if (retryDecision.allowed) {
+            transientRetryBudget.grant();
             if (sessionId && !argv.resume) argv.resume = sessionId;
             // Issue #2037: retry same model on capacity errors before falling back; a
             // capacity-driven switch retries fast, other transient errors use standard backoff.
-            const retryPlan = await prepareRetryAfterError({ tool: 'codex', argv, log, errorMessage: retryableError.message, retryCount, initialDelayMs: isRequestTimeoutRetry ? retryLimits.initialRequestTimeoutDelayMs : retryLimits.initialTransientErrorDelayMs, maxDelayMs: isRequestTimeoutRetry ? retryLimits.maxRequestTimeoutDelayMs : retryLimits.maxTransientErrorDelayMs });
+            const retryPlan = await prepareRetryAfterError({ tool: 'codex', argv, log, errorMessage: retryableError.message, retryCount, initialDelayMs: isRequestTimeoutRetry ? retryLimits.initialRequestTimeoutDelayMs : retryLimits.initialTransientErrorDelayMs, maxDelayMs: isRequestTimeoutRetry ? retryLimits.maxRequestTimeoutDelayMs : retryLimits.maxTransientErrorDelayMs, minDelayMs: retryLimits.minTransientErrorDelayMs });
             const delay = retryPlan.delay;
             const delayLabel = delay >= 60000 ? `${Math.round(delay / 60000)} min` : `${Math.round(delay / 1000)}s`;
-            await log(`\n⚠️ ${retryableError.label} detected. Retry ${retryCount + 1}/${maxRetries} in ${delayLabel}${sessionId ? ' (session preserved)' : ''}...`, { level: 'warning' });
+            await log(`\n⚠️ ${retryableError.label} detected. Retry ${retryCount + 1} in ${delayLabel}${sessionId ? ' (session preserved)' : ''} (${transientRetryBudget.describeProgress()})...`, { level: 'warning' });
             await waitForRetryDelay(delay, log);
             await log('\n🔄 Retrying now...');
             retryCount++;
             return await executeWithRetry();
           }
-          await log(`\n\n❌ ${retryableError.label} persisted after ${maxRetries} retries`, { level: 'error' });
+          await log(`\n\n❌ ${retryableError.label} persisted: ${transientRetryBudget.describeExhaustion(retryDecision)}`, { level: 'error' });
         } else {
           await log(`\n\n❌ Codex emitted error event: ${codexErrorSummary.message}`, { level: 'error' });
           await log(`   Error events: item=${codexErrorSummary.counts.item}, turn=${codexErrorSummary.counts.turn}, stream=${codexErrorSummary.counts.stream}`, { level: 'error' });
@@ -1129,20 +1142,30 @@ export const executeCodexCommand = async params => {
         if (retryableError.isRetryable) {
           const isRequestTimeoutRetry = retryableError.label === 'Request timeout';
           const maxRetries = isRequestTimeoutRetry ? retryLimits.maxRequestTimeoutRetries : retryLimits.maxTransientErrorRetries;
-          if (retryCount < maxRetries) {
+          // Issue #2169: the attempt count is only a runaway backstop — the 12-hour wall-clock budget
+          // (configurable) decides when to stop, and every wait honours the 3-minute minimum.
+          const retryDecision = transientRetryBudget.evaluate({
+            retryCount,
+            maxRetries,
+            initialDelayMs: isRequestTimeoutRetry ? retryLimits.initialRequestTimeoutDelayMs : retryLimits.initialTransientErrorDelayMs,
+            maxDelayMs: isRequestTimeoutRetry ? retryLimits.maxRequestTimeoutDelayMs : retryLimits.maxTransientErrorDelayMs,
+            minDelayMs: retryLimits.minTransientErrorDelayMs,
+          });
+          if (retryDecision.allowed) {
+            transientRetryBudget.grant();
             if (sessionId && !argv.resume) argv.resume = sessionId;
             // Issue #2037: retry same model on capacity errors before falling back; a
             // capacity-driven switch retries fast, other transient errors use standard backoff.
-            const retryPlan = await prepareRetryAfterError({ tool: 'codex', argv, log, errorMessage: retryableError.message, retryCount, initialDelayMs: isRequestTimeoutRetry ? retryLimits.initialRequestTimeoutDelayMs : retryLimits.initialTransientErrorDelayMs, maxDelayMs: isRequestTimeoutRetry ? retryLimits.maxRequestTimeoutDelayMs : retryLimits.maxTransientErrorDelayMs });
+            const retryPlan = await prepareRetryAfterError({ tool: 'codex', argv, log, errorMessage: retryableError.message, retryCount, initialDelayMs: isRequestTimeoutRetry ? retryLimits.initialRequestTimeoutDelayMs : retryLimits.initialTransientErrorDelayMs, maxDelayMs: isRequestTimeoutRetry ? retryLimits.maxRequestTimeoutDelayMs : retryLimits.maxTransientErrorDelayMs, minDelayMs: retryLimits.minTransientErrorDelayMs });
             const delay = retryPlan.delay;
             const delayLabel = delay >= 60000 ? `${Math.round(delay / 60000)} min` : `${Math.round(delay / 1000)}s`;
-            await log(`\n⚠️ ${retryableError.label} detected. Retry ${retryCount + 1}/${maxRetries} in ${delayLabel}${sessionId ? ' (session preserved)' : ''}...`, { level: 'warning' });
+            await log(`\n⚠️ ${retryableError.label} detected. Retry ${retryCount + 1} in ${delayLabel}${sessionId ? ' (session preserved)' : ''} (${transientRetryBudget.describeProgress()})...`, { level: 'warning' });
             await waitForRetryDelay(delay, log);
             await log('\n🔄 Retrying now...');
             retryCount++;
             return await executeWithRetry();
           }
-          await log(`\n\n❌ ${retryableError.label} persisted after ${maxRetries} retries`, { level: 'error' });
+          await log(`\n\n❌ ${retryableError.label} persisted: ${transientRetryBudget.describeExhaustion(retryDecision)}`, { level: 'error' });
         }
         // Check for usage limit errors first (more specific)
         const limitInfo = detectUsageLimit(lastMessage);

package/src/config.lib.mjs

@@ -106,17 +106,34 @@ export const systemLimits = {
 };
 
 // Retry configurations
-// Issue #1331: All API error types use unified retry parameters:
-// 10 max retries, 2 minute initial delay, 30 minute max delay (exponential backoff), session preserved
+// Issue #1331: All API error types use unified retry parameters (exponential backoff, session preserved).
+// Issue #2169: the retry window is now governed by a *total time budget* (default 12 hours) rather
+// than by the retry count alone. A provider outage can last many hours; the previous 10-retry cap
+// with a 2-minute initial delay gave up after ~3.5 hours. The count caps below are kept as
+// backstops against runaway loops — the budget is the knob operators are expected to tune.
 export const retryLimits = {
   maxForkRetries: parseIntWithDefault('HIVE_MIND_MAX_FORK_RETRIES', 5),
   maxVerifyRetries: parseIntWithDefault('HIVE_MIND_MAX_VERIFY_RETRIES', 5),
   maxApiRetries: parseIntWithDefault('HIVE_MIND_MAX_API_RETRIES', 3),
   retryBackoffMultiplier: parseFloatWithDefault('HIVE_MIND_RETRY_BACKOFF_MULTIPLIER', 2),
   // Unified retry config for all transient API errors (Overloaded, 503, Internal Server Error)
-  maxTransientErrorRetries: parseIntWithDefault('HIVE_MIND_MAX_TRANSIENT_ERROR_RETRIES', 10),
-  initialTransientErrorDelayMs: parseIntWithDefault('HIVE_MIND_INITIAL_TRANSIENT_ERROR_DELAY_MS', 2 * 60 * 1000), // 2 minutes
+  // Issue #2169: count backstop only. With the defaults below (3 min → 30 min backoff) the 12-hour
+  // budget is exhausted after ~26 retries, so this cap never fires unless an operator shortens the
+  // delays. Lower it (e.g. HIVE_MIND_MAX_TRANSIENT_ERROR_RETRIES=5) to fail faster than the budget.
+  maxTransientErrorRetries: parseIntWithDefault('HIVE_MIND_MAX_TRANSIENT_ERROR_RETRIES', 100),
+  // Issue #2169: "minimum of 3 minutes" — the first (and therefore smallest) transient backoff.
+  initialTransientErrorDelayMs: parseIntWithDefault('HIVE_MIND_INITIAL_TRANSIENT_ERROR_DELAY_MS', 3 * 60 * 1000), // 3 minutes
   maxTransientErrorDelayMs: parseIntWithDefault('HIVE_MIND_MAX_TRANSIENT_ERROR_DELAY_MS', 30 * 60 * 1000), // 30 minutes
+  // Issue #2169: total wall-clock budget for transient-API-error retries, measured from the first
+  // retry of a run. Retrying stops as soon as the *next* backoff would push the run past this
+  // window. Set to 0 to disable the budget and fall back to the count cap alone.
+  transientErrorRetryBudgetMs: parseIntWithDefault('HIVE_MIND_TRANSIENT_ERROR_RETRY_BUDGET_MS', 12 * 60 * 60 * 1000), // 12 hours
+  // Issue #2169: floor applied to every transient backoff, including operator-supplied initial
+  // delays. Keeps a misconfigured 5-second delay from hammering an API that is already struggling.
+  minTransientErrorDelayMs: parseIntWithDefault('HIVE_MIND_MIN_TRANSIENT_ERROR_DELAY_MS', 3 * 60 * 1000), // 3 minutes
+  // Issue #2169: stream startup/activity timeouts keep their own (short) count cap. They use 30s–2min
+  // backoffs and force-kill the CLI, so they must not inherit the 100-retry transient backstop.
+  maxStreamTimeoutRetries: parseIntWithDefault('HIVE_MIND_MAX_STREAM_TIMEOUT_RETRIES', 10),
   // Issue #2037: When a "model is at capacity" error triggers a switch to a *different*
   // fallback model, the long transient backoff is wasteful — the different model is
   // available now, so retry almost immediately instead of stalling for minutes.
@@ -131,7 +148,8 @@ export const retryLimits = {
   maxCapacityRetryDelayMs: parseIntWithDefault('HIVE_MIND_MAX_CAPACITY_RETRY_DELAY_MS', 4 * 60 * 1000), // 4 minutes
   // Request timeout retry configuration (Issue #1353)
   // Network timeouts need longer waits than API errors — Claude CLI already exhausted its own retries
-  maxRequestTimeoutRetries: parseIntWithDefault('HIVE_MIND_MAX_REQUEST_TIMEOUT_RETRIES', 10),
+  // Issue #2169: count backstop only — the shared 12-hour budget governs when to stop.
+  maxRequestTimeoutRetries: parseIntWithDefault('HIVE_MIND_MAX_REQUEST_TIMEOUT_RETRIES', 100),
   initialRequestTimeoutDelayMs: parseIntWithDefault('HIVE_MIND_INITIAL_REQUEST_TIMEOUT_DELAY_MS', 5 * 60 * 1000), // 5 minutes
   maxRequestTimeoutDelayMs: parseIntWithDefault('HIVE_MIND_MAX_REQUEST_TIMEOUT_DELAY_MS', 60 * 60 * 1000), // 1 hour
   // Not-retryable error fail-fast configuration (Issue #1437)

package/src/gemini.lib.mjs

@@ -22,7 +22,7 @@ import { defaultModels, geminiModels, isFormalAiModel } from './models/index.mjs
 import { isPrepareOnly, logPreparedToolCommand, resolveFormalAiToolExecution } from './formal-ai.lib.mjs';
 import { buildFormalAiPricingInfo } from './formal-ai-pricing.lib.mjs'; // Issue #2119
 import { checkPlaywrightMcpPackageAvailability } from './playwright-mcp.lib.mjs';
-import { classifyRetryableError, prepareRetryAfterError, waitWithCountdown } from './tool-retry.lib.mjs';
+import { classifyRetryableError, createTransientRetryBudget, prepareRetryAfterError, waitWithCountdown } from './tool-retry.lib.mjs';
 import { getCumulativeContextInputTokens, toTokenCount } from './context-fill.lib.mjs';
 import { ensureAiToolScratchIgnored, filterAiToolScratchFromStatus } from './ai-tool-scratch.lib.mjs';
 import { getTerminalEventCompletionHealth } from './tool-run-health.lib.mjs'; // Issue #1990
@@ -391,12 +391,15 @@ export const executeGeminiCommand = async params => {
   const { tempDir, workspaceTmpDir, branchName, prompt, systemPrompt, argv, log, formatAligned, getResourceSnapshot, forkedRepo, feedbackLines, geminiPath, $, waitForRetryDelay = waitWithCountdown } = params;
 
   let retryCount = 0;
+  // Issue #2169: retries are bounded by a wall-clock budget (12 h by default, configurable via
+  // HIVE_MIND_TRANSIENT_ERROR_RETRY_BUDGET_MS) instead of a low attempt count.
+  const transientRetryBudget = createTransientRetryBudget();
 
   const executeWithRetry = async () => {
     if (retryCount === 0) {
       await log(`\n${formatAligned('🤖', 'Executing Gemini:', argv.model.toUpperCase())}`);
     } else {
-      await log(`\n${formatAligned('🔄', 'Retry attempt:', `${retryCount}/${retryLimits.maxTransientErrorRetries}`)}`);
+      await log(`\n${formatAligned('🔄', 'Retry attempt:', `${retryCount} (${transientRetryBudget.describeProgress()})`)}`);
     }
 
     if (argv.verbose) {
@@ -515,7 +518,17 @@ export const executeGeminiCommand = async params => {
         if (retryableError.isRetryable) {
           const isRequestTimeoutRetry = retryableError.label === 'Request timeout';
           const maxRetries = isRequestTimeoutRetry ? retryLimits.maxRequestTimeoutRetries : retryLimits.maxTransientErrorRetries;
-          if (retryCount < maxRetries) {
+          // Issue #2169: the attempt count is only a runaway backstop — the 12-hour wall-clock budget
+          // (configurable) decides when to stop, and every wait honours the 3-minute minimum.
+          const retryDecision = transientRetryBudget.evaluate({
+            retryCount,
+            maxRetries,
+            initialDelayMs: isRequestTimeoutRetry ? retryLimits.initialRequestTimeoutDelayMs : retryLimits.initialTransientErrorDelayMs,
+            maxDelayMs: isRequestTimeoutRetry ? retryLimits.maxRequestTimeoutDelayMs : retryLimits.maxTransientErrorDelayMs,
+            minDelayMs: retryLimits.minTransientErrorDelayMs,
+          });
+          if (retryDecision.allowed) {
+            transientRetryBudget.grant();
             // Issue #2037: retry the same model on capacity errors before falling back;
             // after a capacity-driven model switch, retry quickly instead of waiting the
             // full transient backoff — the new model may be available now.
@@ -527,16 +540,17 @@ export const executeGeminiCommand = async params => {
               retryCount,
               initialDelayMs: isRequestTimeoutRetry ? retryLimits.initialRequestTimeoutDelayMs : retryLimits.initialTransientErrorDelayMs,
               maxDelayMs: isRequestTimeoutRetry ? retryLimits.maxRequestTimeoutDelayMs : retryLimits.maxTransientErrorDelayMs,
+              minDelayMs: retryLimits.minTransientErrorDelayMs,
             });
             const delay = retryPlan.delay;
             const delayLabel = delay >= 60000 ? `${Math.round(delay / 60000)} min` : `${Math.round(delay / 1000)}s`;
-            await log(`\n⚠️ ${retryableError.label} detected. Retry ${retryCount + 1}/${maxRetries} in ${delayLabel}${sessionId ? ' (session preserved)' : ''}...`, { level: 'warning' });
+            await log(`\n⚠️ ${retryableError.label} detected. Retry ${retryCount + 1} in ${delayLabel}${sessionId ? ' (session preserved)' : ''} (${transientRetryBudget.describeProgress()})...`, { level: 'warning' });
             await waitForRetryDelay(delay, log);
             await log('\n🔄 Retrying now...');
             retryCount++;
             return await executeWithRetry();
           }
-          await log(`\n\n❌ ${retryableError.label} persisted after ${maxRetries} retries`, { level: 'error' });
+          await log(`\n\n❌ ${retryableError.label} persisted: ${transientRetryBudget.describeExhaustion(retryDecision)}`, { level: 'error' });
         }
 
         const limitInfo = detectUsageLimit(errorText);

package/src/github-url-parser.lib.mjs

@@ -270,10 +270,40 @@ export function canonicalizeGitHubUrl(url) {
 /** Build the canonical web URL for a pull request already identified by GitHub. */
 export function buildGitHubPullRequestUrl({ owner, repo, number } = {}) {
   if (!owner || !repo || !Number.isInteger(Number(number)) || Number(number) <= 0) {
-    throw new TypeError('A GitHub pull request URL requires owner, repo, and a positive integer number');
+    // Issue #2170: the bare message left no way to tell which of the three
+    // parts was missing from a stack trace alone, so name the received values.
+    throw new TypeError(`A GitHub pull request URL requires owner, repo, and a positive integer number (received owner=${describeUrlPart(owner)}, repo=${describeUrlPart(repo)}, number=${describeUrlPart(number)})`);
   }
   return `https://github.com/${owner}/${repo}/pull/${Number(number)}`;
 }
+
+/** Render a value for the diagnostic above without hiding null/undefined/''. */
+function describeUrlPart(value) {
+  if (value === null) return 'null';
+  if (value === undefined) return 'undefined';
+  if (typeof value === 'string') return JSON.stringify(value);
+  return String(value);
+}
+
+/**
+ * Build a pull request URL when the pull request is already identified, and
+ * return `null` when it is not (for example, `--auto-continue` resumed a
+ * leftover branch whose pull request has not been created yet).
+ *
+ * Callers that legitimately run before a pull request exists must use this
+ * instead of `buildGitHubPullRequestUrl`, whose throw aborts the whole run.
+ *
+ * @see https://github.com/link-assistant/hive-mind/issues/2170
+ * @param {{owner?: string, repo?: string, number?: number|string|null}} [params]
+ * @returns {string|null}
+ */
+export function buildGitHubPullRequestUrlOrNull(params = {}) {
+  try {
+    return buildGitHubPullRequestUrl(params);
+  } catch {
+    return null;
+  }
+}
 /**
  * Check if a URL is a valid GitHub URL of a specific type
  * @param {string} url - The URL to check

package/src/github.lib.mjs

@@ -20,8 +20,8 @@ export { buildCostInfoString };
 // #1756: route gh exec calls through transient + rate-limit retry wrapper
 import { execGhWithRetry } from './github-rate-limit.lib.mjs';
 import { QUIET_PROBE } from './quiet-probe.lib.mjs'; // issues #2130, #2135: keep read-only probe payloads out of the attached log
-import { buildGitHubPullRequestUrl, isGitHubUrlType, normalizeGitHubUrl, parseGitHubUrl } from './github-url-parser.lib.mjs';
-export { buildGitHubPullRequestUrl, isGitHubUrlType, normalizeGitHubUrl, parseGitHubUrl };
+import { buildGitHubPullRequestUrl, buildGitHubPullRequestUrlOrNull, isGitHubUrlType, normalizeGitHubUrl, parseGitHubUrl } from './github-url-parser.lib.mjs';
+export { buildGitHubPullRequestUrl, buildGitHubPullRequestUrlOrNull, isGitHubUrlType, normalizeGitHubUrl, parseGitHubUrl };
 // Issue #1625: Named marker constants (single source of truth) + in-memory tracking for tool-posted comments. See tool-comments.lib.mjs for design.
 import { SOLUTION_DRAFT_LOG_MARKER, SOLUTION_DRAFT_FAILED_MARKER, SOLUTION_DRAFT_FINISHED_WITH_ERRORS_MARKER, USAGE_LIMIT_REACHED_MARKER, NOW_WORKING_SESSION_IS_ENDED_MARKER, postTrackedComment, postTrackedCommentFromFile } from './tool-comments.lib.mjs';
 export const maskGitHubToken = maskToken; // Alias for backward compatibility
@@ -1171,6 +1171,7 @@ export default {
   isRateLimitError,
   batchCheckPullRequestsForIssues,
   buildGitHubPullRequestUrl,
+  buildGitHubPullRequestUrlOrNull,
   parseGitHubUrl,
   normalizeGitHubUrl,
   isGitHubUrlType,

package/src/opencode.lib.mjs

@@ -25,7 +25,7 @@ import { checkPlaywrightMcpPackageAvailability, getOpenCodePlaywrightMcpDisableE
 import { createAgentTokenUsage, accumulateAgentStepFinishUsage, parseAgentTokenUsage as parseOpenCodeTokenUsage } from './agent-token-usage.lib.mjs';
 import { createJsonStreamScanner } from './json-stream.lib.mjs';
 import { calculateAgentPricing } from './agent.lib.mjs';
-import { classifyRetryableError, prepareRetryAfterError, waitWithCountdown } from './tool-retry.lib.mjs';
+import { classifyRetryableError, createTransientRetryBudget, prepareRetryAfterError, waitWithCountdown } from './tool-retry.lib.mjs';
 import { ensureAiToolScratchIgnored, filterAiToolScratchFromStatus } from './ai-tool-scratch.lib.mjs';
 
 export { parseOpenCodeTokenUsage };
@@ -193,13 +193,16 @@ export const executeOpenCodeCommand = async params => {
 
   // Retry configuration
   let retryCount = 0;
+  // Issue #2169: retries are bounded by a wall-clock budget (12 h by default, configurable via
+  // HIVE_MIND_TRANSIENT_ERROR_RETRY_BUDGET_MS) instead of a low attempt count.
+  const transientRetryBudget = createTransientRetryBudget();
 
   const executeWithRetry = async () => {
     // Execute opencode command from the cloned repository directory
     if (retryCount === 0) {
       await log(`\n${formatAligned('🤖', 'Executing OpenCode:', argv.model.toUpperCase())}`);
     } else {
-      await log(`\n${formatAligned('🔄', 'Retry attempt:', `${retryCount}/${retryLimits.maxTransientErrorRetries}`)}`);
+      await log(`\n${formatAligned('🔄', 'Retry attempt:', `${retryCount} (${transientRetryBudget.describeProgress()})`)}`);
     }
 
     if (argv.verbose) {
@@ -483,7 +486,17 @@ export const executeOpenCodeCommand = async params => {
         if (retryableError.isRetryable) {
           const isRequestTimeoutRetry = retryableError.label === 'Request timeout';
           const maxRetries = isRequestTimeoutRetry ? retryLimits.maxRequestTimeoutRetries : retryLimits.maxTransientErrorRetries;
-          if (retryCount < maxRetries) {
+          // Issue #2169: the attempt count is only a runaway backstop — the 12-hour wall-clock budget
+          // (configurable) decides when to stop, and every wait honours the 3-minute minimum.
+          const retryDecision = transientRetryBudget.evaluate({
+            retryCount,
+            maxRetries,
+            initialDelayMs: isRequestTimeoutRetry ? retryLimits.initialRequestTimeoutDelayMs : retryLimits.initialTransientErrorDelayMs,
+            maxDelayMs: isRequestTimeoutRetry ? retryLimits.maxRequestTimeoutDelayMs : retryLimits.maxTransientErrorDelayMs,
+            minDelayMs: retryLimits.minTransientErrorDelayMs,
+          });
+          if (retryDecision.allowed) {
+            transientRetryBudget.grant();
             if (sessionId && !argv.resume) argv.resume = sessionId;
             // Issue #2037: retry the same model on capacity errors before falling back;
             // after a capacity-driven model switch, retry quickly instead of waiting the
@@ -496,16 +509,17 @@ export const executeOpenCodeCommand = async params => {
               retryCount,
               initialDelayMs: isRequestTimeoutRetry ? retryLimits.initialRequestTimeoutDelayMs : retryLimits.initialTransientErrorDelayMs,
               maxDelayMs: isRequestTimeoutRetry ? retryLimits.maxRequestTimeoutDelayMs : retryLimits.maxTransientErrorDelayMs,
+              minDelayMs: retryLimits.minTransientErrorDelayMs,
             });
             const delay = retryPlan.delay;
             const delayLabel = delay >= 60000 ? `${Math.round(delay / 60000)} min` : `${Math.round(delay / 1000)}s`;
-            await log(`\n⚠️ ${retryableError.label} detected. Retry ${retryCount + 1}/${maxRetries} in ${delayLabel}${sessionId ? ' (session preserved)' : ''}...`, { level: 'warning' });
+            await log(`\n⚠️ ${retryableError.label} detected. Retry ${retryCount + 1} in ${delayLabel}${sessionId ? ' (session preserved)' : ''} (${transientRetryBudget.describeProgress()})...`, { level: 'warning' });
             await waitForRetryDelay(delay, log);
             await log('\n🔄 Retrying now...');
             retryCount++;
             return await executeWithRetry();
           }
-          await log(`\n\n❌ ${retryableError.label} persisted after ${maxRetries} retries`, { level: 'error' });
+          await log(`\n\n❌ ${retryableError.label} persisted: ${transientRetryBudget.describeExhaustion(retryDecision)}`, { level: 'error' });
         }
 
         // Check for usage limit errors first (more specific)

package/src/qwen.lib.mjs

@@ -22,7 +22,7 @@ import { qwenModels, defaultModels, isFormalAiModel } from './models/index.mjs';
 import { buildFormalAiEnvExports, isPrepareOnly, logPreparedToolCommand, resolveFormalAiToolExecution } from './formal-ai.lib.mjs';
 import { buildFormalAiPricingInfo } from './formal-ai-pricing.lib.mjs'; // Issue #2119
 import { checkPlaywrightMcpPackageAvailability } from './playwright-mcp.lib.mjs';
-import { classifyRetryableError, prepareRetryAfterError, waitWithCountdown } from './tool-retry.lib.mjs';
+import { classifyRetryableError, createTransientRetryBudget, prepareRetryAfterError, waitWithCountdown } from './tool-retry.lib.mjs';
 import { getCumulativeContextInputTokens, getRestoredContextInputTokens, toTokenCount } from './context-fill.lib.mjs';
 import { ensureAiToolScratchIgnored, filterAiToolScratchFromStatus } from './ai-tool-scratch.lib.mjs';
 import { getTerminalEventCompletionHealth } from './tool-run-health.lib.mjs'; // Issue #1990
@@ -489,6 +489,9 @@ export const executeQwenCommand = async params => {
   const { tempDir, branchName, prompt, systemPrompt, argv, log, formatAligned = (_icon, label, value = '') => `${label} ${value}`.trim(), getResourceSnapshot = async () => ({ memory: '\nunknown', load: 'unknown' }), forkedRepo, feedbackLines, qwenPath = 'qwen', $: dollar = $, waitForRetryDelay = waitWithCountdown } = params;
 
   let retryCount = 0;
+  // Issue #2169: retries are bounded by a wall-clock budget (12 h by default, configurable via
+  // HIVE_MIND_TRANSIENT_ERROR_RETRY_BUDGET_MS) instead of a low attempt count.
+  const transientRetryBudget = createTransientRetryBudget();
   const promptFile = path.join(os.tmpdir(), `qwen_prompt_${Date.now()}_${process.pid}.txt`);
   const systemPromptFile = path.join(os.tmpdir(), `qwen_system_prompt_${Date.now()}_${process.pid}.txt`);
 
@@ -499,7 +502,7 @@ export const executeQwenCommand = async params => {
     if (retryCount === 0) {
       await log(`\n${formatAligned('🤖', 'Executing Qwen Code:', argv.model.toUpperCase())}`);
     } else {
-      await log(`\n${formatAligned('🔄', 'Retry attempt:', `${retryCount}/${retryLimits.maxTransientErrorRetries}`)}`);
+      await log(`\n${formatAligned('🔄', 'Retry attempt:', `${retryCount} (${transientRetryBudget.describeProgress()})`)}`);
     }
 
     if (argv.verbose) {
@@ -625,7 +628,17 @@ export const executeQwenCommand = async params => {
           if (retryableError.isRetryable) {
             const isRequestTimeoutRetry = retryableError.label === 'Request timeout';
             const maxRetries = isRequestTimeoutRetry ? retryLimits.maxRequestTimeoutRetries : retryLimits.maxTransientErrorRetries;
-            if (retryCount < maxRetries) {
+            // Issue #2169: the attempt count is only a runaway backstop — the 12-hour wall-clock budget
+            // (configurable) decides when to stop, and every wait honours the 3-minute minimum.
+            const retryDecision = transientRetryBudget.evaluate({
+              retryCount,
+              maxRetries,
+              initialDelayMs: isRequestTimeoutRetry ? retryLimits.initialRequestTimeoutDelayMs : retryLimits.initialTransientErrorDelayMs,
+              maxDelayMs: isRequestTimeoutRetry ? retryLimits.maxRequestTimeoutDelayMs : retryLimits.maxTransientErrorDelayMs,
+              minDelayMs: retryLimits.minTransientErrorDelayMs,
+            });
+            if (retryDecision.allowed) {
+              transientRetryBudget.grant();
               if (sessionId && !argv.resume) argv.resume = sessionId;
               // Issue #2037: retry the same model on capacity errors before falling back;
               // after a capacity-driven model switch, retry quickly instead of waiting the
@@ -638,16 +651,17 @@ export const executeQwenCommand = async params => {
                 retryCount,
                 initialDelayMs: isRequestTimeoutRetry ? retryLimits.initialRequestTimeoutDelayMs : retryLimits.initialTransientErrorDelayMs,
                 maxDelayMs: isRequestTimeoutRetry ? retryLimits.maxRequestTimeoutDelayMs : retryLimits.maxTransientErrorDelayMs,
+                minDelayMs: retryLimits.minTransientErrorDelayMs,
               });
               const delay = retryPlan.delay;
               const delayLabel = delay >= 60000 ? `${Math.round(delay / 60000)} min` : `${Math.round(delay / 1000)}s`;
-              await log(`\n⚠️ ${retryableError.label} detected. Retry ${retryCount + 1}/${maxRetries} in ${delayLabel}${sessionId ? ' (session preserved)' : ''}...`, { level: 'warning' });
+              await log(`\n⚠️ ${retryableError.label} detected. Retry ${retryCount + 1} in ${delayLabel}${sessionId ? ' (session preserved)' : ''} (${transientRetryBudget.describeProgress()})...`, { level: 'warning' });
               await waitForRetryDelay(delay, log);
               await log('\n🔄 Retrying now...');
               retryCount++;
               return await executeWithRetry();
             }
-            await log(`\n\n❌ ${retryableError.label} persisted after ${maxRetries} retries`, { level: 'error' });
+            await log(`\n\n❌ ${retryableError.label} persisted: ${transientRetryBudget.describeExhaustion(retryDecision)}`, { level: 'error' });
           } else if (exitCode === 130) {
             await log('\n\n⚠️ Qwen Code command interrupted (CTRL+C)');
           } else {

package/src/solve.mjs

@@ -553,8 +553,18 @@ try {
     // Issue #2158: auto-continue can discover a PR while the input remains an
     // issue URL. Passing that issue URL as "Your prepared Pull Request" sent
     // the first Formal AI attempt to the wrong GitHub entity.
-    prUrl = githubLib.buildGitHubPullRequestUrl({ owner, repo, number: prNumber });
-    // prNumber is already set from earlier when we parsed the PR
+    //
+    // Issue #2170: continue mode does not imply a PR exists. --auto-continue
+    // also resumes a leftover `issue-<n>-<hash>` branch that never got a PR,
+    // and then prNumber is null. Building the URL unconditionally threw
+    // "A GitHub pull request URL requires owner, repo, and a positive integer
+    // number" and killed the run right after checkout. The PR is created a few
+    // lines below by handleAutoPrCreation, which sets both prUrl and prNumber.
+    prUrl = githubLib.buildGitHubPullRequestUrlOrNull({ owner, repo, number: prNumber });
+    if (!prUrl) {
+      await log(formatAligned('ℹ️', 'Continue mode:', 'Resuming an existing branch that has no pull request yet'));
+      await log(formatAligned('', 'Pull request:', 'Will be created before the tool session starts', 2));
+    }
   }
   // Handle auto PR creation using the new module
   const autoPrResult = await handleAutoPrCreation({

package/src/tool-retry.lib.mjs

@@ -24,6 +24,22 @@ const normalizeModelKey = value => {
     .trim();
 };
 
+// Issue #2169: HTTP status codes are only meaningful as errors when they appear in an
+// HTTP-status context. A bare number in prose ("PR #524", "issue #523", "line 502") is
+// not an error — matching it wrongly sent an entire successful session into a multi-hour
+// retry loop (see docs/case-studies/issue-2169). `matchesHttpStatus` accepts:
+//   "API Error: 502", "error code: 522", "status 504", "HTTP/1.1 520", "code=524"
+//   "502 Bad Gateway", "524 A Timeout Occurred" (status followed by its canonical phrase)
+const GATEWAY_STATUS_PHRASES = ['bad gateway', 'gateway timeout', 'gateway time-out', 'unknown error', 'web server is down', 'connection timed out', 'origin is unreachable', 'a timeout occurred'];
+const HTTP_STATUS_PREFIX = String.raw`(?:http(?:s|/\d(?:\.\d)?)?\s*)?(?:api\s+)?(?:error|status(?:\s*code)?|code|response|returned|got)\s*(?:code\s*)?[:=#]?\s*`;
+export const matchesHttpStatus = (lowerText, codePattern, phrases = []) => {
+  if (!lowerText) return false;
+  if (new RegExp(`${HTTP_STATUS_PREFIX}(?:${codePattern})\\b`).test(lowerText)) return true;
+  if (new RegExp(`\\bhttp\\s*(?:status\\s*)?(?:${codePattern})\\b`).test(lowerText)) return true;
+  if (phrases.length > 0 && new RegExp(`\\b(?:${codePattern})\\b[\\s,:;-]*(?:${phrases.join('|')})`).test(lowerText)) return true;
+  return false;
+};
+
 export const classifyRetryableError = value => {
   const message = normalizeMessage(value);
   const lower = message.toLowerCase();
@@ -163,7 +179,12 @@ export const classifyRetryableError = value => {
   // These come from an intermediary (CDN/proxy/load balancer), not from a request the
   // client got wrong, and clear on their own — OpenAI/Anthropic/GitHub all front their
   // APIs with such proxies. Safe to retry the same request after a backoff.
-  if (lower.includes('502 bad gateway') || lower.includes('bad gateway') || lower.includes('504 gateway timeout') || lower.includes('gateway time-out') || lower.includes('gateway timeout') || lower.includes('api error: 502') || lower.includes('api error: 504') || /\b52[0-4]\b/.test(lower)) {
+  // Issue #2169: the bare `/\b52[0-4]\b/` test used here before matched ANY standalone
+  // 520-524 in the text, so an agent's own success summary — "PR #524", "issue #523",
+  // "(`463c5ca`, PR #522)" — was classified as a gateway error and retried for hours.
+  // The number now has to appear in an HTTP-status context ("error code: 522",
+  // "API Error: 502", "HTTP 504") or next to the status' canonical phrase.
+  if (lower.includes('502 bad gateway') || lower.includes('bad gateway') || lower.includes('504 gateway timeout') || lower.includes('gateway time-out') || lower.includes('gateway timeout') || matchesHttpStatus(lower, '502|504|52[0-4]', GATEWAY_STATUS_PHRASES)) {
     return { message, isRetryable: true, isCapacity: false, label: 'Gateway error (502/504/52x)' };
   }
 
@@ -201,7 +222,9 @@ export const classifyRetryableError = value => {
   // Issue #1955: broadened to also catch the bare "503 Service Unavailable" that
   // GitHub/OpenAI/Anthropic return when a backend is briefly saturated — a
   // transient, self-clearing condition, safe to retry with the same request.
-  if (lower.includes('api error: 503') || lower.includes('503 service unavailable') || lower.includes('service unavailable') || (lower.includes('503') && (lower.includes('upstream connect error') || lower.includes('remote connection failure')))) {
+  // Issue #2169: `matchesHttpStatus` accepts the status only next to an error-ish prefix
+  // ("api error: 503", "status code: 503"), never a bare number in prose.
+  if (lower.includes('api error: 503') || lower.includes('503 service unavailable') || lower.includes('service unavailable') || matchesHttpStatus(lower, '503') || (lower.includes('503') && (lower.includes('upstream connect error') || lower.includes('remote connection failure')))) {
     return { message, isRetryable: true, isCapacity: false, label: '503 network error' };
   }
 
@@ -212,8 +235,92 @@ export const classifyRetryableError = value => {
   return { message, isRetryable: false, isCapacity: false, label: null };
 };
 
-export const getRetryDelayMs = ({ retryCount, initialDelayMs = retryLimits.initialTransientErrorDelayMs, maxDelayMs = retryLimits.maxTransientErrorDelayMs } = {}) => {
-  return Math.min(initialDelayMs * Math.pow(retryLimits.retryBackoffMultiplier, retryCount), maxDelayMs);
+// Issue #2169: `minDelayMs` is the floor for the transient-API-error paths ("with minimum of
+// 3 minutes"). It defaults to 0 so the deliberately fast paths — capacity retries (15s), a
+// model switch (5s), stream startup/activity timeouts (30s) — keep their short delays.
+export const getRetryDelayMs = ({ retryCount, initialDelayMs = retryLimits.initialTransientErrorDelayMs, maxDelayMs = retryLimits.maxTransientErrorDelayMs, minDelayMs = 0 } = {}) => {
+  const backoff = Math.min(initialDelayMs * Math.pow(retryLimits.retryBackoffMultiplier, retryCount), maxDelayMs);
+  return Math.max(backoff, Math.min(minDelayMs, maxDelayMs));
+};
+
+// Issue #2169: diagnosing a *mis*classification from the log used to be impossible — the retry
+// line printed only the first 200 characters of the message, while the token that actually made
+// the classifier fire ("PR #524", 1.6 KB later) was never shown. This renders the evidence for a
+// classification: how long the message was and the ±40-character context around every HTTP-status
+// -looking token in it, so the next false positive is diagnosable from a single verbose log line.
+export const describeClassificationEvidence = (message, label = null, { maxMatches = 3, contextChars = 40 } = {}) => {
+  const text = String(message ?? '');
+  const parts = [`label=${JSON.stringify(label)}`, `messageChars=${text.length}`];
+  const matches = [];
+  for (const match of text.matchAll(/\b(?:4\d{2}|5\d{2})\b/g)) {
+    const start = Math.max(0, match.index - contextChars);
+    const end = Math.min(text.length, match.index + match[0].length + contextChars);
+    matches.push(`@${match.index} ${JSON.stringify(text.slice(start, end).replace(/\s+/g, ' '))}`);
+    if (matches.length >= maxMatches) break;
+  }
+  parts.push(matches.length > 0 ? `statusTokens=[${matches.join(', ')}]` : 'statusTokens=[]');
+  return parts.join(' ');
+};
+
+// Issue #2169: human-readable duration for retry logs — "45s", "12 min", "3h 15m", "12h".
+export const formatRetryDuration = ms => {
+  if (!Number.isFinite(ms)) return 'unlimited';
+  if (ms < 60000) return `${Math.max(0, Math.round(ms / 1000))}s`;
+  const totalMinutes = Math.round(ms / 60000);
+  if (totalMinutes < 60) return `${totalMinutes} min`;
+  const hours = Math.floor(totalMinutes / 60);
+  const minutes = totalMinutes % 60;
+  return minutes === 0 ? `${hours}h` : `${hours}h ${minutes}m`;
+};
+
+// Issue #2169: a provider outage can last many hours. The retry loops used to stop after a
+// fixed number of attempts (10), which — with the old 2 min → 30 min backoff — gave up after
+// ~3.5 hours. The budget below turns "how long do we keep trying" into the primary knob: retries
+// continue while the *next* backoff still fits inside `budgetMs` (default 12 h), measured from
+// the first retry of the run. The per-tool retry counts stay as runaway-loop backstops.
+//
+// Usage inside a tool's retry loop (the budget object lives outside `executeWithRetry` so it
+// survives the recursive calls):
+//   const budget = createTransientRetryBudget();
+//   const decision = budget.evaluate({ retryCount, maxRetries, initialDelayMs, maxDelayMs, minDelayMs });
+//   if (decision.allowed) { budget.grant(); ...wait decision.delayMs... } else { fail(decision) }
+export const createTransientRetryBudget = ({ budgetMs = retryLimits.transientErrorRetryBudgetMs, now = () => Date.now() } = {}) => {
+  let startedAt = null;
+  let retriesGranted = 0;
+  const elapsedMs = () => (startedAt === null ? 0 : Math.max(0, now() - startedAt));
+  const remainingMs = () => (budgetMs > 0 ? Math.max(0, budgetMs - elapsedMs()) : Infinity);
+  return {
+    budgetMs,
+    elapsedMs,
+    remainingMs,
+    get retriesGranted() {
+      return retriesGranted;
+    },
+    // Starts the clock on the first granted retry and counts it.
+    grant() {
+      if (startedAt === null) startedAt = now();
+      retriesGranted += 1;
+    },
+    evaluate({ retryCount = 0, maxRetries = retryLimits.maxTransientErrorRetries, initialDelayMs, maxDelayMs, minDelayMs = 0 } = {}) {
+      const delayMs = getRetryDelayMs({ retryCount, initialDelayMs, maxDelayMs, minDelayMs });
+      const base = { delayMs, elapsedMs: elapsedMs(), remainingMs: remainingMs(), budgetMs, retryCount, maxRetries };
+      if (retryCount >= maxRetries) return { ...base, allowed: false, reason: 'count' };
+      // Never start a wait that would run past the budget window.
+      if (budgetMs > 0 && delayMs > remainingMs()) return { ...base, allowed: false, reason: 'budget' };
+      return { ...base, allowed: true, reason: null };
+    },
+    // One-line explanation for the "giving up" log, e.g.
+    // "retry budget of 12h exhausted after 26 retries over 11h 45m".
+    describeExhaustion(decision) {
+      const spent = formatRetryDuration(decision?.elapsedMs ?? elapsedMs());
+      if (decision?.reason === 'count') return `retry limit of ${decision.maxRetries} attempts reached after ${spent} (budget ${formatRetryDuration(budgetMs)})`;
+      return `retry budget of ${formatRetryDuration(budgetMs)} exhausted after ${decision?.retryCount ?? retriesGranted} retries over ${spent}`;
+    },
+    // Progress suffix for each retry log line, e.g. "budget 25 min/12h used".
+    describeProgress() {
+      return budgetMs > 0 ? `budget ${formatRetryDuration(elapsedMs())}/${formatRetryDuration(budgetMs)} used` : 'budget disabled';
+    },
+  };
 };
 
 export const waitWithCountdown = async (delayMs, log) => {
@@ -352,7 +459,7 @@ export const maybeSwitchToFallbackModel = async ({ tool, argv, log, errorMessage
 // survives the recursive executeWithRetry calls without each tool tracking extra
 // state. It resets to 0 whenever we actually switch models, so every model in the
 // fallback chain gets its own batch of same-model retries before stepping down.
-export const prepareRetryAfterError = async ({ tool, argv, log, errorMessage, retryCount, initialDelayMs, maxDelayMs } = {}) => {
+export const prepareRetryAfterError = async ({ tool, argv, log, errorMessage, retryCount, initialDelayMs, maxDelayMs, minDelayMs = 0 } = {}) => {
   const classification = classifyRetryableError(errorMessage);
   const isCapacity = classification.isCapacity === true && !!argv?.model;
   const capacityRetryCount = argv?._capacityRetryCount || 0;
@@ -373,13 +480,17 @@ export const prepareRetryAfterError = async ({ tool, argv, log, errorMessage, re
   const switchResult = await maybeSwitchToFallbackModel({ tool, argv, log, errorMessage });
   // A model switch starts a fresh batch of same-model retries for the new model.
   if (switchResult?.switched && argv) argv._capacityRetryCount = 0;
-  const delay = switchResult?.switched ? retryLimits.modelSwitchRetryDelayMs : getRetryDelayMs({ retryCount, initialDelayMs, maxDelayMs });
+  const delay = switchResult?.switched ? retryLimits.modelSwitchRetryDelayMs : getRetryDelayMs({ retryCount, initialDelayMs, maxDelayMs, minDelayMs });
   return { delay, switched: switchResult?.switched === true };
 };
 
 export default {
   classifyRetryableError,
+  matchesHttpStatus,
   getRetryDelayMs,
+  describeClassificationEvidence,
+  formatRetryDuration,
+  createTransientRetryBudget,
   waitWithCountdown,
   resolveConfiguredFallbackModel,
   maybeSwitchToFallbackModel,