free-coding-models 0.5.28 → 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.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.28",
+  "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

@@ -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/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()) {
@@ -1386,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,
@@ -1501,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}`
@@ -2646,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({
@@ -3028,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,
@@ -3184,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) || ''
@@ -3239,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) })
     }
@@ -3323,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)
@@ -3381,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()

package/src/core/router-dashboard.js

@@ -33,6 +33,7 @@
  * @exports fetchRouterSets, createRouterSet, renameRouterSet, duplicateRouterSet
  * @exports deleteRouterSet, activateRouterSet, updateRouterSetModels
  * @exports addModelToRouterSet, removeModelFromRouterSet, reorderRouterSetModel
+ * @exports setDashboardNotice
  *
  * @see ./router-daemon.js — daemon endpoints consumed by this screen
  * @see ./overlays.js — overlay factory that mounts this renderer
@@ -42,7 +43,7 @@
 import chalk from 'chalk'
 import { existsSync, readFileSync } from 'node:fs'
 import { displayWidth, padEndDisplay, sliceOverlayLines, tintOverlayLines } from '../tui/render-helpers.js'
-import { ROUTER_DEFAULT_PORT, ROUTER_MAX_PORT, ROUTER_PID_PATH, ROUTER_PORT_PATH, getRouterPortRange } from './router-daemon.js'
+import { ROUTER_DEFAULT_PORT, ROUTER_MAX_PORT, getRouterPidPath, getRouterPortPath, getRouterPortRange } from './router-daemon.js'
 import { themeColors, getTierRgb } from '../tui/theme.js'
 import { formatTokenTotalCompact } from './token-usage-reader.js'
 import { sendUsageTelemetry } from './telemetry.js'
@@ -150,14 +151,16 @@ async function fetchJson(url, options = {}) {
 }
 
 function readDaemonFiles() {
-  const recordedPort = readNumberFile(ROUTER_PORT_PATH)
-  const recordedPid = readNumberFile(ROUTER_PID_PATH)
+  const portPath = getRouterPortPath()
+  const pidPath = getRouterPidPath()
+  const recordedPort = readNumberFile(portPath)
+  const recordedPid = readNumberFile(pidPath)
   return {
     port: recordedPort,
     pid: recordedPid,
     pidAlive: recordedPid ? isProcessAlive(recordedPid) : false,
-    hasPidFile: existsSync(ROUTER_PID_PATH),
-    hasPortFile: existsSync(ROUTER_PORT_PATH),
+    hasPidFile: existsSync(pidPath),
+    hasPortFile: existsSync(portPath),
   }
 }
 
@@ -168,7 +171,7 @@ function buildPortCandidates(state) {
     ? state.routerDashboardBaseUrl.match(/:(\d+)$/)
     : null
   const baseUrlPort = baseUrlMatch ? Number.parseInt(baseUrlMatch[1], 10) : null
-  const filePort = readNumberFile(ROUTER_PORT_PATH)
+  const filePort = readNumberFile(getRouterPortPath())
   const { defaultPort, maxPort } = getRouterPortRange()
   for (const port of [baseUrlPort, currentPort, filePort, defaultPort]) {
     if (Number.isInteger(port) && port > 0 && !ports.includes(port)) ports.push(port)
@@ -259,6 +262,21 @@ export function normalizeRouterDashboardSnapshot(healthPayload, statsPayload) {
   const merged = { ...health, ...stats }
   const models = Array.isArray(stats.models) ? stats.models.map(normalizeModelHealth) : []
   const requestLog = Array.isArray(stats.requestLog) ? stats.requestLog.map(normalizeRequestEntry) : []
+  // 📖 routingOrder — priority-first attempt order from /stats (issue #120).
+  // 📖 routingOrder[0].key is the model that will serve the next request, so the
+  // 📖 TUI can mark it with a ▶ NEXT glyph. Guarded so older daemons without
+  // 📖 the field still render fine.
+  const routingOrder = Array.isArray(stats.routingOrder)
+    ? stats.routingOrder
+        .filter((entry) => isRecord(entry) && typeof entry.key === 'string')
+        .map((entry) => ({
+          key: entry.key,
+          provider: safeString(entry.provider, ''),
+          model: safeString(entry.model, ''),
+          priority: toFiniteNumber(entry.priority, 0),
+          state: safeString(entry.state, 'UNKNOWN'),
+        }))
+    : []
 
   return {
     ok: merged.ok === true,
@@ -281,6 +299,7 @@ export function normalizeRouterDashboardSnapshot(healthPayload, statsPayload) {
     stalePid: toFiniteNumber(merged.stalePid, null),
     tokens: normalizeTokens(stats.tokens),
     models,
+    routingOrder,
     requestLog,
   }
 }
@@ -331,7 +350,7 @@ function statusBadge(status, snapshot) {
   return themeColors.error('○ UNREACHABLE')
 }
 
-function setDashboardNotice(state, type, message, ttlMs = 3500) {
+export function setDashboardNotice(state, type, message, ttlMs = 3500) {
   state.routerDashboardNotice = { type, message, at: Date.now() }
   if (state.routerDashboardNoticeTimer) clearTimeout(state.routerDashboardNoticeTimer)
   state.routerDashboardNoticeTimer = setTimeout(() => {
@@ -843,15 +862,19 @@ export function renderRouterDashboard(state, deps = {}) {
   lines.push(`  ${paintBanner(bannerLine)}`)
   lines.push('')
 
-  // ── Quick Setup (connection info) ───────────────────────────────────────────
-  const port = snapshot.port || state.routerDashboardPort || '—'
-  const baseUrl = isRunning ? `http://localhost:${port}/v1` : `http://localhost:${port}/v1`
-  lines.push(`  ${themeColors.textBold('Quick Setup')} ${themeColors.dim('— paste into your coding tool')}`)
-  lines.push(`  ${themeColors.dim('URL')}     ${themeColors.info(baseUrl)}`)
-  lines.push(`  ${themeColors.dim('Model')}   ${themeColors.info('fcm')}`)
-  lines.push(`  ${themeColors.dim('API Key')} ${themeColors.info('fcm-local')}`)
+  // ── Quick Setup (connection info) — HERO section ──────────────────────────
+  // 📖 Always visible with default port 19280 so users can copy even when stopped.
+  const { defaultPort: currentDefaultPort } = getRouterPortRange()
+  const port = snapshot.port || state.routerDashboardPort || currentDefaultPort
+  const baseUrl = `http://localhost:${port}/v1`
+  lines.push(`  ${themeColors.textBold('Quick Setup')} ${themeColors.dim('— paste into your coding tool config')}`)
+  lines.push(`  ${themeColors.dim('URL')}     ${themeColors.infoBold(baseUrl)}`)
+  lines.push(`  ${themeColors.dim('Model')}   ${themeColors.infoBold('fcm')}`)
+  lines.push(`  ${themeColors.dim('API Key')} ${themeColors.infoBold('fcm-local')}`)
   if (isRunning) {
     lines.push(`  ${themeColors.dim('Uptime')}  ${themeColors.success(formatRouterDuration(snapshot.uptimeSeconds))}  ${themeColors.dim('Requests routed:')} ${themeColors.info(String(snapshot.requestsRouted))}`)
+  } else {
+    lines.push(`  ${themeColors.dim('Hint')}    ${themeColors.dim('Start the daemon to enable routing')}`)
   }
   lines.push(`  ${separator}`)
   lines.push('')
@@ -868,7 +891,8 @@ export function renderRouterDashboard(state, deps = {}) {
   const cursor = state.routerDashboardCursorIndex ?? 0
 
   if (favorites.length === 0) {
-    lines.push(`  ${themeColors.warning('No favorites yet.')} ${themeColors.dim('Press Esc, then F on any model to add it.')}`)
+    lines.push(`  ${themeColors.warning('No favorites yet. Press Esc, then F on any model to add it.')}`)
+    lines.push(`  ${themeColors.dim('Favorites become your router fallback chain — #1 is tried first.')}`)
   } else {
     // 📖 Priority keycap glyphs for the fallback order
     const KEYCAPS = ['1️⃣','2️⃣','3️⃣','4️⃣','5️⃣','6️⃣','7️⃣','8️⃣','9️⃣','🔟']
@@ -880,8 +904,13 @@ export function renderRouterDashboard(state, deps = {}) {
       healthByKey.set(`${m.provider}/${m.model}`, m)
     }
 
-    // 📖 Column headers
-    lines.push(`  ${themeColors.dim(padEndDisplay('PRI', 4))} ${themeColors.dim(padEndDisplay('MODEL', 42))} ${themeColors.dim(padEndDisplay('DAEMON STATUS', 16))} ${themeColors.dim(padEndDisplay('AVG PING', 8))} ${themeColors.dim('VERDICT')}`)
+    // 📖 The model the daemon will serve on the next request (priority-first,
+    // 📖 see issue #120). Marked with ▶ NEXT so the user understands the top
+    // 📖 of the chain is what actually handles traffic — not whichever is fastest.
+    const nextToServeKey = snapshot.routingOrder?.[0]?.key || null
+
+    // 📖 Column headers — leading space lines up with the ▶ NEXT marker column.
+    lines.push(`   ${themeColors.dim(padEndDisplay('PRI', 4))} ${themeColors.dim(padEndDisplay('MODEL', 42))} ${themeColors.dim(padEndDisplay('STATUS', 16))} ${themeColors.dim(padEndDisplay('AVG PING', 8))} ${themeColors.dim('VERDICT')}`)
 
     for (let i = 0; i < favorites.length; i++) {
       const favKey = favorites[i]
@@ -926,14 +955,14 @@ export function renderRouterDashboard(state, deps = {}) {
       }
 
       // 📖 Get global metrics from main table state
-      let avgPingDisplay = themeColors.dim('———')
+      let avgPingDisplay = themeColors.dim('—')
       let verdictDisplay = themeColors.dim('Pending ⏳')
 
       if (mainResult) {
         // Avg Ping
         const avg = getAvg(mainResult)
         if (avg !== Infinity) {
-          const str = String(avg).padEnd(4)
+          const str = `${avg}ms`
           avgPingDisplay = avg < 500 ? themeColors.metricGood(str) : avg < 1500 ? themeColors.metricWarn(str) : themeColors.metricBad(str)
         }
 
@@ -957,7 +986,13 @@ export function renderRouterDashboard(state, deps = {}) {
         verdictDisplay = padEndDisplay(verdictDisplay, 14)
       }
 
-      const rowText = `  ${padEndDisplay(priorityGlyph(i), 4)} ${padEndDisplay(favKey, 42)} ${padEndDisplay(healthLabel, 16)} ${padEndDisplay(avgPingDisplay, 8)} ${verdictDisplay}`
+      // 📖 Prefix the next-to-serve model with a ▶ NEXT marker so the active
+      // 📖 routing target is obvious. Only shown when the daemon is actually
+      // 📖 running and has reported a routing order (stopped → no marker).
+      const nextMarker = (nextToServeKey && nextToServeKey === favKey)
+        ? themeColors.successBold('▶')
+        : themeColors.dim(' ')
+      const rowText = ` ${nextMarker} ${padEndDisplay(priorityGlyph(i), 4)} ${padEndDisplay(favKey, 42)} ${padEndDisplay(healthLabel, 16)} ${padEndDisplay(avgPingDisplay, 8)} ${verdictDisplay}`
 
       if (isCursorRow) {
         lines.push(themeColors.bgCursor(rowText + ' '.repeat(Math.max(0, width - displayWidth(rowText) - 3))))
@@ -996,14 +1031,14 @@ export function renderRouterDashboard(state, deps = {}) {
   lines.push(`  ${separator}`)
   lines.push('')
 
-  // ── Token Summary (compact) ─────────────────────────────────────────────────
-  lines.push(`  ${themeColors.textBold('Tokens')}  ${themeColors.dim('Today:')} ${themeColors.info(formatTokenTotalCompact(snapshot.tokens.today.total_tokens))}  ${themeColors.dim('All-time:')} ${themeColors.info(formatTokenTotalCompact(snapshot.tokens.all_time.total_tokens))}  ${themeColors.dim('Requests:')} ${snapshot.tokens.today.requests}/${snapshot.tokens.all_time.requests}`)
+  // ── Token Summary (compact, visual) ─────────────────────────────────────────
+  lines.push(`  ${themeColors.textBold('📊 Tokens')}  ${themeColors.dim('Today:')} ${themeColors.info(formatTokenTotalCompact(snapshot.tokens.today.total_tokens))} ${themeColors.dim(`(${snapshot.tokens.today.requests} req)`)}  ${themeColors.dim('Lifetime:')} ${themeColors.info(formatTokenTotalCompact(snapshot.tokens.all_time.total_tokens))} ${themeColors.dim(`(${snapshot.tokens.all_time.requests} req)`)}`)
 
   // ── Live Request Log (compact) ──────────────────────────────────────────────
   const requestRows = requestLogRows(state, snapshot)
+  lines.push('')
+  lines.push(`  ${themeColors.textBold('Recent Requests')}`)
   if (requestRows.length > 0) {
-    lines.push('')
-    lines.push(`  ${themeColors.textBold('Recent Requests')}`)
     const header = `  ${padEndDisplay('Time', 10)} ${padEndDisplay('Model', 34)} ${padEndDisplay('Status', 8)} ${padEndDisplay('Latency', 9)} Detail`
     lines.push(themeColors.dim(header))
     for (const row of requestRows.slice(0, 6)) {
@@ -1025,6 +1060,8 @@ export function renderRouterDashboard(state, deps = {}) {
         `${compactText(detail, Math.max(10, width - 68)).trimEnd()}`
       )
     }
+  } else {
+    lines.push(`  ${themeColors.dim('No requests routed yet')}`)
   }
 
   // ── Health check speed ──────────────────────────────────────────────────────
@@ -1048,7 +1085,8 @@ export function renderRouterDashboard(state, deps = {}) {
 
   // ── Footer ──────────────────────────────────────────────────────────────────
   lines.push('')
-  lines.push(`  ${themeColors.hotkey('↑↓')} ${themeColors.dim('Navigate')}  ${themeColors.dim('•')}  ${themeColors.hotkey('Shift+↑↓')} ${themeColors.dim('Reorder')}  ${themeColors.dim('•')}  ${themeColors.hotkey('S')} ${themeColors.dim(isStopped ? 'Start daemon' : 'Stop daemon')}  ${themeColors.dim('•')}  ${themeColors.hotkey('I')} ${themeColors.dim(`Health check: ${probeLabel}`)}  ${themeColors.dim('•')}  ${themeColors.hotkey('C')} ${themeColors.dim('Clear log')}  ${themeColors.dim('•')}  ${themeColors.hotkey('Esc')} ${themeColors.dim('Back')}`)
+  lines.push(`  ${separator}`)
+  lines.push(`  ${themeColors.hotkey('↑↓')} ${themeColors.dim('Navigate')}  ${themeColors.dim('•')}  ${themeColors.hotkey('Shift+↑↓')} ${themeColors.dim('Reorder')}  ${themeColors.dim('•')}  ${themeColors.hotkey('S')} ${themeColors.dim(isStopped ? 'Start daemon' : 'Stop daemon')}  ${themeColors.dim('•')}  ${themeColors.hotkey('I')} ${themeColors.dim(`Health check: ${probeLabel}`)}  ${themeColors.dim('•')}  ${themeColors.hotkey('C')} ${themeColors.dim('Clear log')}  ${themeColors.dim('•')}  ${themeColors.hotkey('R')} ${themeColors.dim('Sync best')}  ${themeColors.dim('•')}  ${themeColors.hotkey('Esc')} ${themeColors.dim('Back')}`)
 
   const { visible, offset } = sliceOverlayLines(lines, state.routerDashboardScrollOffset || 0, state.terminalRows || 24)
   state.routerDashboardScrollOffset = offset