free-coding-models 0.5.56 → 0.5.58

package/src/core/probe-cache.js

@@ -0,0 +1,515 @@
+/**
+ * @file probe-cache.js
+ * @description Persistent cache for health-probe results, shared across CLI, daemon, and Tauri.
+ *
+ * @details
+ *   📖 Why this exists:
+ *   📖 - Today every `pnpm start` re-pings all ~238 models from scratch (10-30s cold start).
+ *   📖 - A model returning `ok` < 24h ago is almost certainly still healthy — skip the ping.
+ *   📖 - A model returning `broken` should always be re-probed (allows recovery detection)
+ *   📖   AND hidden from the default view until it recovers.
+ *
+ *   📖 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)
+ *   📖   4. now - lastProbedAt >= ttlMs → due for probe
+ *   📖   5. otherwise              → fresh, skip
+ *
+ *   📖 File location:
+ *   📖   - $XDG_CACHE_HOME/free-coding-models/probe-cache.json if XDG_CACHE_HOME is set
+ *   📖   - ~/.free-coding-models/probe-cache.json otherwise
+ *
+ *   📖 All surface modes (CLI TUI, Web Dashboard / daemon, Tauri Desktop) read/write the
+ *   📖 same file. Concurrency between daemon and CLI is handled via read-merge-write on
+ *   📖 every flush (see flushCache) plus the atomic tmp + rename helper from shared-helpers.
+ *
+ * @functions
+ *   → getProbeCachePath()                       — Resolves the cache file path
+ *   → loadCache({ path, now }?)                  — Reads + migrates the JSON file
+ *   → flushCache({ path, cache, now }?)          — Atomic write of the cache
+ *   → clearCache({ path }?)                      — Nukes the file (for --reprobe)
+ *   → getModelsDueForProbe(providerKey, modelIds, opts?) → string[] of IDs needing ping
+ *   → isCacheFresh(providerKey, modelId, opts?) → boolean freshness check
+ *   → recordProbeResults(providerKey, results, opts?) → mutates in-memory cache
+ *   → getCacheStats(opts?) → { total, ok, broken, freshCount, staleCount, ... }
+ *   → getCachedResultsForProvider(providerKey, opts?) → array of synthesized results
+ *
+ * @exports getProbeCachePath, loadCache, flushCache, clearCache,
+ *          getModelsDueForProbe, isCacheFresh, recordProbeResults,
+ *          getCacheStats, getCachedResultsForProvider,
+ *          DEFAULT_PROBE_TTL_MS, 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)
+ * @see src/core/shared-helpers.js — atomicWriteJson (used by flushCache)
+ */
+
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { atomicWriteJson } from './shared-helpers.js'
+
+// ─── Constants ────────────────────────────────────────────────────────────────
+
+/** 📖 Default probe-result freshness window — 24h. Override via opts.ttlMs. */
+export const DEFAULT_PROBE_TTL_MS = 24 * 60 * 60 * 1000
+
+/**
+ * 📖 Bump this number whenever ping behaviour changes (new endpoint, different prompt,
+ * 📖 new provider factory from t7, etc.). On load, any entry whose probeVersion differs
+ * 📖 is treated as due-for-probe and silently overwritten — no manual purge needed.
+ */
+export const CURRENT_PROBE_VERSION = 2
+
+/** 📖 Cache file basename. Lives in a directory alongside other FCM state files. */
+const CACHE_FILENAME = 'probe-cache.json'
+const CACHE_DIRNAME = 'free-coding-models'
+
+// ─── Module-level state ──────────────────────────────────────────────────────
+
+/**
+ * 📖 In-memory mirror of the on-disk cache. Loaded lazily on first call to
+ * 📖 any function that needs it (loadCache / getModelsDueForProbe / etc.).
+ * 📖 Mutations via recordProbeResults() update this object; flushCache() writes it.
+ */
+let _cache = null
+let _cacheLoadedFrom = null  // path we last loaded from (for write-back)
+
+// ─── Path resolution ──────────────────────────────────────────────────────────
+
+/**
+ * 📖 Resolves where the probe-cache JSON lives.
+ * 📖 Honours XDG_CACHE_HOME when set (Linux/macOS convention), else falls back to ~/.free-coding-models.
+ *
+ * @returns {string} Absolute path to the cache file (may not exist yet).
+ */
+export function getProbeCachePath() {
+  const xdg = process.env.XDG_CACHE_HOME
+  const baseDir = xdg && xdg.trim()
+    ? path.join(xdg, CACHE_DIRNAME)
+    : path.join(os.homedir(), `.${CACHE_DIRNAME}`)
+  return path.join(baseDir, CACHE_FILENAME)
+}
+
+// ─── Low-level load / flush / clear ───────────────────────────────────────────
+
+/**
+ * 📖 Empty cache shape — used as the default when no file exists or it cannot be parsed.
+ * @returns {{ version: number, providers: Record<string, { models: Record<string, ProbeEntry> }> }}
+ */
+function emptyCache() {
+  return { version: CURRENT_PROBE_VERSION, providers: {} }
+}
+
+/**
+ * 📖 Read the cache JSON from disk. Returns an empty cache on any I/O or parse error.
+ * 📖 Also normalises older versions by setting version = CURRENT_PROBE_VERSION so the
+ * 📖 freshness check picks them up as due (the per-entry probeVersion mismatch handles it).
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.path]   — Override the cache file path (mainly for tests).
+ * @returns {object} The loaded cache object.
+ */
+export function loadCache({ path: cachePath } = {}) {
+  const target = cachePath ?? getProbeCachePath()
+
+  let raw
+  try {
+    raw = fs.readFileSync(target, 'utf-8')
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return emptyCache()
+    // 📖 Any other read error — start fresh rather than crash.
+    return emptyCache()
+  }
+
+  let parsed
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    // 📖 Corrupt JSON — start fresh (atomic write means we should never see this,
+    // 📖 but if the file is hand-edited or partially written by an older buggy version
+    // 📖 we recover gracefully).
+    return emptyCache()
+  }
+
+  // 📖 Structural validation — missing fields get filled with defaults.
+  if (!parsed || typeof parsed !== 'object') return emptyCache()
+  if (typeof parsed.version !== 'number') parsed.version = CURRENT_PROBE_VERSION
+  if (!parsed.providers || typeof parsed.providers !== 'object') parsed.providers = {}
+  for (const provider of Object.values(parsed.providers)) {
+    if (!provider || typeof provider !== 'object') continue
+    if (!provider.models || typeof provider.models !== 'object') provider.models = {}
+  }
+
+  _cache = parsed
+  _cacheLoadedFrom = target
+  return parsed
+}
+
+/**
+ * 📖 Merge two cache objects: incoming wins on key collision, but absent fields
+ * 📖 from incoming do NOT delete fields from base. Used by flushCache to merge
+ * 📖 our in-memory mirror with whatever the on-disk file now contains (covers
+ * 📖 the daemon + CLI running concurrently case).
+ */
+function mergeCache(base, incoming) {
+  if (!base || typeof base !== 'object') return incoming
+  if (!incoming || typeof incoming !== 'object') return base
+  const out = { ...incoming, providers: { ...(incoming.providers || {}) } }
+  for (const [providerKey, providerBucket] of Object.entries(base.providers || {})) {
+    const incomingBucket = out.providers[providerKey] || { models: {} }
+    out.providers[providerKey] = {
+      models: { ...(providerBucket?.models || {}), ...(incomingBucket.models || {}) },
+    }
+  }
+  return out
+}
+
+/**
+ * 📖 Persist the in-memory cache to disk atomically (tmp + rename) with a
+ * 📖 read-merge-write pass so concurrent daemons and CLIs don't clobber each
+ * 📖 other. Worst case: one batch of deltas is merged twice (idempotent), or
+ * 📖 a stale `lastProbedAt` survives briefly (acceptable per t1 risk register).
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.path]  — Override the cache file path.
+ * @param {object} [opts.cache] — Override the in-memory cache (defaults to module state).
+ * @returns {boolean} true on success, false on any I/O error.
+ */
+export function flushCache({ path: cachePath, cache } = {}) {
+  const target = cachePath ?? _cacheLoadedFrom ?? getProbeCachePath()
+  const localData = cache ?? _cache ?? emptyCache()
+
+  // 📖 Read whatever is on disk RIGHT NOW (may have been written by another process
+  // 📖 since we last loaded), and merge our deltas over the top.
+  let onDisk = null
+  try {
+    const raw = fs.readFileSync(target, 'utf-8')
+    onDisk = JSON.parse(raw)
+    if (!onDisk || typeof onDisk !== 'object') onDisk = null
+  } catch {
+    onDisk = null
+  }
+
+  const merged = onDisk ? mergeCache(onDisk, localData) : localData
+
+  try {
+    atomicWriteJson(target, merged, 0o600)
+    _cacheLoadedFrom = target
+    _cache = merged
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * 📖 Delete the cache file from disk. Used by `--reprobe` / `--no-cache` flags.
+ * 📖 Also clears the in-memory mirror so the next call reloads from scratch.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.path] — Override the cache file path.
+ * @returns {boolean} true if the file was deleted (or didn't exist), false on error.
+ */
+export function clearCache({ path: cachePath } = {}) {
+  const target = cachePath ?? getProbeCachePath()
+  _cache = null
+  _cacheLoadedFrom = null
+  try {
+    fs.unlinkSync(target)
+    return true
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return true
+    return false
+  }
+}
+
+// ─── Module-state accessor ───────────────────────────────────────────────────
+
+/**
+ * 📖 Get the current in-memory cache, loading from disk if not yet loaded.
+ * 📖 Pure-isolated: callers can pass `opts.cache` to avoid touching module state
+ * 📖 (used by all freshness / stats functions for testability).
+ */
+function getCache(opts) {
+  if (opts && Object.prototype.hasOwnProperty.call(opts, 'cache')) return opts.cache
+  if (_cache) return _cache
+  return loadCache()
+}
+
+// ─── Freshness rules ─────────────────────────────────────────────────────────
+
+/**
+ * 📖 Decide which model IDs are due for a (re-)probe, given the current cache.
+ * 📖 See file header for the 5 rules.
+ *
+ * @param {string} providerKey
+ * @param {string[]} modelIds
+ * @param {object} [opts]
+ * @param {number} [opts.ttlMs=86400000]
+ * @param {number} [opts.now=Date.now()]
+ * @param {object} [opts.cache]            — Injected cache (skips module state + disk)
+ * @param {number} [opts.probeVersion=2]
+ * @returns {string[]} Subset of `modelIds` that need probing this cycle.
+ */
+export function getModelsDueForProbe(providerKey, modelIds, opts = {}) {
+  const ttlMs = opts.ttlMs ?? DEFAULT_PROBE_TTL_MS
+  const now = opts.now ?? Date.now()
+  const probeVersion = opts.probeVersion ?? CURRENT_PROBE_VERSION
+  const cache = getCache(opts)
+  const providerBucket = cache?.providers?.[providerKey]
+  const models = providerBucket?.models ?? {}
+
+  const due = []
+  for (const id of modelIds) {
+    const entry = models[id]
+    // Rule 1: no entry → due
+    if (!entry) { due.push(id); continue }
+    // Rule 2: version mismatch → due (silently overwritten on next record)
+    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 4: TTL expired → due
+    if (typeof entry.lastProbedAt !== 'number' || now - entry.lastProbedAt >= ttlMs) {
+      due.push(id); continue
+    }
+    // Rule 5: fresh + ok → skip
+  }
+  return due
+}
+
+/**
+ * 📖 Single-model freshness check. Returns true only when ALL conditions hold:
+ * 📖   - entry exists
+ * 📖   - probeVersion matches CURRENT_PROBE_VERSION
+ * 📖   - status !== 'broken'
+ * 📖   - now - lastProbedAt < ttlMs
+ *
+ * @param {string} providerKey
+ * @param {string} modelId
+ * @param {object} [opts]
+ * @returns {boolean}
+ */
+export function isCacheFresh(providerKey, modelId, opts = {}) {
+  const ttlMs = opts.ttlMs ?? DEFAULT_PROBE_TTL_MS
+  const now = opts.now ?? Date.now()
+  const probeVersion = opts.probeVersion ?? CURRENT_PROBE_VERSION
+  const cache = getCache(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 (typeof entry.lastProbedAt !== 'number') return false
+  return now - entry.lastProbedAt < ttlMs
+}
+
+// ─── Write path ───────────────────────────────────────────────────────────────
+
+/**
+ * 📖 Validate + normalise a single probe result into the on-disk shape.
+ * 📖 Throws on garbage input — callers should catch and drop.
+ */
+function normaliseResult(r) {
+  if (!r || typeof r !== 'object') throw new Error('probe result must be an object')
+  if (typeof r.modelId !== 'string' || !r.modelId) throw new Error('modelId required')
+  if (r.status !== 'ok' && r.status !== 'broken') throw new Error(`status must be 'ok' or 'broken'`)
+  return {
+    modelId: r.modelId,
+    status: r.status,
+    latencyMs: typeof r.latencyMs === 'number' && Number.isFinite(r.latencyMs) ? r.latencyMs : null,
+    lastError: typeof r.lastError === 'string' ? r.lastError : null,
+  }
+}
+
+/**
+ * 📖 Persist a batch of probe results into the in-memory cache (and schedule a flush).
+ * 📖 Per-result validation: bad entries are dropped, good ones are written.
+ * 📖 The module-level cache is mutated in place; flushCache() is a separate call.
+ *
+ * @param {string} providerKey
+ * @param {Array<{ modelId: string, status: 'ok'|'broken', latencyMs?: number, lastError?: string }>} results
+ * @param {object} [opts]
+ * @param {number} [opts.now=Date.now()]
+ * @param {object} [opts.cache] — Optional explicit cache to mutate (skips module state).
+ * @returns {{ written: number, dropped: number }} Counts for telemetry.
+ */
+export function recordProbeResults(providerKey, results, opts = {}) {
+  const now = opts.now ?? Date.now()
+  const cache = (opts && Object.prototype.hasOwnProperty.call(opts, 'cache')) ? opts.cache : getCache(opts)
+
+  if (!cache.providers[providerKey]) {
+    cache.providers[providerKey] = { models: {} }
+  }
+  const bucket = cache.providers[providerKey].models
+
+  let written = 0
+  let dropped = 0
+  for (const raw of results || []) {
+    try {
+      const r = normaliseResult(raw)
+      bucket[r.modelId] = {
+        status: r.status,
+        lastProbedAt: now,
+        latencyMs: r.latencyMs,
+        lastError: r.lastError,
+        probeVersion: CURRENT_PROBE_VERSION,
+      }
+      written++
+    } catch {
+      dropped++
+    }
+  }
+
+  // 📖 Mark cache as dirty if we're touching module state. flushCache() picks it up later.
+  if (!opts || !Object.prototype.hasOwnProperty.call(opts, 'cache')) {
+    _cache = cache
+  }
+
+  return { written, dropped }
+}
+
+// ─── Stats ────────────────────────────────────────────────────────────────────
+
+/**
+ * 📖 Aggregate stats over the current cache, useful for the TUI footer chip and
+ * 📖 the daemon's /health endpoint.
+ *
+ * @param {object} [opts]
+ * @param {number} [opts.ttlMs=86400000]
+ * @param {number} [opts.now=Date.now()]
+ * @param {object} [opts.cache]
+ * @returns {{
+ *   total: number,
+ *   ok: number,
+ *   broken: number,
+ *   freshCount: number,   // ok + within TTL
+ *   staleCount: number,   // ok but past TTL (would be due for probe under rules 1/4)
+ *   dueCount: number,     // models that would be re-probed right now (broken + stale)
+ *   hiddenCount: number,  // == broken
+ *   providers: number,
+ * }}
+ */
+export function getCacheStats(opts = {}) {
+  const ttlMs = opts.ttlMs ?? DEFAULT_PROBE_TTL_MS
+  const now = opts.now ?? Date.now()
+  const cache = getCache(opts)
+  const probeVersion = opts.probeVersion ?? CURRENT_PROBE_VERSION
+
+  let total = 0, ok = 0, broken = 0, freshCount = 0, staleCount = 0
+  for (const providerBucket of Object.values(cache.providers ?? {})) {
+    for (const entry of Object.values(providerBucket?.models ?? {})) {
+      if (!entry) continue
+      total++
+      const isFresh = entry.status === 'ok'
+        && typeof entry.probeVersion === 'number'
+        && entry.probeVersion === probeVersion
+        && typeof entry.lastProbedAt === 'number'
+        && now - entry.lastProbedAt < ttlMs
+      if (entry.status === 'ok') ok++
+      else if (entry.status === 'broken') broken++
+      if (isFresh) freshCount++
+      else if (entry.status === 'ok') staleCount++
+    }
+  }
+
+  return {
+    total,
+    ok,
+    broken,
+    freshCount,
+    staleCount,
+    dueCount: broken + staleCount,
+    hiddenCount: broken,
+    providers: Object.keys(cache.providers ?? {}).length,
+  }
+}
+
+// ─── Synthesised results for the TUI ──────────────────────────────────────────
+
+/**
+ * 📖 Convert a provider's cache entries into the shape ping-loop emits so the TUI
+ * 📖 can render them instantly on warm start. Only returns FRESH entries (rule 5);
+ * 📖 broken/stale entries are intentionally excluded so the live ping will refresh them.
+ *
+ * 📖 Returned shape mirrors what `src/core/ping.js` builds for a successful ping,
+ * 📖 so the downstream renderer / ranker don't need to know whether data is cached
+ * 📖 or live. Minimum fields used by `render-table.js`:
+ * 📖   modelId, providerKey, status ('up'|'down'), avg, p95, jitter, stability,
+ * 📖   uptime, verdict, lastProbedAt, source ('cache'|'live')
+ *
+ * @param {string} providerKey
+ * @param {object} [opts]
+ * @param {number} [opts.ttlMs=86400000]
+ * @param {number} [opts.now=Date.now()]
+ * @param {object} [opts.cache]
+ * @returns {Array<object>} Synthesised result objects (empty array if no fresh entries).
+ */
+export function getCachedResultsForProvider(providerKey, opts = {}) {
+  const ttlMs = opts.ttlMs ?? DEFAULT_PROBE_TTL_MS
+  const now = opts.now ?? Date.now()
+  const cache = getCache(opts)
+  const probeVersion = opts.probeVersion ?? CURRENT_PROBE_VERSION
+  const bucket = cache?.providers?.[providerKey]?.models ?? {}
+
+  const out = []
+  for (const [modelId, entry] of Object.entries(bucket)) {
+    if (!entry || entry.status !== 'ok') continue
+    if (typeof entry.probeVersion !== 'number' || entry.probeVersion !== probeVersion) continue
+    if (typeof entry.lastProbedAt !== 'number') continue
+    if (now - entry.lastProbedAt >= ttlMs) continue
+
+    const latency = typeof entry.latencyMs === 'number' ? entry.latencyMs : 0
+    out.push({
+      modelId,
+      providerKey,
+      status: 'up',
+      avg: latency,
+      p95: latency,
+      jitter: 0,
+      stability: 100,
+      uptime: 100,
+      verdict: 'Cached',
+      httpCode: '200',
+      lastProbedAt: entry.lastProbedAt,
+      source: 'cache',
+      latencyMs: latency,
+    })
+  }
+  return out
+}
+
+// ─── Pruning ──────────────────────────────────────────────────────────────────
+
+/**
+ * 📖 Drop entries whose modelId is no longer present in the live catalog.
+ * 📖 Called once per boot from ping-loop to keep the cache file bounded as the
+ * 📖 catalog evolves (providers add/remove models over time).
+ *
+ * @param {string} providerKey
+ * @param {Set<string> | string[]} liveModelIds
+ * @param {object} [opts]
+ * @param {object} [opts.cache]
+ * @returns {number} Number of entries pruned.
+ */
+export function pruneStaleEntries(providerKey, liveModelIds, opts = {}) {
+  const cache = getCache(opts)
+  const bucket = cache?.providers?.[providerKey]?.models
+  if (!bucket) return 0
+
+  const live = liveModelIds instanceof Set ? liveModelIds : new Set(liveModelIds)
+  let pruned = 0
+  for (const id of Object.keys(bucket)) {
+    if (!live.has(id)) {
+      delete bucket[id]
+      pruned++
+    }
+  }
+
+  if (!opts || !Object.prototype.hasOwnProperty.call(opts, 'cache')) {
+    _cache = cache
+  }
+  return pruned
+}

package/src/core/router-daemon.js

@@ -54,6 +54,15 @@ 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'
 
 export const ROUTER_DEFAULT_PORT = 19280
 export const ROUTER_MAX_PORT = 19289
@@ -870,6 +879,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 +1038,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 +1483,10 @@ 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(),
     }
   }
 
@@ -1529,7 +1581,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',
     })))
   }
@@ -3101,12 +3160,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,
   }
 }