free-coding-models 0.5.58 → 0.5.59

package/README.md

@@ -517,6 +517,39 @@ 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.
+
+---
+
 ## π 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 +763,7 @@ 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.
 
 ---
 

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "free-coding-models",
-  "version": "0.5.58",
+  "version": "0.5.59",
   "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",
     "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()
+}

package/src/core/router-daemon.js

@@ -63,6 +63,11 @@ import {
   isCacheFresh as isProbeCacheFresh,
   pruneStaleEntries as pruneProbeCacheStaleEntries,
 } from './probe-cache.js'
+import {
+  processResponseHeaders as processPassiveQuotaHeaders,
+  getAllQuotas as getAllPassiveQuotas,
+  STALENESS_MS as PASSIVE_QUOTA_STALENESS_MS,
+} from './provider-quota-fetchers.js'
 
 export const ROUTER_DEFAULT_PORT = 19280
 export const ROUTER_MAX_PORT = 19289
@@ -475,11 +480,16 @@ function serveWebStaticFile(res, pathname, requestId) {
   serveStaticFromDist(res, candidate)
 }
 
-function buildUpstreamMeta(response, text = '') {
+function buildUpstreamMeta(response, text = '', providerKey = '') {
   // 📖 Keep quota diagnostics structural only: headers and retry timing are safe,
   // 📖 while upstream response bodies stay out of logs and telemetry.
   const rateLimitHeaders = extractRateLimitHeaders(response.headers)
   const retryAfterMs = parseRetryAfterMs(rateLimitHeaders['retry-after'])
+  // 📖 Passive quota tracker (t2): every upstream response carries rate-limit
+  // 📖 headers — we parse them once here and write to the in-memory snapshot
+  // 📖 map. Zero extra network requests; works on providers with no quota
+  // 📖 endpoint. See src/core/provider-quota-fetchers.js for the 8 header pairs.
+  if (providerKey) processPassiveQuotaHeaders(providerKey, response.headers)
   const quotaExhausted = response.status === 429
     || hasZeroRemainingQuota(rateLimitHeaders)
     || /\b(quota|rate[_ -]?limit|too many requests)\b/i.test(text || '')
@@ -1487,6 +1497,12 @@ class RouterRuntime {
       // 📖 Surfaced so the Web Dashboard + CLI can show cache hit rate + how many
       // 📖 broken models are currently hidden. Refreshed every /stats call.
       probeCache: getProbeCacheStats(),
+      // 📖 Passive quota (t2): latest known rate-limit headers per provider, keyed
+      // 📖 by providerKey. Each entry is { remaining, limit, percent, source,
+      // 📖 lastUpdated } — source can be 'header' (live) or 'endpoint' (active
+      // 📖 fetcher fallback). Stale entries (older than PASSIVE_QUOTA_STALENESS_MS)
+      // 📖 are excluded so the consumer only sees fresh data.
+      quota: Object.fromEntries(getAllPassiveQuotas()),
     }
   }
 
@@ -2051,7 +2067,7 @@ class RouterRuntime {
       clearTimeout(timeout)
       const latencyMs = Math.round(performance.now() - started)
       const text = await response.text()
-      const upstreamMeta = buildUpstreamMeta(response, text)
+      const upstreamMeta = buildUpstreamMeta(response, text, candidate.provider)
 
       if (isLikelyHtmlResponse(response.headers, text)) {
         this.markFailure(key, 'upstream_html_maintenance', 503, upstreamMeta)
@@ -2193,7 +2209,7 @@ class RouterRuntime {
       })
       clearTimeout(timeout)
       const latencyMs = Math.round(performance.now() - started)
-      const upstreamMeta = buildUpstreamMeta(response)
+      const upstreamMeta = buildUpstreamMeta(response, '', candidate.provider)
       if (isLikelyHtmlResponse(response.headers)) {
         this.markFailure(key, 'upstream_html_maintenance', 503, upstreamMeta)
         this.recordRouterError('upstream_html_maintenance', requestId, { model: key, status: response.status, stream: true })

package/src/tui/app.js

@@ -99,7 +99,7 @@ import { buildMergedModels } from '../core/model-merger.js'
 import { loadOpenCodeConfig, saveOpenCodeConfig } from '../core/opencode-config.js'
 import { usageForRow as _usageForRow } from '../core/usage-reader.js'
 import { buildProviderModelTokenKey, loadTokenUsageByProviderModel } from '../core/token-usage-reader.js'
-import { parseOpenRouterResponse, fetchProviderQuota as _fetchProviderQuotaFromModule } from '../core/provider-quota-fetchers.js'
+import { parseOpenRouterResponse, fetchProviderQuota as _fetchProviderQuotaFromModule, getAllQuotas as _getAllPassiveQuotasFromModule } from '../core/provider-quota-fetchers.js'
 import { isKnownQuotaTelemetry } from '../core/quota-capabilities.js'
 import { ALT_ENTER, ALT_LEAVE, ALT_HOME, PING_TIMEOUT, PING_INTERVAL, FPS, COL_MODEL, COL_MS, CELL_W, FRAMES, TIER_CYCLE, VERDICT_CYCLE, HEALTH_CYCLE, SETTINGS_OVERLAY_BG, HELP_OVERLAY_BG, RECOMMEND_OVERLAY_BG, OVERLAY_PANEL_WIDTH, TABLE_HEADER_LINES, TABLE_FOOTER_LINES, TABLE_FIXED_LINES, WIDTH_WARNING_MIN_COLS, msCell, spinCell } from '../core/constants.js'
 import { TIER_COLOR } from './tier-colors.js'
@@ -954,6 +954,10 @@ export async function runApp(cliArgs, config, startupOptions = {}) {
       probeCacheMisses: state.probeCacheMisses || 0,
       probeCacheBrokenHidden: state.probeCacheBrokenHidden || 0,
       showBrokenMode: !!state.showBrokenMode,
+      // 📖 Passive quota (t2): live snapshots from response headers, populated
+      // 📖 by pings (every ping pre-warms quota for its provider). See
+      // 📖 src/core/provider-quota-fetchers.js for getAllPassiveQuotas().
+      quota: Object.fromEntries(_getAllPassiveQuotasFromModule()),
     }
     if (state.commandPaletteOpen) {
       if (!state.commandPaletteFrozenTable) {

package/src/tui/render-table.js

@@ -155,6 +155,10 @@ export const PROVIDER_COLOR = new Proxy({}, {
  *   probeCacheMisses?: number,       // t1: number of models that needed a live probe
  *   probeCacheBrokenHidden?: number, // t1: number of broken models auto-hidden this session
  *   showBrokenMode?: boolean,        // t1: true when Shift+B has un-hidden broken models
+ *   quota?: Record<string, {         // t2: live quota from response headers
+ *     remaining: number, limit: number, percent: number,
+ *     source: 'header'|'endpoint', lastUpdated: number, windowType?: string,
+ *   }>,
  * }} opts
  * @returns {string}
  */
@@ -205,6 +209,7 @@ export function renderTable({
   probeCacheMisses = 0,
   probeCacheBrokenHidden = 0,
   showBrokenMode = false,
+  quota = {},
 } = _) {
   // 📖 Filter out hidden models for display
   const visibleResults = results.filter(r => !r.hidden)
@@ -1219,8 +1224,27 @@ export function renderTable({
     probeCacheLabel = chalk.bgRgb(40, 90, 140).rgb(220, 235, 255).bold(` ${cachedTxt}${brokenTxt} `)
   }
 
-  // 📖 Line 3: Speed Test + Global Benchmark + Probe + Probe-cache + Last release
-  if (releaseLabel || speedTestLabel || globalBenchmarkLabel || probeLabel || probeCacheLabel) {
+  // 📖 Passive quota chip (t2): `📊 groq 78% · sambanova 41%` (top-N depleted first).
+  // 📖 Shows live rate-limit headers that the daemon / pings collected from upstream
+  // 📖 responses. Zero extra network requests — see provider-quota-fetchers.js.
+  // 📖 Cap at 5 providers to avoid footer bloat; pick most-depleted first.
+  let quotaLabel = ''
+  if (quota && typeof quota === 'object') {
+    const entries = Object.entries(quota)
+      .filter(([, s]) => s && typeof s.percent === 'number')
+      .sort((a, b) => a[1].percent - b[1].percent)  // 📖 most depleted first
+      .slice(0, 5)
+    if (entries.length > 0) {
+      const parts = entries.map(([providerKey, snap]) => {
+        const icon = snap.percent <= 10 ? '🚨' : snap.percent <= 25 ? '⚠️ ' : '📊'
+        return `${icon} ${providerKey} ${snap.percent}%`
+      })
+      quotaLabel = chalk.bgRgb(60, 100, 60).rgb(220, 255, 220).bold(` ${parts.join(' · ')} `)
+    }
+  }
+
+  // 📖 Line 3: Speed Test + Global Benchmark + Probe + Probe-cache + Quota + Last release
+  if (releaseLabel || speedTestLabel || globalBenchmarkLabel || probeLabel || probeCacheLabel || quotaLabel) {
     const parts = [
       { text: '  ', key: null },
       { text: speedTestLabel, key: 'a' },
@@ -1230,6 +1254,8 @@ export function renderTable({
       { text: probeLabel, key: null },
       { text: probeCacheLabel ? '  ' : '', key: null },
       { text: probeCacheLabel, key: null },
+      { text: quotaLabel ? '  ' : '', key: null },
+      { text: quotaLabel, key: null },
       { text: '  ', key: null },
       { text: releaseLabel, key: null },
     ]