@link-assistant/hive-mind 2.0.7 → 2.0.8

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # @link-assistant/hive-mind
 
+## 2.0.8
+
+### Patch Changes
+
+- 072e941: fix(retry): keep the requested `--model` on transient overloads instead of switching to the fallback (#1949)
+
+  A transient **HTTP 529 "Overloaded"** result used to be classified as a
+  model-_capacity_ error (`isCapacity: true`), which made the shared retry helper
+  switch the user's requested `--model` to the configured fallback
+  (`opus -> opus-4-7`) on every overload. A 529 is a server-wide, transient
+  overload — not a signal that the selected model is full — so the run should retry
+  the **same** model. The overload branch in `src/tool-retry.lib.mjs` now returns
+  `isCapacity: false`; only a genuine "the selected model is at capacity" message
+  still triggers a `--model` switch. The fix lives in the shared helper, so every
+  tool (claude, codex, gemini, qwen, opencode, agent) inherits it.
+
+  Per-request fallback is now delegated to Claude Code itself: the claude tool
+  forwards `--fallback-model <id>` so overloads fall back _inside_ the CLI while our
+  `--model` stays stable.
+
+  Two display fixes remove the ambiguity that made this hard to diagnose:
+  - Warnings now render the resolved model ID alongside the alias, e.g.
+    `opus (claude-opus-4-8) -> opus-4-7 (claude-opus-4-7)`, via a new
+    `formatModelWithResolvedId` helper.
+  - The verbose per-retry "execution context" block now uses a shared
+    `logExecutionContext` helper that prints the resolved model actually passed to
+    the CLI, replacing a broken `argv.model === 'opus' ? 'opus' : 'sonnet'`
+    heuristic that mislabelled every non-`opus` alias as `sonnet`.
+
+  The PR/issue comment now shows the requested model with its resolved ID and the
+  requested thinking level (e.g. `high (~23999 tokens)`) via a new
+  `describeRequestedThinking` helper.
+
 ## 2.0.7
 
 ### Patch Changes

package/package.json

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

package/src/claude.lib.mjs

@@ -26,7 +26,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, maybeSwitchToFallbackModel, waitWithCountdown } from './tool-retry.lib.mjs';
+import { classifyRetryableError, logExecutionContext, maybeSwitchToFallbackModel, 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
@@ -619,18 +619,10 @@ export const executeClaudeCommand = async params => {
       await log(`\n${formatAligned('🔄', 'Retry attempt:', `${retryCount}/${retryLimits.maxTransientErrorRetries}`)}`);
     }
     if (argv.verbose) {
-      // Output the actual model being used
-      const modelName = argv.model === 'opus' ? 'opus' : 'sonnet';
-      await log(`   Model: ${modelName}`, { verbose: true });
-      await log(`   Working directory: ${tempDir}`, { verbose: true });
-      await log(`   Branch: ${branchName}`, { verbose: true });
-      await log(`   Prompt length: ${prompt.length} chars`, { verbose: true });
-      await log(`   System prompt length: ${systemPrompt.length} chars`, { verbose: true });
-      if (feedbackLines && feedbackLines.length > 0) {
-        await log(`   Feedback info included: Yes (${feedbackLines.length} lines)`, { verbose: true });
-      } else {
-        await log('   Feedback info included: No', { verbose: true });
-      }
+      // Issue #1949: logExecutionContext shows the requested alias with its resolved
+      // full ID (e.g. "opus (claude-opus-4-8)"). The old `argv.model === 'opus' ?
+      // 'opus' : 'sonnet'` heuristic mislabelled every non-"opus" alias as "sonnet".
+      await logExecutionContext({ log, model: argv.model, tool: 'claude', tempDir, branchName, promptLength: prompt.length, systemPromptLength: systemPrompt.length, feedbackLines });
     }
     const resourcesBefore = await getResourceSnapshot();
     await log('📈 System resources before execution:', { verbose: true });
@@ -704,7 +696,13 @@ export const executeClaudeCommand = async params => {
     const resolvedPlanModel = argv.planModel ? mapModelToId(argv.planModel) : undefined; // Issue #1223
     const effectiveModel = resolvedPlanModel ? 'opusplan' : mappedModel;
     const resolvedExecutionModel = resolvedPlanModel ? mappedModel : undefined;
+    // Issue #1949: Let Claude Code handle transient overload (529) fallback via its own
+    // `--fallback-model` flag (it re-tries the primary each turn) instead of us swapping
+    // `--model`. Only for plain `--model` runs (not opusplan) with a distinct fallback.
+    const mappedFallbackModel = argv.fallbackModel ? mapModelToId(argv.fallbackModel) : undefined;
+    const useClaudeFallbackModel = !resolvedPlanModel && mappedFallbackModel && mappedFallbackModel !== effectiveModel;
     let claudeArgs = `--output-format stream-json --verbose --dangerously-skip-permissions --model ${effectiveModel}`;
+    if (useClaudeFallbackModel) claudeArgs += ` --fallback-model ${mappedFallbackModel}`;
     // Declare queuedFeedback for use in catch/finally blocks and return value
     let queuedFeedback = [];
     // Issue #817: When --accept-incomming-comments-as-input is set and we are
@@ -761,17 +759,19 @@ export const executeClaudeCommand = async params => {
       const simpleEscapedSystem = systemPrompt.replace(/"/g, '\\"');
       const mcpDisableArgs = mcpConfigPath ? ['--strict-mcp-config', '--mcp-config', mcpConfigPath] : [];
       const disallowedToolsArgs = disallowedToolsList.length ? ['--disallowedTools', ...disallowedToolsList] : [];
+      const fallbackModelArgs = useClaudeFallbackModel ? ['--fallback-model', mappedFallbackModel] : []; // Issue #1949: Claude Code's per-request overload fallback
+      if (useClaudeFallbackModel && argv.verbose) await log(`📊 Claude --fallback-model: ${mappedFallbackModel} (Issue #1949 — primary --model ${effectiveModel} stays stable across overload retries)`, { verbose: true });
       if (argv.resume) {
         const simpleEscapedPrompt = prompt.replace(/"/g, '\\"');
-        execCommand = $({ cwd: tempDir, mirror: false, env: claudeEnv })`${claudePath} --resume ${argv.resume} --output-format stream-json --verbose --dangerously-skip-permissions --model ${effectiveModel} ${mcpDisableArgs} ${disallowedToolsArgs} -p "${simpleEscapedPrompt}" --append-system-prompt "${simpleEscapedSystem}"`;
+        execCommand = $({ cwd: tempDir, mirror: false, env: claudeEnv })`${claudePath} --resume ${argv.resume} --output-format stream-json --verbose --dangerously-skip-permissions --model ${effectiveModel} ${fallbackModelArgs} ${mcpDisableArgs} ${disallowedToolsArgs} -p "${simpleEscapedPrompt}" --append-system-prompt "${simpleEscapedSystem}"`;
       } else if (streamingInput) {
         // Issue #817: Drive Claude via --input-format stream-json on a pipe
         // stdin. Initial prompt + later PR comments are written as NDJSON
         // frames by attachStreamingInput (see bidirectional-interactive.lib.mjs).
         const streamingInputArgs = ['-p', '--input-format', 'stream-json'];
-        execCommand = $({ cwd: tempDir, stdin: 'pipe', mirror: false, env: claudeEnv })`${claudePath} --output-format stream-json --verbose --dangerously-skip-permissions --model ${effectiveModel} ${mcpDisableArgs} ${disallowedToolsArgs} ${streamingInputArgs} --append-system-prompt "${simpleEscapedSystem}"`;
+        execCommand = $({ cwd: tempDir, stdin: 'pipe', mirror: false, env: claudeEnv })`${claudePath} --output-format stream-json --verbose --dangerously-skip-permissions --model ${effectiveModel} ${fallbackModelArgs} ${mcpDisableArgs} ${disallowedToolsArgs} ${streamingInputArgs} --append-system-prompt "${simpleEscapedSystem}"`;
       } else {
-        execCommand = $({ cwd: tempDir, stdin: prompt, mirror: false, env: claudeEnv })`${claudePath} --output-format stream-json --verbose --dangerously-skip-permissions --model ${effectiveModel} ${mcpDisableArgs} ${disallowedToolsArgs} --append-system-prompt "${simpleEscapedSystem}"`;
+        execCommand = $({ cwd: tempDir, stdin: prompt, mirror: false, env: claudeEnv })`${claudePath} --output-format stream-json --verbose --dangerously-skip-permissions --model ${effectiveModel} ${fallbackModelArgs} ${mcpDisableArgs} ${disallowedToolsArgs} --append-system-prompt "${simpleEscapedSystem}"`;
       }
       if (streamingInput) {
         await attachStreamingInput(bidirectionalHandler, execCommand, prompt, log, !!argv.verbose);

package/src/config.lib.mjs

@@ -412,6 +412,42 @@ export const getTokensToThinkingLevel = (maxBudget = DEFAULT_MAX_THINKING_BUDGET
 // Default tokens to thinking level function (using default max budget)
 export const tokensToThinkingLevel = getTokensToThinkingLevel(DEFAULT_MAX_THINKING_BUDGET);
 
+/**
+ * Issue #1949: Produce a human-readable description of the thinking level that was
+ * requested for a run, for inclusion in the PR/issue "Models used" comment. The
+ * user asked us to "display requested and (actual thinking level if possible)".
+ *
+ * The level is derived from `argv.think` (an explicit level keyword) and/or
+ * `argv.thinkingBudget` (an explicit token budget), mirroring the same translation
+ * logic used by resolveThinkingSettings():
+ *   - When only --think is given, show the keyword (with the token budget it maps to).
+ *   - When only --thinking-budget is given, derive the keyword from the budget.
+ *   - When neither is given, the level is the tool's default → returns null so the
+ *     caller can omit the line rather than guess.
+ *
+ * @param {Object} argv - Parsed CLI args (reads think, thinkingBudget, maxThinkingBudget)
+ * @returns {string|null} e.g. "high (~24000 tokens)", "off (disabled)", or null
+ */
+export const describeRequestedThinking = (argv = {}) => {
+  if (!argv || typeof argv !== 'object') return null;
+  const maxBudget = argv.maxThinkingBudget ?? DEFAULT_MAX_THINKING_BUDGET;
+  const levelToTokens = getThinkingLevelToTokens(maxBudget);
+  const tokensToLevel = getTokensToThinkingLevel(maxBudget);
+
+  let level = argv.think;
+  let budget = argv.thinkingBudget;
+
+  // Neither specified → tool default; the caller omits the line.
+  if (level === undefined && budget === undefined) return null;
+
+  if (level === undefined && budget !== undefined) level = tokensToLevel(budget);
+  if (budget === undefined && level !== undefined) budget = levelToTokens[level];
+
+  if (level === 'off' || budget === 0) return 'off (disabled)';
+  if (budget !== undefined && budget !== null) return `${level} (~${budget} tokens)`;
+  return String(level);
+};
+
 /**
  * Valid effort levels for Opus 4.6 and Sonnet 4.6 (Issue #1238, Issue #1620)
  * These models use CLAUDE_CODE_EFFORT_LEVEL for thinking depth control

package/src/github.lib.mjs

@@ -5,7 +5,7 @@ if (typeof globalThis.use === 'undefined') await ensureUseM();
 const { $ } = await use('command-stream'); // Use command-stream for consistent $ behavior
 import { log, maskToken, cleanErrorMessage, isENOSPC, ghCmdRetry } from './lib.mjs';
 import { reportError } from './sentry.lib.mjs';
-import { githubLimits, timeouts } from './config.lib.mjs';
+import { describeRequestedThinking, githubLimits, timeouts } from './config.lib.mjs';
 import { batchCheckPullRequestsForIssues as batchCheckPRs, batchCheckArchivedRepositories as batchCheckArchived } from './github.batch.lib.mjs';
 import { isSafeToken, isHexInSafeContext, getGitHubTokensFromFiles, getGitHubTokensFromCommand, sanitizeOutput, sanitizeLogContent } from './token-sanitization.lib.mjs';
 export { isSafeToken, isHexInSafeContext, getGitHubTokensFromFiles, getGitHubTokensFromCommand, sanitizeOutput, sanitizeLogContent }; // Re-export for backward compatibility
@@ -356,6 +356,8 @@ export async function attachLogToGitHub(options) {
     pricingInfo = null,
     errorDuringExecution = false, // Issue #1088
     requestedModel = null, // Issue #1225: The --model flag value
+    argv = null, // Issue #1949: parsed CLI args, used to derive the requested thinking level for the comment
+    thinkingInfo = null, // Issue #1949: explicit thinking level description (overrides the value derived from argv)
     tool = null, // The tool used (claude, agent, opencode, codex)
     resultModelUsage = null, // Issue #1454
     budgetStatsData = null, // Issue #1491: budget stats for comment
@@ -428,7 +430,10 @@ export async function attachLogToGitHub(options) {
     let modelInfoString = '';
     if (requestedModel || tool || actualModelIds) {
       try {
-        modelInfoString = await getModelInfoForComment({ requestedModel, tool, pricingInfo, actualModelIds });
+        // Issue #1949: prefer an explicit thinkingInfo, otherwise derive it from argv
+        // (e.g. "high (~24000 tokens)"). null when the run used the tool's default.
+        const resolvedThinkingInfo = thinkingInfo ?? describeRequestedThinking(argv);
+        modelInfoString = await getModelInfoForComment({ requestedModel, tool, pricingInfo, actualModelIds, thinkingInfo: resolvedThinkingInfo });
         if (verbose && modelInfoString) {
           await log('  🤖 Model info fetched for comment', { verbose: true });
         }

package/src/models/index.mjs

@@ -926,7 +926,7 @@ const doesRequestedMatchActual = (requestedModel, actualModelId, tool) => {
  * @param {Array<{modelId: string, modelInfo: Object|null}>|null} options.modelsUsed - Actual models used from CLI JSON output
  * @returns {string} Formatted markdown string for model info section
  */
-export const buildModelInfoString = ({ requestedModel = null, tool = null, pricingInfo = null, modelInfo = null, modelsUsed = null } = {}) => {
+export const buildModelInfoString = ({ requestedModel = null, tool = null, pricingInfo = null, modelInfo = null, modelsUsed = null, thinkingInfo = null } = {}) => {
   const hasRequested = requestedModel !== null && requestedModel !== undefined;
   const hasModelsUsed = Array.isArray(modelsUsed) && modelsUsed.length > 0;
   const hasModelInfo = modelInfo !== null;
@@ -941,7 +941,22 @@ export const buildModelInfoString = ({ requestedModel = null, tool = null, prici
   }
 
   if (hasRequested) {
-    info += `\n- Requested: \`${requestedModel}\``;
+    // Issue #1949: the bare alias (e.g. "opus") is ambiguous \u2014 show the full model
+    // ID it resolves to so reviewers know exactly which model ran, e.g.
+    // "Requested: `opus` (`claude-opus-4-8`)". When the alias already equals its
+    // resolved ID (or cannot be resolved) we just print the alias once.
+    const resolvedRequested = resolveModelId(requestedModel, tool);
+    if (resolvedRequested && String(resolvedRequested).toLowerCase() !== String(requestedModel).toLowerCase()) {
+      info += `\n- Requested: \`${requestedModel}\` (\`${resolvedRequested}\`)`;
+    } else {
+      info += `\n- Requested: \`${requestedModel}\``;
+    }
+  }
+
+  // Issue #1949: surface the requested thinking level alongside the model so the
+  // comment records how deeply the model was asked to think (null = tool default).
+  if (thinkingInfo) {
+    info += `\n- Thinking level: ${thinkingInfo}`;
   }
 
   if (hasModelsUsed) {
@@ -1044,7 +1059,7 @@ export const resolveDefaultFallbackModel = (tool, model) => {
  * @param {Array<string>|null} options.actualModelIds - Actual model IDs from CLI JSON output
  * @returns {Promise<string>} Formatted markdown model info section
  */
-export const getModelInfoForComment = async ({ requestedModel = null, tool = null, pricingInfo = null, actualModelIds = null } = {}) => {
+export const getModelInfoForComment = async ({ requestedModel = null, tool = null, pricingInfo = null, actualModelIds = null, thinkingInfo = null } = {}) => {
   let modelIds = [];
 
   if (Array.isArray(actualModelIds) && actualModelIds.length > 0) {
@@ -1075,5 +1090,6 @@ export const getModelInfoForComment = async ({ requestedModel = null, tool = nul
     pricingInfo,
     modelInfo: modelsUsed.length === 0 ? firstModelInfo : null,
     modelsUsed: modelsUsed.length > 0 ? modelsUsed : null,
+    thinkingInfo,
   });
 };

package/src/solve.execution.lib.mjs

@@ -197,6 +197,7 @@ export const handleExecutionError = async (error, shouldAttachLogs, owner, repo,
           verbose: argv.verbose || false,
           errorMessage: cleanErrorMessage(error),
           // Issue #1225: Pass model and tool info for PR comments
+          argv,
           requestedModel: argv.originalModel || argv.model,
           tool: argv.tool || 'claude',
         });

package/src/solve.mjs

@@ -942,10 +942,10 @@ try {
             toolName: getToolDisplayName(argv.tool),
             resumeCommand,
             sessionId,
+            argv,
             requestedModel: argv.originalModel || argv.model,
             tool: argv.tool || 'claude',
-            // Issue #1454: Pass resultModelUsage for accurate multi-model display
-            resultModelUsage,
+            resultModelUsage, // Issue #1454: accurate multi-model display
           });
 
           if (logUploadSuccess) {
@@ -1014,10 +1014,10 @@ try {
               // See: https://github.com/link-assistant/hive-mind/issues/1152
               isAutoResumeEnabled: true,
               autoResumeMode: limitContinueMode,
+              argv,
               requestedModel: argv.originalModel || argv.model,
               tool: argv.tool || 'claude',
-              // Issue #1454: Pass resultModelUsage for accurate multi-model display
-              resultModelUsage,
+              resultModelUsage, // Issue #1454: accurate multi-model display
             });
 
             if (logUploadSuccess) {
@@ -1125,10 +1125,10 @@ try {
           sessionId,
           // If not a usage limit case, fall back to generic failure format
           errorMessage: limitReached ? undefined : toolFailureMessage,
+          argv,
           requestedModel: argv.originalModel || argv.model,
           tool: argv.tool || 'claude',
-          // Issue #1454: Pass resultModelUsage for accurate multi-model display
-          resultModelUsage,
+          resultModelUsage, // Issue #1454: accurate multi-model display
         });
 
         if (logUploadSuccess) {
@@ -1380,10 +1380,10 @@ try {
           sessionId,
           tempDir,
           anthropicTotalCostUSD,
+          argv,
           requestedModel: argv.originalModel || argv.model,
           tool: argv.tool || 'claude',
-          // Issue #1454: Pass resultModelUsage for accurate multi-model display
-          resultModelUsage,
+          resultModelUsage, // Issue #1454: accurate multi-model display
         });
 
         if (logUploadSuccess) {

package/src/solve.pre-pr-failure-notifier.lib.mjs

@@ -206,6 +206,7 @@ export async function notifyIssueAboutPrePullRequestFailure(options) {
           verbose: argv.verbose,
           errorMessage: `${errorPrefix}\n\nReason: ${reason || 'Unknown error'}`,
           failureActionSection: buildPrePullRequestFailureActionSection(reason),
+          argv,
           requestedModel: argv.originalModel || argv.model,
           tool: argv.tool || 'claude',
         });

package/src/solve.results.lib.mjs

@@ -875,6 +875,7 @@ Fixes ${issueRef}
             // Issue #1152: Pass sessionType for differentiated log comments
             sessionType,
             // Issue #1225: Pass model and tool info for PR comments
+            argv,
             requestedModel: argv.originalModel || argv.model,
             tool: argv.tool || 'claude',
             // Issue #1454: Pass resultModelUsage for accurate multi-model display
@@ -961,6 +962,7 @@ Fixes ${issueRef}
           // Issue #1152: Pass sessionType for differentiated log comments
           sessionType,
           // Issue #1225: Pass model and tool info for issue comments
+          argv,
           requestedModel: argv.originalModel || argv.model,
           tool: argv.tool || 'claude',
           // Issue #1454: Pass resultModelUsage for accurate multi-model display
@@ -1052,6 +1054,7 @@ export const handleExecutionError = async (error, shouldAttachLogs, owner, repo,
           verbose: argv.verbose || false,
           errorMessage: cleanErrorMessage(error),
           // Issue #1225: Pass model and tool info for PR comments
+          argv,
           requestedModel: argv.originalModel || argv.model,
           tool: argv.tool || 'claude',
         });

package/src/tool-retry.lib.mjs

@@ -27,12 +27,28 @@ export const classifyRetryableError = value => {
   const message = normalizeMessage(value);
   const lower = message.toLowerCase();
 
+  // Genuine model-specific capacity: the API explicitly tells us this *particular*
+  // model is full and recommends trying a *different* model (e.g. Codex's
+  // "Selected model is at capacity. Please try a different model."). Here a model
+  // switch is the correct, API-recommended recovery, so isCapacity stays true.
   if (lower.includes('selected model is at capacity') || (lower.includes('at capacity') && lower.includes('try a different model'))) {
     return { message, isRetryable: true, isCapacity: true, label: 'Model capacity error' };
   }
 
+  // Issue #1949: Transient server-wide overload (HTTP 529 / "overloaded_error"). The
+  // Claude API surfaces this as a synthetic result message:
+  //   "API Error: 529 Overloaded. This is a server-side issue, usually temporary —
+  //    try again in a moment. If it persists, check https://status.claude.com."
+  // This is NOT a model-specific capacity problem — Anthropic's own guidance is to
+  // retry the *same* request after a short backoff (the message literally says "try
+  // again in a moment"). Switching the requested `--model` to a fallback (e.g.
+  // opus -> opus-4-7) is wrong here: it silently downgrades the user's chosen model
+  // for a purely transient blip, and the fallback model lives behind the same
+  // overloaded API anyway. Claude Code already exposes its own per-request fallback
+  // via `--fallback-model` (wired in claude.lib.mjs), so we keep `--model` stable and
+  // simply retry. Therefore isCapacity is false → retry with the same model.
   if (lower.includes('overloaded') || lower.includes('overloaded_error')) {
-    return { message, isRetryable: true, isCapacity: true, label: 'API overload' };
+    return { message, isRetryable: true, isCapacity: false, label: 'API overload' };
   }
 
   if (lower.includes('request timed out')) {
@@ -140,6 +156,34 @@ export const resolveConfiguredFallbackModel = ({ tool, currentModel, configuredF
   return resolveDefaultFallbackModel(tool, currentModel);
 };
 
+// Issue #1949: Render a model alias together with the full ID it resolves to, e.g.
+// "opus (claude-opus-4-8)". Earlier the warning printed only the bare alias, so a
+// message like "Switching to fallback model: opus -> opus-4-7" was ambiguous (what
+// does "opus" actually map to?). Showing both removes that ambiguity. When the alias
+// already equals its resolved ID (or cannot be resolved) we just print the alias.
+export const formatModelWithResolvedId = (model, tool) => {
+  if (!model) return String(model);
+  const resolved = resolveModelId(model, tool);
+  if (!resolved || normalizeModelKey(resolved) === normalizeModelKey(model)) return String(model);
+  return `${model} (${resolved})`;
+};
+
+// Issue #1949: Shared verbose "execution context" logger. Extracted from
+// claude.lib.mjs so the per-tool retry loops can emit a consistent pre-run summary
+// (resolved model, working dir, branch, prompt sizes, feedback) without each file
+// duplicating the block. The model line uses formatModelWithResolvedId so the alias
+// and its full ID are always shown together (e.g. "opus (claude-opus-4-8)").
+export const logExecutionContext = async ({ log, model, tool, tempDir, branchName, promptLength, systemPromptLength, feedbackLines } = {}) => {
+  if (typeof log !== 'function') return;
+  await log(`   Model: ${formatModelWithResolvedId(model, tool)}`, { verbose: true });
+  await log(`   Working directory: ${tempDir}`, { verbose: true });
+  await log(`   Branch: ${branchName}`, { verbose: true });
+  await log(`   Prompt length: ${promptLength} chars`, { verbose: true });
+  await log(`   System prompt length: ${systemPromptLength} chars`, { verbose: true });
+  const feedbackCount = feedbackLines && feedbackLines.length > 0 ? feedbackLines.length : 0;
+  await log(feedbackCount > 0 ? `   Feedback info included: Yes (${feedbackCount} lines)` : '   Feedback info included: No', { verbose: true });
+};
+
 export const maybeSwitchToFallbackModel = async ({ tool, argv, log, errorMessage } = {}) => {
   const fallbackModel = resolveConfiguredFallbackModel({
     tool,
@@ -148,7 +192,17 @@ export const maybeSwitchToFallbackModel = async ({ tool, argv, log, errorMessage
   });
 
   const classification = classifyRetryableError(errorMessage);
+
+  // Issue #1949: Only switch the requested `--model` for genuine model-specific
+  // capacity errors where the API itself recommends a different model. Transient,
+  // retryable conditions (overload/529, timeouts, rate limits, socket drops, …) are
+  // classified with isCapacity=false and must retry the *same* model — Claude Code's
+  // own `--fallback-model` handles per-request fallback for those without us mutating
+  // the user's chosen model.
   if (!fallbackModel || !classification.isCapacity || !argv?.model) {
+    if (typeof log === 'function' && classification.isRetryable && !classification.isCapacity) {
+      await log(`   Keeping requested model ${formatModelWithResolvedId(argv?.model, tool)} (transient ${classification.label || 'error'} — no fallback switch, Issue #1949)`, { verbose: true });
+    }
     return { switched: false, fallbackModel, reason: classification.label };
   }
 
@@ -163,7 +217,9 @@ export const maybeSwitchToFallbackModel = async ({ tool, argv, log, errorMessage
   if (!argv.fallbackModel) argv.fallbackModel = fallbackModel;
 
   if (typeof log === 'function') {
-    await log(`🔀 Switching to fallback model: ${previousModel} -> ${fallbackModel}`, { level: 'warning' });
+    // Issue #1949: show the resolved full model IDs so the switch is unambiguous,
+    // e.g. "opus (claude-opus-4-8) -> opus-4-7 (claude-opus-4-7)".
+    await log(`🔀 Switching to fallback model: ${formatModelWithResolvedId(previousModel, tool)} -> ${formatModelWithResolvedId(fallbackModel, tool)}`, { level: 'warning' });
   }
 
   return {
@@ -180,4 +236,6 @@ export default {
   waitWithCountdown,
   resolveConfiguredFallbackModel,
   maybeSwitchToFallbackModel,
+  formatModelWithResolvedId,
+  logExecutionContext,
 };