free-coding-models 0.5.27 → 0.5.29

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.27.md

@@ -13,3 +13,5 @@
 
 ### Fixed
 - Fixed first-run usability for keyless providers by allowing Kilo and LLM7 to count as usable providers without forcing the API key wizard.
+- Fixed Docker dashboard 404s by serving the Web Router Dashboard aliases (`/api/router/status`, `/api/router/stats`, `/api/router/sets`, `/api/router/tokens`, `/api/router/quick-setup`) and `/api/changelog` directly from the router daemon.
+- Fixed confusing "pending" status for models not in the active router set. Models outside the set now show a distinct "NOT IN SET" label with a dim dot and faded row, instead of the animated yellow "wait" indicator. Applies to Web Dashboard (both Docker daemon and local dev mode).

package/changelog/v0.5.28.md

@@ -0,0 +1,5 @@
+# Changelog v0.5.28 - 2026-06-11
+
+### Fixed
+- Fixed Docker dashboard 404s — the router daemon now serves 10 web dashboard API aliases (`/api/router/status`, `/api/router/stats`, `/api/router/sets`, `/api/router/tokens`, `/api/router/quick-setup`, `/api/router/start`, `/api/router/stop`, `/api/router/probe-mode`, `/api/router/sets/:name/*`, `/api/changelog`) directly, so the React frontend works identically in Docker mode and local dev. Cross-origin guards protect mutating endpoints. (Fixes #116, reported by @stgreenb)
+- Fixed confusing "pending" status for models not in the active router set — models outside the set now show a distinct "NOT IN SET" label with a dim gray dot and faded row opacity, instead of the animated yellow "wait" indicator. The `inRouterSet` field is now exposed by both the Docker daemon and the local web server. (Fixes #117, reported by @stgreenb)

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

@@ -1,6 +1,6 @@
 {
   "name": "free-coding-models",
-  "version": "0.5.27",
+  "version": "0.5.29",
   "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

@@ -210,6 +210,18 @@ function normalizeFavoriteList(favorites) {
   return normalized
 }
 
+// 📖 normalizeStringSet: Convert an array (from JSON) or existing Set into a Set<string>.
+// 📖 Used for hiddenModels and similar set-shaped config fields.
+function normalizeStringSet(value) {
+  if (value instanceof Set) return value
+  if (!Array.isArray(value)) return new Set()
+  const result = new Set()
+  for (const entry of value) {
+    if (typeof entry === 'string' && entry.trim()) result.add(entry.trim())
+  }
+  return result
+}
+
 function normalizeApiKeyValue(value) {
   if (Array.isArray(value)) {
     const normalized = []
@@ -263,6 +275,7 @@ function normalizeSettingsSection(settings) {
     hideUnconfiguredModels: typeof safeSettings.hideUnconfiguredModels === 'boolean' ? safeSettings.hideUnconfiguredModels : true,
     favoritesPinnedAndSticky: typeof safeSettings.favoritesPinnedAndSticky === 'boolean' ? safeSettings.favoritesPinnedAndSticky : false,
     runAiSpeedTestOnStartup: typeof safeSettings.runAiSpeedTestOnStartup === 'boolean' ? safeSettings.runAiSpeedTestOnStartup : false,
+    autoHideBrokenModels: typeof safeSettings.autoHideBrokenModels === 'boolean' ? safeSettings.autoHideBrokenModels : true,
     theme: ['dark', 'light', 'auto'].includes(safeSettings.theme) ? safeSettings.theme : 'auto',
   }
 }
@@ -451,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 : {}
@@ -471,8 +474,9 @@ function normalizeConfigShape(config) {
     favorites: normalizeFavoriteList(safeConfig.favorites),
     telemetry: normalizeTelemetrySection(safeConfig.telemetry),
     endpointInstalls: normalizeEndpointInstalls(safeConfig.endpointInstalls),
-
-
+    // 📖 hiddenModels: Set of "provider/modelId" keys auto-hidden by the 404 probe (Ctrl+Shift+P).
+    // 📖 Only populated when settings.autoHideBrokenModels is true (default).
+    hiddenModels: normalizeStringSet(safeConfig.hiddenModels),
   }
   const normalizedRouter = normalizeRouterConfig(safeConfig.router)
   if (normalizedRouter) normalized.router = normalizedRouter
@@ -513,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
@@ -684,8 +685,12 @@ export function saveConfig(config, options = {}) {
 
   try {
     const persistedConfig = buildPersistedConfig(config, readStoredConfigSnapshot(), options)
-    const json = JSON.stringify(persistedConfig, null, 2)
-    writeFileSync(tempPath, json, { mode: 0o600 })
+    // 📖 Serialize Sets to arrays for JSON compatibility (e.g. hiddenModels)
+    const jsonSafe = JSON.stringify(persistedConfig, (key, value) => {
+      if (value instanceof Set) return [...value]
+      return value
+    }, 2)
+    writeFileSync(tempPath, jsonSafe, { mode: 0o600 })
     renameSync(tempPath, CONFIG_PATH)
 
     // 📖 Verify the write succeeded by reading back and validating
@@ -1082,6 +1087,7 @@ export function _emptyProfileSettings() {
     hideUnconfiguredModels: true, // 📖 true = default to providers that are actually configured
     favoritesPinnedAndSticky: false, // 📖 default mode keeps favorites as normal starred rows; press Y to pin+stick them.
     runAiSpeedTestOnStartup: false, // 📖 opt-in: automatically fire the Ctrl+U global AI Speed Test after startup.
+    autoHideBrokenModels: true, // 📖 opt-out: auto-hide models that return 404/410 from probe (Ctrl+Shift+P).
     preferredToolMode: 'opencode', // 📖 remember the last Z-selected launcher across app restarts
     theme: 'auto',        // 📖 'auto' follows the terminal/OS theme, override with 'dark' or 'light' if needed
   }
@@ -1131,5 +1137,6 @@ function _emptyConfig() {
     telemetry: { enabled: null, consentVersion: 0, anonymousId: null },
     endpointInstalls: [],
     settings: _emptyProfileSettings(),
+    hiddenModels: new Set(),
   }
 }

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/router-daemon.js

@@ -49,7 +49,10 @@ import {
 } from './config.js'
 import { buildChatCompletionPingBody, ping, resolveCloudflareUrl, shouldUseDisabledThinkingForProvider } from './ping.js'
 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
@@ -58,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 }
 }
@@ -82,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 = [
@@ -109,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) }
@@ -125,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 {
@@ -207,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
@@ -539,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
@@ -897,7 +884,7 @@ class RouterRuntime {
           tier,
           sweScore,
           ctx,
-          routeable: isRouteableProvider(providerKey),
+          routeable: isRouteableProvider(providerKey, sources),
         })
       }
     }
@@ -1177,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) => {
@@ -1188,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()) {
@@ -1385,6 +1409,11 @@ 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),
       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,
@@ -1500,7 +1529,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}`
@@ -2397,8 +2426,8 @@ class RouterRuntime {
    * 📖 with only the ones that come back 2xx. Returns the new set + a
    * 📖 sample of probe results so the UI can show "what changed".
    */
-  async handleSyncSetRequest(req, res, requestId) {
-    const url = req.url ? new URL(req.url, 'http://localhost') : null
+  async handleSyncSetRequest(req, res, requestId, routeUrl = null) {
+    const url = routeUrl || (req.url ? new URL(req.url, 'http://localhost') : null)
     const pathname = url ? url.pathname : ''
     const setSyncMatch = pathname.match(/^\/sets\/([^/]+)\/sync$/)
     if (!setSyncMatch) {
@@ -2524,6 +2553,87 @@ class RouterRuntime {
         await this.handleProbeModeRequest(req, res, requestId)
         return
       }
+
+      // 📖 Docker mode serves the built Web Dashboard directly from the daemon
+      // 📖 on :19280. The React app uses the same `/api/router/*` routes as
+      // 📖 local dev (`web/server.js`), so the daemon must expose aliases for
+      // 📖 its canonical `/health`, `/stats`, and `/sets` APIs instead of
+      // 📖 forcing the frontend to special-case Docker.
+      if (req.method === 'GET' && url.pathname === '/api/router/status') {
+        sendJson(res, 200, this.statusPayload(), { 'x-request-id': requestId })
+        return
+      }
+      if (req.method === 'GET' && url.pathname === '/api/router/stats') {
+        sendJson(res, 200, this.statsPayload(), { 'x-request-id': requestId })
+        return
+      }
+      if (req.method === 'GET' && url.pathname === '/api/router/tokens') {
+        sendJson(res, 200, this.tokenTracker.summary(), { 'x-request-id': requestId })
+        return
+      }
+      if (req.method === 'GET' && url.pathname === '/api/router/quick-setup') {
+        const router = this.routerConfig()
+        sendJson(res, 200, {
+          running: true,
+          port: this.port,
+          baseUrl: `http://127.0.0.1:${this.port}/v1`,
+          model: 'fcm',
+          activeSet: router.activeSet || DEFAULT_ROUTER_SETTINGS.activeSet,
+          apiKey: 'not-needed',
+        }, { 'x-request-id': requestId })
+        return
+      }
+      if (url.pathname === '/api/router/start') {
+        if (req.method !== 'POST') {
+          sendError(res, 405, 'Method not allowed', 'invalid_request_error', 'method_not_allowed', requestId, { allowed: ['POST'] })
+          return
+        }
+        if (!isSameOriginOrLocal(req)) {
+          sendError(res, 403, 'Forbidden cross-origin request', 'invalid_request_error', 'forbidden_origin', requestId)
+          return
+        }
+        sendJson(res, 200, { ...this.statusPayload(), alreadyRunning: true }, { 'x-request-id': requestId })
+        return
+      }
+      if (url.pathname === '/api/router/stop') {
+        if (req.method !== 'POST') {
+          sendError(res, 405, 'Method not allowed', 'invalid_request_error', 'method_not_allowed', requestId, { allowed: ['POST'] })
+          return
+        }
+        if (!isSameOriginOrLocal(req)) {
+          sendError(res, 403, 'Forbidden cross-origin request', 'invalid_request_error', 'forbidden_origin', requestId)
+          return
+        }
+        sendJson(res, 200, { ok: true, stopped: true, message: 'Daemon shutting down' }, { 'x-request-id': requestId })
+        setTimeout(() => this.shutdown(0), 50)
+        return
+      }
+      if (url.pathname === '/api/router/probe-mode' && req.method === 'POST') {
+        if (!isSameOriginOrLocal(req)) {
+          sendError(res, 403, 'Forbidden cross-origin request', 'invalid_request_error', 'forbidden_origin', requestId)
+          return
+        }
+        await this.handleProbeModeRequest(req, res, requestId)
+        return
+      }
+      if (req.method === 'GET' && url.pathname === '/api/changelog') {
+        sendJson(res, 200, loadChangelog(), { 'x-request-id': requestId })
+        return
+      }
+      if (url.pathname === '/api/router/sets' || url.pathname.startsWith('/api/router/sets/')) {
+        if (req.method !== 'GET' && !isSameOriginOrLocal(req)) {
+          sendError(res, 403, 'Forbidden cross-origin request', 'invalid_request_error', 'forbidden_origin', requestId)
+          return
+        }
+        const aliasedUrl = new URL(req.url, `http://localhost:${this.port}`)
+        aliasedUrl.pathname = aliasedUrl.pathname.replace(/^\/api\/router/, '')
+        if (/^\/sets\/[^/]+\/sync$/.test(aliasedUrl.pathname) && req.method === 'POST') {
+          await this.handleSyncSetRequest(req, res, requestId, aliasedUrl)
+          return
+        }
+        await this.handleSetsRequest(req, res, aliasedUrl, requestId)
+        return
+      }
       if (url.pathname === '/sets' || url.pathname.startsWith('/sets/')) {
         // 📖 /sets/:name/sync has a different return type (rebuilds the
         // 📖 set from probes) so it gets its own handler.
@@ -2564,7 +2674,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({
@@ -2946,7 +3056,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,
@@ -3102,7 +3212,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) || ''
@@ -3157,7 +3267,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) })
     }
@@ -3241,7 +3351,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)
@@ -3299,6 +3409,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()