free-coding-models 0.5.64 → 0.5.66

package/changelog/v0.5.65.md

@@ -0,0 +1,35 @@
+# Changelog v0.5.65 - 2026-07-29
+
+### Fixed
+
+- 🛡️ **#146 — OpenRouter / rate-limited providers no longer burned the user's daily quota.** Health-probe pings are now throttled at two orthogonal levels so a single overloaded model can no longer wipe out an OpenRouter (or similar) daily request limit. Issue submitted by `@ia-S-on`.
+
+  - **Per-provider quota circuit-breaker** — New module `src/core/provider-cooldown.js` exposes an in-memory pause map. When a probe returns HTTP `429`, FCM parses the `Retry-After` header (and falls back to the OpenRouter-style body `"Rate limit exceeded, please try again N seconds later."`), then pauses **every model of that provider** until the window expires. Probe pressure drops from ~30 req/min/provider to ~0 req/min/provider for the entire duration. Affected code: `src/core/ping.js` (trigger on `resp.status === 429`), `src/tui/app.js` (skip paused providers in `runPingCycle`).
+  - **Per-model broken cooldown with exponential backoff** — `src/core/probe-cache.js` now caches `broken` entries too. `isCacheFresh()` and `getModelsDueForProbe()` honour a new `brokenCooldownMs(failureCount)` ladder (30 s → 1 m → 2 m → 5 m, then plateau at 5 min). `recordProbeResults()` tracks `consecutiveFailures` (increments on `broken`, resets to `0` on `ok`). This caps worst-case probe pressure on a permanently-broken model at **~0.2 req/min** instead of the previous **~30 req/min**.
+  - **Live footer chip** — When one or more providers are paused, the TUI footer now shows e.g. `⏸ openrouter 14h · ⏸ ovhcloud 34s` (warm amber background, live countdown that auto-rolls to s/m/h/d). New state field `state.pausedProviders` (defaults to `{}`) + render-table chip fed by `pausedProviders` option. Behaviour verified on first run — OVHcloud was correctly paused for 34 s on a real 429 during smoke testing.
+
+### Added
+
+- 📖 **README health-check warning** — New section `⚠️ Health checks consume provider quota` between the providers table and the Tier scale. Explains the 1k/day OpenRouter cap, links the v0.5.65 fix points, and offers the immediate workaround (remove the provider's key from Settings — anonymous probes still work for liveness checks).
+- 🧪 **18 new unit tests** in `test/test.js` covering both layers (`Issue #146: provider quota circuit-breaker` + `Issue #146: per-model broken-cooldown backoff`). Three pre-existing tests in `test/probe-cache.test.js` updated to reflect the new `broken`-is-fresh-during-cooldown contract.
+
+### Changed
+
+- 📖 `pnpm test` suite: **797 / 797 passing** (was 779 / 779 in 0.5.64; net +18 new tests + 3 updated).
+- 📖 `node --check` clean on every touched file; TUI smoke-tested in tmux (no runtime regression).
+- 📖 Footer's existing probe-cache chip is unchanged in behaviour but gains the sibling paused-providers chip immediately to its right.
+
+### Migration / workaround
+
+> **If you were already hitting the 429 from issue #146 before upgrading**, simply upgrading to v0.5.65 fixes the runaway probe loop — no manual step required. The provider will be auto-paused on its next probe.
+>
+> **If you want zero authenticated probes for a particular provider** (e.g. you only use OpenRouter for ad-hoc calls and want FCM to leave the key alone), leave the key empty in Settings — anonymous probes still tell us whether each model is up and will not burn your personal daily quota.
+
+### Files
+
+- **New**: `src/core/provider-cooldown.js` (≈220 lines).
+- **Modified**: `src/core/ping.js` (import + 429 trigger), `src/core/probe-cache.js` (constants, `brokenCooldownMs`, `isCacheFresh`, `getModelsDueForProbe`, `recordProbeResults`), `src/tui/app.js` (import + `runPingCycle` skip + paused snapshot), `src/tui/tui-state.js` (`pausedProviders: {}` on state), `src/tui/render-table.js` (new chip + thread option through), `README.md` (warning section), `test/test.js` (18 new tests), `test/probe-cache.test.js` (3 updated), `package.json` (`0.5.64` → `0.5.65`), this changelog.
+
+### Breaking changes
+
+None. All changes are additive and behaviour-preserving for users who were not already rate-limited.

package/changelog/v0.5.66.md

@@ -0,0 +1,55 @@
+# Changelog v0.5.66 - 2026-07-29
+
+### Added
+
+- 📚 **Project-wide documentation overhaul** — The README, the `docs/` repo, and the marketing site (`website/`) were rewritten end-to-end by a pro doc pass. ~2,000 insertions / ~1,600 deletions across **29 files**. Public behaviour is unchanged; this is a content-only release.
+
+- **Reordered README around the product priority** — TUI → Web → Agent Extensions → Smart Model Router (last). The router and the extensions moved out of the middle of the doc and into dedicated sections at the end, so the TUI and the Web Dashboard (the two core surfaces) are now the centerpiece of the reading flow.
+
+- **Expanded Quick Start** — grew from a 3-step outline to a 6-step user-centric walkthrough (Install → Grab a key → Launch & paste → Pick & launch → The 30-second cool tour → Go further). Each step links to the relevant deep section. Includes a `headless` sidebar (`--json`, `--fiable`) and a `pre-target a tool from the command line` example block.
+
+- **🟢 Free AI Providers** — kept the 20-provider table near the top, but now sits after Quick Start with a clean `⚠️ Health checks consume provider quota` note and a collapsible `🧹 Providers removed from the catalog` details block.
+
+- **🎛️ TUI section** — now opens with a `First-run flow` (3 steps), then 7 user-framed workflows (`"Give me the fastest model that actually works"`, `"Pick a model & launch"`, `"Benchmark before I commit"`, `"Smart Recommend"`, `"Keep my go-to models pinned"`, `"Switch tools without restarting"`, `"My terminal theme fights the TUI colors"`), followed by the complete keyboard reference and a mouse reference.
+
+- **🌐 Web Dashboard** — feature table condensed, `web` (port 3333) vs `--daemon` (port 19280) port distinction made explicit, Docker quick-start + image tags + env vars + compose + troubleshooting all in one place.
+
+- **🔌 19 per-tool integration pages** — replaced the previous 3 generic integration pages (`opencode`, `pi-extension`, `openclaw`) with a dedicated page for every supported target: OpenCode, Pi, OpenClaw, Crush, Goose, Aider, Kilo, Hermes, Continue, Cline, Amp, Qwen Code, ForgeCode, ZCode, jcode, Caveman Code, Copilot CLI, OpenHands, Xcode Intelligence. Each page documents the launch flag, the exact config file FCM writes (path + JSON example verified against `src/core/tool-launchers.js`), the install/bootstrap behaviour, and (for OpenCode + Pi) the in-agent plugin commands.
+
+- **OpenCode + Pi merged into one page per tool** — `integrations/opencode.mdx` and `integrations/pi.mdx` each combine the FCM launch flow (CLI flag, config, install) with the in-agent plugin (`/fcm` commands, progress display, architecture). The old `pi-extension` slug redirects to `pi` so any external link still resolves.
+
+- **📖 5 video wrappers added across the docs and the landing** — `<Video name="…" />` placeholders for the 5 planned screen recordings (`tui-first-launch`, `tui-pick-and-launch`, `tui-speed-test`, `web-url-deep-linking`, `router-playground`). On the doc pages a `<Callout>` immediately below each wrapper contains the recording script (shot list, export spec, file location) and a `{/* AGENT TODO: … */}` comment that tells the next agent exactly which block to delete once the `.mp4` is committed. On the landing page the wrappers are bare — no Callout, because the landing is public.
+
+- **🧠 Persistent site component changes** — a new `<Video />` component (`website/src/components/Video.tsx`) renders an autoplay / muted / loop / playsinline `<video>` in a styled figure. The Markdown renderer now wraps every MDX `<table>` in a `.table-scroll` container so wide tables scroll *inside* the page instead of pushing the viewport wider, and the first column gets a `min-width: 8rem` so label columns (e.g. the "Area" column in the Web Dashboard features table) stay readable. The "On this page" right-side table-of-contents was removed from every docs page; the content was already in flow and the column was redundant.
+
+- **Sidebar "View more" toggle on long nav groups** — `Agent Integrations` now lists the 9 most-used tools in the user's preferred order (OpenCode, Pi, Hermes, OpenClaw, Qwen Code, Cline, Goose, Kilo, jcode) and hides the remaining 10 behind a "+ View 10 more…" toggle that expands to "- View less". The active page is always shown even when the group is collapsed, so you never lose your place in the nav.
+
+- **Repository docs cleaned up** — `docs/config.md` no longer lists the deprecated providers that were removed from the active catalog (huggingface, replicate, deepinfra, siliconflow, together, perplexity); the env-var table is now aligned with the 20 active providers. `docs/development.md` is updated from the stale `160 models across 20 providers` figure to the real `222 models`, and the file-path table is rewritten from the obsolete `src/*.js` layout to the current `src/core/`, `src/tui/`, `src/data/` structure. `docs/integrations.md` now lists **19 tools + the FCM router** in the tool → config mapping.
+
+- **Marketing site MDX content realigned** — the entire `website/src/content/docs/` tree was rewritten to match the README. Architectural inaccuracies (e.g. `Gemini CLI` referenced as a provider, fabricated REST endpoints like `/api/best`, half-true circuit-breaker states) were corrected against the source code and the README. The `cli-tui.mdx` keybinding table was rebuilt from the README so it is now 100% accurate (fixing the historical bugs where `N` was mislabelled as "Sort by Context" and `Y` was mislabelled as "Sort by Tier"). The docs nav sidebar was reordered so the surfaces (TUI, Web, Docker) come first, the agent integrations follow, and the Smart Router is the last item in "Core concepts & advanced" — matching the README's reading order.
+
+- **Landing-page video integration** — the static `LogoMark` + `MorphingText` content in the Hero card was replaced with the `<Video name="tui-first-launch">` wrapper so the first thing a visitor sees becomes a live demo as soon as the recording lands. The router demo is embedded in the FailoverSection, and the remaining three demos live in a new "See it live" grid at the bottom of the SurfacesSection.
+
+### Changed
+
+- **README "double title" bug** — every docs page used to render the title twice (once in the route header, once in the leading `# Title` of the MDX body). All 18 MDX files had their leading `# <Title>` line removed; the route header is now the single source of truth for the page title.
+- **Markdown renderer table overflow** — the previous `.prose table { white-space: nowrap }` rule forced every cell onto a single line, which exploded the page width whenever a cell contained a long description (e.g. the "Highlights" column in the Web Dashboard features table). Tables now wrap their content (`overflow-wrap: anywhere`) and live inside a horizontal-scroll wrapper as a fallback so even pathological tables scroll *inside* the page instead of stretching the viewport.
+- **`README.md` now contains 5 video references** — the same 5 recordings are available on the landing and the docs; all three surfaces reference the same files in `website/public/videos/`. Mutualised, no duplication.
+- **Removed `pi-extension.mdx`** — superseded by the merged `integrations/pi.mdx`. A redirect from the old slug lives in `docs/$.tsx` so any external link still resolves.
+
+### Migration / workaround
+
+> **No code or behaviour changes.** This release is documentation-only. No new flags, no new endpoints, no breaking changes. Upgrade is safe and invisible to runtime users.
+>
+> **The 5 videos are not yet recorded.** The wrappers currently render empty `<video>` frames everywhere. Drop the recorded `.mp4` files at `website/public/videos/<name>.mp4` and the surrounding `<Callout>` recording scripts in the docs remove themselves via the `{/* AGENT TODO: … */}` comment the next time an agent touches them. Public behaviour is unchanged.
+
+### Files
+
+- **Modified**: `README.md` (full rewrite, ~1,000 lines), `docs/config.md`, `docs/development.md`, `docs/integrations.md`, 16 docs MDX files under `website/src/content/docs/`, `website/src/components/MdxComponents.tsx` (registers `Video`, `table`), `website/src/components/DocsSidebar.tsx` (refactored with `NavGroup` + `View more` toggle), `website/src/routes/index.tsx` (landing videos + import cleanup), `website/src/routes/docs/$.tsx` (TOC removed, `pi-extension` redirect), `website/src/styles.css` (table wrapping + scroll wrapper, `.table-scroll` activated), `website/src/content/nav.ts` (reordered + `primaryCount`), `package.json` (`0.5.65` → `0.5.66`), this changelog.
+- **New**: `website/src/components/Video.tsx` (~35 lines).
+- **New folder**: `website/public/videos/` (target for the 5 upcoming recordings).
+- **Deleted**: `website/src/content/docs/integrations/pi-extension.mdx` (replaced by `integrations/pi.mdx`; redirect handles old links).
+
+### Breaking changes
+
+None. This is a documentation-only release. No CLI flags added, no flags removed, no endpoints changed, no behaviour changed.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "free-coding-models",
-  "version": "0.5.64",
-  "description": "Find the fastest coding LLM models in seconds \u2014 ping free models from multiple providers, pick the best one for OpenCode, Cursor, or any AI coding assistant.",
+  "version": "0.5.66",
+  "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",
     "nim",
@@ -89,4 +89,4 @@
     "vite": "^8.0.16",
     "vite-plus": "^0.2.6"
   }
-}
+}

package/src/core/ping.js

@@ -13,6 +13,9 @@
  *   - Quota extraction from rate limit headers (multiple variants supported)
  *   - Cached provider quota polling with TTL and error backoff
  *   - Cloudflare account ID resolution from environment
+ *   - Per-provider circuit-breaker on 429 (issue #146): pauses ALL models of a provider
+ *     when the provider returns a quota-exhausted response, so the ping loop stops
+ *     hammering the user's daily quota while the provider's retry window is active.
  *
  *   → Functions:
  *   - `resolveCloudflareUrl`: Resolve {account_id} placeholder from CLOUDFLARE_ACCOUNT_ID env var
@@ -31,6 +34,7 @@
  *   - ../src/constants.js: PING_TIMEOUT
  *   - ../src/provider-quota-fetchers.js: _fetchProviderQuotaFromModule (quota fetching with cache)
  *   - ../src/quota-capabilities.js: supportsUsagePercent
+ *   - ./provider-cooldown.js: pauseProviderQuota, extractRetryAfterFromResponse (issue #146)
  *
  *   ⚙️ Configuration:
  *   - PING_TIMEOUT: Timeout in ms for ping requests (default: 15000)
@@ -43,6 +47,10 @@
 import { PING_TIMEOUT } from './constants.js'
 import { fetchProviderQuota as _fetchProviderQuotaFromModule, extractQuota as _extractQuotaFromModule, processResponseHeaders as _processResponseHeadersFromModule } from './provider-quota-fetchers.js'
 import { supportsUsagePercent } from './quota-capabilities.js'
+import {
+  extractRetryAfterFromResponse,
+  pauseProviderQuota,
+} from './provider-cooldown.js'
 
 const DISABLED_THINKING_RETRY_STATUSES = new Set([400, 422])
 const disabledThinkingUnsupportedProviders = new Set()
@@ -171,6 +179,14 @@ export async function ping(apiKey, modelId, providerKey, url) {
       req = buildPingRequest(apiKey, modelId, providerKey, url, { disableThinking: false })
       resp = await sendPingFetch(req, ctrl.signal)
     }
+    // 📖 Provider circuit-breaker (issue #146): openrouter + similar gateways rate-limit
+    // 📖 at the provider/key level, not per-model. A 429 means the WHOLE key is paused,
+    // 📖 often for hours — re-pinging every model every 2-30s would burn the quota in minutes.
+    // 📖 Honour Retry-After header + the OpenRouter body "try again N seconds later".
+    if (resp.status === 429) {
+      const retryMs = await extractRetryAfterFromResponse(resp)
+      if (retryMs > 0) pauseProviderQuota(providerKey, retryMs)
+    }
     // 📖 Normalize all HTTP 2xx statuses to "200" so existing verdict/avg logic still works.
     const code = resp.status >= 200 && resp.status < 300 ? '200' : String(resp.status)
     // 📖 Passive quota tracker (t2): parse the response headers via the shared module.

package/src/core/probe-cache.js

@@ -12,7 +12,9 @@
  *   📖 Freshness rules (in order):
  *   📖   1. No entry              → due for probe
  *   📖   2. probeVersion mismatch  → due for probe (silently re-probed, entry overwritten)
- *   📖   3. status === 'broken'    → always due (allows recovery detection)
+ *   📖   3. status === 'broken'    → only due AFTER `brokenCooldownMs(consecutiveFailures)`
+ *   📖                            ✅ (issue #146: was always-due → caused quota burn on
+ *   📖                            rate-limited providers like openrouter)
  *   📖   4. now - lastProbedAt >= ttlMs → due for probe
  *   📖   5. otherwise              → fresh, skip
  *
@@ -34,11 +36,13 @@
  *   → recordProbeResults(providerKey, results, opts?) → mutates in-memory cache
  *   → getCacheStats(opts?) → { total, ok, broken, freshCount, staleCount, ... }
  *   → getCachedResultsForProvider(providerKey, opts?) → array of synthesized results
+ *   → brokenCooldownMs(failureCount)            — Backoff ladder for broken models (issue #146)
  *
  * @exports getProbeCachePath, loadCache, flushCache, clearCache,
  *          getModelsDueForProbe, isCacheFresh, recordProbeResults,
  *          getCacheStats, getCachedResultsForProvider,
- *          DEFAULT_PROBE_TTL_MS, CURRENT_PROBE_VERSION
+ *          DEFAULT_PROBE_TTL_MS, BROKEN_COOLDOWN_STEPS_MS,
+ *          brokenCooldownMs, CURRENT_PROBE_VERSION
  *
  * @see src/core/ping-loop.js — the integration point (skips fresh entries)
  * @see src/core/cache.js     — older per-session ping cache (5 min TTL, distinct concern)
@@ -55,6 +59,30 @@ import { atomicWriteJson } from './shared-helpers.js'
 /** 📖 Default probe-result freshness window — 24h. Override via opts.ttlMs. */
 export const DEFAULT_PROBE_TTL_MS = 24 * 60 * 60 * 1000
 
+/**
+ * 📖 Cooldown ladder for broken models (issue #146). After a consecutive failure,
+ * 📖 the model is treated as fresh for the duration returned by `brokenCooldownMs()`,
+ * 📖 so the ping loop skips it instead of hammering it every 2–30s.
+ * 📖 The ladder grows exponentially then plateaus: 30s → 1m → 2m → 5m.
+ * 📖 Reaching the plateau (5min) caps the probe pressure on a permanently-broken
+ * 📖 model at ~0.2 req/min instead of the previous ~30 req/min.
+ */
+export const BROKEN_COOLDOWN_STEPS_MS = [30_000, 60_000, 120_000, 300_000]
+
+/**
+ * 📖 brokenCooldownMs: Cooldown duration for a model that has failed N consecutive times.
+ * 📖 Failure count is 1-indexed (1 = first failure, 2 = second, ...).
+ * 📖 Saturates at the last entry of BROKEN_COOLDOWN_STEPS_MS.
+ *
+ * @param {number} failureCount
+ * @returns {number} milliseconds (always >= 0)
+ */
+export function brokenCooldownMs(failureCount) {
+  const n = Math.max(1, Math.floor(Number(failureCount) || 1))
+  const idx = Math.min(n - 1, BROKEN_COOLDOWN_STEPS_MS.length - 1)
+  return BROKEN_COOLDOWN_STEPS_MS[idx]
+}
+
 /**
  * 📖 Bump this number whenever ping behaviour changes (new endpoint, different prompt,
  * 📖 new provider factory from t7, etc.). On load, any entry whose probeVersion differs
@@ -270,8 +298,16 @@ export function getModelsDueForProbe(providerKey, modelIds, opts = {}) {
     if (typeof entry.probeVersion !== 'number' || entry.probeVersion !== probeVersion) {
       due.push(id); continue
     }
-    // Rule 3: broken → always due (recovery detection)
-    if (entry.status === 'broken') { due.push(id); continue }
+    // Rule 3: broken → due only AFTER brokenCooldownMs elapsed (issue #146)
+    // 📖 Previous behaviour re-pinged broken models every cycle, which burned
+    // 📖 rate-limited providers' quota (openrouter: ~1000 req/day cap).
+    // 📖 Now we honour an exponential backoff: 30s → 1m → 2m → 5m (plateau).
+    if (entry.status === 'broken') {
+      const cooldown = brokenCooldownMs(entry.consecutiveFailures ?? 1)
+      if (now - entry.lastProbedAt < cooldown) continue
+      due.push(id)
+      continue
+    }
     // Rule 4: TTL expired → due
     if (typeof entry.lastProbedAt !== 'number' || now - entry.lastProbedAt >= ttlMs) {
       due.push(id); continue
@@ -301,7 +337,13 @@ export function isCacheFresh(providerKey, modelId, opts = {}) {
   const entry = cache?.providers?.[providerKey]?.models?.[modelId]
   if (!entry) return false
   if (typeof entry.probeVersion !== 'number' || entry.probeVersion !== probeVersion) return false
-  if (entry.status === 'broken') return false
+  if (entry.status === 'broken') {
+    // 📖 Issue #146 — broken models are now FRESH for `brokenCooldownMs` after their
+    // 📖 last failure, instead of always being due. This caps the probe pressure
+    // 📖 on permanently-broken models at ~0.2 req/min instead of ~30 req/min.
+    const cooldown = brokenCooldownMs(entry.consecutiveFailures ?? 1)
+    return now - entry.lastProbedAt < cooldown
+  }
   if (typeof entry.lastProbedAt !== 'number') return false
   return now - entry.lastProbedAt < ttlMs
 }
@@ -350,12 +392,19 @@ export function recordProbeResults(providerKey, results, opts = {}) {
   for (const raw of results || []) {
     try {
       const r = normaliseResult(raw)
+      // 📖 Consecutive failure tracker (issue #146): drives the broken-cooldown ladder.
+      // 📖 `ok` resets to 0; `broken` increments from the previous value (or 1 if absent).
+      const prev = bucket[r.modelId]
+      const consecutiveFailures = r.status === 'broken'
+        ? ((prev && Number.isInteger(prev.consecutiveFailures)) ? prev.consecutiveFailures + 1 : 1)
+        : 0
       bucket[r.modelId] = {
         status: r.status,
         lastProbedAt: now,
         latencyMs: r.latencyMs,
         lastError: r.lastError,
         probeVersion: CURRENT_PROBE_VERSION,
+        consecutiveFailures,
       }
       written++
     } catch {

package/src/core/provider-cooldown.js

@@ -0,0 +1,185 @@
+/**
+ * @file provider-cooldown.js
+ * @description Per-provider quota circuit-breaker for the health-ping loop.
+ *
+ * @details
+ *   📖 Why this exists:
+ *   📖 - OpenRouter (and similar rate-limited gateways) enforce rate limits at the
+ *   📖   **provider/key** level, not per-model. A single 429 "Rate limit exceeded"
+ *   📖   response means **the whole key is paused**, often for hours.
+ *   📖 - Without this breaker, FCM keeps re-pinging every model of that provider
+ *   📖   every 2–30 seconds (because probe-cache treats `broken` as always-due),
+ *   📖   burning the user's daily quota in minutes (issue #146).
+ *   📖 - This module exposes a tiny in-memory map of paused providers so the ping
+ *   📖   loop can short-circuit them until the Retry-After window expires.
+ *
+ *   📖 Design notes:
+ *   📖 - In-memory only, intentionally. The pause is short-lived (minutes to hours)
+ *   📖   and we don't want a stale pause to outlive a server-side reset.
+ *   📖 - `pauseProviderQuota` keeps the **maximum** pause if the provider is already
+ *   📖   paused, so a rapid succession of 429s with decreasing Retry-After values
+ *   📖   never accidentally **shortens** an existing longer pause.
+ *
+ * @functions
+ *   → isProviderQuotaPaused(providerKey, now?)              — Is this provider currently paused?
+ *   → pauseProviderQuota(providerKey, ms)                    — Set a pause for ms milliseconds
+ *   → providerQuotaPauseRemaining(providerKey, now?)        — ms left in the current pause
+ *   → listPausedProviders(now?)                              — Diagnostic: {[providerKey]: remainingMs}
+ *   → clearProviderQuotaPause(providerKey)                   — Force-reset (testing/escape hatch)
+ *   → parseRetryAfterMs(value)                               — Header-only Retry-After parser
+ *   → extractRetryAfterFromResponse(resp)                    — Header + body parser (OR style message)
+ *
+ * @exports isProviderQuotaPaused, pauseProviderQuota, providerQuotaPauseRemaining,
+ *          listPausedProviders, clearProviderQuotaPause, parseRetryAfterMs,
+ *          extractRetryAfterFromResponse
+ */
+
+// ─── Module state ─────────────────────────────────────────────────────────────
+
+/**
+ * 📖 Map<providerKey, timestamp-ms> until which the provider's quota is considered
+ * 📖 paused. `now >= value` means the pause has expired and the entry is purged lazily.
+ */
+const providerQuotaPausedUntil = new Map()
+
+// ─── Pure helpers (exported, easy to unit test) ───────────────────────────────
+
+/**
+ * 📖 parseRetryAfterMs: Parse a Retry-After header value into milliseconds.
+ * 📖 Accepts either a plain-seconds integer ("120") or an HTTP-date ("Wed, 21 Oct 2026 07:28:00 GMT").
+ * 📖 Returns null if the value is missing, malformed, or already in the past.
+ *
+ * @param {string|number|null|undefined} value
+ * @returns {number|null} milliseconds, or null when not parseable
+ */
+export function parseRetryAfterMs(value) {
+  if (value == null) return null
+  if (typeof value === 'string' && value.trim() === '') return null
+  const seconds = Number(value)
+  if (Number.isFinite(seconds) && seconds >= 0) return Math.round(seconds * 1000)
+  const dateMs = Date.parse(value)
+  if (Number.isFinite(dateMs)) {
+    const delta = dateMs - Date.now()
+    return delta > 0 ? delta : null
+  }
+  return null
+}
+
+/**
+ * 📖 extractRetryAfterFromResponse: Best-effort Retry-After extraction.
+ * 📖 Tries the header first (RFC 7231), then falls back to the OpenRouter-style
+ * 📖 error body "Rate limit exceeded, please try again N seconds later.".
+ * 📖 Returns the delay in milliseconds, or 0 if no signal is found.
+ *
+ * @param {Response} resp — A Fetch Response object (uses .headers + .clone()/.text()).
+ * @returns {Promise<number>}
+ */
+export async function extractRetryAfterFromResponse(resp) {
+  if (!resp || typeof resp.headers?.get !== 'function') return 0
+
+  // 1) Standard Retry-After header (lowercase lookup matches Headers semantics)
+  const headerMs = parseRetryAfterMs(resp.headers.get('retry-after'))
+  if (headerMs && headerMs > 0) return headerMs
+
+  // 2) OpenRouter-style message body, e.g.: "Rate limit exceeded, please try again 50680 seconds later."
+  try {
+    const text = await resp.clone().text()
+    if (!text) return 0
+    const m = text.match(/try again (\d+)\s*seconds? later/i)
+    if (m) {
+      const secs = parseInt(m[1], 10)
+      if (Number.isFinite(secs) && secs > 0) return secs * 1000
+    }
+  } catch {
+    // Body unreadable — treat as no signal, don't throw.
+  }
+  return 0
+}
+
+// ─── Pause map API ────────────────────────────────────────────────────────────
+
+/**
+ * 📖 isProviderQuotaPaused: Return true while the provider's quota pause is active.
+ * 📖 Lazily purges expired pauses so the map stays bounded over long sessions.
+ *
+ * @param {string} providerKey
+ * @param {number} [now=Date.now()]
+ * @returns {boolean}
+ */
+export function isProviderQuotaPaused(providerKey, now = Date.now()) {
+  const until = providerQuotaPausedUntil.get(providerKey)
+  if (until == null) return false
+  if (now >= until) {
+    providerQuotaPausedUntil.delete(providerKey)
+    return false
+  }
+  return true
+}
+
+/**
+ * 📖 pauseProviderQuota: Mark a provider as paused for `ms` milliseconds.
+ * 📖 If already paused, keeps the longer of the existing and new windows (never shortens).
+ *
+ * @param {string} providerKey
+ * @param {number} ms — Duration in milliseconds. Non-positive values are ignored.
+ * @returns {boolean} true if the pause was applied or extended, false otherwise.
+ */
+export function pauseProviderQuota(providerKey, ms, opts = {}) {
+  if (!providerKey || typeof ms !== 'number' || !Number.isFinite(ms) || ms <= 0) return false
+  const now = opts.now ?? Date.now()
+  const until = now + ms
+  const cur = providerQuotaPausedUntil.get(providerKey) ?? 0
+  // 📖 Keep the max so a 5s pause arriving after a 14h pause never shortens it.
+  if (until > cur) providerQuotaPausedUntil.set(providerKey, until)
+  return true
+}
+
+/**
+ * 📖 providerQuotaPauseRemaining: How many ms remain on the current pause.
+ * 📖 Returns 0 when the pause has expired or the provider is not paused.
+ *
+ * @param {string} providerKey
+ * @param {number} [now=Date.now()]
+ * @returns {number} milliseconds remaining (always >= 0)
+ */
+export function providerQuotaPauseRemaining(providerKey, now = Date.now()) {
+  const until = providerQuotaPausedUntil.get(providerKey)
+  if (!until) return 0
+  const remaining = until - now
+  if (remaining <= 0) {
+    providerQuotaPausedUntil.delete(providerKey)
+    return 0
+  }
+  return remaining
+}
+
+/**
+ * 📖 listPausedProviders: Snapshot of currently paused providers + ms remaining.
+ * 📖 Intended for diagnostics (TUI footer chip, daemon /stats, error logs).
+ *
+ * @param {number} [now=Date.now()]
+ * @returns {Record<string, number>} {[providerKey]: msRemaining}
+ */
+export function listPausedProviders(now = Date.now()) {
+  const out = {}
+  for (const [providerKey, until] of providerQuotaPausedUntil) {
+    const remaining = until - now
+    if (remaining > 0) out[providerKey] = remaining
+  }
+  return out
+}
+
+/**
+ * 📖 clearProviderQuotaPause: Force-reset the pause for a provider (or all).
+ * 📖 Mainly a test/escape hatch — production code should let pauses expire naturally.
+ *
+ * @param {string} [providerKey] — omit to clear all pauses
+ * @returns {void}
+ */
+export function clearProviderQuotaPause(providerKey) {
+  if (!providerKey) {
+    providerQuotaPausedUntil.clear()
+    return
+  }
+  providerQuotaPausedUntil.delete(providerKey)
+}

package/src/tui/app.js

@@ -139,6 +139,10 @@ import {
   pruneStaleEntries as pruneProbeCacheStaleEntries,
   DEFAULT_PROBE_TTL_MS,
 } from '../core/probe-cache.js'
+import {
+  isProviderQuotaPaused,
+  listPausedProviders,
+} from '../core/provider-cooldown.js'
 import { checkConfigSecurity } from '../core/security.js'
 import { buildCliHelpText } from './cli-help.js'
 import { detectActiveTheme, THEME_BG_RGB, getTheme, patchThemeBg } from './theme.js'
@@ -1046,6 +1050,8 @@ export async function runApp(cliArgs, config, startupOptions = {}) {
       probeCacheMisses: state.probeCacheMisses || 0,
       probeCacheBrokenHidden: state.probeCacheBrokenHidden || 0,
       showBrokenMode: !!state.showBrokenMode,
+      // 📖 Provider circuit-breaker (issue #146): footer chip for paused providers
+      pausedProviders: state.pausedProviders || {},
       // 📖 Enrichment chips (t4 + t5): benchmark catalog + models.dev provenance
       // 📖 Read fresh from moduleEnrichmentStats on every render so the async
       // 📖 models.dev fetch (background, never blocks the TUI) is reflected as
@@ -1229,6 +1235,13 @@ export async function runApp(cliArgs, config, startupOptions = {}) {
         if (!state.config.favorites.includes(favKey)) return
       }
 
+      // 📖 Per-provider circuit-breaker (issue #146): if the provider's quota is
+      // 📖 paused (e.g. openrouter returned 429 "try again 50680s later"), skip
+      // 📖 every model of that provider until the Retry-After window expires.
+      // 📖 Without this, broken/overloaded models are re-pinged every cycle,
+      // 📖 burning the user's daily quota in minutes.
+      if (isProviderQuotaPaused(r.providerKey)) return
+
       // 📖 Probe-cache (t1): skip models that are still fresh + ok in the cache.
       // 📖 Broken models always pass through isCacheFresh() (it returns false for them),
       // 📖 which gives us automatic recovery detection for free.
@@ -1241,6 +1254,11 @@ export async function runApp(cliArgs, config, startupOptions = {}) {
       })
     })
 
+    // 📖 Take a snapshot of currently paused providers so the TUI footer can
+    // 📖 surface a "⏸ openrouter (14h)" chip while we wait out a Retry-After.
+    // 📖 Updates every cycle so the remaining-time ticks down live.
+    state.pausedProviders = listPausedProviders()
+
     refreshAutoPingMode()
     scheduleNextPing()
     } catch (err) {

package/src/tui/render-table.js

@@ -216,6 +216,7 @@ export function renderTable({
   probeCacheMisses = 0,
   probeCacheBrokenHidden = 0,
   showBrokenMode = false,
+  pausedProviders = {},          // 📖 issue #146: { openrouter: 50680000 } while a provider is paused
   enrichmentBenchCount = 0,
   enrichmentBenchLastUpdated = null,
   metaSourceCounts = null,
@@ -1235,6 +1236,36 @@ export function renderTable({
     probeCacheLabel = chalk.bgRgb(40, 90, 140).rgb(220, 235, 255).bold(` ${cachedTxt}${brokenTxt} `)
   }
 
+  // 📖 Provider circuit-breaker chip (issue #146): surfaces any provider that the
+  // 📖 health-ping loop has paused because it returned a 429 quota response.
+  // 📖 Format: `⏸ openrouter 14h · ⏸ mistral 5m`. The live duration auto-rolls
+  // 📖 to s/m/h/d so users see a real countdown and don't get surprised later
+  // 📖 when their requests stop working ("wait, why is everything 429-ing?").
+  let pausedProvidersLabel = ''
+  if (pausedProviders && typeof pausedProviders === 'object') {
+    const fmtRemaining = (ms) => {
+      if (!Number.isFinite(ms) || ms <= 0) return '0s'
+      const totalSec = Math.round(ms / 1000)
+      const day = Math.floor(totalSec / 86400)
+      const hr = Math.floor((totalSec % 86400) / 3600)
+      const min = Math.floor((totalSec % 3600) / 60)
+      const sec = totalSec % 60
+      if (day > 0) return `${day}d${hr}h`
+      if (hr > 0) return `${hr}h${min}m`
+      if (min > 0) return `${min}m${sec}s`
+      return `${sec}s`
+    }
+    const entries = Object.entries(pausedProviders)
+      .filter(([, ms]) => Number.isFinite(ms) && ms > 0)
+      .sort(([a], [b]) => a.localeCompare(b))
+    if (entries.length > 0) {
+      const txt = entries.map(([k, ms]) => `⏸ ${k} ${fmtRemaining(ms)}`).join(' \u00b7 ')
+      // 📖 Warm amber background — distinct from the blue probe-cache chip so the
+      // 📖 user can spot it at a glance and understand "these providers are resting".
+      pausedProvidersLabel = chalk.bgRgb(140, 80, 30).rgb(255, 230, 200).bold(` ${txt} `)
+    }
+  }
+
   // 📖 Enrichment chips (t4 + t5):
   // 📖 `📊 bench N (date) · 📡 live K / 📦 cached M`
   // 📖 Always shown when any enrichment state exists.
@@ -1277,8 +1308,8 @@ export function renderTable({
     }
   }
 
-  // 📖 Line 3: Speed Test + Global Benchmark + Probe + Probe-cache + Enrichment + Quota + Last release
-  if (releaseLabel || speedTestLabel || globalBenchmarkLabel || probeLabel || probeCacheLabel || enrichmentLabel || quotaLabel) {
+  // 📖 Line 3: Speed Test + Global Benchmark + Probe + Probe-cache + Paused-providers + Enrichment + Quota + Last release
+  if (releaseLabel || speedTestLabel || globalBenchmarkLabel || probeLabel || probeCacheLabel || pausedProvidersLabel || enrichmentLabel || quotaLabel) {
     const parts = [
       { text: '  ', key: null },
       { text: speedTestLabel, key: 'a' },
@@ -1288,6 +1319,8 @@ export function renderTable({
       { text: probeLabel, key: null },
       { text: probeCacheLabel ? '  ' : '', key: null },
       { text: probeCacheLabel, key: null },
+      { text: pausedProvidersLabel ? '  ' : '', key: null },
+      { text: pausedProvidersLabel, key: null },
       { text: enrichmentLabel ? '  ' : '', key: null },
       { text: enrichmentLabel, key: null },
       { text: quotaLabel ? '  ' : '', key: null },

package/src/tui/tui-state.js

@@ -297,6 +297,13 @@ export function createTuiState({
     probeCacheTtlMs: null,        // 📖 Set in app.js from cliArgs.probeTtlMs || DEFAULT
     showBrokenMode: false,
 
+    // 📖 Per-provider quota circuit-breaker (issue #146): snapshot of providers
+    // 📖 currently paused because they returned 429 during a health-probe.
+    // 📖 Format: { [providerKey]: remainingMs } — refreshed each ping cycle
+    // 📖 so the TUI footer can show a live "⏸ openrouter (14h)" chip.
+    // 📖 Empty when no provider is in pause.
+    pausedProviders: {},
+
     // 📖 Runtime telemetry overlay state (t3): Shift+W opens the Runtime Report
     // 📖 overlay. Data is loaded fresh from ~/.free-coding-models/runtime-telemetry.json
     // 📖 when the overlay opens — no polling, no daemon dependency.