@link-assistant/hive-mind 2.12.5 → 2.13.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @link-assistant/hive-mind
 
+## 2.13.0
+
+### Minor Changes
+
+- aaf809a: Recognize subscription/account access blocks from every supported CLI (Claude, Codex, Qwen, Gemini, opencode) as their own error class: stop the run instead of retrying or switching model, auto-commit and push the in-flight work first, report what happened and what to do in the terminal, in the `/solve` exit message and in the Telegram completion message (en/ru/zh/hi), and stop the `/hive` queue so the fleet no longer rediscovers the block once per issue.
+
 ## 2.12.5
 
 ### Patch Changes

package/package.json

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

package/src/claude.lib.mjs

@@ -9,6 +9,7 @@ import { isENOSPC, buildToolErrorMessage } from './lib.mjs';
 import { reportError } from './sentry.lib.mjs';
 import { timeouts, retryLimits, claudeCode, getClaudeEnv, getMaxOutputTokensForModel } from './config.lib.mjs';
 import { detectUsageLimit, formatUsageLimitMessage, isUsageLimitError } from './usage-limit.lib.mjs';
+import { detectSubscriptionError, SUBSCRIPTION_BLOCKED_MARKER } from './subscription-error.lib.mjs'; // Issue #2161
 import { createInteractiveHandler } from './interactive-mode.lib.mjs';
 import { setupBidirectionalHandler, finalizeBidirectionalHandler, validateBidirectionalModeConfig, attachStreamingInput } from './bidirectional-interactive.lib.mjs';
 import { initProgressMonitoring } from './solve.progress-monitoring.lib.mjs';
@@ -376,6 +377,10 @@ export const executeClaudeCommand = async params => {
     let isInternalServerError = false;
     let isRequestTimeout = false;
     let isRateLimitError = false; // Issue #1924: server-side 429 temporary rate limiting
+    // Issue #2161: account/subscription-level block (e.g. oauth_org_not_allowed).
+    // Terminal — never retried, never model-switched; carried out to the caller
+    // so /solve can stop with a specific diagnosis instead of a generic failure.
+    let subscriptionError = null;
     let apiMarkedNotRetryable = false;
     let resultNumTurns = 0;
     let stderrErrors = [];
@@ -731,6 +736,24 @@ export const executeClaudeCommand = async params => {
                     isRateLimitError = true;
                     await log(`⚠️ Detected server-side rate limiting (429) from Claude CLI (will retry with --resume). request_id=${data.request_id || 'unknown'}`, { verbose: true });
                   }
+                  // Issue #2161: account/subscription block. `data.error` carries the
+                  // machine-readable code ("oauth_org_not_allowed" for the reported
+                  // case) alongside api_error_status 403 — a far stronger signal than
+                  // the rendered sentence, so it is passed to the detector first.
+                  if (!subscriptionError) {
+                    subscriptionError = detectSubscriptionError({
+                      message: lastMessage,
+                      tool: 'claude',
+                      errorCode: typeof data.error === 'string' ? data.error : null,
+                      apiErrorStatus: data.api_error_status,
+                      terminalReason: data.terminal_reason,
+                    });
+                    if (subscriptionError) {
+                      // Not verbose: this is the reason the whole run is about to end.
+                      await log(`${SUBSCRIPTION_BLOCKED_MARKER} — ${subscriptionError.label}`);
+                      await log(`   code=${subscriptionError.code || 'n/a'} http=${data.api_error_status || 'n/a'} terminal_reason=${data.terminal_reason || 'n/a'} request_id=${data.request_id || 'unknown'}`, { verbose: true });
+                    }
+                  }
                   // Issue #1834: Detect corrupted extended-thinking-block 400 (un-resumable session).
                   // Capture diagnostics (request id, content path) to aid debugging and upstream reports.
                   if ((lastMessage.includes('thinking') || lastMessage.includes('redacted_thinking')) && lastMessage.includes('cannot be modified')) {
@@ -765,6 +788,26 @@ export const executeClaudeCommand = async params => {
                   await log(`🤖 Sub-agent "${callEntry.description || 'unknown'}" completed: ${data.usage.total_tokens} total tokens`, { verbose: true });
                 }
               }
+              // Issue #2161: Claude Code injects API failures as synthetic assistant
+              // messages flagged `is_api_error_message` and carrying the error code.
+              // In the reported run this arrived ~40s before the terminal result
+              // event, so detecting it here surfaces the diagnosis earlier.
+              if (data.type === 'assistant' && data.is_api_error_message === true && !subscriptionError) {
+                const apiErrorText = getClaudeMessageContent(data)
+                  .filter(item => item.type === 'text' && item.text)
+                  .map(item => item.text)
+                  .join('\n');
+                subscriptionError = detectSubscriptionError({
+                  message: apiErrorText,
+                  tool: 'claude',
+                  errorCode: typeof data.error === 'string' ? data.error : null,
+                });
+                if (subscriptionError) {
+                  if (apiErrorText) lastMessage = apiErrorText;
+                  await log(`${SUBSCRIPTION_BLOCKED_MARKER} — ${subscriptionError.label}`);
+                  await log(`   code=${subscriptionError.code || 'n/a'} request_id=${data.request_id || 'unknown'} uuid=${data.uuid || 'unknown'}`, { verbose: true });
+                }
+              }
               if (data.type === 'assistant' && data.message && data.message.content) {
                 const content = getClaudeMessageContent(data);
                 for (const item of content) {
@@ -977,7 +1020,12 @@ 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');
-      if ((commandFailed || isTransientError) && isTransientError) {
+      // 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
         const isTimeoutRetry = isStartupTimeout || isActivityTimeout;
         const maxRetries = isTimeoutRetry ? retryLimits.maxTransientErrorRetries : isRequestTimeout ? retryLimits.maxRequestTimeoutRetries : retryLimits.maxTransientErrorRetries;
@@ -1005,6 +1053,7 @@ export const executeClaudeCommand = async params => {
             resultSummary,
             // Issue #1845/#1941: surface the actual error, rejecting meaningless fragments (e.g. a lone "}")
             errorInfo: { message: buildToolErrorMessage({ lastMessage, exitCode, fallback: 'API explicitly marked error as not retryable', toolLabel: 'Claude' }), exitCode },
+            subscriptionError, // Issue #2161
             queuedFeedback, // Issue #817: Bidirectional mode feedback
           };
         }
@@ -1055,6 +1104,7 @@ export const executeClaudeCommand = async params => {
             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 },
+            subscriptionError, // Issue #2161
             queuedFeedback, // Issue #817: Bidirectional mode feedback
           };
         }
@@ -1123,6 +1173,7 @@ export const executeClaudeCommand = async params => {
           // Issue #1845: surface the core error (e.g. "API Error: Output blocked by content filtering policy").
           // Issue #1941: a lone "}" fragment at interrupt time must not become "CLAUDE execution failed with }".
           errorInfo: { message: buildToolErrorMessage({ lastMessage, exitCode, fallback: `Claude command failed with exit code ${exitCode}`, toolLabel: 'Claude' }), exitCode },
+          subscriptionError, // Issue #2161: terminal account block — /solve stops and preserves the work
           queuedFeedback, // Issue #817: Bidirectional mode feedback
         };
       }

package/src/hive.mjs

@@ -36,6 +36,7 @@ if (earlyArgs.includes('--help') || earlyArgs.includes('-h')) {
 }
 export { createYargsConfig } from './hive.config.lib.mjs';
 import { attachChildExitHandlers } from './child-exit.lib.mjs';
+import { SUBSCRIPTION_BLOCKED_MARKER } from './subscription-error.lib.mjs'; // Issue #2161
 import { isDirectExecution, withTimeout } from './hive.bootstrap.lib.mjs';
 import { createShutdownManager } from './hive.shutdown.lib.mjs';
 const isRunningDirectly = isDirectExecution(process.argv[1], import.meta.url);
@@ -653,6 +654,22 @@ if (isRunningDirectly) {
     // controlled SIGTERM to each (they run in their own detached process group, so the
     // terminal's SIGINT never reaches them); a *second* interrupt force-kills the groups.
     const activeSolveChildren = new Set();
+    // Issue #2161: an account/subscription block is hive-wide, not per-issue. The
+    // credentials every worker shares have been refused, so each remaining issue
+    // would spin up a full solve run only to die the same way — burning clones,
+    // containers and PR comments while the queue drains into "failed". The first
+    // worker to see the marker in its child's output records it here and stops the
+    // queue; the rest exit as soon as their current child returns.
+    let subscriptionBlock = null;
+    const noteSubscriptionBlock = (workerId, line) => {
+      if (subscriptionBlock) return;
+      subscriptionBlock = { workerId, line: line.trim() };
+      log(`\n${SUBSCRIPTION_BLOCKED_MARKER} — worker ${workerId} reported that the account can no longer use the tool:`, { level: 'error' }).catch(() => {});
+      log(`   ${subscriptionBlock.line}`, { level: 'error' }).catch(() => {});
+      log('   Stopping the hive: every remaining issue would fail the same way until access is restored.', { level: 'error' }).catch(() => {});
+      log('   In-flight workers finish (and auto-commit their work) before the run ends.', { level: 'error' }).catch(() => {});
+      issueQueue.stop();
+    };
     // Worker function to process issues from queue
     async function worker(workerId) {
       await log(`🔧 Worker ${workerId} started`, { verbose: true });
@@ -758,6 +775,9 @@ if (isRunningDirectly) {
                 const lines = data.toString().split('\n');
                 for (const line of lines) {
                   if (line.trim()) {
+                    // Issue #2161: solve prints SUBSCRIPTION_BLOCKED_MARKER on a terminal
+                    // account block. Seen here, it stops the whole hive (see noteSubscriptionBlock).
+                    if (line.includes(SUBSCRIPTION_BLOCKED_MARKER)) noteSubscriptionBlock(workerId, line);
                     log(`   [${solveCommand} worker-${workerId}] ${line}`).catch(logError => {
                       reportError(logError, {
                         context: 'worker_stdout_log',
@@ -777,6 +797,7 @@ if (isRunningDirectly) {
                 const lines = data.toString().split('\n');
                 for (const line of lines) {
                   if (line.trim()) {
+                    if (line.includes(SUBSCRIPTION_BLOCKED_MARKER)) noteSubscriptionBlock(workerId, line); // Issue #2161
                     log(`   [${solveCommand} worker-${workerId} stderr] ${line}`).catch(logError => {
                       reportError(logError, {
                         context: 'worker_stderr_log',
@@ -813,6 +834,14 @@ if (isRunningDirectly) {
               await log(`   🛑 Worker ${workerId} stopped gracefully during shutdown on ${issueUrl} (exit ${exitCode}, ${duration}s)`);
               gracefulStop = true;
               break; // stop processing more PRs for this issue
+            } else if (subscriptionBlock) {
+              // Issue #2161: the run did not fail because of this issue — the account
+              // lost access mid-flight. Report the real reason and stop; solve has
+              // already auto-committed whatever work existed.
+              await log(`   ${SUBSCRIPTION_BLOCKED_MARKER} Worker ${workerId} stopped on ${issueUrl} after ${duration}s: the tool account can no longer be used (exit ${exitCode}).`, { level: 'error' });
+              await log(`   Restore access, then re-run the hive — this issue stays queued, not failed.`, { level: 'error' });
+              gracefulStop = true;
+              break;
             } else {
               throw new Error(`${solveCommand} exited with code ${exitCode}`);
             }
@@ -1260,6 +1289,16 @@ if (isRunningDirectly) {
       }
       await log('\n👋 Hive Mind monitoring stopped');
       await log(`   📁 Full log file: ${absoluteLogPath}`);
+      // Issue #2161: the hive did not simply "finish" — it was cut short because the
+      // account lost access. Say so last (that is what a human scrolls to) and exit
+      // non-zero so supervisors and the Telegram monitor report a failure, not a
+      // clean completion.
+      if (subscriptionBlock) {
+        await log(`\n${SUBSCRIPTION_BLOCKED_MARKER} Hive stopped early: the tool account can no longer be used.`, { level: 'error' });
+        await log(`   Reported by worker ${subscriptionBlock.workerId}: ${subscriptionBlock.line}`, { level: 'error' });
+        await log('   Restore subscription/account access, then start the hive again.', { level: 'error' });
+        await safeExit(1, 'Subscription/account access blocked');
+      }
     }
     // Issue #1823: Graceful-shutdown + force-kill logic lives in hive.shutdown.lib.mjs.
     // gracefulShutdown waits (uncapped) for in-flight solve workers to finish on the first

package/src/limits-i18n.lib.mjs

@@ -85,6 +85,14 @@ const ENGLISH_LIMITS = {
   subscription_detail_trial_ends: 'trial ends {{time}}',
   subscription_detail_trial_ends_in: 'trial ends in {{duration}}; {{time}}',
   subscription_status: 'Subscription: {{status}}',
+  subscription_blocked_title: 'Subscription/account access blocked',
+  subscription_blocked_provider: 'Provider said',
+  subscription_blocked_code: 'Error code',
+  subscription_blocked_reason: 'Why the run stopped',
+  subscription_blocked_note: 'This is not a usage limit: waiting, retrying or switching model cannot fix it.',
+  subscription_blocked_steps: 'What to do',
+  subscription_blocked_preserved: 'Uncommitted work was auto-committed before stopping.',
+  subscription_blocked_resume: 'Resume after access is restored',
   telegram_api: 'Telegram Bot API',
   telegram_flood_control: 'flood control',
   telegram_last_rate_limit: 'Last 429: {{method}}',

package/src/locales/en.lino

@@ -322,6 +322,15 @@ en
     session "session"
     start "Start"
     subscription
+      blocked
+        title "Subscription/account access blocked"
+        provider "Provider said"
+        code "Error code"
+        reason "Why the run stopped"
+        note "This is not a usage limit: waiting, retrying or switching model cannot fix it."
+        steps "What to do"
+        preserved "Uncommitted work was auto-committed before stopping."
+        resume "Resume after access is restored"
       detail
         ends
           label "ends {{time}}"

package/src/locales/hi.lino

@@ -322,6 +322,15 @@ hi
     session "सत्र"
     start "शुरुआत"
     subscription
+      blocked
+        title "सदस्यता/खाता पहुँच अवरुद्ध"
+        provider "प्रदाता ने कहा"
+        code "त्रुटि कोड"
+        reason "रन क्यों रुका"
+        note "यह उपयोग सीमा नहीं है: प्रतीक्षा, पुनः प्रयास या मॉडल बदलना इसे ठीक नहीं करेगा।"
+        steps "क्या करें"
+        preserved "रुकने से पहले बिना कमिट किए बदलाव स्वतः कमिट कर दिए गए।"
+        resume "पहुँच बहाल होने पर फिर से शुरू करें"
       detail
         ends
           label "{{time}} को समाप्त होगी"

package/src/locales/ru.lino

@@ -322,6 +322,15 @@ ru
     session "сеанс"
     start "Начало"
     subscription
+      blocked
+        title "Доступ по подписке/аккаунту заблокирован"
+        provider "Ответ провайдера"
+        code "Код ошибки"
+        reason "Почему запуск остановлен"
+        note "Это не лимит использования: ожидание, повтор или смена модели не помогут."
+        steps "Что делать"
+        preserved "Незакоммиченные изменения были автоматически закоммичены перед остановкой."
+        resume "Продолжить после восстановления доступа"
       detail
         ends
           label "заканчивается {{time}}"

package/src/locales/zh.lino

@@ -322,6 +322,15 @@ zh
     session "会话"
     start "开始"
     subscription
+      blocked
+        title "订阅/账号访问被阻止"
+        provider "服务方提示"
+        code "错误代码"
+        reason "运行停止的原因"
+        note "这不是用量限制：等待、重试或切换模型都无法解决。"
+        steps "如何处理"
+        preserved "停止前已自动提交未提交的改动。"
+        resume "恢复访问后继续"
       detail
         ends
           label "结束于 {{time}}"

package/src/session-monitor.lib.mjs

@@ -389,6 +389,35 @@ export async function buildDiskDiagnosticsExtraSection(logPath, { verbose = fals
     return '';
   }
 }
+/**
+ * Issue #2161: Replay the `🚫 SUBSCRIPTION/ACCESS BLOCKED` report from the
+ * captured solve log into the Telegram completion message, so the operator is
+ * told that the account itself lost access (and not that "claude failed") on the
+ * surface they actually watch. Returns '' when the session hit no such block.
+ */
+export async function buildSubscriptionBlockedExtraSection(logPath, { verbose = false, readFile = fs.readFile, locale = null } = {}) {
+  if (!logPath) return '';
+  try {
+    let logText = '';
+    try {
+      logText = await readFile(logPath, 'utf8');
+    } catch (readError) {
+      if (verbose) {
+        console.log(`[VERBOSE] Could not read session log ${logPath} for subscription block: ${readError?.message || readError}`);
+      }
+      return '';
+    }
+    const telegramLib = await import('./subscription-block-telegram.lib.mjs');
+    const parsed = telegramLib.parseSubscriptionBlockFromLog(logText);
+    if (!parsed) return '';
+    return telegramLib.formatSubscriptionBlockedSection(parsed, { locale });
+  } catch (error) {
+    if (verbose) {
+      console.log(`[VERBOSE] Could not build subscription block section for ${logPath}: ${error?.message || error}`);
+    }
+    return '';
+  }
+}
 async function getDockerContainerFilesystemSizeForSession(sessionName, sessionInfo, { verbose = false, sizeProvider = null } = {}) {
   if (sessionInfo?.isolationBackend !== 'docker') return null;
   const containerName = sessionInfo.sessionId || sessionName;
@@ -826,6 +855,21 @@ export async function monitorSessions(bot, verbose = false, options = {}) {
           }
         }
         const dockerTaskContainerExtraSections = dockerTaskContainerAction?.extraSection ? [dockerTaskContainerAction.extraSection] : [];
+        // Issue #2161: a blocked subscription/account explains every other
+        // symptom of the run, so it goes first in the completion message.
+        const subscriptionBlockedExtraSections = [];
+        try {
+          const blockedSection = await buildSubscriptionBlockedExtraSection(statusResult?.logPath || sessionInfo?.logPath || null, {
+            verbose,
+            readFile: options.readFile,
+            locale: sessionInfo?.locale || null,
+          });
+          if (blockedSection) subscriptionBlockedExtraSections.push(blockedSection);
+        } catch (blockedError) {
+          if (verbose) {
+            console.log(`[VERBOSE] Could not build subscription block section for ${sessionName}: ${blockedError?.message || blockedError}`);
+          }
+        }
         // Issue #2134: say exactly WHY a session was killed, and warn when a
         // session merely survived a kill event instead of reporting a plain
         // success. The pull request gets the very same report below.
@@ -869,7 +913,7 @@ export async function monitorSessions(bot, verbose = false, options = {}) {
           infoBlock: sessionInfo?.infoBlock || '',
           pullRequestUrl,
           pullRequestState,
-          extraSections: [...limitsExtraSections, ...killReport.sections, ...resumeExtraSections, ...diskExtraSections, ...dockerTaskContainerExtraSections],
+          extraSections: [...subscriptionBlockedExtraSections, ...limitsExtraSections, ...killReport.sections, ...resumeExtraSections, ...diskExtraSections, ...dockerTaskContainerExtraSections],
         });
         if (killReport.killed || killReport.recovered) {
           const notice = await announceKillOnPullRequest({

package/src/solve.mjs

@@ -19,7 +19,9 @@ const fs = (await use('fs')).promises;
 const crypto = (await use('crypto')).default;
 const memoryCheck = await import('./memory-check.mjs');
 const lib = await import('./lib.mjs');
-const { log, setLogFile, getLogFile, getAbsoluteLogPath, cleanErrorMessage, formatAligned, formatToolExecutionFailure, getVersionInfo, logSolveStartup, setupVerboseLogInterceptor, setupStdioLogInterceptor } = lib;
+const { log, setLogFile, getLogFile, getAbsoluteLogPath, cleanErrorMessage, formatAligned, formatToolExecutionFailure, extractToolErrorCore, getVersionInfo, logSolveStartup, setupVerboseLogInterceptor, setupStdioLogInterceptor } = lib;
+// Issue #2161: terminal subscription/account-access blocks.
+const { detectSubscriptionError, formatSubscriptionErrorReport, formatSubscriptionErrorSummary, SUBSCRIPTION_BLOCKED_MARKER } = await import('./subscription-error.lib.mjs');
 const githubLib = await import('./github.lib.mjs');
 const { sanitizeLogContent, attachLogToGitHub, getToolDisplayName } = githubLib;
 const validation = await import('./solve.validation.lib.mjs');
@@ -1000,6 +1002,15 @@ try {
     const toolForFailure = argv.tool || 'claude';
     // Issue #1845: surface the core error instead of just "<TOOL> execution failed" (terminal + comment).
     const toolFailureMessage = formatToolExecutionFailure({ tool: toolForFailure, toolResult });
+    // Issue #2161: an account/subscription block ("Your organization has disabled
+    // Claude subscription access for Claude Code", a revoked OAuth token, an
+    // expired plan) is terminal — the run must stop, say precisely what happened
+    // and preserve the work, instead of ending on a bare "<TOOL> execution failed
+    // with <provider sentence>". Adapters that parse structured provider codes
+    // (claude.lib.mjs) hand the classification over directly; for every other tool
+    // the rendered message is re-classified here, so the whole failure surface is
+    // covered by one chokepoint.
+    const subscriptionInfo = toolResult?.subscriptionError || detectSubscriptionError({ message: extractToolErrorCore({ toolResult }) || toolFailureMessage, tool: toolForFailure });
     if (sessionId) {
       await log('');
       await log('💡 To continue this session:');
@@ -1014,15 +1025,32 @@ try {
       await log('');
     }
     // Preserve work before remote diagnostics; issue #2101 ended during log upload.
+    let preservedWork = null;
     try {
       const { criticalErrorRecovery } = await import('./config.lib.mjs');
       if (criticalErrorRecovery.autoCommitUncommittedChanges) {
         const { commitUncommittedChangesOnCriticalError } = await import('./critical-error-commit.lib.mjs');
-        await commitUncommittedChangesOnCriticalError({ tempDir, branchName, $, log, reason: toolFailureMessage });
+        // Issue #2161: when the subscription is gone it is unknown whether/when it
+        // will be restored, so the emergency commit is the only thing standing
+        // between the operator and hours of lost work — name it as such.
+        preservedWork = await commitUncommittedChangesOnCriticalError({ tempDir, branchName, $, log, reason: subscriptionInfo ? formatSubscriptionErrorSummary(subscriptionInfo, { tool: toolForFailure }) : toolFailureMessage });
       }
     } catch (preserveError) {
       await log(`  ⚠️  Could not auto-commit before failure exit: ${preserveError.message}`, { verbose: true });
     }
+    // Issue #2161: printed after the emergency commit so the block can state
+    // whether the work was preserved. This is the message the operator reads.
+    if (subscriptionInfo) {
+      const reportLines = formatSubscriptionErrorReport(subscriptionInfo, {
+        tool: toolForFailure,
+        sessionId,
+        tempDir,
+        branchName,
+        committed: preservedWork ? preservedWork.committed : null,
+        resumeCommand: sessionId && argv.url ? buildSolveResumeCommand({ issueUrl: argv.url, sessionId, tool: toolForFailure, model: argv.model, fallbackModel: argv.fallbackModel, tempDir }) : null,
+      });
+      for (const line of reportLines) await log(line, { level: 'error' });
+    }
     // Attach failure logs before exiting (Issues #1212, #1462: fall back to issue if no PR)
     const hasPR = global.createdPR && global.createdPR.number;
     const hasIssue = global.issueNumber;
@@ -1052,7 +1080,9 @@ try {
           // Include sessionId so the PR comment can present it
           sessionId,
           // If not a usage limit case, fall back to generic failure format
-          errorMessage: limitReached ? undefined : toolFailureMessage,
+          // Issue #2161: the PR/issue comment gets the diagnosis + the remediation
+          // steps too — whoever finds the run in the morning reads that, not the log.
+          errorMessage: limitReached ? undefined : subscriptionInfo ? [formatSubscriptionErrorSummary(subscriptionInfo, { tool: toolForFailure }), '', ...(subscriptionInfo.guidance || []).map(step => `- ${step}`)].join('\n') : toolFailureMessage,
           argv,
           requestedModel: argv.originalModel || argv.model,
           tool: argv.tool || 'claude',
@@ -1070,7 +1100,9 @@ try {
         await log(`  ⚠️  Error uploading failure logs: ${uploadError.message}`);
       }
     }
-    await safeExit(1, toolFailureMessage);
+    // Issue #2161: the exit message is what /hive and the session monitor see, so
+    // it carries the marker rather than the generic tool-failure sentence.
+    await safeExit(1, subscriptionInfo ? `${SUBSCRIPTION_BLOCKED_MARKER} — ${formatSubscriptionErrorSummary(subscriptionInfo, { tool: toolForFailure })}` : toolFailureMessage);
   }
   // Clean up .playwright-mcp/ to prevent browser artifacts from triggering auto-restart (Issue #1124)
   if (argv.playwrightMcpAutoCleanup !== false) {

package/src/subscription-block-telegram.lib.mjs

@@ -0,0 +1,115 @@
+// Issue #2161: Telegram surface for subscription/account-access blocks.
+//
+// `/solve` prints a SUBSCRIPTION_BLOCKED_MARKER report into the session log when
+// the account can no longer use the agent tool (expired/cancelled Claude MAX
+// subscription, org policy, revoked ChatGPT/Codex entitlement, ...). The session
+// monitor captures that log, so the same block can be replayed into the Telegram
+// completion message without any extra plumbing between processes.
+
+import { SUBSCRIPTION_BLOCKED_MARKER } from './subscription-error.lib.mjs';
+import { lt } from './limits-i18n.lib.mjs';
+
+const MAX_MESSAGE_LENGTH = 400;
+const MAX_GUIDANCE_STEPS = 4;
+
+const truncate = (value, limit = MAX_MESSAGE_LENGTH) => {
+  const text = String(value || '').trim();
+  if (text.length <= limit) return text;
+  return `${text.slice(0, limit - 1)}…`;
+};
+
+const stripPrefix = (line, prefix) => line.slice(line.indexOf(prefix) + prefix.length).trim();
+
+/**
+ * Parse the last SUBSCRIPTION_BLOCKED_MARKER report out of a captured session log.
+ *
+ * The report is emitted by formatSubscriptionErrorReport(); every line after the
+ * marker line is indented, so the block ends at the first non-indented line.
+ *
+ * @param {string} logText
+ * @returns {null|{tool: string|null, label: string|null, message: string|null, code: string|null, reason: string|null, guidance: string[], committed: boolean|null, resumeCommand: string|null}}
+ */
+export function parseSubscriptionBlockFromLog(logText) {
+  if (!logText || typeof logText !== 'string') return null;
+  if (!logText.includes(SUBSCRIPTION_BLOCKED_MARKER)) return null;
+
+  const lines = logText.split('\n');
+  // Walk backwards: the richest report (from /solve) is the last one printed.
+  let markerIndex = -1;
+  for (let i = lines.length - 1; i >= 0; i -= 1) {
+    if (lines[i].includes(SUBSCRIPTION_BLOCKED_MARKER)) {
+      markerIndex = i;
+      break;
+    }
+  }
+  if (markerIndex === -1) return null;
+
+  const headline = stripPrefix(lines[markerIndex], SUBSCRIPTION_BLOCKED_MARKER).replace(/^—\s*/, '');
+  const separator = headline.indexOf(':');
+  const parsed = {
+    tool: separator > 0 ? headline.slice(0, separator).trim() : null,
+    label: separator > 0 ? headline.slice(separator + 1).trim() : headline || null,
+    message: null,
+    code: null,
+    reason: null,
+    guidance: [],
+    committed: null,
+    resumeCommand: null,
+  };
+
+  for (let i = markerIndex + 1; i < lines.length; i += 1) {
+    const raw = lines[i];
+    if (!raw.trim()) continue;
+    if (!/^\s{3}/.test(raw)) break; // end of the indented report block
+    const line = raw.trim();
+    if (line.startsWith('Provider said:')) parsed.message = stripPrefix(line, 'Provider said:');
+    else if (line.startsWith('Error code:')) parsed.code = stripPrefix(line, 'Error code:');
+    else if (line.startsWith('HTTP status:')) parsed.code = `HTTP ${stripPrefix(line, 'HTTP status:')}`;
+    else if (line.startsWith('Why this stops the run:')) parsed.reason = stripPrefix(line, 'Why this stops the run:');
+    else if (line.startsWith('•')) parsed.guidance.push(line.slice(1).trim());
+    else if (line.startsWith('💾')) parsed.committed = true;
+    else if (line.startsWith('⚠️')) parsed.committed = false;
+    else if (line.startsWith('▶️')) parsed.resumeCommand = stripPrefix(line, ':');
+  }
+
+  return parsed;
+}
+
+/**
+ * Render the parsed block as a Telegram extraSection (title + fenced body), the
+ * same shape formatDiskDiagnosticsBlock() uses.
+ *
+ * @returns {string} empty string when there is nothing to show
+ */
+export function formatSubscriptionBlockedSection(parsed, { locale = null } = {}) {
+  if (!parsed) return '';
+  const options = locale ? { locale } : {};
+  const body = [];
+
+  const label = parsed.label || lt('subscription_blocked_title', {}, options);
+  body.push(parsed.tool ? `${parsed.tool}: ${label}` : label);
+  if (parsed.message) body.push(`${lt('subscription_blocked_provider', {}, options)}: ${truncate(parsed.message)}`);
+  if (parsed.code) body.push(`${lt('subscription_blocked_code', {}, options)}: ${parsed.code}`);
+  if (parsed.reason) body.push(`${lt('subscription_blocked_reason', {}, options)}: ${parsed.reason}`);
+  body.push(lt('subscription_blocked_note', {}, options));
+  if (parsed.guidance.length) {
+    body.push('');
+    body.push(`${lt('subscription_blocked_steps', {}, options)}:`);
+    for (const step of parsed.guidance.slice(0, MAX_GUIDANCE_STEPS)) body.push(`  • ${step}`);
+  }
+  if (parsed.committed === true) {
+    body.push('');
+    body.push(lt('subscription_blocked_preserved', {}, options));
+  }
+  if (parsed.resumeCommand) {
+    body.push('');
+    body.push(`${lt('subscription_blocked_resume', {}, options)}: ${parsed.resumeCommand}`);
+  }
+
+  return `🚫 ${lt('subscription_blocked_title', {}, options)}\n\`\`\`\n${body.join('\n')}\n\`\`\``;
+}
+
+export default {
+  parseSubscriptionBlockFromLog,
+  formatSubscriptionBlockedSection,
+};

package/src/subscription-error.lib.mjs

@@ -0,0 +1,328 @@
+/**
+ * Subscription / account-access error detection for AI CLI tools.
+ *
+ * Issue #2161: a `/solve` run died after 4h11m and $31.39 of work with nothing
+ * but the generic line
+ *
+ *   ❌ CLAUDE execution failed with Your organization has disabled Claude
+ *      subscription access for Claude Code · Use an Anthropic API key instead,
+ *      or ask your admin to enable access
+ *
+ * That sentence is not a transient API fault and not a usage limit: it means the
+ * *account itself* is no longer permitted to use the tool. Waiting does not help,
+ * retrying does not help, switching to a fallback model does not help — the run
+ * must stop immediately, preserve the work, and tell the operator exactly what to
+ * do.
+ *
+ * This module is the single place that recognises that whole class of errors for
+ * every tool hive-mind can drive. Two detection layers are used, strongest first:
+ *
+ *   1. Machine-readable codes emitted by the tool (Claude Code's `error` field on
+ *      stream-json `assistant`/`result` events, Codex's auth error codes). These
+ *      are exact and locale independent.
+ *   2. Verbatim user-facing strings, transcribed from the shipped CLI binaries
+ *      (see docs/case-studies/issue-2161/provider-error-strings.md). Used when
+ *      only the rendered message survives (most tools give us nothing else).
+ *
+ * Deliberately NOT matched here:
+ *   - "Authentication error · This may be a temporary network issue, please try
+ *     again" — Claude Code's own wording says it is transient, so it belongs to
+ *     the retry path, not to this terminal path.
+ *   - Usage/quota limits ("You've hit your usage limit", "resets 5am") — those
+ *     have a reset time and are handled by usage-limit.lib.mjs.
+ */
+
+/** Emitted verbatim into the log so /hive, the Telegram monitor and humans can grep for it. */
+export const SUBSCRIPTION_BLOCKED_MARKER = '🚫 SUBSCRIPTION/ACCESS BLOCKED';
+
+export const SUBSCRIPTION_ERROR_KINDS = {
+  ORG_SUBSCRIPTION_DISABLED: 'org_subscription_disabled',
+  ACCOUNT_NO_ACCESS: 'account_no_access',
+  LOGIN_REQUIRED: 'login_required',
+  BILLING: 'billing',
+  PLAN_RESTRICTED: 'plan_restricted',
+  API_KEY_INVALID: 'api_key_invalid',
+};
+
+const K = SUBSCRIPTION_ERROR_KINDS;
+
+/**
+ * Machine-readable codes → kind. Sources:
+ *   - Claude Code CLI 2.1.233, blocked-state switch (`oauth_org_not_allowed`,
+ *     `authentication_failed`, `billing_error`, …).
+ *   - Codex CLI 0.147.0 auth error codes (`missing_codex_entitlement`,
+ *     `refresh_token_expired`, `disabled_by_admin`, `plan_not_eligible`, …).
+ */
+export const SUBSCRIPTION_ERROR_CODES = Object.freeze({
+  // Claude Code
+  oauth_org_not_allowed: K.ORG_SUBSCRIPTION_DISABLED,
+  authentication_failed: K.LOGIN_REQUIRED,
+  token_revoked: K.LOGIN_REQUIRED,
+  invalid_api_key: K.API_KEY_INVALID,
+  billing_error: K.BILLING,
+  credit_balance_low: K.BILLING,
+  // Codex
+  missing_codex_entitlement: K.ACCOUNT_NO_ACCESS,
+  disabled_by_admin: K.ORG_SUBSCRIPTION_DISABLED,
+  plan_not_eligible: K.PLAN_RESTRICTED,
+  required_app_unavailable: K.ACCOUNT_NO_ACCESS,
+  refresh_token_expired: K.LOGIN_REQUIRED,
+  refresh_token_invalidated: K.LOGIN_REQUIRED,
+  not_chatgpt_auth: K.LOGIN_REQUIRED,
+});
+
+/**
+ * Substrings that look authentication-ish but are explicitly transient. Checked
+ * before every other rule so a network blip is never reported as a cancelled
+ * subscription (which would stop the whole hive).
+ */
+const TRANSIENT_AUTH_PATTERNS = ['this may be a temporary network issue', 'could not authenticate with its upstream provider', 'temporary failure in name resolution'];
+
+/**
+ * Verbatim strings from the shipped CLIs, lower-cased. `tool` is informational:
+ * a message is matched regardless of which tool produced it, because hive-mind
+ * often only sees the rendered text several layers away from its origin.
+ */
+const MESSAGE_RULES = [
+  // ---- Claude Code -------------------------------------------------------
+  { kind: K.ORG_SUBSCRIPTION_DISABLED, tool: 'claude', needles: ['organization has disabled claude subscription access'] },
+  { kind: K.ORG_SUBSCRIPTION_DISABLED, tool: 'claude', needles: ['organization has disabled api key authentication'] },
+  { kind: K.ORG_SUBSCRIPTION_DISABLED, tool: 'claude', needles: ['belongs to a disabled organization'] },
+  { kind: K.ORG_SUBSCRIPTION_DISABLED, tool: 'claude', needles: ['organization has been disabled'] },
+  { kind: K.ACCOUNT_NO_ACCESS, tool: 'claude', needles: ['your account does not have access to claude'] },
+  { kind: K.LOGIN_REQUIRED, tool: 'claude', needles: ['oauth token revoked'] },
+  { kind: K.LOGIN_REQUIRED, tool: 'claude', needles: ['login expired'] },
+  { kind: K.LOGIN_REQUIRED, tool: 'claude', needles: ['not logged in'] },
+  { kind: K.LOGIN_REQUIRED, tool: 'claude', needles: ['session expired. please run /login'] },
+  { kind: K.LOGIN_REQUIRED, tool: 'claude', needles: ['oauth session expired and could not be refreshed'] },
+  { kind: K.LOGIN_REQUIRED, tool: 'claude', needles: ['anthropic profile login expired'] },
+  { kind: K.BILLING, tool: 'claude', needles: ['credit balance is too low'] },
+  { kind: K.API_KEY_INVALID, tool: 'claude', needles: ['invalid api key'] },
+  { kind: K.API_KEY_INVALID, tool: 'claude', needles: ['invalid auth token'] },
+  { kind: K.PLAN_RESTRICTED, tool: 'claude', needles: ['is not available with the claude pro plan'] },
+  { kind: K.PLAN_RESTRICTED, tool: 'claude', needles: ['auto mode is unavailable for your plan'] },
+
+  // ---- Codex -------------------------------------------------------------
+  { kind: K.ACCOUNT_NO_ACCESS, tool: 'codex', needles: ['you do not have access to codex'] },
+  { kind: K.ACCOUNT_NO_ACCESS, tool: 'codex', needles: ['not currently authorized to use codex'] },
+  { kind: K.ACCOUNT_NO_ACCESS, tool: 'codex', needles: ['contact your workspace administrator to request access to codex'] },
+  { kind: K.LOGIN_REQUIRED, tool: 'codex', needles: ['access token could not be refreshed'] },
+  { kind: K.LOGIN_REQUIRED, tool: 'codex', needles: ['oauth refresh token was rejected'] },
+  { kind: K.LOGIN_REQUIRED, tool: 'codex', needles: ["not signed in. please run 'codex login'"] },
+
+  // ---- Qwen Code ---------------------------------------------------------
+  { kind: K.LOGIN_REQUIRED, tool: 'qwen', needles: ['qwen oauth credentials expired'] },
+  { kind: K.LOGIN_REQUIRED, tool: 'qwen', needles: ['refresh token expired or invalid'] },
+  { kind: K.LOGIN_REQUIRED, tool: 'qwen', needles: ['failed to obtain valid qwen access token'] },
+  { kind: K.PLAN_RESTRICTED, tool: 'qwen', needles: ['coding plan api key not found'] },
+
+  // ---- Gemini CLI --------------------------------------------------------
+  { kind: K.LOGIN_REQUIRED, tool: 'gemini', needles: ['please re-authenticate with the correct type'] },
+  { kind: K.PLAN_RESTRICTED, tool: 'gemini', needles: ["doesn't have a gemini code assist"] },
+
+  // ---- OpenCode ----------------------------------------------------------
+  { kind: K.LOGIN_REQUIRED, tool: 'opencode', needles: ['run `opencode auth login` in the terminal'] },
+  { kind: K.LOGIN_REQUIRED, tool: 'opencode', needles: ['oauth token refresh failed and no fallback'] },
+  { kind: K.ACCOUNT_NO_ACCESS, tool: 'opencode', needles: ['your account does not have access to ai features'] },
+
+  // ---- Generic provider phrasing (any tool) ------------------------------
+  { kind: K.ORG_SUBSCRIPTION_DISABLED, tool: null, needles: ['has disabled', 'subscription access'] },
+  { kind: K.BILLING, tool: null, needles: ['subscription', 'expired'] },
+  { kind: K.BILLING, tool: null, needles: ['subscription', 'cancel'] },
+];
+
+const KIND_LABELS = Object.freeze({
+  [K.ORG_SUBSCRIPTION_DISABLED]: 'Subscription access disabled for this organization',
+  [K.ACCOUNT_NO_ACCESS]: 'Account is not authorized to use this tool',
+  [K.LOGIN_REQUIRED]: 'Authentication expired — re-login required',
+  [K.BILLING]: 'Subscription/billing problem',
+  [K.PLAN_RESTRICTED]: 'Current plan does not allow this request',
+  [K.API_KEY_INVALID]: 'Invalid API key or auth token',
+});
+
+const KIND_REASONS = Object.freeze({
+  [K.ORG_SUBSCRIPTION_DISABLED]: 'The provider rejected the request because the organization/account behind the subscription is no longer allowed to use this CLI. This is an account-level block, not a rate limit — it will not clear on its own.',
+  [K.ACCOUNT_NO_ACCESS]: 'The provider accepted the credentials but the account has no entitlement for this product. Access must be granted before any further run can succeed.',
+  [K.LOGIN_REQUIRED]: 'The stored OAuth credentials are gone, revoked or unrefreshable. Every request will fail until the tool is logged in again.',
+  [K.BILLING]: 'The subscription is expired, cancelled or out of credit. Requests stay rejected until billing is restored.',
+  [K.PLAN_RESTRICTED]: 'The account is authenticated, but the requested model/mode is not included in the current plan.',
+  [K.API_KEY_INVALID]: 'The configured API key or auth token was rejected by the provider.',
+});
+
+/** Per-tool re-authentication commands, used to build actionable guidance. */
+const TOOL_LOGIN_HINTS = Object.freeze({
+  claude: 'claude /login  (or set ANTHROPIC_API_KEY for API-key billing)',
+  codex: 'codex login  (add --device-auth on a headless machine)',
+  qwen: 'qwen  → /auth',
+  gemini: 'gemini  → /auth',
+  opencode: 'opencode auth login',
+  agent: 'agent auth login',
+});
+
+const TOOL_ACCOUNT_URLS = Object.freeze({
+  claude: 'https://claude.ai/settings/billing',
+  codex: 'https://chatgpt.com/codex/settings/usage',
+  qwen: 'https://chat.qwen.ai',
+  gemini: 'https://codeassist.google.com',
+});
+
+const toText = value => {
+  if (value === null || value === undefined) return '';
+  if (typeof value === 'string') return value;
+  if (typeof value?.error?.message === 'string') return value.error.message;
+  if (typeof value?.message === 'string') return value.message;
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+};
+
+/**
+ * True when the text is an authentication-flavoured error that the provider
+ * itself describes as temporary. Such errors must keep using the retry path.
+ */
+export const isTransientAuthError = value => {
+  const lower = toText(value).toLowerCase();
+  if (!lower) return false;
+  return TRANSIENT_AUTH_PATTERNS.some(p => lower.includes(p));
+};
+
+const buildGuidance = (kind, tool) => {
+  const loginHint = TOOL_LOGIN_HINTS[tool] || TOOL_LOGIN_HINTS.claude;
+  const accountUrl = TOOL_ACCOUNT_URLS[tool] || null;
+  const steps = [];
+  switch (kind) {
+    case K.ORG_SUBSCRIPTION_DISABLED:
+      steps.push('Ask the organization/workspace admin to re-enable CLI access for this account.');
+      steps.push('Or switch this run to API-key billing instead of the subscription.');
+      break;
+    case K.ACCOUNT_NO_ACCESS:
+      steps.push('Request access for this account from the workspace administrator.');
+      steps.push('Verify you are logged in with the account that actually owns the subscription.');
+      break;
+    case K.LOGIN_REQUIRED:
+      steps.push(`Re-authenticate the tool: ${loginHint}`);
+      break;
+    case K.BILLING:
+      steps.push('Renew/reactivate the subscription or top up the credit balance.');
+      if (accountUrl) steps.push(`Billing page: ${accountUrl}`);
+      break;
+    case K.PLAN_RESTRICTED:
+      steps.push('Pick a model/mode included in the current plan (see --model), or upgrade the plan.');
+      steps.push(`After a plan change, re-login so the new entitlements are picked up: ${loginHint}`);
+      break;
+    case K.API_KEY_INVALID:
+      steps.push('Fix or regenerate the configured API key / auth token, then re-run.');
+      break;
+    default:
+      steps.push(`Re-authenticate the tool: ${loginHint}`);
+  }
+  steps.push('Once access is restored, resume with the session ID printed above — no work is lost.');
+  return steps;
+};
+
+/**
+ * Detect an account/subscription-level block.
+ *
+ * @param {string|Object} input - Raw message, or a descriptor:
+ *   { message, tool, errorCode, apiErrorStatus, terminalReason }
+ * @returns {null|{isSubscriptionError: true, kind, code, tool, label, reason, message, guidance, apiErrorStatus}}
+ */
+export const detectSubscriptionError = input => {
+  const descriptor = typeof input === 'string' || input === null || input === undefined ? { message: input } : input;
+  const message = toText(descriptor.message ?? descriptor);
+  const tool = descriptor.tool ? String(descriptor.tool).toLowerCase() : null;
+  const rawCode = descriptor.errorCode ? String(descriptor.errorCode).toLowerCase().trim() : null;
+  const apiErrorStatus = Number.isFinite(descriptor.apiErrorStatus) ? descriptor.apiErrorStatus : null;
+
+  // Layer 1: machine-readable code. Trusted even when the message is missing.
+  if (rawCode && Object.hasOwn(SUBSCRIPTION_ERROR_CODES, rawCode)) {
+    const kind = SUBSCRIPTION_ERROR_CODES[rawCode];
+    return {
+      isSubscriptionError: true,
+      kind,
+      code: rawCode,
+      tool,
+      label: KIND_LABELS[kind],
+      reason: KIND_REASONS[kind],
+      message,
+      apiErrorStatus,
+      guidance: buildGuidance(kind, tool),
+    };
+  }
+
+  if (!message) return null;
+  const lower = message.toLowerCase();
+  if (isTransientAuthError(lower)) return null;
+
+  // Layer 2: verbatim provider strings.
+  for (const rule of MESSAGE_RULES) {
+    if (!rule.needles.every(n => lower.includes(n))) continue;
+    return {
+      isSubscriptionError: true,
+      kind: rule.kind,
+      code: rawCode || null,
+      tool: tool || rule.tool || null,
+      label: KIND_LABELS[rule.kind],
+      reason: KIND_REASONS[rule.kind],
+      message,
+      apiErrorStatus,
+      guidance: buildGuidance(rule.kind, tool || rule.tool),
+    };
+  }
+  return null;
+};
+
+/** Convenience boolean wrapper mirroring isUsageLimitError(). */
+export const isSubscriptionBlockedError = input => detectSubscriptionError(input) !== null;
+
+/**
+ * Render the terminal/log block. The first line is SUBSCRIPTION_BLOCKED_MARKER so
+ * downstream consumers (/hive worker output scanner, Telegram session monitor,
+ * `grep`) have one stable anchor.
+ *
+ * @returns {string[]} lines
+ */
+export const formatSubscriptionErrorReport = (info, { tool = null, sessionId = null, tempDir = null, branchName = null, committed = null, resumeCommand = null } = {}) => {
+  if (!info) return [];
+  const toolName = (info.tool || tool || 'tool').toUpperCase();
+  const lines = [];
+  lines.push('');
+  lines.push(`${SUBSCRIPTION_BLOCKED_MARKER} — ${toolName}: ${info.label}`);
+  lines.push(`   Provider said: ${info.message || '(no message)'}`);
+  if (info.code) lines.push(`   Error code: ${info.code}${info.apiErrorStatus ? ` (HTTP ${info.apiErrorStatus})` : ''}`);
+  else if (info.apiErrorStatus) lines.push(`   HTTP status: ${info.apiErrorStatus}`);
+  lines.push(`   Why this stops the run: ${info.reason}`);
+  lines.push('   This is NOT a usage limit and NOT a transient API error — retrying, waiting for a reset');
+  lines.push('   or switching to a fallback model cannot fix it, so the task is stopped now.');
+  lines.push('');
+  lines.push('   What to do:');
+  for (const step of info.guidance || []) lines.push(`     • ${step}`);
+  if (committed === true) lines.push('   💾 Uncommitted changes were auto-committed and pushed before stopping.');
+  else if (committed === false) lines.push('   ⚠️  No uncommitted changes to preserve (working tree was clean).');
+  if (tempDir) lines.push(`   📁 Working directory: ${tempDir}`);
+  if (branchName) lines.push(`   🌿 Branch: ${branchName}`);
+  if (sessionId) lines.push(`   📌 Session ID: ${sessionId}`);
+  if (resumeCommand) lines.push(`   ▶️  Resume after access is restored: ${resumeCommand}`);
+  lines.push('');
+  return lines;
+};
+
+/** One-line summary used for exit messages, PR comments and commit reasons. */
+export const formatSubscriptionErrorSummary = (info, { tool = null } = {}) => {
+  if (!info) return '';
+  const toolName = (info.tool || tool || 'tool').toUpperCase();
+  return `${toolName} stopped: ${info.label}${info.code ? ` [${info.code}]` : ''} — ${info.message || ''}`.trim();
+};
+
+export default {
+  SUBSCRIPTION_BLOCKED_MARKER,
+  SUBSCRIPTION_ERROR_KINDS,
+  SUBSCRIPTION_ERROR_CODES,
+  detectSubscriptionError,
+  isSubscriptionBlockedError,
+  isTransientAuthError,
+  formatSubscriptionErrorReport,
+  formatSubscriptionErrorSummary,
+};

package/src/tool-retry.lib.mjs

@@ -2,6 +2,7 @@
 
 import { retryLimits } from './config.lib.mjs';
 import { resolveDefaultFallbackModel, resolveModelId } from './models/index.mjs';
+import { detectSubscriptionError, isTransientAuthError } from './subscription-error.lib.mjs';
 
 const normalizeMessage = value => {
   if (value === null || value === undefined) return '';
@@ -27,6 +28,34 @@ export const classifyRetryableError = value => {
   const message = normalizeMessage(value);
   const lower = message.toLowerCase();
 
+  // Issue #2161: account/subscription-level blocks ("Your organization has
+  // disabled Claude subscription access for Claude Code", "You do not have
+  // access to Codex", revoked OAuth tokens, expired subscriptions, …). These are
+  // terminal by nature: the credentials themselves are no longer accepted, so
+  // neither a backoff nor a different model can recover — the run must stop and
+  // the operator must restore access. isCapacity stays false so
+  // maybeSwitchToFallbackModel() never burns a fallback hop on them.
+  //
+  // Checked first, because several of these messages contain words ("timed
+  // out", "rate", "503") that later transient branches would otherwise claim.
+  // detectSubscriptionError() itself excludes provider errors that are
+  // explicitly described as temporary — see isTransientAuthError below.
+  const subscriptionError = detectSubscriptionError(message);
+  if (subscriptionError) {
+    return { message, isRetryable: false, isCapacity: false, isSubscriptionError: true, subscriptionError, label: 'subscription access blocked' };
+  }
+
+  // Issue #2161: the counterpart — Claude Code's own wording marks this
+  // authentication failure as temporary ("This may be a temporary network
+  // issue, please try again"). Without an explicit branch it would fall through
+  // to the non-retryable default and abort a run that a retry would have saved.
+  // The `auth` guard keeps purely network-level members of that list (e.g.
+  // "Temporary failure in name resolution") on their own, more specific branches
+  // below — this branch only claims the *authentication* wordings.
+  if (isTransientAuthError(lower) && lower.includes('auth')) {
+    return { message, isRetryable: true, isCapacity: false, label: 'Transient authentication/network error' };
+  }
+
   // 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