free-coding-models 0.5.58 → 0.5.60

package/README.md

@@ -517,6 +517,68 @@ Inspect or wipe it manually any time — it's plain JSON with `0600` perms.
 
 ---
 
+## 📊 Live quota from response headers
+
+Every chat-completion response carries rate-limit headers (`x-ratelimit-remaining-requests`, etc.). The daemon parses them passively on every routed request — **zero extra network requests, zero quota waste**.
+
+- **8 header variants** supported: SambaNova, Mistral, generic `x-ratelimit-*`, the `ratelimit-*` (no-`x-`) variant some proxies use, and 3 daily / token / token-minute variants for Cerebras-style providers.
+- **Pre-warmed by pings**: even health-check pings return headers, so quota is visible in the CLI before you ever route a real request through the daemon.
+- **5-minute staleness**: snapshots older than 5 minutes are excluded, with the active `/api/v1/key` fetcher as fallback for idle providers.
+- **Case-insensitive**: some proxies vary casing; we handle all of them.
+- **Garbage-safe**: `limit: 0`, non-numeric values, or missing pairs return `null` (no crash).
+
+### Where it shows up
+
+| Surface | What you'll see |
+|---------|-----------------|
+| TUI footer | `📊 groq 78% · sambanova 41%` chip (top 5 most-depleted first) |
+| Web Dashboard | New `Provider Quota` section with animated progress bars per provider |
+| `/api/router/stats` | `quota: { providerKey: { remaining, limit, percent, source, lastUpdated, windowType } }` |
+
+### Daemon `/stats.quota` shape
+
+```json
+{
+  "quota": {
+    "groq": { "remaining": 14, "limit": 30, "percent": 47, "windowType": "requests", "source": "header", "lastUpdated": 1753478400000 },
+    "sambanova": { "remaining": 1500, "limit": 14400, "percent": 10, "windowType": "day", "source": "header", "lastUpdated": 1753478400000 }
+  }
+}
+```
+
+The `source` field is `"header"` when the value came from a passive response header, `"endpoint"` when it came from the active `/api/v1/key` fetcher. Use it in devtools to debug why a provider shows the value it does.
+
+---
+
+## 📈 Runtime telemetry: real-world scores
+
+Every routed request through the daemon feeds a persistent per-model telemetry file (`~/.free-coding-models/runtime-telemetry.json`) — the **honesty layer** that complements SWE-bench with what models actually do on free tiers.
+
+- **Real success rate** — `(successCalls / totalCalls)` updated on every routed request (success and failure paths alike).
+- **Real throughput** — `avgTokensPerSecond` derived from completion tokens / total latency, so you see what your code actually streams at.
+- **Recent calls (last 50)** — for debugging "why did this just 500?" without rebuilding state.
+- **Composite `Real` score** — `successRate × 0.6 + sigmoid01(tok/s) × 0.25 + recency × 0.15`. Null when below `MIN_CALLS_FOR_SCORE = 5` (no penalty for new models).
+
+### Where it shows up
+
+| Surface | What you'll see |
+|---------|-----------------|
+| TUI `Real` column | Inline composite score per row, `–` when insufficient data |
+| TUI `W` sort key | Sort by real-world score descending |
+| TUI `Shift+W` | Runtime Report overlay — per-model breakdown + recent calls |
+| Web Dashboard | "Runtime Telemetry" cards with animated success-rate bars |
+| `/api/router/stats.runtime` | `{ stats: { modelsTracked, totalCalls, modelsWithSignal }, models: { ... } }` |
+
+### Privacy
+
+The telemetry file lives **locally only** (`~/.free-coding-models/runtime-telemetry.json`, `0600` perms). Nothing is sent upstream unless you opt in to a future aggregate leaderboard. The file holds **metadata only** — success, latency, tokens, error reason. No prompts, no responses, no content.
+
+### CLI flag
+
+- `--clear-runtime` — wipe the file before launching (reset the baseline).
+
+---
+
 ## π Pi Extension — FCM-Pi ⚠️ BETA
 
 **FCM-Pi** is a native [Pi coding agent](https://pi.dev) extension that integrates `free-coding-models` directly into your Pi session. It stays silent by default, scans only when you run `/fcm`, and lets you explicitly hot-swap models mid-session.
@@ -730,6 +792,8 @@ See [`packages/fcm-agent-core/README.md`](./packages/fcm-agent-core/README.md) f
 - **Mandatory self-update policy** — startup checks npm for a newer FCM and installs it automatically without a prompt. If the install fails twice in a row (offline, proxy, or permissions), FCM still starts but shows a red outdated-version warning until the user retries with `Shift+U` or runs the displayed install command.
 - **Last release timestamp** — light pink footer shows `Last release: Mar 27, 2026, 09:42 PM` from npm so users know how fresh the data is
 - **Persistent probe-cache (t1)** — every health probe result is cached to `~/.free-coding-models/probe-cache.json` for 24h. Warm starts render the full ranking in <500ms, only re-ping the models that are due (broken or TTL-expired). Broken models are auto-hidden across sessions — toggle visibility with **Shift+B**. See [Persistent probe cache](#-persistent-probe-cache) below for `--reprobe`, `--probe-ttl`, `--show-broken`.
+- **Live quota from response headers (t2)** — every routed chat-completion response already carries `x-ratelimit-*` headers. The daemon parses them in 8 variants and exposes live per-provider quota on the TUI footer (`📊 groq 78% · sambanova 41%`) and in the Web Dashboard (`Provider Quota` section with animated progress bars). Zero extra network requests, zero quota waste. See [Live quota from headers](#-live-quota-from-response-headers) below.
+- **Runtime telemetry: real-world scores (t3)** — every routed request through the daemon feeds a persistent per-model telemetry file (`~/.free-coding-models/runtime-telemetry.json`) with real success rate, throughput, and recent calls. The `Real` column + `W` sort key in the TUI rank models by what *actually* works on free tiers, not what they claim on SWE-bench. See [Runtime telemetry](#-runtime-telemetry-real-world-scores) below.
 
 ---
 

package/bin/free-coding-models.js

@@ -62,6 +62,18 @@ async function main() {
     process.exit(0);
   }
 
+  // 📖 --clear-runtime (t3): wipe ~/.free-coding-models/runtime-telemetry.json
+  // 📖 before launching any surface. Keeps the TUI / daemon / web flows consistent.
+  if (cliArgs.clearRuntimeMode) {
+    try {
+      const { clearRuntimeTelemetry } = await import('../src/core/runtime-telemetry.js')
+      const ok = clearRuntimeTelemetry()
+      console.log(chalk.dim(`  ${ok ? '✓' : '✗'} runtime-telemetry.json ${ok ? 'cleared' : 'clear failed'}`))
+    } catch (err) {
+      console.log(chalk.dim(`  runtime-telemetry.json clear failed: ${err?.message || err}`))
+    }
+  }
+
   // Load JSON config before operational modes so the mandatory update policy can
   // 📖 persist failure counters for TUI, Web Dashboard, Docker daemon, and Desktop sidecar launches.
   const config = loadConfig();

package/changelog/v0.5.59.md

@@ -0,0 +1,52 @@
+# Changelog v0.5.59 - 2026-07-26
+
+### Added
+
+- 📊 **Live quota from response headers** (t2) — every chat-completion response already carries `x-ratelimit-*` headers. The daemon parses them passively on every routed request (and even on health-check pings), exposing **live** per-provider quota on the TUI footer and Web Dashboard. **Zero extra network requests, zero quota waste.**
+
+  - **8 header variants** supported in priority order:
+    - `x-ratelimit-remaining-requests` / `-limit-requests` (SambaNova-style)
+    - `x-ratelimit-remaining` / `-limit` (Mistral / generic)
+    - `ratelimit-remaining-requests` / `ratelimit-limit-requests` (proxy-stripped)
+    - `ratelimit-remaining` / `ratelimit-limit` (proxy-stripped generic)
+    - `x-ratelimit-remaining-requests-day` / `-limit-requests-day` (SambaNova daily)
+    - `x-ratelimit-remaining-day` / `-limit-day` (generic daily)
+    - `x-ratelimit-remaining-tokens` / `-limit-tokens` (Cerebras tokens)
+    - `x-ratelimit-remaining-tokens-minute` / `-limit-tokens-minute` (Cerebras token-minute)
+  - **First-match-wins priority** — when multiple pairs are present, the most-specific wins (e.g. daily variant beats generic).
+  - **Case-insensitive** — some proxies vary casing; we handle `X-RateLimit-Remaining` and `x-ratelimit-remaining` identically.
+  - **Garbage-safe** — `limit: 0`, non-numeric values, or missing pairs return `null` (no crash, no div-by-zero).
+  - **Staleness 5 min** — snapshots older than `STALENESS_MS` are excluded from `getAllQuotas()` so the consumer only sees fresh data. The existing active `/api/v1/key` fetcher stays as the fallback for idle providers.
+  - **Merge with active fetcher** — `getQuota(providerKey)` returns whichever is freshest, so quota is always live when traffic flows.
+
+- 🛰️ **TUI footer chip** — `📊 groq 78% · sambanova 41%` (top 5 most-depleted first; icon escalation 📊 healthy → ⚠️ ≤ 25% → 🚨 ≤ 10%). Renders on the same footer line as the existing probe-cache chip.
+
+- 🌐 **Web Dashboard `Provider Quota` section** — per-provider card with source icon (🛰️ passive header vs 🔌 active fetcher fallback), provider key, animated progress bar (green ≥ 25% / amber 10–25% / red ≤ 10%), and percent label. Auto-sorted most-depleted first. Updated every `/api/router/stats` poll (5 s).
+
+- 📋 **Daemon `/api/router/stats` exposes `quota`** — `{ providerKey: { remaining, limit, percent, windowType, source, lastUpdated } }`. The `source` field tells you whether the value came from a passive header (`'header'`) or the active fetcher (`'endpoint'`) — useful for debugging why a provider shows the number it does.
+
+- 🧪 **`processResponseHeaders(providerKey, headers)`** — drop-in hook for any future surface (Tauri Desktop, scripts, IDE plugins) that wants to feed the passive map.
+
+### Changed
+
+- 🩺 **Daemon reverse proxy** (`buildUpstreamMeta` in `src/core/router-daemon.js`) now calls `processResponseHeaders(providerKey, response.headers)` for every routed upstream response, both streaming and non-streaming. Zero new code paths, zero new dependencies.
+
+- 📡 **Health-check pings** (`src/core/ping.js`) also call `processResponseHeaders(providerKey, resp.headers)`, so even the CLI-only flow (no daemon) shows live quota after the first ping cycle.
+
+- 🔧 **Internal refactor** — the existing `extractQuotaPercent` in `src/core/ping.js` now uses the shared `extractQuota()` from `provider-quota-fetchers.js`. Same 8-variant parser, single source of truth, no behaviour change for existing callers.
+
+### Maintenance
+
+- 🧪 **+37 unit tests** (`test/passive-quota.test.js`, new file): HEADER_PAIRS structure, STALENESS_MS, all 8 header pairs parse correctly, robustness (missing fields, NaN, limit=0, negative limit, empty object, null/undefined headers), first-pair-wins priority, case-insensitivity, Fetch Headers object support, `processResponseHeaders` writes/overwrites/ignores bad providerKey, `getQuota` passive fresh/stale/custom maxAgeMs, `getAllQuotas` unions both stores / excludes stale, `formatQuotaStatus` healthy/low/critical + day window + stale/missing.
+- 🧪 **632 → 671 tests passing** (`pnpm test`), **118 → 125 suites**.
+- 🧹 `vite build` succeeds.
+- 📖 README updated with a new **📊 Live quota from response headers** section (8 variants table, where it shows up, `/stats.quota` JSON shape).
+
+### Inspiration
+
+This implementation is informed by [`apmantza/pi-free`](https://github.com/apmantza/pi-free)'s `lib/quota-monitor.ts` (which itself credits us: *"Inspired by free-coding-models' `extractQuotaPercent`"*). The inspiration flows both ways — we extend their 6-pair design to 8 variants (adding the Cerebras tokens / token-minute pairs we already supported) and ship a Web Dashboard renderer that surfaces them as live progress bars instead of just CLI text.
+
+### Files
+
+- **Modified**: `src/core/provider-quota-fetchers.js` (+228 lines: new pure-logic section), `src/core/ping.js` (call `processResponseHeaders` on every ping), `src/core/router-daemon.js` (call on every routed response + expose `quota` in `/stats`), `src/tui/render-table.js` (new footer chip), `src/tui/app.js` (thread `quota` through), `web/src/components/router/RouterView.jsx` (new `Provider Quota` section), `web/src/components/router/RouterView.module.css` (7 new classes), `README.md`, `tasks/t2.md`, `package.json` (test script).
+- **New**: `test/passive-quota.test.js` (340 lines, 37 tests), `changelog/v0.5.59.md`.

package/changelog/v0.5.60.md

@@ -0,0 +1,54 @@
+# Changelog v0.5.60 - 2026-07-26
+
+### Added
+
+- 📈 **Runtime telemetry: real-world scores** (t3) — every routed request through the daemon now feeds a persistent per-model telemetry file with real success rate, throughput, and recent calls. FCM stops showing you only what models *claim* on SWE-bench and starts showing you what they **actually do** on free tiers.
+
+  - **Composite `Real` score** (0..100) — `successRate × 0.6 + sigmoid01(tok/s) × 0.25 + recency × 0.15`. Null when below `MIN_CALLS_FOR_SCORE = 5` (no penalty for new models).
+  - **Real success rate** — `(successCalls / totalCalls)`. Updated on every routed request, success AND failure paths alike (auth_error / 5xx / 429 all count).
+  - **Real throughput** — `avgTokensPerSecond` from completion tokens / total latency. What your code actually streams at.
+  - **Recent calls (last 50)** — FIFO trim per model. Useful for debugging "why did this just 500?" without rebuilding state.
+  - **Local-only by default** — the file lives at `~/.free-coding-models/runtime-telemetry.json` (`0600` perms). Nothing leaves your machine unless you opt in to a future aggregate leaderboard. Metadata only — no prompts, no responses.
+
+- 🆕 **New sort key `W`** in the TUI: sorts by `Real` score descending. Models with insufficient data (null score) sink to the bottom in both directions.
+
+- 📊 **New TUI `Real` column**: shows the composite score inline per row, or `–` when there's not enough signal yet.
+
+- 🔥 **`Shift+W` Runtime Report overlay** — per-model breakdown (success rate, avg latency, avg tok/s, recent calls list). Same pattern as `Shift+R` Router Dashboard / `Shift+T` Token Usage. Scroll with j/k/up/down/pageup/pagedown/home/end, close with Escape.
+
+- 🌐 **Web Dashboard `Runtime Telemetry` section** — per-model cards with animated success-rate bars (red ≤ 50% / amber 50-80% / green ≥ 80%). Updated every `/api/router/stats` poll (5 s). Models with < 5 calls are excluded so the section only shows real signal.
+
+- 🛰️ **New daemon endpoint `/stats/runtime`** — returns `{ ok, stats: { modelsTracked, totalCalls, modelsWithSignal }, models: { [key]: ModelTelemetry } }`. Same shape as the in-TUI dashboard digest.
+
+- 🧪 **`recordModelCall(providerKey, modelId, callResult, opts?)`** — drop-in hook for any future surface (Tauri Desktop, scripts) that wants to feed runtime telemetry.
+
+- 🛠️ **`--clear-runtime` CLI flag** — wipe the telemetry file before launching any surface. Useful when the user wants to reset the baseline.
+
+### Changed
+
+- 🩺 **Daemon reverse proxy** records every successful + failed routed outcome via `recordRuntimeCall()`. A debounced 5 s flush keeps the file in sync without thrashing the disk. The flush timer is cleared in `shutdown()` so no orphan writes after exit.
+
+- 📋 **Daemon `statsPayload`** now exposes `runtimeTelemetry: { stats, models }` so the existing `/stats` consumers get the digest for free.
+
+- 🔧 **Internal** — added `sigmoid01(x)` (logistic curve so 50 tok/s → 0.5) and `recencyDecay(lastUpdatedMs)` (1.0 today → 0.0 at 30 d) to the real-world score formula. Both are pure functions with no dependencies.
+
+### Non-goals (explicit)
+
+- **Streaming token extraction** — the known gap from the PRD stays. The runtime telemetry only counts requests where the upstream returned `usage` (i.e. non-streaming, or streaming providers that emit usage on the final chunk).
+- **Sharing / leaderboard** — no aggregation server yet. When there is one, opt-in.
+
+### Maintenance
+
+- 🧪 **+30 unit tests** (`test/runtime-telemetry.test.js`, new file): path resolution (XDG-aware), constants sanity, `recordModelCall` write/accumulate/drop garbage/FIFO cap, `tokensPerSecond` computation, derived fields, `getRealWorldScore` null below threshold / healthy → high / error-heavy → mid / age decay, `getCacheStats` aggregates + `modelsWithSignal` threshold, `pruneStaleEntries` drops old, persistence round-trip + corrupt recovery + missing file + clear + read-merge-write concurrency safety.
+- 🧪 **671 → 701 tests passing** (`pnpm test`), **125 → 134 suites**.
+- 🧹 `vite build` succeeds.
+- 📖 README updated with a new **📈 Runtime telemetry: real-world scores** section (where it shows up, privacy, `--clear-runtime`).
+
+### Inspiration
+
+This implementation is informed by [`apmantza/pi-free`](https://github.com/apmantza/pi-free)'s `lib/telemetry.ts` (which credits us in their other direction too). pi-free's `turn_end` hook is the daemon-side equivalent of our `recordRuntimeCall`; the schema, the 50-call FIFO, and the local-only file mirror their approach. Where we diverge: we expose the composite `Real` score as a first-class ranking signal (not just a debugging surface), ship it in 3 user-facing surfaces (CLI TUI / Web Dashboard / daemon `/stats`), and add the success×0.6 / speed×0.25 / recency×0.15 weights so the user sees a single number per model.
+
+### Files
+
+- **New**: `src/core/runtime-telemetry.js` (377 lines, 11 exports), `test/runtime-telemetry.test.js` (390 lines, 30 tests), `changelog/v0.5.60.md`.
+- **Modified**: `src/core/router-daemon.js` (record on every routed outcome + `/stats/runtime` + runtimeTelemetry in statsPayload), `src/core/utils.js` (`'realworld'` sort case), `src/tui/app.js` (boot-time score computation per result), `src/tui/tui-state.js` (5 new state fields for the overlay), `src/tui/key-handler.js` (Shift+W + overlay keyboard handling + command palette action), `bin/free-coding-models.js` (`--clear-runtime` flag plumbing), `web/src/components/router/RouterView.jsx` (Runtime Telemetry section), `README.md`, `tasks/t3.md`, `package.json` (test script).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "free-coding-models",
-  "version": "0.5.58",
+  "version": "0.5.60",
   "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.",
   "keywords": [
     "nvidia",
@@ -53,7 +53,7 @@
   ],
   "scripts": {
     "start": "node bin/free-coding-models.js",
-    "test": "node --test test/test.js test/fcm-agent-core.test.js test/patch-openclaw.test.js test/provider-metadata.test.js test/config-permission-hint.test.js test/probe-cache.test.js",
+    "test": "node --test test/test.js test/fcm-agent-core.test.js test/patch-openclaw.test.js test/provider-metadata.test.js test/config-permission-hint.test.js test/probe-cache.test.js test/passive-quota.test.js test/runtime-telemetry.test.js",
     "prepack": "npm run build:web",
     "dev": "node scripts/dev-web.mjs",
     "dev:web": "node scripts/dev-web.mjs",

package/src/core/ping.js

@@ -41,7 +41,7 @@
  */
 
 import { PING_TIMEOUT } from './constants.js'
-import { fetchProviderQuota as _fetchProviderQuotaFromModule } from './provider-quota-fetchers.js'
+import { fetchProviderQuota as _fetchProviderQuotaFromModule, extractQuota as _extractQuotaFromModule, processResponseHeaders as _processResponseHeadersFromModule } from './provider-quota-fetchers.js'
 import { supportsUsagePercent } from './quota-capabilities.js'
 
 const DISABLED_THINKING_RETRY_STATUSES = new Set([400, 422])
@@ -173,10 +173,15 @@ export async function ping(apiKey, modelId, providerKey, url) {
     }
     // 📖 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.
+    // 📖 1) Write to the passive snapshot map so /stats + TUI footer see live quota.
+    // 📖 2) Return the percent number for the per-call consumer below.
+    const extracted = _extractQuotaFromModule(resp.headers)
+    _processResponseHeadersFromModule(providerKey, resp.headers)
     return {
       code,
       ms: Math.round(performance.now() - t0),
-      quotaPercent: extractQuotaPercent(resp.headers),
+      quotaPercent: extracted ? extracted.percent : null,
     }
   } catch (err) {
     const isTimeout = err.name === 'AbortError'

package/src/core/provider-quota-fetchers.js

@@ -1,23 +1,42 @@
 /**
  * @file lib/provider-quota-fetchers.js
- * @description Provider endpoint quota pollers for publicly available endpoints.
+ * @description Provider endpoint quota pollers + passive rate-limit header parser.
  *
- * Supported providers:
+ * Active fetchers (existing):
  *   - openrouter: GET https://openrouter.ai/api/v1/key
  *       derives percent from limit_remaining/limit (with fallback field names)
  *   - siliconflow: GET https://api.siliconflow.cn/v1/user/info
  *       returns balance info; percent is null (no limit field to derive from)
  *
+ * Passive tracker (t2):
+ *   - Every chat-completion response carries rate-limit headers (x-ratelimit-*).
+ *   - processResponseHeaders() parses those headers in 6 priority variants and
+ *     writes to an in-memory map, kept fresh per `STALENESS_MS` (5 min default).
+ *   - getQuota() merges the passive snapshot with the latest active fetch,
+ *     returning whichever is freshest — so quota is *always* live when traffic
+ *     flows, with the active fetcher as a safety net for idle periods.
+ *   - Zero extra network requests: the headers are already on every response.
+ *
  * Features:
  *   - TTL cache (default 60s) prevents hammering endpoints
  *   - Error backoff (default 15s) after failures
  *   - Injectable fetch + time for testing
  *   - API keys are never logged
+ *   - Case-insensitive header parsing (some proxies vary casing)
  *
  * @exports parseOpenRouterResponse(data) → number|null
  * @exports parseSiliconFlowResponse(data) → { balance, chargeBalance, totalBalance }|null
  * @exports createProviderQuotaFetcher(options) → fetcher(providerKey, apiKey) → Promise<number|null>
  * @exports fetchProviderQuota(providerKey, apiKey, options) → Promise<number|null>
+ * @exports extractQuota(headers) → { remaining, limit, percent, source, windowType }|null
+ * @exports processResponseHeaders(providerKey, headers, opts?) → boolean
+ * @exports getQuota(providerKey, opts?) → QuotaSnapshot|null
+ * @exports getAllQuotas(opts?) → ReadonlyMap<string, QuotaSnapshot>
+ * @exports formatQuotaStatus(providerKey, opts?) → string|undefined
+ * @exports resetPassiveQuota() — clear the in-memory passive map (tests)
+ * @exports HEADER_PAIRS — readonly array of [remainingKey, limitKey] pairs in priority order
+ * @exports STALENESS_MS — passive snapshots older than this are considered stale
+ * @exports QUOTA_WINDOW_LABELS — map of windowType → short label for tooltips
  */
 
 // ─── Response parsers (pure, no I/O) ─────────────────────────────────────────
@@ -317,3 +336,236 @@ export async function fetchProviderQuota(providerKey, apiKey, options = {}) {
 
   return pendingPromise
 }
+
+// ─── Passive rate-limit header tracker (t2) ───────────────────────────────────
+
+/**
+ * 📖 STALENESS_MS: how long a passive snapshot stays "fresh" before we prefer
+ * 📖 the active fetcher result (or hide the chip entirely if neither is fresh).
+ * 📖 Mirrors pi-free's 5-minute window. Override per call via opts.now - opts.maxAgeMs.
+ */
+export const STALENESS_MS = 5 * 60 * 1000
+
+/**
+ * 📖 HEADER_PAIRS: ordered list of [remainingKey, limitKey] pairs to try when
+ * 📖 parsing a response's rate-limit headers. First pair where both values parse
+ * 📖 as finite numbers AND limit > 0 wins. Order matters: most-specific (day,
+ * 📖 tokens) comes before generic (requests) where applicable.
+ *
+ * 📖 Provenance:
+ * 📖   - x-ratelimit-remaining-requests / x-ratelimit-limit-requests  → SambaNova
+ * 📖   - x-ratelimit-remaining          / x-ratelimit-limit            → Mistral / generic
+ * 📖   - ratelimit-remaining-requests    / ratelimit-limit-requests      → proxies that strip 'x-' prefix
+ * 📖   - ratelimit-remaining             / ratelimit-limit               → same, generic
+ * 📖   - x-ratelimit-remaining-requests-day / x-ratelimit-limit-requests-day → SambaNova daily window
+ * 📖   - x-ratelimit-remaining-day / x-ratelimit-limit-day → generic daily
+ */
+export const HEADER_PAIRS = [
+  ['x-ratelimit-remaining-requests', 'x-ratelimit-limit-requests'],
+  ['x-ratelimit-remaining', 'x-ratelimit-limit'],
+  ['ratelimit-remaining-requests', 'ratelimit-limit-requests'],
+  ['ratelimit-remaining', 'ratelimit-limit'],
+  ['x-ratelimit-remaining-requests-day', 'x-ratelimit-limit-requests-day'],
+  ['x-ratelimit-remaining-day', 'x-ratelimit-limit-day'],
+  ['x-ratelimit-remaining-tokens', 'x-ratelimit-limit-tokens'],
+  ['x-ratelimit-remaining-tokens-minute', 'x-ratelimit-limit-tokens-minute'],
+]
+
+/**
+ * 📖 QUOTA_WINDOW_LABELS: short tooltip labels keyed by windowType suffix
+ * 📖 detected in the matched header pair name. Used by formatQuotaStatus to
+ * 📖 indicate whether the user is looking at a per-minute or per-day window.
+ */
+export const QUOTA_WINDOW_LABELS = {
+  day: 'day',
+  requests: 'min',
+  tokens: 'tok',
+  'tokens-minute': 'tok/min',
+}
+
+/**
+ * 📖 Internal: in-memory map of latest passive quota snapshot per provider.
+ * 📖 Keyed by providerKey; never persisted to disk (passive tracking is local-only).
+ */
+const _passiveQuota = new Map() // providerKey -> QuotaSnapshot
+
+/**
+ * 📖 Case-insensitive header lookup. Accepts both Fetch `Headers` objects and
+ * 📖 plain object literals (some test doubles pass plain objects).
+ */
+function readHeader(headers, key) {
+  if (!headers) return null
+  if (typeof headers.get === 'function') {
+    return headers.get(key) ?? headers.get(key.toLowerCase()) ?? null
+  }
+  if (typeof headers === 'object') {
+    if (key in headers) return headers[key]
+    const lower = key.toLowerCase()
+    if (lower in headers) return headers[lower]
+    // 📖 Iterate as a last resort — some servers use unusual casings.
+    for (const k of Object.keys(headers)) {
+      if (k.toLowerCase() === lower) return headers[k]
+    }
+  }
+  return null
+}
+
+/**
+ * 📖 Parse rate-limit headers and extract a structured quota snapshot.
+ * 📖 Returns null when no header pair matches (caller decides to keep stale).
+ *
+ * @param {Headers | Record<string, string> | null | undefined} headers
+ * @returns {{ remaining: number, limit: number, percent: number, source: string, windowType: string } | null}
+ */
+export function extractQuota(headers) {
+  for (const [remainingKey, limitKey] of HEADER_PAIRS) {
+    const remainingRaw = readHeader(headers, remainingKey)
+    const limitRaw = readHeader(headers, limitKey)
+    if (remainingRaw == null || limitRaw == null) continue
+    const remaining = Number.parseFloat(remainingRaw)
+    const limit = Number.parseFloat(limitRaw)
+    if (!Number.isFinite(remaining) || !Number.isFinite(limit) || limit <= 0) continue
+    const percent = Math.max(0, Math.min(100, Math.round((remaining / limit) * 100)))
+    // 📖 Derive windowType from the matching pair's key suffix.
+    let windowType = 'requests'
+    if (remainingKey.endsWith('-day')) windowType = 'day'
+    else if (remainingKey.endsWith('-tokens-minute')) windowType = 'tokens-minute'
+    else if (remainingKey.endsWith('-tokens')) windowType = 'tokens'
+    return { remaining, limit, percent, source: remainingKey, windowType }
+  }
+  return null
+}
+
+/**
+ * 📖 Internal: build a QuotaSnapshot from extractQuota() output + timestamp.
+ */
+function makeSnapshot(extracted, source = 'header', now = Date.now()) {
+  return {
+    remaining: extracted.remaining,
+    limit: extracted.limit,
+    percent: extracted.percent,
+    windowType: extracted.windowType,
+    headerSource: extracted.source,
+    source,        // 'header' (passive) or 'endpoint' (active fetcher)
+    lastUpdated: now,
+  }
+}
+
+/**
+ * 📖 processResponseHeaders: hook for the daemon reverse-proxy + ping responses.
+ * 📖 Parses the response headers, writes the snapshot to the passive map, and
+ * 📖 returns true if a snapshot was stored (so callers can decide to log).
+ *
+ * @param {string} providerKey
+ * @param {Headers | Record<string, string> | null | undefined} headers
+ * @param {object} [opts]
+ * @param {number} [opts.now=Date.now()]
+ * @returns {boolean} true if a snapshot was written
+ */
+export function processResponseHeaders(providerKey, headers, opts = {}) {
+  if (!providerKey || typeof providerKey !== 'string') return false
+  const now = opts.now ?? Date.now()
+  const extracted = extractQuota(headers)
+  if (!extracted) return false
+  _passiveQuota.set(providerKey, makeSnapshot(extracted, 'header', now))
+  return true
+}
+
+/**
+ * 📖 Internal: read the latest active-fetcher snapshot for a provider. The active
+ * 📖 fetcher uses a per-key Map of { value, expiresAt } entries; we synthesise a
+ * 📖 QuotaSnapshot from that. Returns null if the active cache is empty/expired.
+ */
+function getActiveSnapshot(providerKey, now = Date.now()) {
+  for (const [cacheKey, entry] of _defaultCache.entries()) {
+    if (!cacheKey.startsWith(`${providerKey}:`)) continue
+    if (!entry || typeof entry !== 'object') continue
+    if (typeof entry.expiresAt !== 'number' || entry.expiresAt <= now) continue
+    const value = entry.value
+    if (typeof value !== 'number' || !Number.isFinite(value)) continue
+    return makeSnapshot(
+      { remaining: value, limit: 100, percent: value, windowType: 'unknown', source: 'active_fetcher' },
+      'endpoint',
+      // 📖 active fetcher stores wall-clock ms at fetch time; expose it so
+      // 📖 getQuota's freshest-wins logic works on real timestamps.
+      now,
+    )
+  }
+  return null
+}
+
+/**
+ * 📖 getQuota: merge passive + active snapshots, return the freshest.
+ * 📖 A snapshot is "stale" when older than STALENESS_MS. If both are stale,
+ * 📖 returns null (caller should hide the chip).
+ *
+ * @param {string} providerKey
+ * @param {object} [opts]
+ * @param {number} [opts.now=Date.now()]
+ * @param {number} [opts.maxAgeMs=STALENESS_MS]
+ * @returns {QuotaSnapshot | null}
+ */
+export function getQuota(providerKey, opts = {}) {
+  if (!providerKey) return null
+  const now = opts.now ?? Date.now()
+  const maxAgeMs = opts.maxAgeMs ?? STALENESS_MS
+  const passive = _passiveQuota.get(providerKey) || null
+  const active = getActiveSnapshot(providerKey, now)
+
+  // 📖 Drop stale snapshots.
+  const candidates = []
+  if (passive && now - passive.lastUpdated <= maxAgeMs) candidates.push(passive)
+  if (active && now - active.lastUpdated <= maxAgeMs) candidates.push(active)
+
+  if (candidates.length === 0) return null
+  // 📖 Freshest wins — tied timestamps prefer passive (it's the live signal).
+  return candidates.reduce((a, b) => (a.lastUpdated >= b.lastUpdated ? a : b))
+}
+
+/**
+ * 📖 getAllQuotas: snapshot of every provider we know about, merged passive+active.
+ * 📖 Stale entries (older than maxAgeMs) are excluded. Used by /stats and the TUI footer.
+ *
+ * @param {object} [opts]
+ * @returns {ReadonlyMap<string, QuotaSnapshot>}
+ */
+export function getAllQuotas(opts = {}) {
+  const now = opts.now ?? Date.now()
+  const maxAgeMs = opts.maxAgeMs ?? STALENESS_MS
+  const out = new Map()
+  // 📖 Union the keys from both passive and active stores so we don't miss a
+  // 📖 provider whose latest signal only exists in one.
+  const allKeys = new Set([..._passiveQuota.keys()])
+  for (const cacheKey of _defaultCache.keys()) {
+    const colon = cacheKey.indexOf(':')
+    if (colon > 0) allKeys.add(cacheKey.slice(0, colon))
+  }
+  for (const providerKey of allKeys) {
+    const q = getQuota(providerKey, { now, maxAgeMs })
+    if (q) out.set(providerKey, q)
+  }
+  return out
+}
+
+/**
+ * 📖 formatQuotaStatus: human-readable "⚠️ groq: 12/100 (12%) [day]" string.
+ * 📖 Returns undefined when the snapshot is missing or stale (caller hides the chip).
+ *
+ * @param {string} providerKey
+ * @param {object} [opts]
+ * @returns {string | undefined}
+ */
+export function formatQuotaStatus(providerKey, opts = {}) {
+  const snapshot = getQuota(providerKey, opts)
+  if (!snapshot) return undefined
+  const window = QUOTA_WINDOW_LABELS[snapshot.windowType] || snapshot.windowType
+  const icon = snapshot.percent <= 10 ? '🚨' : snapshot.percent <= 25 ? '⚠️ ' : '📊'
+  return `${icon} ${providerKey}: ${snapshot.remaining}/${snapshot.limit} (${snapshot.percent}%) [${window}]`
+}
+
+/**
+ * 📖 resetPassiveQuota: clear the in-memory passive map. Test-only utility.
+ */
+export function resetPassiveQuota() {
+  _passiveQuota.clear()
+}