free-coding-models 0.5.28 → 0.5.30

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

package/src/core/shared-helpers.js

@@ -0,0 +1,117 @@
+/**
+ * @file shared-helpers.js
+ * @description Shared utility functions used across multiple modules.
+ *
+ * @details
+ *   📖 DRY helpers extracted from router-daemon.js, tool-launchers.js,
+ *   📖 endpoint-installer.js, and legacy-proxy-cleanup.js to eliminate
+ *   duplicate implementations of the same patterns.
+ *
+ * @functions
+ *   → sleep — Promise-based setTimeout
+ *   → ensureDir — Create parent directory if missing
+ *   → readJson — Read and parse JSON file with fallback
+ *   → writeJson — Write JSON file with directory creation
+ *   → atomicWriteJson — Atomic write via temp file + rename
+ *   → safeJsonParse — JSON.parse with fallback
+ *   → maskApiKey — Mask API key for display (show last 4 chars)
+ *
+ * @exports sleep, ensureDir, readJson, writeJson, atomicWriteJson, safeJsonParse, maskApiKey
+ */
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+
+/**
+ * 📖 Promise-based sleep. Used by daemon probe staggering, TUI animations, etc.
+ * @param {number} ms
+ * @returns {Promise<void>}
+ */
+export function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+/**
+ * 📖 Create parent directory of `filePath` if it doesn't exist.
+ * @param {string} filePath
+ */
+export function ensureDir(filePath) {
+  const dir = dirname(filePath)
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+}
+
+/**
+ * 📖 Read and parse a JSON file. Returns `fallback` on any error.
+ * @param {string} filePath
+ * @param {*} [fallback=null]
+ * @returns {*}
+ */
+export function readJson(filePath, fallback = null) {
+  if (!existsSync(filePath)) return fallback
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf8'))
+  } catch {
+    return fallback
+  }
+}
+
+/**
+ * 📖 Write JSON to file, creating parent directories as needed.
+ * @param {string} filePath
+ * @param {*} value
+ * @param {object} [options]
+ * @param {boolean} [options.backup=false] — Not implemented here; callers handle it
+ */
+export function writeJson(filePath, value) {
+  ensureDir(filePath)
+  writeFileSync(filePath, JSON.stringify(value, null, 2))
+}
+
+/**
+ * 📖 Atomic JSON write: writes to a temp file, then renames over the target.
+ * Prevents partial writes from corrupting the file on crash.
+ * @param {string} path
+ * @param {*} data
+ * @param {number} [mode=0o600]
+ */
+export 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)
+}
+
+/**
+ * 📖 JSON.parse with fallback. Returns `fallback` on parse failure.
+ * @param {string} raw
+ * @param {*} [fallback=null]
+ * @returns {*}
+ */
+export function safeJsonParse(raw, fallback = null) {
+  try {
+    return JSON.parse(raw)
+  } catch {
+    return fallback
+  }
+}
+
+/**
+ * 📖 Mask an API key for display. Shows last 4 chars, rest as bullets.
+ * @param {string} key
+ * @returns {string}
+ */
+/**
+ * 📖 Check if a provider supports routing (has chat/completions URL, not CLI-only).
+ * @param {string} providerKey
+ * @param {Record<string, {url?: string, cliOnly?: boolean}>} sources — provider catalog
+ * @returns {boolean}
+ */
+export function isRouteableProvider(providerKey, sources) {
+  const source = sources[providerKey]
+  return Boolean(source?.url && !source.cliOnly && source.url.includes('/chat/completions'))
+}
+
+export function maskApiKey(key) {
+  if (!key || typeof key !== 'string') return ''
+  if (key.length <= 8) return '••••••••'
+  return '••••••••' + key.slice(-4)
+}

package/src/core/sync-set.js

@@ -37,11 +37,10 @@ import {
   saveConfig,
 } from './config.js'
 import { resolveCloudflareUrl } from './ping.js'
-import { ROUTER_PID_PATH } from './router-daemon.js'
+import { ROUTER_PID_PATH, getRouterPidPath } from './router-daemon.js'
 import { existsSync, readFileSync } from 'node:fs'
-
-// 📖 Tier ordering — best tiers first, used for scoring candidates.
-const TIER_ORDER = ['S+', 'S', 'A+', 'A', 'A-', 'B+', 'B', 'C']
+import { TIER_ORDER, parseSweToNum } from './utils.js'
+import { isRouteableProvider } from './shared-helpers.js'
 
 // 📖 Numeric value per tier for composite scoring.
 const TIER_SCORES = {
@@ -69,14 +68,7 @@ const OPENROUTER_FREE_MODEL_IDS = new Set([
   'openrouter/owl-alpha',
 ])
 
-/**
- * Check whether a provider's catalog entry supports routing (has a
- * chat/completions URL and is not CLI-only).
- */
-function isRouteableProvider(providerKey) {
-  const source = sources[providerKey]
-  return Boolean(source?.url && !source.cliOnly && source.url.includes('/chat/completions'))
-}
+// 📖 isRouteableProvider imported from shared-helpers.js (needs `sources` param)
 
 /**
  * Resolve the upstream URL for a provider, handling Cloudflare template substitution.
@@ -98,14 +90,7 @@ function isOpenRouterFreeModelId(modelId) {
   return String(modelId).endsWith(':free') || OPENROUTER_FREE_MODEL_IDS.has(String(modelId))
 }
 
-/**
- * Parse a SWE-bench percentage string like "49.2%" to a number.
- */
-function parseSwePercent(value) {
-  if (typeof value !== 'string') return 0
-  const numeric = parseFloat(value.replace('%', '').trim())
-  return Number.isFinite(numeric) ? numeric : 0
-}
+// 📖 parseSwePercent replaced by shared parseSweToNum (same logic)
 
 /**
  * Score a candidate model for ranking. Higher is better.
@@ -156,12 +141,12 @@ export function buildSyncCandidates(apiKeys, options = {}) {
 
   for (const [providerKey, sourceData] of Object.entries(sources)) {
     if (!apiKeys[providerKey]) continue
-    if (!isRouteableProvider(providerKey)) continue
+    if (!isRouteableProvider(providerKey, sources)) continue
 
     for (const tuple of sourceData.models || []) {
       const [modelId, label = '', tier = '', swe = '0%'] = tuple
       if (typeof modelId !== 'string' || !modelId.trim()) continue
-      const swePercent = parseSwePercent(swe)
+      const swePercent = parseSweToNum(swe)
       if (shouldSkipModel(providerKey, modelId, tier, swePercent, options)) continue
       const score = scoreCandidate(providerKey, modelId, label, tier, swePercent)
       candidates.push({
@@ -323,8 +308,10 @@ export async function probeModel(candidate, apiKey) {
  */
 function signalDaemonReload() {
   try {
-    if (!existsSync(ROUTER_PID_PATH)) return false
-    const pid = Number(readFileSync(ROUTER_PID_PATH, 'utf8').trim())
+    // 📖 Dynamic resolver so dev checkouts signal the dev daemon (FCM_DEV=1).
+    const pidPath = getRouterPidPath()
+    if (!existsSync(pidPath)) return false
+    const pid = Number(readFileSync(pidPath, 'utf8').trim())
     if (!Number.isFinite(pid) || pid <= 0) return false
     process.kill(pid, 'SIGHUP')
     return true

package/src/core/tool-launchers.js

@@ -39,7 +39,7 @@
 import chalk from 'chalk'
 import { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync } from 'fs'
 import { homedir } from 'os'
-import { dirname, join } from 'path'
+import { join } from 'path'
 import { spawn, spawnSync } from 'child_process'
 import { sources } from '../../sources.js'
 import { PROVIDER_COLOR } from '../tui/render-table.js'
@@ -48,6 +48,7 @@ import { ENV_VAR_NAMES, isWindows } from './provider-metadata.js'
 import { getToolMeta, TOOL_METADATA } from './tool-metadata.js'
 import { PROVIDER_METADATA } from './provider-metadata.js'
 import { resolveToolBinaryPath } from './tool-bootstrap.js'
+import { ensureDir, readJson, writeJson } from './shared-helpers.js'
 
 const OPENAI_COMPAT_ENV_KEYS = [
   'OPENAI_API_KEY',
@@ -60,11 +61,6 @@ const OPENAI_COMPAT_ENV_KEYS = [
 ]
 const SANITIZED_TOOL_ENV_KEYS = [...OPENAI_COMPAT_ENV_KEYS]
 
-function ensureDir(filePath) {
-  const dir = dirname(filePath)
-  if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
-}
-
 // 📖 Parse a context window string (e.g. "128k", "1M", "32k") to token count number.
 function parseCtxToTokens(ctx) {
   if (!ctx || typeof ctx !== 'string') return null
@@ -104,19 +100,7 @@ function backupIfExists(filePath) {
   return backupPath
 }
 
-function readJson(filePath, fallback) {
-  if (!existsSync(filePath)) return fallback
-  try {
-    return JSON.parse(readFileSync(filePath, 'utf8'))
-  } catch {
-    return fallback
-  }
-}
-
-function writeJson(filePath, value) {
-  ensureDir(filePath)
-  writeFileSync(filePath, JSON.stringify(value, null, 2))
-}
+// 📖 readJson/writeJson imported from shared-helpers.js
 
 function getProviderBaseUrl(providerKey) {
   const url = sources[providerKey]?.url
@@ -966,55 +950,8 @@ export async function startExternalTool(mode, model, config) {
   console.log(chalk.cyan(`  ▶ Launching ${meta.label} with ${chalk.bold(model.label)}...`))
   printConfigArtifacts(meta.label, launchPlan.configArtifacts)
 
-  if (mode === 'aider') {
-    return spawnCommand(resolveLaunchCommand(mode, launchPlan.command), launchPlan.args, launchPlan.env)
-  }
-
-  if (mode === 'crush') {
-    console.log(chalk.dim('  📖 Crush will use the provider directly for this launch.'))
-    return spawnCommand(resolveLaunchCommand(mode, launchPlan.command), launchPlan.args, launchPlan.env)
-  }
-
-  if (mode === 'goose') {
-    return spawnCommand(resolveLaunchCommand(mode, launchPlan.command), launchPlan.args, launchPlan.env)
-  }
-
-  if (mode === 'qwen') {
-    return spawnCommand(resolveLaunchCommand(mode, launchPlan.command), launchPlan.args, launchPlan.env)
-  }
-
-  if (mode === 'openhands') {
-    console.log(chalk.dim(`  📖 OpenHands launched with model: ${model.modelId}`))
-    return spawnCommand(resolveLaunchCommand(mode, launchPlan.command), launchPlan.args, launchPlan.env)
-  }
-
-  if (mode === 'amp') {
-    console.log(chalk.dim(`  📖 Amp config updated with model: ${model.modelId}`))
-    return spawnCommand(resolveLaunchCommand(mode, launchPlan.command), launchPlan.args, launchPlan.env)
-  }
-
-  if (mode === 'pi') {
-    // 📖 Pi supports --provider and --model flags for guaranteed auto-selection
-    return spawnCommand(resolveLaunchCommand(mode, launchPlan.command), launchPlan.args, launchPlan.env)
-  }
-
-  if (mode === 'hermes') {
-    // 📖 Restart the Hermes gateway so the new model config takes effect immediately
-    restartHermesGateway()
-    console.log(chalk.dim(`  📖 Hermes Agent configured with model: ${model.modelId}`))
-    return spawnCommand(resolveLaunchCommand(mode, launchPlan.command), launchPlan.args, launchPlan.env)
-  }
-
-  if (mode === 'continue') {
-    console.log(chalk.dim(`  📖 Continue CLI configured with model: ${model.modelId}`))
-    return spawnCommand(resolveLaunchCommand(mode, launchPlan.command), launchPlan.args, launchPlan.env)
-  }
-
-  if (mode === 'cline') {
-    console.log(chalk.dim(`  📖 Cline configured with model: ${model.modelId}`))
-    return spawnCommand(resolveLaunchCommand(mode, launchPlan.command), launchPlan.args, launchPlan.env)
-  }
-
+  // 📖 Pre-launch hooks for tools that need special treatment
+  if (mode === 'hermes') restartHermesGateway()
   if (mode === 'xcode') {
     const xcodeUrl = launchPlan.baseUrl ? launchPlan.baseUrl.replace(/\/v1$/, '').replace(/\/v1\/chat\/completions$/, '') : ''
     console.log(chalk.bold.cyan('\n  🛠️  Xcode Intelligence Setup Instructions:'))
@@ -1027,29 +964,24 @@ export async function startExternalTool(mode, model, config) {
     console.log(chalk.dim('     Description: ') + chalk.green(`FCM - ${sources[model.providerKey]?.name || model.providerKey}`))
     console.log(chalk.white(`  4. Click Add, then select `) + chalk.bold(model.modelId) + chalk.white(` from the list.\n`))
     console.log(chalk.dim(`  📖 Attempting to launch Xcode...`))
-    return spawnCommand(launchPlan.command, launchPlan.args, launchPlan.env)
   }
-
-  if (mode === 'caveman') {
-    console.log(chalk.dim(`  📖 Launching Caveman Code...`))
-    return spawnCommand(resolveLaunchCommand(mode, launchPlan.command), launchPlan.args, launchPlan.env)
-  }
-
-  if (mode === 'jcode') {
-    console.log(chalk.dim(`  📖 Launching jcode...`))
-    return spawnCommand(resolveLaunchCommand(mode, launchPlan.command), launchPlan.args, launchPlan.env)
-  }
-
-  if (mode === 'copilot') {
-    console.log(chalk.dim(`  📖 Copilot CLI configured with model: ${model.modelId}`))
-    return spawnCommand(resolveLaunchCommand(mode, launchPlan.command), launchPlan.args, launchPlan.env)
-  }
-
-  if (mode === 'forgecode') {
-    console.log(chalk.dim(`  📖 ForgeCode configured with model: ${model.modelId}`))
-    return spawnCommand(resolveLaunchCommand(mode, launchPlan.command), launchPlan.args, launchPlan.env)
-  }
-
-  console.log(chalk.red(`  X Unsupported external tool mode: ${mode}`))
-  return 1
+  if (mode === 'crush') console.log(chalk.dim('  📖 Crush will use the provider directly for this launch.'))
+
+  // 📖 Tool-specific info messages (only for modes that have no prepare-step message)
+  const infoMessages = {
+    openhands: `  📖 OpenHands launched with model: ${model.modelId}`,
+    amp:       `  📖 Amp config updated with model: ${model.modelId}`,
+    hermes:    `  📖 Hermes Agent configured with model: ${model.modelId}`,
+    continue:  `  📖 Continue CLI configured with model: ${model.modelId}`,
+    cline:     `  📖 Cline configured with model: ${model.modelId}`,
+    caveman:   '  📖 Launching Caveman Code...',
+    jcode:     '  📖 Launching jcode...',
+    copilot:   `  📖 Copilot CLI configured with model: ${model.modelId}`,
+    forgecode: `  📖 ForgeCode configured with model: ${model.modelId}`,
+  }
+  if (infoMessages[mode]) console.log(chalk.dim(infoMessages[mode]))
+
+  // 📖 xcode uses raw command ("open"), everything else resolves via tool-bootstrap
+  const command = mode === 'xcode' ? launchPlan.command : resolveLaunchCommand(mode, launchPlan.command)
+  return spawnCommand(command, launchPlan.args, launchPlan.env)
 }