free-coding-models 0.2.17 → 0.3.1

package/bin/free-coding-models.js

@@ -78,7 +78,11 @@
  *   - --best: Show only top-tier models (A+, S, S+)
  *   - --fiable: Analyze 10s and output the most reliable model
  *   - --json: Output results as JSON (for scripting/automation)
+ *   - --recommend: Open Smart Recommend immediately on startup
+ *   - --profile <name>: Load a saved config profile before entering the TUI
+ *   - --clean-proxy / --proxy-clean: Remove persisted fcm-proxy config from OpenCode
  *   - --no-telemetry: Disable anonymous usage analytics for this run
+ *   - --help / -h: Print the full CLI help and exit
  *   - --tier S/A/B/C: Filter models by tier letter (S=S+/S, A=A+/A/A-, B=B+/B, C=C)
  *
  *   @see {@link https://build.nvidia.com} NVIDIA API key generation
@@ -88,6 +92,7 @@
 
 import chalk from 'chalk'
 import { createRequire } from 'module'
+import { fileURLToPath } from 'url'
 import { readFileSync, writeFileSync, existsSync, copyFileSync, mkdirSync } from 'fs'
 import { randomUUID } from 'crypto'
 import { homedir } from 'os'
@@ -98,6 +103,7 @@ import { loadConfig, saveConfig, getApiKey, getProxySettings, resolveApiKeys, ad
 import { buildMergedModels } from '../src/model-merger.js'
 import { ProxyServer } from '../src/proxy-server.js'
 import { loadOpenCodeConfig, saveOpenCodeConfig, syncToOpenCode, restoreOpenCodeBackup, cleanupOpenCodeProxyConfig } from '../src/opencode-sync.js'
+import { syncProxyToTool, cleanupToolConfig, PROXY_SYNCABLE_TOOLS } from '../src/proxy-sync.js'
 import { usageForRow as _usageForRow } from '../src/usage-reader.js'
 import { loadRecentLogs } from '../src/log-reader.js'
 import { buildProviderModelTokenKey, loadTokenUsageByProviderModel } from '../src/token-usage-reader.js'
@@ -108,7 +114,7 @@ import { TIER_COLOR } from '../src/tier-colors.js'
 import { resolveCloudflareUrl, buildPingRequest, ping, extractQuotaPercent, getProviderQuotaPercentCached, usagePlaceholderForProvider } from '../src/ping.js'
 import { runFiableMode, filterByTierOrExit, fetchOpenRouterFreeModels } from '../src/analysis.js'
 import { PROVIDER_METADATA, ENV_VAR_NAMES, isWindows, isMac } from '../src/provider-metadata.js'
-import { parseTelemetryEnv, isTelemetryDebugEnabled, telemetryDebug, ensureTelemetryConfig, getTelemetryDistinctId, getTelemetrySystem, getTelemetryTerminal, isTelemetryEnabled, sendUsageTelemetry, sendFeatureRequest, sendBugReport } from '../src/telemetry.js'
+import { parseTelemetryEnv, isTelemetryDebugEnabled, telemetryDebug, ensureTelemetryConfig, getTelemetryDistinctId, getTelemetrySystem, getTelemetryTerminal, isTelemetryEnabled, sendUsageTelemetry, sendBugReport } from '../src/telemetry.js'
 import { ensureFavoritesConfig, toFavoriteKey, syncFavoriteFlags, toggleFavoriteModel } from '../src/favorites.js'
 import { checkForUpdateDetailed, checkForUpdate, runUpdate, promptUpdateNotification } from '../src/updater.js'
 import { promptApiKey } from '../src/setup.js'
@@ -123,6 +129,7 @@ import { startExternalTool } from '../src/tool-launchers.js'
 import { getConfiguredInstallableProviders, installProviderEndpoints, refreshInstalledEndpoints, getInstallTargetModes, getProviderCatalogModels, CONNECTION_MODES } from '../src/endpoint-installer.js'
 import { loadCache, saveCache, clearCache, getCacheAge } from '../src/cache.js'
 import { checkConfigSecurity } from '../src/security.js'
+import { buildCliHelpText } from '../src/cli-help.js'
 
 // 📖 mergedModels: cross-provider grouped model list (one entry per label, N providers each)
 // 📖 mergedModelByLabel: fast lookup map from display label → merged model entry
@@ -140,7 +147,7 @@ const readline = require('readline')
 const pkg = require('../package.json')
 const LOCAL_VERSION = pkg.version
 
-// 📖 sendFeatureRequest, sendBugReport → imported from ../src/telemetry.js
+// 📖 sendBugReport → imported from ../src/telemetry.js
 
 // 📖 parseTelemetryEnv, isTelemetryDebugEnabled, telemetryDebug, ensureTelemetryConfig → imported from ../src/telemetry.js
 
@@ -172,6 +179,13 @@ const LOCAL_VERSION = pkg.version
 async function main() {
   const cliArgs = parseArgs(process.argv)
 
+  if (cliArgs.helpMode) {
+    console.log()
+    console.log(buildCliHelpText({ chalk, title: 'free-coding-models' }))
+    console.log()
+    process.exit(0)
+  }
+
   // Validate --tier early, before entering alternate screen
   if (cliArgs.tierFilter && !TIER_LETTER_MAP[cliArgs.tierFilter]) {
     console.error(chalk.red(`  Unknown tier "${cliArgs.tierFilter}". Valid tiers: S, A, B, C`))
@@ -199,6 +213,80 @@ async function main() {
     process.exit(0)
   }
 
+  // 📖 CLI subcommand: free-coding-models daemon <action>
+  const daemonSubcmd = process.argv[2] === 'daemon' ? (process.argv[3] || 'status') : null
+  if (daemonSubcmd) {
+    const dm = await import('../src/daemon-manager.js')
+    if (daemonSubcmd === 'status') {
+      const s = await dm.getDaemonStatus()
+      console.log()
+      if (s.status === 'running') {
+        console.log(chalk.greenBright(`  📡 FCM Proxy V2: Running`))
+        console.log(chalk.dim(`  PID: ${s.info.pid}  •  Port: ${s.info.port}  •  Accounts: ${s.info.accountCount}  •  Version: ${s.info.version}`))
+        console.log(chalk.dim(`  Started: ${s.info.startedAt}`))
+      } else if (s.status === 'stopped') {
+        console.log(chalk.yellow(`  📡 FCM Proxy V2: Stopped (service installed but not running)`))
+      } else if (s.status === 'stale') {
+        console.log(chalk.red(`  📡 FCM Proxy V2: Stale (crashed — PID ${s.info?.pid} no longer alive)`))
+      } else if (s.status === 'unhealthy') {
+        console.log(chalk.red(`  📡 FCM Proxy V2: Unhealthy (PID alive but health check failed)`))
+      } else {
+        console.log(chalk.dim(`  📡 FCM Proxy V2: Not installed`))
+        console.log(chalk.dim(`  Install via: free-coding-models daemon install`))
+      }
+      console.log()
+      process.exit(0)
+    }
+    if (daemonSubcmd === 'install') {
+      const result = dm.installDaemon()
+      console.log()
+      if (result.success) {
+        console.log(chalk.greenBright('  ✅ FCM Proxy V2 background service installed and started!'))
+        console.log(chalk.dim('  The proxy will now run automatically at login.'))
+      } else {
+        console.log(chalk.red(`  ❌ Install failed: ${result.error}`))
+      }
+      console.log()
+      process.exit(result.success ? 0 : 1)
+    }
+    if (daemonSubcmd === 'uninstall') {
+      const result = dm.uninstallDaemon()
+      console.log()
+      if (result.success) {
+        console.log(chalk.greenBright('  ✅ FCM Proxy V2 background service uninstalled.'))
+      } else {
+        console.log(chalk.red(`  ❌ Uninstall failed: ${result.error}`))
+      }
+      console.log()
+      process.exit(result.success ? 0 : 1)
+    }
+    if (daemonSubcmd === 'restart') {
+      const result = dm.restartDaemon()
+      console.log()
+      if (result.success) {
+        console.log(chalk.greenBright('  ✅ FCM Proxy V2 service restarted.'))
+      } else {
+        console.log(chalk.red(`  ❌ Restart failed: ${result.error}`))
+      }
+      console.log()
+      process.exit(result.success ? 0 : 1)
+    }
+    if (daemonSubcmd === 'logs') {
+      const logPath = dm.getDaemonLogPath()
+      console.log(chalk.dim(`  Log file: ${logPath}`))
+      try {
+        const { execSync } = await import('child_process')
+        execSync(`tail -50 "${logPath}"`, { stdio: 'inherit' })
+      } catch {
+        console.log(chalk.dim('  (no logs yet)'))
+      }
+      process.exit(0)
+    }
+    console.log(chalk.red(`  Unknown command: ${daemonSubcmd}`))
+    console.log(chalk.dim('  Usage: free-coding-models daemon [status|install|uninstall|restart|logs]'))
+    process.exit(1)
+  }
+
   // 📖 If --profile <name> was passed, load that profile into the live config
   let startupProfileSettings = null
   if (cliArgs.profileName) {
@@ -261,28 +349,48 @@ async function main() {
     ts: new Date().toISOString(),
   })
 
-  // 📖 Check for updates in the background (non-blocking, non-forced)
-  // 📖 The old auto-update on startup caused infinite loops, so we've moved to:
-  // 📖 1. Optional prompt when a new version is available (user chooses to update or not)
-  // 📖 2. Display "OUTDATED" in TUI footer if update check fails repeatedly
+  // 📖 Auto-update detection: check npm registry for new versions at startup.
+  // 📖 If a new version is available, show an interactive prompt (Update / Changelogs / Skip).
+  // 📖 Dev mode (git checkout) skips auto-update to avoid infinite relaunch loops.
   let latestVersion = null
-  let isOutdated = false
+  const isDevMode = existsSync(join(dirname(fileURLToPath(import.meta.url)), '..', '.git'))
   try {
     latestVersion = await checkForUpdate()
-    // 📖 Track update check failures - if it fails 3+ times, mark as outdated
-    if (!latestVersion && config.settings?.updateCheckFailures >= 3) {
-      isOutdated = true
+    // 📖 Reset failure counter on successful check
+    if (config.settings?.updateCheckFailures) {
+      config.settings.updateCheckFailures = 0
+      saveConfig(config)
     }
   } catch (err) {
-    // 📖 Silently fail - don't block the app if npm registry is unreachable
-    // 📖 But track the failure for outdated detection
     const failures = (config.settings?.updateCheckFailures || 0) + 1
     if (!config.settings) config.settings = {}
     config.settings.updateCheckFailures = Math.min(failures, 3)
-    if (failures >= 3) isOutdated = true
     saveConfig(config)
   }
 
+  // 📖 Show interactive update prompt if a new version is available (skip in dev mode)
+  if (latestVersion && !isDevMode) {
+    const choice = await promptUpdateNotification(latestVersion)
+    if (choice === 'update') {
+      runUpdate(latestVersion)
+      return // 📖 runUpdate relaunches the process — this line is a safety guard
+    } else if (choice === 'changelogs') {
+      const { execSync: _exec } = await import('child_process')
+      const url = 'https://github.com/vava-nessa/free-coding-models/releases'
+      try {
+        if (process.platform === 'darwin') _exec(`open ${url}`)
+        else if (process.platform === 'linux') _exec(`xdg-open ${url}`)
+        else console.log(chalk.dim(`  📋 ${url}`))
+      } catch { console.log(chalk.dim(`  📋 ${url}`)) }
+      // 📖 After opening changelogs, re-prompt so user can still update or continue
+      const choice2 = await promptUpdateNotification(latestVersion)
+      if (choice2 === 'update') {
+        runUpdate(latestVersion)
+        return
+      }
+    }
+  }
+
   // 📖 Dynamic OpenRouter free model discovery — fetch live free models from API
   // 📖 Replaces static openrouter entries in MODELS with fresh data.
   // 📖 Fallback: if fetch fails, the static list from sources.js stays intact + warning shown.
@@ -371,8 +479,8 @@ async function main() {
     lastPingTime: now,            // 📖 Track when last ping cycle started
     lastUserActivityAt: now,      // 📖 Any keypress refreshes this timer; inactivity can force slow mode.
     resumeSpeedOnActivity: false, // 📖 Set after idle slowdown so the next activity restarts a 60s speed burst.
-    latestVersion,                // 📖 Latest npm version available (null if none or check failed)
-    isOutdated,                   // 📖 Set to true if update check failed 3+ times (show red "OUTDATED" footer)
+    startupLatestVersion: latestVersion, // 📖 Startup auto-check result reused by the footer banner after "skip update".
+    versionAlertsEnabled: !isDevMode, // 📖 Dev checkouts should not tell contributors to upgrade the global npm package.
     mode,                         // 📖 'opencode' or 'openclaw' — controls Enter action
     tierFilterMode: 0,            // 📖 Index into TIER_CYCLE (0=All, 1=S+, 2=S, ...)
     originFilterMode: 0,          // 📖 Index into ORIGIN_CYCLE (0=All, then providers)
@@ -382,6 +490,7 @@ async function main() {
     terminalCols: process.stdout.columns || 80, // 📖 Current terminal width
     widthWarningStartedAt: (process.stdout.columns || 80) < 166 ? now : null, // 📖 Start the narrow-terminal countdown immediately when booting in a small viewport.
     widthWarningDismissed: false, // 📖 Esc hides the narrow-terminal warning early for the current narrow-width session.
+    widthWarningShowCount: 0, // 📖 Counter for how many times the narrow-terminal warning has been shown (max 2 per session).
     // 📖 Settings screen state (P key opens it)
     settingsOpen: false,          // 📖 Whether settings overlay is active
     settingsCursor: 0,            // 📖 Which provider row is selected in settings
@@ -396,6 +505,13 @@ async function main() {
     settingsUpdateError: null,    // 📖 Last update-check error message for maintenance row
     settingsProxyPortEditMode: false, // 📖 Whether Settings is editing the preferred proxy port field.
     settingsProxyPortBuffer: '',  // 📖 Inline input buffer for the preferred proxy port (0 = auto).
+    daemonStatus: 'not-installed', // 📖 Background daemon status: 'running'|'stopped'|'stale'|'unhealthy'|'not-installed'
+    daemonInfo: null,             // 📖 daemon.json contents when daemon is running
+    // 📖 Proxy & Daemon overlay state (opened from Settings)
+    proxyDaemonOpen: false,       // 📖 Whether the dedicated Proxy & Daemon overlay is active
+    proxyDaemonCursor: 0,         // 📖 Selected row in the proxy/daemon overlay
+    proxyDaemonScrollOffset: 0,   // 📖 Vertical scroll offset for the proxy/daemon overlay
+    proxyDaemonMessage: null,     // 📖 Feedback message { type: 'success'|'warning'|'error', msg: string, ts: number }
     config,                       // 📖 Live reference to the config object (updated on save)
     visibleSorted: [],            // 📖 Cached visible+sorted models — shared between render loop and key handlers
     helpVisible: false,           // 📖 Whether the help overlay (K key) is active
@@ -429,14 +545,9 @@ async function main() {
     activeProfile: getActiveProfileName(config), // 📖 Currently loaded profile name (or null)
     profileSaveMode: false,       // 📖 Whether the inline "Save profile" name input is active
     profileSaveBuffer: '',        // 📖 Typed characters for the profile name being saved
-    // 📖 Feature Request state (J key opens it)
-    featureRequestOpen: false,    // 📖 Whether the feature request overlay is active
-    featureRequestBuffer: '',     // 📖 Typed characters for the feature request message
-    featureRequestStatus: 'idle', // 📖 'idle'|'sending'|'success'|'error' — webhook send status
-    featureRequestError: null,    // 📖 Last webhook error message
-    // 📖 Bug Report state (I key opens it)
-    bugReportOpen: false,         // 📖 Whether the bug report overlay is active
-    bugReportBuffer: '',          // 📖 Typed characters for the bug report message
+    // 📖 Feedback state (J/I keys open it)
+    feedbackOpen: false,          // 📖 Whether the feedback overlay is active
+    bugReportBuffer: '',          // 📖 Typed characters for the feedback message
     bugReportStatus: 'idle',      // 📖 'idle'|'sending'|'success'|'error' — webhook send status
     bugReportError: null,         // 📖 Last webhook error message
     // 📖 OpenCode sync status (S key in settings)
@@ -468,6 +579,7 @@ async function main() {
       if (prevCols >= 166 || state.widthWarningDismissed) {
         state.widthWarningStartedAt = Date.now()
         state.widthWarningDismissed = false
+        state.widthWarningShowCount++ // 📖 Increment counter when showing the warning again
       } else if (!state.widthWarningStartedAt) {
         state.widthWarningStartedAt = Date.now()
       }
@@ -525,11 +637,9 @@ async function main() {
     }
   }
 
-  // 📖 Auto-start proxy on launch if OpenCode config already has an fcm-proxy provider.
+  // 📖 Auto-start proxy on launch when proxy auto-sync is enabled for the current tool.
   // 📖 Fire-and-forget: does not block UI startup. state.proxyStartupStatus is updated async.
-  if (mode === 'opencode' || mode === 'opencode-desktop') {
-    void autoStartProxyIfSynced(config, state)
-  }
+  void autoStartProxyIfSynced(config, state)
 
   // 📖 Load cache if available (for faster startup with cached ping results)
   const cached = loadCache()
@@ -726,7 +836,7 @@ async function main() {
     ENV_VAR_NAMES,
     ensureProxyRunning,
     syncToOpenCode,
-    cleanupOpenCodeProxyConfig,
+    cleanupToolConfig,
     restoreOpenCodeBackup,
     checkForUpdateDetailed,
     runUpdate,
@@ -740,7 +850,6 @@ async function main() {
     getToolModeOrder,
     startRecommendAnalysis: overlays.startRecommendAnalysis,
     stopRecommendAnalysis: overlays.stopRecommendAnalysis,
-    sendFeatureRequest,
     sendBugReport,
     stopUi,
     ping,
@@ -788,27 +897,27 @@ async function main() {
     refreshAutoPingMode()
     state.frame++
     // 📖 Cache visible+sorted models each frame so Enter handler always matches the display
-    if (!state.settingsOpen && !state.installEndpointsOpen && !state.recommendOpen && !state.featureRequestOpen && !state.bugReportOpen && !state.changelogOpen) {
+    if (!state.settingsOpen && !state.installEndpointsOpen && !state.recommendOpen && !state.feedbackOpen && !state.changelogOpen && !state.proxyDaemonOpen) {
       const visible = state.results.filter(r => !r.hidden)
       state.visibleSorted = sortResultsWithPinnedFavorites(visible, state.sortColumn, state.sortDirection)
     }
     const content = state.settingsOpen
       ? overlays.renderSettings()
+      : state.proxyDaemonOpen
+        ? overlays.renderProxyDaemon()
       : state.installEndpointsOpen
         ? overlays.renderInstallEndpoints()
       : state.recommendOpen
         ? overlays.renderRecommend()
-        : state.featureRequestOpen
-          ? overlays.renderFeatureRequest()
-          : state.bugReportOpen
-            ? overlays.renderBugReport()
-              : state.helpVisible
+        : state.feedbackOpen
+          ? overlays.renderFeedback()
+            : state.helpVisible
                 ? overlays.renderHelp()
               : state.logVisible
                 ? overlays.renderLog()
               : state.changelogOpen
                 ? overlays.renderChangelog()
-                : renderTable(state.results, state.pendingPings, state.frame, state.cursor, state.sortColumn, state.sortDirection, state.pingInterval, state.lastPingTime, state.mode, state.tierFilterMode, state.scrollOffset, state.terminalRows, state.terminalCols, state.originFilterMode, state.activeProfile, state.profileSaveMode, state.profileSaveBuffer, state.proxyStartupStatus, state.pingMode, state.pingModeSource, state.hideUnconfiguredModels, state.widthWarningStartedAt, state.widthWarningDismissed, state.settingsUpdateState, state.settingsUpdateLatestVersion, getProxySettings(state.config).enabled === true, state.isOutdated, state.latestVersion)
+                : renderTable(state.results, state.pendingPings, state.frame, state.cursor, state.sortColumn, state.sortDirection, state.pingInterval, state.lastPingTime, state.mode, state.tierFilterMode, state.scrollOffset, state.terminalRows, state.terminalCols, state.originFilterMode, state.activeProfile, state.profileSaveMode, state.profileSaveBuffer, state.proxyStartupStatus, state.pingMode, state.pingModeSource, state.hideUnconfiguredModels, state.widthWarningStartedAt, state.widthWarningDismissed, state.widthWarningShowCount, state.settingsUpdateState, state.settingsUpdateLatestVersion, getProxySettings(state.config).enabled === true, state.startupLatestVersion, state.versionAlertsEnabled)
     process.stdout.write(ALT_HOME + content)
   }, Math.round(1000 / FPS))
 
@@ -816,7 +925,7 @@ async function main() {
   const initialVisible = state.results.filter(r => !r.hidden)
   state.visibleSorted = sortResultsWithPinnedFavorites(initialVisible, state.sortColumn, state.sortDirection)
 
-  process.stdout.write(ALT_HOME + renderTable(state.results, state.pendingPings, state.frame, state.cursor, state.sortColumn, state.sortDirection, state.pingInterval, state.lastPingTime, state.mode, state.tierFilterMode, state.scrollOffset, state.terminalRows, state.terminalCols, state.originFilterMode, state.activeProfile, state.profileSaveMode, state.profileSaveBuffer, state.proxyStartupStatus, state.pingMode, state.pingModeSource, state.hideUnconfiguredModels, state.widthWarningStartedAt, state.widthWarningDismissed, state.settingsUpdateState, state.settingsUpdateLatestVersion, getProxySettings(state.config).enabled === true, state.isOutdated, state.latestVersion))
+  process.stdout.write(ALT_HOME + renderTable(state.results, state.pendingPings, state.frame, state.cursor, state.sortColumn, state.sortDirection, state.pingInterval, state.lastPingTime, state.mode, state.tierFilterMode, state.scrollOffset, state.terminalRows, state.terminalCols, state.originFilterMode, state.activeProfile, state.profileSaveMode, state.profileSaveBuffer, state.proxyStartupStatus, state.pingMode, state.pingModeSource, state.hideUnconfiguredModels, state.widthWarningStartedAt, state.widthWarningDismissed, state.widthWarningShowCount, state.settingsUpdateState, state.settingsUpdateLatestVersion, getProxySettings(state.config).enabled === true, state.startupLatestVersion, state.versionAlertsEnabled))
 
   // 📖 If --recommend was passed, auto-open the Smart Recommend overlay on start
   if (cliArgs.recommendMode) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "free-coding-models",
-  "version": "0.2.17",
+  "version": "0.3.1",
   "description": "Find the fastest coding LLM models in seconds — ping free models from multiple providers, pick the best one for OpenCode, Cursor, or any AI coding assistant.",
   "keywords": [
     "nvidia",
@@ -36,7 +36,8 @@
   "type": "module",
   "main": "bin/free-coding-models.js",
   "bin": {
-    "free-coding-models": "./bin/free-coding-models.js"
+    "free-coding-models": "./bin/free-coding-models.js",
+    "fcm-proxy-daemon": "./bin/fcm-proxy-daemon.js"
   },
   "files": [
     "bin/",

package/src/account-manager.js

@@ -39,6 +39,12 @@ const UNKNOWN_COOLDOWN_BASE_MS = 15 * 60 * 1000 // 15m initial cooldown
 const UNKNOWN_COOLDOWN_MAX_MS = 6 * 60 * 60 * 1000 // 6h max cooldown
 const KNOWN_FALLBACK_COOLDOWN_MS = 5 * 60 * 1000 // 5m fallback for known providers
 
+// 📖 Generic consecutive-failure cooldown constants.
+// When an account accumulates FAILURE_COOLDOWN_THRESHOLD consecutive non-429 failures,
+// it enters a graduated cooldown (30s → 60s → 120s) so the proxy routes around it.
+const FAILURE_COOLDOWN_THRESHOLD = 3
+const FAILURE_COOLDOWN_STEPS_MS = [30_000, 60_000, 120_000]
+
 // ─── Internal: per-account health state ──────────────────────────────────────
 
 class AccountHealth {
@@ -85,6 +91,15 @@ class AccountHealth {
       cooldownUntilMs: 0,
       probeInFlight: false,
     }
+
+    /**
+     * 📖 Generic consecutive-failure tracking for non-429 errors.
+     * When consecutiveFailures >= FAILURE_COOLDOWN_THRESHOLD, the account enters
+     * a graduated cooldown to avoid wasting requests on a failing endpoint.
+     */
+    this.consecutiveFailures = 0
+    this.failureCooldownUntilMs = 0
+    this.failureCooldownLevel = 0
   }
 
   /**
@@ -265,6 +280,9 @@ export class AccountManager {
     const retryAfterTs = this._retryAfterMap.get(acct.id)
     if (retryAfterTs && Date.now() < retryAfterTs) return false
 
+    // 📖 Generic failure cooldown — blocks account after consecutive non-429 failures
+    if (health.failureCooldownUntilMs > 0 && Date.now() < health.failureCooldownUntilMs) return false
+
     // Only exclude when quota is known to be nearly exhausted.
     // When quotaSignal is 'unknown' (null quotaPercent), we remain available.
     if (health.quotaSignal === 'known' && health.quotaPercent !== null && health.quotaPercent <= 5) return false
@@ -455,6 +473,17 @@ export class AccountManager {
     if (classifiedError?.retryAfterSec) {
       this._retryAfterMap.set(accountId, Date.now() + classifiedError.retryAfterSec * 1000)
     }
+
+    // 📖 Generic consecutive-failure cooldown: when an account hits FAILURE_COOLDOWN_THRESHOLD
+    // consecutive non-429 failures, put it in graduated cooldown (30s → 60s → 120s)
+    // so the proxy routes around it instead of wasting requests.
+    health.consecutiveFailures++
+    if (health.consecutiveFailures >= FAILURE_COOLDOWN_THRESHOLD) {
+      const stepIdx = Math.min(health.failureCooldownLevel, FAILURE_COOLDOWN_STEPS_MS.length - 1)
+      health.failureCooldownUntilMs = Date.now() + FAILURE_COOLDOWN_STEPS_MS[stepIdx]
+      health.failureCooldownLevel++
+      health.consecutiveFailures = 0
+    }
   }
 
   /**
@@ -532,6 +561,11 @@ export class AccountManager {
 
     // Clear retry-after from the retryAfterMap (no longer cooling down)
     this._retryAfterMap.delete(accountId)
+
+    // 📖 Reset generic failure cooldown state on success
+    health.consecutiveFailures = 0
+    health.failureCooldownUntilMs = 0
+    health.failureCooldownLevel = 0
   }
 
   /**