free-coding-models 0.5.57 → 0.5.59

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

@@ -54,6 +54,20 @@ import { sendUsageTelemetry } from './telemetry.js'
 import { TIER_ORDER } from './utils.js'
 import { atomicWriteJson, safeJsonParse, sleep, maskApiKey, isRouteableProvider } from './shared-helpers.js'
 import { normalizeRequestBody } from './schema-normalizer.js'
+import {
+  loadCache as loadProbeCache,
+  flushCache as flushProbeCache,
+  recordProbeResults as recordProbeCacheResults,
+  getCacheStats as getProbeCacheStats,
+  getModelsDueForProbe,
+  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
@@ -466,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 || '')
@@ -870,6 +889,12 @@ class RouterRuntime {
     this.webGlobalBenchmarkRunning = false
     this.webGlobalBenchmarkTotal = 0
     this.webGlobalBenchmarkCompleted = 0
+    // 📖 Probe-cache (t1): load the persistent probe-cache on boot so the daemon
+    // 📖 can skip fresh healthy models during its health-probe loop and write
+    // 📖 results back to the same file the CLI TUI uses. See src/core/probe-cache.js.
+    this.probeCache = loadProbeCache()
+    this.probeCacheDirty = false
+    this.probeCacheFlushTimer = null
     this.refreshRouteState()
   }
 
@@ -1023,6 +1048,39 @@ class RouterRuntime {
       latency_ms: result.latencyMs ?? null,
       circuit_state: this.circuit.get(key)?.state || 'UNKNOWN',
     })
+
+    // 📖 Probe-cache (t1): mirror the result into the persistent cross-session
+    // 📖 cache so the CLI TUI can skip fresh healthy models and auto-hide broken
+    // 📖 ones. key is `provider/modelId` — split on the first slash.
+    const slashIdx = key.indexOf('/')
+    if (slashIdx > 0) {
+      const providerKey = key.slice(0, slashIdx)
+      const modelId = key.slice(slashIdx + 1)
+      recordProbeCacheResults(providerKey, [{
+        modelId,
+        status: result.ok ? 'ok' : 'broken',
+        latencyMs: result.latencyMs ?? null,
+        lastError: result.ok ? null : (result.code != null ? String(result.code) : 'error'),
+      }])
+      this.probeCacheDirty = true
+      this.scheduleProbeCacheFlush()
+    }
+  }
+
+  /**
+   * 📖 scheduleProbeCacheFlush — debounced write to disk so we don't thrash the
+   * 📖 filesystem when a probe burst records dozens of results at once.
+   */
+  scheduleProbeCacheFlush() {
+    if (this.probeCacheFlushTimer) return
+    this.probeCacheFlushTimer = setTimeout(() => {
+      this.probeCacheFlushTimer = null
+      if (this.probeCacheDirty) {
+        flushProbeCache()
+        this.probeCacheDirty = false
+      }
+    }, 2000)
+    if (typeof this.probeCacheFlushTimer.unref === 'function') this.probeCacheFlushTimer.unref()
   }
 
   markAuthError(key, detail = 'authentication failed') {
@@ -1435,6 +1493,16 @@ class RouterRuntime {
       configPath: CONFIG_PATH,
       tokenStatsPath: ROUTER_TOKENS_PATH,
       logPath: ROUTER_LOG_PATH,
+      // 📖 Probe-cache (t1): live aggregates from the persistent probe-cache.
+      // 📖 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()),
     }
   }
 
@@ -1529,7 +1597,14 @@ class RouterRuntime {
     if (!set) return
     const candidates = this.scoreCandidates(set)
       .filter((candidate) => candidate.catalog?.routeable && !candidate.circuit?.stale)
-    await Promise.allSettled(candidates.map((candidate) => this.probeCandidate(candidate, {
+    // 📖 Probe-cache (t1): skip models that are still fresh + ok in the persistent
+    // 📖 cache. Broken models naturally pass through (isProbeCacheFresh returns false
+    // 📖 for them), so recovery detection keeps working unchanged.
+    const filtered = candidates.filter((c) => {
+      if (!c.catalog) return true
+      return !isProbeCacheFresh(c.catalog.providerKey, c.catalog.modelId)
+    })
+    await Promise.allSettled(filtered.map((candidate) => this.probeCandidate(candidate, {
       eco: this.routerConfig().probeMode === 'eco',
     })))
   }
@@ -1992,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)
@@ -2134,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 })
@@ -3101,12 +3176,14 @@ class RouterRuntime {
     if (this.probeTimer) clearInterval(this.probeTimer)
     if (this.configReloadTimer) clearInterval(this.configReloadTimer)
     if (this.tokenFlushTimer) clearInterval(this.tokenFlushTimer)
+    if (this.probeCacheFlushTimer) clearInterval(this.probeCacheFlushTimer)
     for (const timeout of this.probeTimeouts) clearTimeout(timeout)
     const started = Date.now()
     while (this.inFlight > 0 && Date.now() - started < 30000) {
       await sleep(100)
     }
     this.tokenTracker.flush({ force: true })
+    flushProbeCache()  // 📖 t1: persist any pending probe-cache deltas before exit
     try { this.server?.close() } catch {}
     try { unlinkSync(ROUTER_PID_PATH) } catch {}
     try { unlinkSync(ROUTER_PORT_PATH) } catch {}

package/src/core/utils.js

@@ -452,11 +452,16 @@ export function findBestModel(results) {
 //     --daemon-status, --no-telemetry, --json, --help/-h (case-insensitive)
 //     --playground / playground subcommand (open the in-TUI chat playground)
 //   - Value flag: --tier <letter> (the next non-flag arg is the tier value)
+//   - Probe-cache flags (t1):
+//     --reprobe / --no-cache (boolean) — force-rebuild the probe cache this run
+//     --probe-ttl <ms> (value)          — override the 24h default TTL
+//     --show-broken (boolean)           — don't auto-hide broken models (one-shot)
 //
 // Returns:
 //   { apiKey, bestMode, fiableMode, openCodeMode, openCodeDesktopMode, openCodeWebMode, openClawMode,
 //     aiderMode, crushMode, gooseMode, qwenMode, openHandsMode, ampMode,
-//     piMode, jcodeMode, copilotMode, forgecodeMode, zcodeMode, noTelemetry, jsonMode, helpMode, tierFilter }
+//     piMode, jcodeMode, copilotMode, forgecodeMode, zcodeMode, noTelemetry, jsonMode, helpMode, tierFilter,
+//     reprobeMode, probeTtlMs, showBrokenMode }
 //
 // 📖 Note: apiKey may be null here — the main CLI falls back to env vars and saved config.
 export function parseArgs(argv) {
@@ -486,6 +491,12 @@ export function parseArgs(argv) {
     ? pingIntervalIdx + 1
     : -1
 
+  // 📖 --probe-ttl <ms> — override the 24h probe-cache TTL (power users / debugging)
+  const probeTtlIdx = args.findIndex(a => a.toLowerCase() === '--probe-ttl')
+  const probeTtlValueIdx = (probeTtlIdx !== -1 && args[probeTtlIdx + 1] && !args[probeTtlIdx + 1].startsWith('--'))
+    ? probeTtlIdx + 1
+    : -1
+
   // 📖 --sync-set [name] — auto-discover and live-probe models into a named router set
   const syncSetIdx = args.findIndex(a => a.toLowerCase() === '--sync-set')
   const syncSetValueIdx = (syncSetIdx !== -1 && args[syncSetIdx + 1] && !args[syncSetIdx + 1].startsWith('--'))
@@ -499,6 +510,7 @@ export function parseArgs(argv) {
   if (originValueIdx !== -1) skipIndices.add(originValueIdx)
   if (pingIntervalValueIdx !== -1) skipIndices.add(pingIntervalValueIdx)
   if (syncSetValueIdx !== -1) skipIndices.add(syncSetValueIdx)
+  if (probeTtlValueIdx !== -1) skipIndices.add(probeTtlValueIdx)
 
   for (const [i, arg] of args.entries()) {
     if (arg.startsWith('--') || arg === '-h') {
@@ -574,6 +586,13 @@ export function parseArgs(argv) {
   // 📖 --recommend — launch directly into Smart Recommend mode (Q key equivalent)
   const recommendMode = flags.includes('--recommend')
 
+  // 📖 Probe-cache flags (t1): --reprobe / --no-cache force a fresh probe pass;
+  // 📖 --probe-ttl overrides the 24h default; --show-broken un-hides broken models for this run.
+  const reprobeMode = flags.includes('--reprobe') || flags.includes('--no-cache')
+  const showBrokenMode = flags.includes('--show-broken')
+  const probeTtlRaw = probeTtlValueIdx !== -1 ? args[probeTtlValueIdx] : null
+  const probeTtlMs = probeTtlRaw !== null ? parseInt(probeTtlRaw, 10) : null
+
   return {
     apiKey,
     bestMode,
@@ -621,6 +640,10 @@ export function parseArgs(argv) {
     devMode,
     syncSetMode,
     syncSetName,
+    // 📖 Probe-cache flags (t1) — see src/core/probe-cache.js
+    reprobeMode,
+    probeTtlMs: Number.isFinite(probeTtlMs) && probeTtlMs > 0 ? probeTtlMs : null,
+    showBrokenMode,
   }
 }