free-coding-models 0.5.28 → 0.5.30

package/README.md

@@ -184,7 +184,7 @@ and every TUI capability that's safe to port ships behind a button or chip.
 | **Theme** | Tri-state `auto / dark / light` cycle (TUI `G`) — auto follows the OS preference. |
 | **Smart Recommend** | Header "Recommend" opens the 3-question wizard, runs the 10s analysis phase, then returns the Top 3 shared-score recommendations with Pin + install-endpoint actions. |
 | **Endpoint installs** | The Web never starts external tools. It writes the selected provider/model endpoint into the chosen tool config (`/api/install-endpoint`), then users start their tool themselves. |
-| **Router Dashboard** | Header "Router" opens a full modal with daemon start/stop, model health table with circuit breaker badges, request log, probe mode selector, and quick-setup card (copy base URL + model to clipboard). |
+| **Router Dashboard** | Header "Router" opens a full modal with daemon start/stop, model health table with circuit breaker badges, request log, probe mode selector, quick-setup card (copy base URL + model to clipboard), **"Probe all" AI Latency/TPS benchmarking**, and a **"Test Router" mini playground** to live-route chats through the fallback chain. |
 | **Token Usage** | Integrated inside Analytics: today + all-time summary cards, 7-day usage bar chart, top models and top providers breakdown. |
 | **Installed Models** | Header overflow → "Installed Models" opens a modal that scans all tool configs (Goose, Crush, Aider, Kilo, Qwen, Pi, OpenHands, Amp) and shows configured models with soft-delete (backup saved). |
 | **Install Endpoints wizard** | Header overflow → "Install Endpoints" opens a 4-step wizard: pick provider → pick tool → select models → install. Writes managed provider catalogs into tool configs using the same engine as the TUI. |

package/bin/free-coding-models.js

@@ -4,8 +4,16 @@
  * @description Live terminal availability checker for coding LLM models with OpenCode & OpenClaw integration.
  */
 
-// 📖 --dev mode: must set FCM_DEV before any module imports resolve daemon paths
-if (process.argv.includes('--dev')) {
+// 📖 --dev mode: must set FCM_DEV before any module imports resolve daemon paths.
+// 📖 Also auto-detect git checkouts — a repo checkout is always in dev mode because
+// 📖 the router daemon must use dev ports/files to avoid clashing with a production
+// 📖 npm install running on the same machine.
+// 📖 IMPORTANT: these checks MUST run synchronously before any static imports
+// 📖 resolve, because router-daemon.js reads FCM_DEV at module load time.
+import { existsSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+if (process.argv.includes('--dev') || (!process.env.FCM_DEV && existsSync(join(dirname(fileURLToPath(import.meta.url)), '..', '.git')))) {
   process.env.FCM_DEV = '1'
 }
 

package/changelog/v0.5.29.md

@@ -0,0 +1,19 @@
+# Changelog v0.5.29 - 2026-06-15
+
+### Fixed
+- **Router now respects your priority order (fixes #120, reported by @jammin1911).** Previously, priority was only 20% of the routing score, so a healthy low-priority model (e.g. GPT-OSS 120B) could serve traffic even when higher-priority models you deliberately ranked above it were also healthy. Routing is now **strict priority-first**: `#1` is always tried first while it is healthy, and the health score is only used as a tiebreaker between models that share the same priority (e.g. cold-start ties). Circuit-breaker safety is preserved — closed (healthy) models always come before half-open (recovering) ones. Your fallback chain is now authoritative.
+- **Daemon startup errors are now surfaced instead of swallowed.** The TUI captures `--daemon-bg` stdout/stderr and shows the real failure reason (port in use, config corruption, etc.) as a dashboard notice, instead of silently flipping back to "stopped".
+- **Dev checkouts no longer clash with production installs.** A git checkout now auto-enables dev mode (`FCM_DEV=1`) so its router daemon uses dev ports/files (`29280`, `-dev` suffixed PID/port/log files) and never collides with a globally-installed `free-coding-models` running on the same machine. Dynamic path resolvers pick up `FCM_DEV` changes that happen after module load.
+
+### Added
+- **`routingOrder` field in `/stats`** — exposes the exact attempt order the daemon will use for the next request (priority-first among healthy models). `routingOrder[0]` is the model that will serve the next chat completion. Dashboards use it to show which model is active.
+- **Clearer priority indicators in the Router UI (all surfaces)** so users understand the fallback chain at a glance:
+  - **Web Dashboard:** the active-set list now labels `#1` as a highlighted **Primary** badge (accent-colored) and the rest as numbered fallbacks. A one-line legend explains *"Primary tries first → Fallback on failure / rate-limit"*. The model that will serve the next request gets a green accent border + tint (**Next up** badge in the legend). Tooltips on every badge explain the semantics.
+  - **TUI Dashboard:** a `▶ NEXT` marker (green) is drawn on the exact model the daemon will route to next, so the top of your fallback chain is obvious. Empty-state copy now explains *"Favorites become your router fallback chain — #1 is tried first."*
+- **Always-visible Quick Setup card** on the Router dashboard (Web + TUI) with sensible defaults (`localhost:19280/v1`, model `fcm`, key `fcm-local`), so you can copy your tool config even before starting the daemon. The Web version adds a one-click **Copy all** button and a hero glow when running.
+- **Better empty states** across the Web Router view: the active-set list and request log now show helpful guidance ("No models in the active set → Add models or Sync best", "No requests yet. Start coding to see traffic here.") instead of disappearing.
+- **Auto-expanding request log** — the Web request log expands automatically the first time traffic appears, so you don't have to click to see your routed requests.
+- **More prominent Start button** — the stopped-state "Start Router" CTA is now larger and easier to hit.
+
+### Changed
+- Router candidate sorting changed from `score DESC, priority ASC` to `priority ASC, score DESC` — the user's explicit ranking now wins. The `scoring` weights config is retained (still used for the health table and same-tier tiebreaks), so existing user configs and config normalization are unaffected.

package/changelog/v0.5.30.md

@@ -0,0 +1,15 @@
+# Changelog v0.5.30 - 2026-06-15
+
+### Added
+- **Harmonized Playgrounds across all surfaces (fixes Playground UI mismatches).** Created a single shared `<PlaygroundChat>` React component that acts as the single source of truth for the full-screen Playground modal, the Router View's "Test Router" panel, and the Expanded Detail Row's "Mini Playground". 
+- **Universal real-time response metadata.** Under every assistant reply in all three playground locations, users now see the serving model (correctly resolved, even when routed through `fcm`), total latency, generated token count, and tokens per second (TPS). The addressed model or the router's Primary pick is also displayed under every user bubble for clarity.
+- **Web Router Benchmarking (`Probe all`).** Added a "Probe all" action to the Web Router Dashboard. This lets you benchmark AI Latency and TPS on all models in the active routing set concurrently inside the daemon process. A visual progress bar displays the benchmarking status, and results flow back into each row's AI Latency cell.
+- **New server proxy endpoint `/api/router/probe-all`** in `web/server.js` to handle the web dashboard's probe request and safely proxy it to the daemon's `/api/global-benchmark` with an extended timeout.
+- **Playground daemon-status alignment tests.** Added unit tests in `test/test.js` to ensure the `/health` and `/stats` daemon endpoints consistently report `running: true` alongside `ok: true`, preventing a mismatch where the router dashboard would report "running" but the playground would report "offline".
+
+### Changed
+- **Dynamic port and PID resolvers for dev mode (`FCM_DEV=1`).** Refined paths in `src/core/router-daemon.js`, `src/core/playground.js`, `src/core/sync-set.js`, and `web/server.js` to use dynamic functions (`getRouterPortPath()`, `getRouterPidPath()`). This ensures dev checkouts correctly detect and signal the dev daemon (`-dev` port/PID files) instead of reading stale production constants resolved at module load time.
+
+### Fixed
+- **Fixed false "router offline" alerts.** The Playground now correctly trusts the daemon status because both `/health` and `/stats` endpoints uniformly report `running: true`.
+- **Restored served-model badge for routed streams.** Forwarded the daemon's custom `x-fcm-router-model` response header in stream completions through the web proxy, so the playground can display which specific provider/model actually resolved the request when calling the `fcm` auto-router.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "free-coding-models",
-  "version": "0.5.28",
+  "version": "0.5.30",
   "description": "Find the fastest coding LLM models in seconds — ping free models from multiple providers, pick the best one for OpenCode, Cursor, or any AI coding assistant.",
   "keywords": [
     "nvidia",

package/sources.js

@@ -549,7 +549,8 @@ export const sources = {
 export const MODELS = [];
 for (const [sourceKey, sourceData] of Object.entries(sources)) {
   if (!sourceData || !sourceData.models) continue
-  for (const [modelId, label, tier, sweScore, ctx] of sourceData.models) {
-    MODELS.push([modelId, label, tier, sweScore, ctx, sourceKey])
+  for (const model of sourceData.models) {
+    const [modelId, label, tier, sweScore, ctx, addedDate] = model
+    MODELS.push([modelId, label, tier, sweScore, ctx, sourceKey, addedDate || null])
   }
 }

package/src/core/config.js

@@ -464,16 +464,6 @@ export function defaultRouterPrePromptText() {
   return DEFAULT_ROUTER_SETTINGS.prePrompt.text
 }
 
-function normalizeProfileSettings(settings) {
-  const safeSettings = isPlainObject(settings) ? { ...settings } : {}
-  return {
-    ..._emptyProfileSettings(),
-    ...safeSettings,
-    theme: ['dark', 'light', 'auto'].includes(safeSettings.theme) ? safeSettings.theme : 'auto',
-  }
-}
-
-
 
 function normalizeConfigShape(config) {
   const safeConfig = isPlainObject(config) ? config : {}
@@ -527,10 +517,7 @@ function mergeEndpointInstalls(diskEndpointInstalls, incomingEndpointInstalls) {
   return [...merged.values()]
 }
 
-function mergeProfiles(diskProfiles, incomingProfiles, options = {}) {
-  // 📖 Profile system removed - return empty object
-  return {}
-}
+
 
 /**
  * 📖 buildPersistedConfig merges the latest disk snapshot with the in-memory config so

package/src/core/endpoint-installer.js

@@ -47,6 +47,7 @@ import { MODELS, sources } from '../../sources.js'
 import { getApiKey, saveConfig } from './config.js'
 import { ENV_VAR_NAMES, PROVIDER_METADATA } from './provider-metadata.js'
 import { getToolMeta } from './tool-metadata.js'
+import { ensureDir, readJson as sharedReadJson } from './shared-helpers.js'
 
 // 📖 replicate uses /v1/predictions (not /chat/completions), so it's not OpenAI-compatible.
 // 📖 zai and opencode-zen ARE OpenAI-compatible and CAN be installed into any tool.
@@ -72,9 +73,8 @@ function getDefaultPaths() {
   }
 }
 
-function ensureDirFor(filePath) {
-  mkdirSync(dirname(filePath), { recursive: true })
-}
+// 📖 ensureDirFor replaced by shared ensureDir (same logic)
+const ensureDirFor = ensureDir
 
 function backupIfExists(filePath) {
   if (!existsSync(filePath)) return null
@@ -83,13 +83,9 @@ function backupIfExists(filePath) {
   return backupPath
 }
 
+// 📖 readJson with default fallback of {} — matches shared helper's signature
 function readJson(filePath, fallback = {}) {
-  if (!existsSync(filePath)) return fallback
-  try {
-    return JSON.parse(readFileSync(filePath, 'utf8'))
-  } catch {
-    return fallback
-  }
+  return sharedReadJson(filePath, fallback)
 }
 
 function writeJson(filePath, value, { backup = true } = {}) {

package/src/core/legacy-proxy-cleanup.js

@@ -81,6 +81,8 @@ function noteError(summary, filePath, error) {
   summary.errors.push(`${filePath}: ${error instanceof Error ? error.message : String(error)}`)
 }
 
+// 📖 Thin wrappers: readJsonFile propagates parse errors (callers have try/catch).
+// 📖 writeJsonFile appends a trailing newline for clean diffs.
 function readJsonFile(filePath, fallback = null) {
   if (!existsSync(filePath)) return fallback
   return JSON.parse(readFileSync(filePath, 'utf8'))

package/src/core/model-merger.js

@@ -1,15 +1,6 @@
-const TIER_RANK = { 'S+': 0, 'S': 1, 'A+': 2, 'A': 3, 'A-': 4, 'B+': 5, 'B': 6, 'C': 7 }
-
-function parseCtxK(ctx) {
-  if (!ctx) return 0
-  const s = ctx.toLowerCase()
-  if (s.endsWith('m')) return parseFloat(s) * 1000
-  return parseFloat(s) || 0
-}
+import { parseCtxToK, parseSweToNum } from './utils.js'
 
-function parseSwePercent(swe) {
-  return parseFloat(swe) || 0
-}
+const TIER_RANK = { 'S+': 0, 'S': 1, 'A+': 2, 'A': 3, 'A-': 4, 'B+': 5, 'B': 6, 'C': 7 }
 
 /**
  * Generate a unique slug from a label.
@@ -60,11 +51,11 @@ export function buildMergedModels(models) {
       group.tier = tier
     }
     // Keep highest SWE score
-    if (parseSwePercent(sweScore) > parseSwePercent(group.sweScore)) {
+    if (parseSweToNum(sweScore) > parseSweToNum(group.sweScore)) {
       group.sweScore = sweScore
     }
     // Keep largest context
-    if (parseCtxK(ctx) > parseCtxK(group.ctx)) {
+    if (parseCtxToK(ctx) > parseCtxToK(group.ctx)) {
       group.ctx = ctx
     }
   }

package/src/core/playground.js

@@ -22,7 +22,7 @@
  */
 
 import { displayWidth, sliceOverlayLines, tintOverlayLines } from '../tui/render-helpers.js'
-import { ROUTER_PORT_PATH } from './router-daemon.js'
+import { ROUTER_PORT_PATH, getRouterPortPath } from './router-daemon.js'
 import { existsSync, readFileSync } from 'node:fs'
 import { themeColors } from '../tui/theme.js'
 
@@ -295,10 +295,12 @@ async function readSseStream(resp, fetchFn, controller) {
  * 📖 can stand alone in the TUI process.
  */
 async function readDaemonPort() {
-  // 📖 Try the recorded port file first.
+  // 📖 Try the recorded port file first. Use the dynamic resolver so dev
+  // 📖 checkouts (FCM_DEV=1) read the `-dev` port file and find the dev daemon.
   try {
-    if (existsSync(ROUTER_PORT_PATH)) {
-      const raw = readFileSync(ROUTER_PORT_PATH, 'utf8').trim()
+    const portPath = getRouterPortPath()
+    if (existsSync(portPath)) {
+      const raw = readFileSync(portPath, 'utf8').trim()
       if (/^\d+$/.test(raw)) return Number(raw)
     }
   } catch {}

package/src/core/router-daemon.js

@@ -51,6 +51,8 @@ import { buildChatCompletionPingBody, ping, resolveCloudflareUrl, shouldUseDisab
 import { benchmarkModel, BENCHMARK_TIMEOUT_MS } from './benchmark.js'
 import { loadChangelog } from './changelog-loader.js'
 import { sendUsageTelemetry } from './telemetry.js'
+import { TIER_ORDER } from './utils.js'
+import { atomicWriteJson, safeJsonParse, sleep, maskApiKey, isRouteableProvider } from './shared-helpers.js'
 
 export const ROUTER_DEFAULT_PORT = 19280
 export const ROUTER_MAX_PORT = 19289
@@ -59,15 +61,28 @@ export const ROUTER_MAX_PORT_DEV = 29289
 
 // 📖 Dev mode uses -dev suffixed files so the local dev daemon never clashes
 // 📖 with a production install running on the same machine.
-const _dev = typeof process.env.FCM_DEV !== 'undefined' ? !!process.env.FCM_DEV : false
+// 📖 IMPORTANT: _isDev() is a function, not a constant, so it picks up FCM_DEV
+// 📖 changes that happen after module load (e.g. the bin entry point setting
+// 📖 FCM_DEV=1 on git checkouts). Constant exports for PID/PORT/LOG paths
+// 📖 are still computed eagerly — they are only used by the daemon child process
+// 📖 which always has FCM_DEV set before import. The TUI and dashboard use
+// 📖 getRouterPortRange() and getRouterPidPath() for dynamic resolution.
+function _isDev() { return typeof process.env.FCM_DEV !== 'undefined' ? !!process.env.FCM_DEV : false }
+const _dev = _isDev()
 export const ROUTER_PID_PATH = join(homedir(), `.free-coding-models-daemon${_dev ? '-dev' : ''}.pid`)
 export const ROUTER_PORT_PATH = join(homedir(), `.free-coding-models-daemon${_dev ? '-dev' : ''}.port`)
 export const ROUTER_LOG_PATH = join(homedir(), `.free-coding-models-daemon${_dev ? '-dev' : ''}.log`)
 export const ROUTER_TOKENS_PATH = join(homedir(), `.free-coding-models-tokens${_dev ? '-dev' : ''}.json`)
 
+// 📖 Dynamic path resolvers — used by the TUI dashboard which may have FCM_DEV
+// 📖 set after module load time (git checkout auto-detection in bin/ entry).
+export function getRouterPidPath() { return join(homedir(), `.free-coding-models-daemon${_isDev() ? '-dev' : ''}.pid`) }
+export function getRouterPortPath() { return join(homedir(), `.free-coding-models-daemon${_isDev() ? '-dev' : ''}.port`) }
+export function getRouterLogPath() { return join(homedir(), `.free-coding-models-daemon${_isDev() ? '-dev' : ''}.log`) }
+
 // 📖 Returns effective port range for current mode (dev vs production)
 export function getRouterPortRange() {
-  return _dev
+  return _isDev()
     ? { defaultPort: ROUTER_DEFAULT_PORT_DEV, maxPort: ROUTER_MAX_PORT_DEV }
     : { defaultPort: ROUTER_DEFAULT_PORT, maxPort: ROUTER_MAX_PORT }
 }
@@ -83,7 +98,6 @@ const MAX_PROBE_WINDOW = 20
 const TOKEN_FLUSH_INTERVAL_MS = 60000
 const CONFIG_RELOAD_INTERVAL_MS = 10000
 const STATS_RETENTION_DAYS = 90
-const TIER_ORDER = ['S+', 'S', 'A+', 'A', 'A-', 'B+', 'B', 'C']
 const RETRYABLE_STATUS_CODES = new Set([429, 500, 502, 503])
 const AUTH_STATUS_CODES = new Set([401, 403])
 const RATE_LIMIT_HEADER_NAMES = [
@@ -110,14 +124,7 @@ function modelKey(provider, model) {
   return `${provider}/${model}`
 }
 
-function safeJsonParse(raw, fallback = null) {
-  try {
-    return JSON.parse(raw)
-  } catch {
-    return fallback
-  }
-}
-
+// 📖 parseJsonResult is still local — it returns {ok, value/error} which is different from safeJsonParse
 function parseJsonResult(raw) {
   try {
     return { ok: true, value: JSON.parse(raw) }
@@ -126,16 +133,6 @@ function parseJsonResult(raw) {
   }
 }
 
-function atomicWriteJson(path, data, mode = 0o600) {
-  const tempPath = `${path}.tmp-${process.pid}-${Date.now()}`
-  writeFileSync(tempPath, JSON.stringify(data, null, 2), { mode })
-  renameSync(tempPath, path)
-}
-
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms))
-}
-
 function isProcessAlive(pid) {
   if (!Number.isInteger(pid) || pid <= 0) return false
   try {
@@ -208,12 +205,6 @@ function isLikelyHtmlResponse(headers, text = '') {
 
 // ─── Web Dashboard Helpers ─────────────────────────────────────────────────────
 
-function maskApiKey(key) {
-  if (!key || typeof key !== 'string') return ''
-  if (key.length <= 8) return '••••••••'
-  return '••••••••' + key.slice(-4)
-}
-
 // 📖 Same-origin / loopback check for state-changing or secret-revealing
 // 📖 endpoints. Blocks CSRF from malicious tabs and key exfiltration from
 // 📖 cross-origin scripts. Plain CLI calls (curl/fetch without Origin) are
@@ -540,11 +531,6 @@ function getApiModelId(providerKey, modelId) {
   return providerKey === 'zai' ? modelId.replace(/^zai\//, '') : modelId
 }
 
-function isRouteableProvider(providerKey) {
-  const source = sources[providerKey]
-  return Boolean(source?.url && !source.cliOnly && source.url.includes('/chat/completions'))
-}
-
 function resolveProviderUrl(providerKey) {
   const url = sources[providerKey]?.url
   if (!url) return null
@@ -898,7 +884,7 @@ class RouterRuntime {
           tier,
           sweScore,
           ctx,
-          routeable: isRouteableProvider(providerKey),
+          routeable: isRouteableProvider(providerKey, sources),
         })
       }
     }
@@ -1178,6 +1164,25 @@ class RouterRuntime {
     })
   }
 
+  // 📖 getRoutingCandidates — the ordered list of models the router will try,
+  // 📖 in EXACT attempt order. This is the heart of routing.
+  // 📖
+  // 📖 Strategy (priority-first): the user's priority order is authoritative.
+  // 📖 A model ranked #1 is always tried first while it is healthy, even if a
+  // 📖 lower-priority model has a better health score. The health score is only
+  // 📖 used to break ties between models that share the same priority — which
+  // 📖 happens in practice when multiple models tie because they have no probe
+  // 📖 data yet (cold start) or identical stats.
+  // 📖
+  // 📖 Why: before this, priority was only 20% of the score and a fast
+  // 📖 low-priority model could steal traffic from a deliberately higher-ranked
+  // 📖 one (see issue #120 — GPT-OSS 120B served despite higher-priority models
+  // 📖 being healthy). Users set the fallback chain on purpose; routing must
+  // 📖 respect it.
+  // 📖
+  // 📖 Circuit-breaker safety is preserved: CLOSED (healthy) models always come
+  // 📖 before HALF_OPEN (probing after cooldown) models, so a recovering model
+  // 📖 never pre-empts a known-good one.
   getRoutingCandidates(set) {
     const scored = this.scoreCandidates(set)
     const usable = scored.filter((candidate) => {
@@ -1189,8 +1194,26 @@ class RouterRuntime {
     })
     const closed = usable.filter((candidate) => candidate.circuit.state === 'CLOSED')
     const halfOpen = usable.filter((candidate) => candidate.circuit.state === 'HALF_OPEN')
-    const byScore = (a, b) => b.score - a.score || a.priority - b.priority
-    return [...closed.sort(byScore), ...halfOpen.sort(byScore)]
+    // 📖 Priority ascending (1 before 2); within the same priority, healthier
+    // 📖 score wins so cold-start ties resolve deterministically.
+    const byPriorityThenHealth = (a, b) => a.priority - b.priority || b.score - a.score
+    return [...closed.sort(byPriorityThenHealth), ...halfOpen.sort(byPriorityThenHealth)]
+  }
+
+  // 📖 getRoutingOrder — slim projection of getRoutingCandidates for the /stats
+  // 📖 payload and dashboards. Exposes the EXACT order the router will attempt
+  // 📖 on the next request, so the UI can mark the model that will serve it
+  // 📖 (routingOrder[0]) and label every entry as Primary vs Fallback.
+  // 📖 Cheap to compute: reuses getRoutingCandidates + already-recorded health.
+  getRoutingOrder(set) {
+    return this.getRoutingCandidates(set).map((candidate) => ({
+      key: candidate.key,
+      provider: candidate.provider,
+      model: candidate.model,
+      priority: candidate.priority,
+      state: candidate.circuit?.state || 'UNKNOWN',
+      score: Number(candidate.score.toFixed(4)),
+    }))
   }
 
   getModelHealth(set = this.getSet()) {
@@ -1210,6 +1233,11 @@ class RouterRuntime {
       last_latency_ms: candidate.stats.last?.latencyMs ?? null,
       uptime: candidate.stats.uptime,
       last_error: candidate.circuit?.lastError || null,
+      // 📖 AI Latency benchmark results for the Router Dashboard's "Probe all"
+      // 📖 button. Mirrors the per-model fields already exposed on /api/models
+      // 📖 so the set list can show live AI latency + TPS after a probe.
+      isBenchmarking: this.webBenchmarkRunning?.has(candidate.key) || false,
+      benchmark: this.webBenchmarkResults?.get(candidate.key) || null,
     }))
   }
 
@@ -1346,6 +1374,11 @@ class RouterRuntime {
     const activeSet = this.getSet(router.activeSet)
     return {
       ok: true,
+      // 📖 `running` mirrors `ok` so every consumer (Router view reads `ok`,
+      // 📖 Playground reads `running`) agrees on daemon state. Without this,
+      // 📖 the Playground showed "router offline" even when the Router card
+      // 📖 said "Running" — both hit /api/router/status but read different fields.
+      running: true,
       pid: process.pid,
       port: this.port,
       enabled: router.enabled,
@@ -1386,6 +1419,19 @@ class RouterRuntime {
       ...this.statusPayload(),
       tokens: this.tokenTracker.summary(),
       models: this.getModelHealth(activeSet),
+      // 📖 routingOrder — the exact attempt order for the next request
+      // 📖 (priority-first among healthy models). routingOrder[0] is what will
+      // 📖 serve the next chat completion. Surfaced so dashboards can mark the
+      // 📖 "next" model and label Primary vs Fallback semantics. See issue #120.
+      routingOrder: this.getRoutingOrder(activeSet),
+      // 📖 Global AI Latency probe progress — powers the Router Dashboard's
+      // 📖 "Probe all" button progress bar. Per-model results live on each
+      // 📖 entry of `models` above (isBenchmarking / benchmark).
+      globalBenchmark: {
+        running: this.webGlobalBenchmarkRunning || false,
+        total: this.webGlobalBenchmarkTotal || 0,
+        completed: this.webGlobalBenchmarkCompleted || 0,
+      },
       requestLog: this.requestLog.slice(0, 20),
       circuitBreakers: Object.fromEntries([...this.circuit.entries()].map(([key, value]) => [key, {
         state: value.authError ? 'AUTH_ERROR' : value.stale ? 'STALE' : value.unsupported ? 'UNSUPPORTED' : value.state,
@@ -1501,7 +1547,7 @@ class RouterRuntime {
     // 📖 skip that provider as a candidate for replacements.
     const providerProbeStats = new Map() // provider -> { probed: n, authError: n, stale: n, alive: n }
     for (const [providerKey, source] of Object.entries(sources)) {
-      if (!isRouteableProvider(providerKey)) continue
+      if (!isRouteableProvider(providerKey, sources)) continue
       if (!providerProbeStats.has(providerKey)) providerProbeStats.set(providerKey, { probed: 0, authError: 0, stale: 0, alive: 0 })
       for (const [modelId, , tier, sweScore, ctx] of source.models || []) {
         const key = `${providerKey}/${modelId}`
@@ -2646,7 +2692,7 @@ class RouterRuntime {
       if (req.method === 'GET' && url.pathname === '/api/router/catalog') {
         const rows = []
         for (const [providerKey, source] of Object.entries(sources)) {
-          if (!isRouteableProvider(providerKey)) continue
+          if (!isRouteableProvider(providerKey, sources)) continue
           if (!Array.isArray(source.models)) continue
           for (const [modelId, label, tier, sweScore, ctx] of source.models) {
             rows.push({
@@ -3028,7 +3074,7 @@ export async function buildDefaultRouterSet(config = {}, maxModels, options = {}
   if (maxModels === undefined) maxModels = Math.max(5, keyedProviders.size * 2)
   const entries = []
   for (const [providerKey, source] of Object.entries(sources)) {
-    if (!isRouteableProvider(providerKey)) continue
+    if (!isRouteableProvider(providerKey, sources)) continue
     for (const [model, label, tier, sweScore, ctx] of source.models || []) {
       entries.push({
         provider: providerKey,
@@ -3184,7 +3230,7 @@ export function createRouterRuntimeForTest({ config, port = 0, logger = null, to
 function createDefaultProbeFn(apiKeys) {
   return async (entry) => {
     const { provider, model } = entry
-    if (!isRouteableProvider(provider)) return { ok: false, code: 'NOT_ROUTEABLE', latencyMs: 0 }
+    if (!isRouteableProvider(provider, sources)) return { ok: false, code: 'NOT_ROUTEABLE', latencyMs: 0 }
     const url = resolveProviderUrl(provider)
     if (!url) return { ok: false, code: 'NO_URL', latencyMs: 0 }
     const apiKey = getApiKey({ apiKeys: apiKeys || {} }, provider) || ''
@@ -3239,7 +3285,7 @@ function buildDefaultRouterSetSync(config = {}, maxModels = 5) {
     .map(([provider]) => provider))
   const entries = []
   for (const [providerKey, source] of Object.entries(sources)) {
-    if (!isRouteableProvider(providerKey)) continue
+    if (!isRouteableProvider(providerKey, sources)) continue
     for (const [model, label, tier, sweScore, ctx] of source.models || []) {
       entries.push({ provider: providerKey, model, label, tier, sweScore, ctx, hasKey: keyedProviders.has(providerKey) })
     }
@@ -3323,7 +3369,7 @@ function buildRouterSetFromFavorites(config) {
     if (slashIdx < 0) continue
     const providerKey = fav.slice(0, slashIdx)
     const modelId = fav.slice(slashIdx + 1)
-    if (!isRouteableProvider(providerKey)) continue
+    if (!isRouteableProvider(providerKey, sources)) continue
     const source = sources[providerKey]
     if (!source) continue
     const found = (source.models || []).find((m) => m[0] === modelId)
@@ -3381,6 +3427,13 @@ async function listenWithFallback(server, preferredPort, logger, host = '127.0.0
 export async function runRouterDaemon() {
   const config = loadConfig()
   const router = await ensureRouterConfigForDaemon(config)
+  // 📖 In dev mode, override the saved port with the dev default so a local
+  // 📖 checkout doesn't clash with a production install on the same machine.
+  // 📖 The saved config has port: 19280 (production); dev should use 29280.
+  const { defaultPort: devDefault } = getRouterPortRange()
+  if (_dev && router.port !== devDefault && router.port === DEFAULT_ROUTER_SETTINGS.port) {
+    router.port = devDefault
+  }
   const logger = new RouterLogger(ROUTER_LOG_PATH, router.logLevel)
   const runtime = new RouterRuntime({ config, port: router.port, logger })
   runtime.installProcessSafety()
@@ -3443,7 +3496,12 @@ export async function runRouterDaemon() {
 export async function getRouterDaemonStatus() {
   const { defaultPort, maxPort } = getRouterPortRange()
   const ports = []
-  const recordedPort = readNumberFile(ROUTER_PORT_PATH)
+  // 📖 Use the dynamic path resolvers so dev checkouts (FCM_DEV=1) read the
+  // 📖 `-dev` port/pid files and discover the dev daemon. The static constants
+  // 📖 are frozen at module load and would always point at the production files.
+  const portPath = getRouterPortPath()
+  const pidPath = getRouterPidPath()
+  const recordedPort = readNumberFile(portPath)
   if (recordedPort) ports.push(recordedPort)
   for (let port = defaultPort; port <= maxPort; port += 1) {
     if (!ports.includes(port)) ports.push(port)
@@ -3456,7 +3514,7 @@ export async function getRouterDaemonStatus() {
       // 📖 Keep scanning the small discovery range.
     }
   }
-  const pid = readNumberFile(ROUTER_PID_PATH)
+  const pid = readNumberFile(pidPath)
   return {
     ok: false,
     running: false,