free-coding-models 0.5.4 → 0.5.6

package/README.md

@@ -169,14 +169,17 @@ and every TUI capability that's safe to port ships behind a button or chip.
 | **Filter bar** | Sticky right below the header (always visible) · Tier / Status / Verdict / Health chip rows · Visibility dropdown (Normal / Configured only / Usable only) · Provider select · custom text filter chip with `X` clear · Reset button (TUI `N`) · ping mode (Speed / Normal / Slow / Forced) · "next ping in Xs" countdown (TUI style, always shown) |
 | **Stats bar** | Removed in M1 (users found it noisy; the table + chips carry the same info at a glance) |
 | **Detail panel** | Slide-in from the right on row click · per-row benchmark button (TUI `Ctrl+A`) · favorite toggle (TUI `F`) + up/down reorder (TUI `Shift+↑↓`) · latency trend chart · all stats |
-| **Command palette** | `⌘K` / `Ctrl+P` (the only global keyboard shortcut) · fuzzy search across views, theme, ping mode, reset, export |
+| **Command palette** | `⌘K` / `Ctrl+P` (the only global keyboard shortcut) · fuzzy search across views, theme, ping mode, reset, export, **and the full TUI command registry** (every filter / sort / tool / page entry from `src/tui/command-palette.js`) |
 | **Keyboard** | `Esc` closes any modal · `Cmd+K` toggles the palette — that's it. Everything else is mouse-first. |
-| **URL deep-linking** | `?tier=S+&sort=verdict&origin=groq&view=dashboard&q=…` hydrates the dashboard on load. CLI flags become shareable links. |
+| **URL deep-linking** | `?tier=S+&sort=verdict&origin=groq&view=dashboard&q=…` hydrates the dashboard on load **and** every filter / sort / view change is reflected back in the URL (debounced 80ms, `history.replaceState`). CLI flags become shareable links. |
 | **Favorites** | Shared with the TUI through `~/.free-coding-models.json` — a star in the Web is a star in the TUI. Includes pinned+sticky display mode (TUI `Y`). |
+| **Help modal** | Header overflow menu → "Help" opens a full-screen modal with all the TUI's keyboard shortcuts, filter behavior, and parity notes. Live search bar. |
+| **Changelog modal** | Header overflow menu → "Changelog" or Settings "Open Changelog" link. Two-phase (index of versions + per-version release notes). Deep-linkable to a specific version. |
+| **Update flow** | Header `⬆ vX.Y.Z` chip + popover with "Update now" + "What's new" (jumps to the new version's changelog entry). Polls every 5 min. |
+| **Settings parity** | Full Settings page: theme (auto/dark/light), favorites pinned mode, startup AI Speed Scan, shell env export, legacy proxy cleanup, per-provider **Test** key button (TUI `T` key), update row. All settings persisted to the same `~/.free-coding-models.json` the TUI uses. |
 | **Theme** | Tri-state `auto / dark / light` cycle (TUI `G`) — auto follows the OS preference. |
 
-Roadmap items (header menu badges show "M2 / M3 / M4" until they land):
-- **M2** — Help modal, Changelog viewer, Settings parity (theme toggle, test key, shell-env, legacy cleanup, startup AI scan), Update flow, URL write-back, full command palette backed by the TUI registry.
+Roadmap items (header menu badges show "M3 / M4" until they land):
 - **M3** — Smart Recommend (3-question wizard → 10s analysis → Top 3), tool mode picker, per-row Launch, missing-tool install prompt, incompatible-fallback modal.
 - **M4** — Router Dashboard, Token Usage, Install Endpoints wizard, Installed Models manager.
 
@@ -511,7 +514,7 @@ When a tool mode is active (via `Z`), models incompatible with that tool are hig
 - **Readable everywhere** — semantic theme palette keeps table rows, overlays, badges, and help screens legible in dark and light terminals
 - **Global theme switch** — `G` cycles `auto`, `dark`, + `light` live without restarting
 - **Auto-retry** — timeout models keep getting retried
-- **Aggressive update nudging** — fluorescent green banner when an update is available, impossible to miss, Shift+U hotkey, command palette entry, background re-check every 5 min, mid-session updates the banner live without restarting
+- **Mandatory self-update policy** — startup checks npm for a newer FCM and installs it automatically without a prompt. If the install fails twice in a row (offline, proxy, or permissions), FCM still starts but shows a red outdated-version warning until the user retries with `Shift+U` or runs the displayed install command.
 - **Last release timestamp** — light pink footer shows `Last release: Mar 27, 2026, 09:42 PM` from npm so users know how fresh the data is
 
 ---

package/bin/free-coding-models.js

@@ -11,11 +11,12 @@ if (process.argv.includes('--dev')) {
 
 import chalk from 'chalk';
 import { parseArgs, TIER_LETTER_MAP } from '../src/core/utils.js';
-import { loadConfig } from '../src/core/config.js';
+import { loadConfig, saveConfig } from '../src/core/config.js';
 import { ensureTelemetryConfig } from '../src/core/telemetry.js';
 import { ensureFavoritesConfig } from '../src/core/favorites.js';
 import { buildCliHelpText } from '../src/tui/cli-help.js';
 import { ALT_LEAVE } from '../src/core/constants.js';
+import { enforceMandatoryStartupUpdate, isPackageDevMode } from '../src/core/updater.js';
 import { runApp } from '../src/tui/app.js';
 
 // Global error handlers to ensure terminal is restored if something crashes catastrophically
@@ -53,13 +54,38 @@ async function main() {
     process.exit(0);
   }
 
+  // Load JSON config before operational modes so the mandatory update policy can
+  // 📖 persist failure counters for TUI, Web Dashboard, Docker daemon, and Desktop sidecar launches.
+  const config = loadConfig();
+  ensureTelemetryConfig(config);
+  ensureFavoritesConfig(config);
+
+  const isDevMode = isPackageDevMode();
+  const shouldEnforceUpdate = !cliArgs.daemonStopMode && !cliArgs.daemonStatusMode;
+  const startupUpdate = shouldEnforceUpdate
+    ? await enforceMandatoryStartupUpdate(config, {
+      saveConfig,
+      isDevMode,
+      surface: cliArgs.webMode ? 'web dashboard' : cliArgs.daemonMode ? 'router daemon' : 'TUI',
+    })
+    : { latestVersion: null, allowedOutdated: false, warningMessage: null, failures: 0, checked: false, updated: false, blocked: false };
+
+  if (startupUpdate.updated) return;
+  if (startupUpdate.blocked) process.exit(1);
+  if (startupUpdate.allowedOutdated) {
+    process.env.FCM_UPDATE_ALLOWED_OUTDATED = '1';
+    process.env.FCM_UPDATE_LATEST_VERSION = startupUpdate.latestVersion || '';
+    process.env.FCM_UPDATE_WARNING_MESSAGE = startupUpdate.warningMessage || '';
+    process.env.FCM_UPDATE_FAILURES = String(startupUpdate.failures || 0);
+  }
+
   // 📖 Standalone web dashboard: same full-catalog ping UI as the TUI, served
   // 📖 locally with Socket.IO/SSE/REST realtime updates.
   if (cliArgs.webMode) {
     const { startWebServer } = await import('../web/server.js');
     const parsedPort = Number.parseInt(process.env.FCM_WEB_PORT || process.env.FCM_PORT || '3333', 10);
     const port = Number.isFinite(parsedPort) && parsedPort > 0 ? parsedPort : 3333;
-    await startWebServer(port, { open: true, startPingLoop: true });
+    await startWebServer(port, { open: true, startPingLoop: true, updateStatus: startupUpdate });
     return;
   }
 
@@ -102,12 +128,7 @@ async function main() {
     process.exit(1);
   }
 
-  // Load JSON config
-  const config = loadConfig();
-  ensureTelemetryConfig(config);
-  ensureFavoritesConfig(config);
-
-  await runApp(cliArgs, config);
+  await runApp(cliArgs, config, { startupUpdate, isDevMode });
 }
 
 main().catch((err) => {

package/changelog/v0.5.5.md

@@ -0,0 +1,16 @@
+# Changelog v0.5.5 - 2026-06-01
+
+### Changed
+- 🔒 **Mandatory self-update policy**: FCM now checks npm at startup across the TUI, Web Dashboard, Docker/daemon, and Desktop sidecar paths, then installs newer releases automatically without asking the user. If automatic installation fails twice in a row, FCM stops blocking startup and shows a red outdated-version warning so offline/proxy/permission users can still work while clearly seeing that their model catalog may be stale.
+- ⬆️ **deps-dev**: bump `vite` from `8.0.14` → `8.0.16` (#105)
+- ⬆️ **deps-dev**: bump `vite-plus` from `0.1.20` → `0.1.23` (#106)
+- ⬆️ **deps-dev**: bump `@vitejs/plugin-react` from `6.0.1` → `6.0.2` (#107)
+
+### CI
+- ⬆️ bump `docker/setup-buildx-action` from `3` → `4` (#104)
+- ⬆️ bump `docker/login-action` from `3` → `4` (#103)
+- ⬆️ bump `pnpm/action-setup` from `4` → `6` (#102)
+
+### Notes
+- All 6 dependabot PRs merged in a single batch with conflict resolution on `pnpm-lock.yaml`.
+- 440/440 tests passing.

package/changelog/v0.5.6.md

@@ -0,0 +1,24 @@
+# Changelog v0.5.6 - 2026-06-01
+
+### Added
+- **Web Dashboard M2 — Settings parity + full command palette + URL write-back + help / changelog / update** — the local Web Dashboard now mirrors the TUI for the everyday flow on every view it ships today.
+  - **Full command palette (TUI registry 1:1)** — `⌘K` / `Ctrl+P` opens a fuzzy-searchable palette that pulls every command from `src/tui/command-palette.js` (filters, sorts, target tools, theme, ping, reset, export, plus Web-only pages). Commands without a Web equivalent route to a friendly "arrives in M3/M4" toast.
+  - **Help modal** — Header overflow menu → "Help" opens a full-screen modal with 11 sections of Web behavior + TUI parity notes. Live search bar.
+  - **Changelog modal** — Two-phase (index of versions + per-version release notes). Settings "Open Changelog" link and the update chip "What's new" button both deep-link to a specific version.
+  - **Update chip + popover** — Header shows `⬆ vX.Y.Z` when a newer npm release is available. Click → "Update now" (spawns the package manager) + "What's new" (jumps to the new version's changelog entry). Polls every 5 minutes.
+  - **Full Settings parity** — theme dropdown (auto / dark / light), favorites pinned+sticky toggle, startup AI Speed Scan toggle, shell env export toggle, legacy proxy cleanup button, **per-provider Test key button** (TUI `T` key) with outcome badge, update status row, open Changelog link. All settings persist to the same `~/.free-coding-models.json` the TUI uses.
+  - **URL write-back (read + write)** — every filter / sort / view / tool-mode / palette state change is reflected back to the URL via `history.replaceState` (debounced 80ms). Sharing a URL with `?tier=S+&sort=verdict&origin=groq&view=analytics&q=…` opens a pre-filtered dashboard.
+
+### Changed
+- **Web command palette upgraded** from M1's static placeholder to a fully wired palette that imports `buildCommandPaletteEntries` + `filterCommandPaletteEntries` from the TUI engine — both surfaces are now guaranteed to show the same command set.
+- **Header menu** marks `Help` and `Changelog` as live (no more `M2` badge). `Recommend` (M3), `Router` (M4), `Install Endpoints` (M4), and `Installed Models` (M4) still badge.
+
+### Fixed
+- 🐛 **TUI Changelog overlay was silently broken** — `src/core/changelog-loader.js` resolved `changelog/` relative to `src/` instead of the project root. Fix walks up two levels. The TUI's `N` key and the new Web Changelog modal both load 142 versioned changelog files now.
+- 🐛 **`/api/key/:provider/test` and `/api/key/:provider` were colliding** — the general single-segment key match ate the two-segment test path. The test path is now matched at the top of the request handler so the two routes coexist.
+- 🐛 **`/api/settings/feature` only handled booleans** — passing a string (e.g. `theme=dark`) silently fell into the toggle branch and saved `true`. The endpoint now accepts arbitrary `value` payloads (string, number, boolean) and only toggles when `value` is omitted.
+
+### Notes
+- All 451 unit tests pass (was 440 before M2). The new M2 tests cover `buildUrlParams`, the URL state validation allowlists, and import-cleanly smoke tests for the three new React hooks.
+- The TUI source of truth is untouched — every new Web feature uses the same engine modules (`src/core/changelog-loader.js`, `src/core/updater.js`, `src/core/legacy-proxy-cleanup.js`, `src/core/shell-env.js`, `src/tui/command-palette.js`).
+- This release is the Web Dashboard reaching parity with the TUI for the day-to-day table flow. M3 ships the tool-mode picker + Smart Recommend; M4 ships the Router Dashboard + Token Usage.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "free-coding-models",
-  "version": "0.5.4",
+  "version": "0.5.6",
   "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",
@@ -75,10 +75,10 @@
     "node": ">=18.0.0"
   },
   "devDependencies": {
-    "@vitejs/plugin-react": "^6.0.1",
+    "@vitejs/plugin-react": "^6.0.2",
     "react": "^19.2.6",
     "react-dom": "^19.2.6",
-    "vite": "^8.0.13",
-    "vite-plus": "^0.1.16"
+    "vite": "^8.0.16",
+    "vite-plus": "^0.1.23"
   }
 }

package/src/core/changelog-loader.js

@@ -20,7 +20,11 @@ import { fileURLToPath } from 'url'
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = dirname(__filename)
-const CHANGELOG_DIR = join(__dirname, '..', 'changelog')
+// 📖 Resolve the project-root changelog directory. The loader lives at
+// 📖 src/core/, so we walk up two levels to reach the project root, then
+// 📖 into changelog/. (A previous version only walked up one level and
+// 📖 ended up pointing at src/changelog/, which never existed.)
+const CHANGELOG_DIR = join(__dirname, '..', '..', 'changelog')
 
 /**
  * 📖 loadChangelog: Read and parse all per-version changelog files

package/src/core/router-daemon.js

@@ -353,6 +353,16 @@ function getWebModelsPayload(runtime) {
   return payload
 }
 
+function getWebUpdateStatusPayload() {
+  if (process.env.FCM_UPDATE_ALLOWED_OUTDATED !== '1') return null
+  return {
+    latestVersion: process.env.FCM_UPDATE_LATEST_VERSION || null,
+    allowedOutdated: true,
+    warningMessage: process.env.FCM_UPDATE_WARNING_MESSAGE || null,
+    failures: Number.parseInt(process.env.FCM_UPDATE_FAILURES || '0', 10) || 0,
+  }
+}
+
 function getWebStatePayload(runtime) {
   const router = runtime.routerConfig()
   const probeInterval = router.probeIntervals?.[router.probeMode] || DEFAULT_ROUTER_SETTINGS.probeIntervals.balanced
@@ -366,6 +376,7 @@ function getWebStatePayload(runtime) {
     globalBenchmarkRunning: runtime.webGlobalBenchmarkRunning || false,
     globalBenchmarkTotal: runtime.webGlobalBenchmarkTotal || 0,
     globalBenchmarkCompleted: runtime.webGlobalBenchmarkCompleted || 0,
+    updateStatus: getWebUpdateStatusPayload(),
     models: getWebModelsPayload(runtime),
   }
 }

package/src/core/updater.js

@@ -32,22 +32,29 @@
  *   → getManualInstallCmd(pm, version)   — Human-readable install command string for error messages
  *   → checkForUpdateDetailed()           — Fetch npm latest with explicit error info
  *   → checkForUpdate()                   — Startup wrapper, returns version string or null
+ *   → isPackageDevMode()                 — Detect git/dev checkouts that must not self-update
+ *   → enforceMandatoryStartupUpdate()    — Mandatory startup self-update with two-failure fallback
  *   → runUpdate(latestVersion)           — Install new version via detected PM + relaunch
  * @exports
  *   detectPackageManager, getInstallArgs, getManualInstallCmd,
- *   checkForUpdateDetailed, checkForUpdate, runUpdate, fetchLastReleaseDate
+ *   checkForUpdateDetailed, checkForUpdate, isPackageDevMode,
+ *   enforceMandatoryStartupUpdate, runUpdate, fetchLastReleaseDate
  *
  * @see bin/free-coding-models.js — calls checkForUpdate() at startup and runUpdate() on confirm
  */
 
 import chalk from 'chalk'
 import { createRequire } from 'module'
-import { accessSync, constants } from 'fs'
+import { fileURLToPath } from 'url'
+import { dirname, join } from 'path'
+import { accessSync, constants, existsSync } from 'fs'
 
 const require = createRequire(import.meta.url)
 const readline = require('readline')
 const pkg = require('../../package.json')
 const LOCAL_VERSION = pkg.version
+const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..')
+export const UPDATE_FAILURE_THRESHOLD = 2
 
 /**
  * 📖 detectPackageManager: figure out which package manager owns the current installation.
@@ -65,6 +72,70 @@ export function detectPackageManager() {
   return 'npm'
 }
 
+/**
+ * 📖 isPackageDevMode: true for repo checkouts and explicit --dev runs.
+ * 📖 Self-updating a git checkout creates noisy loops during local development,
+ * 📖 while published npm installs do not ship a .git directory and can update safely.
+ * @returns {boolean}
+ */
+export function isPackageDevMode() {
+  return process.env.FCM_DEV === '1' || existsSync(join(PACKAGE_ROOT, '.git'))
+}
+
+/**
+ * 📖 getUpdateInstallFailureCount: sanitized persistent failure counter.
+ * @param {object} config
+ * @returns {number}
+ */
+export function getUpdateInstallFailureCount(config) {
+  const raw = Number(config?.settings?.updateInstallFailures || 0)
+  if (!Number.isFinite(raw) || raw < 0) return 0
+  return Math.floor(raw)
+}
+
+function ensureUpdateSettings(config) {
+  if (!config.settings || typeof config.settings !== 'object') config.settings = {}
+  return config.settings
+}
+
+function persistUpdateSettings(config, saveConfig) {
+  if (typeof saveConfig !== 'function') return
+  try { saveConfig(config) } catch {}
+}
+
+function resetUpdateInstallFailures(config, saveConfig) {
+  const settings = ensureUpdateSettings(config)
+  if (!settings.updateInstallFailures && !settings.updateLastFailureAt && !settings.updateLastFailureMessage) return
+  settings.updateInstallFailures = 0
+  delete settings.updateLastFailureAt
+  delete settings.updateLastFailureMessage
+  delete settings.updateInstallFailureVersion
+  persistUpdateSettings(config, saveConfig)
+}
+
+function recordUpdateInstallFailure(config, latestVersion, error, saveConfig) {
+  const settings = ensureUpdateSettings(config)
+  const nextFailures = Math.min(getUpdateInstallFailureCount(config) + 1, UPDATE_FAILURE_THRESHOLD)
+  settings.updateInstallFailures = nextFailures
+  settings.updateInstallFailureVersion = latestVersion
+  settings.updateLastFailureAt = new Date().toISOString()
+  settings.updateLastFailureMessage = error instanceof Error ? error.message : String(error || 'Unknown update error')
+  persistUpdateSettings(config, saveConfig)
+  return nextFailures
+}
+
+/**
+ * 📖 buildOutdatedWarningMessage: one-line message shown when mandatory updates
+ * 📖 failed twice and FCM must let the UI start instead of trapping the user.
+ * @param {string|null} latestVersion
+ * @param {number} failures
+ * @returns {string}
+ */
+export function buildOutdatedWarningMessage(latestVersion, failures = UPDATE_FAILURE_THRESHOLD) {
+  const target = latestVersion ? `v${LOCAL_VERSION} → v${latestVersion}` : `v${LOCAL_VERSION}`
+  return `⚠️ OUTDATED VERSION (${target}) — automatic update failed ${failures} times. Models and free quotas change often; update as soon as possible for the freshest catalog.`
+}
+
 /**
  * 📖 getInstallArgs: return the correct binary and argument list for a given PM.
  * 📖 Each PM has different syntax for global install — this normalises them.
@@ -120,6 +191,89 @@ export async function checkForUpdate() {
   return latestVersion
 }
 
+/**
+ * 📖 enforceMandatoryStartupUpdate: startup policy for every user-facing surface.
+ * 📖 If npm has a newer release, FCM installs it immediately without asking.
+ * 📖 The first failed install blocks startup so the next launch retries. After two
+ * 📖 consecutive install failures, startup is allowed with a loud outdated warning
+ * 📖 so offline/proxy/permission users are not permanently locked out.
+ *
+ * @param {object} config
+ * @param {{ saveConfig?: Function, isDevMode?: boolean, surface?: string }} [options]
+ * @returns {Promise<{ latestVersion: string|null, allowedOutdated: boolean, warningMessage: string|null, failures: number, checked: boolean, updated: boolean, blocked: boolean }>}
+ */
+export async function enforceMandatoryStartupUpdate(config, options = {}) {
+  const { saveConfig, surface = 'app' } = options
+  const devMode = typeof options.isDevMode === 'boolean' ? options.isDevMode : isPackageDevMode()
+  const base = {
+    latestVersion: null,
+    allowedOutdated: false,
+    warningMessage: null,
+    failures: getUpdateInstallFailureCount(config),
+    checked: false,
+    updated: false,
+    blocked: false,
+  }
+
+  if (devMode) return base
+
+  const { latestVersion, error } = await checkForUpdateDetailed()
+  base.checked = true
+
+  if (error) {
+    const settings = ensureUpdateSettings(config)
+    settings.updateCheckFailures = Math.min(Number(settings.updateCheckFailures || 0) + 1, UPDATE_FAILURE_THRESHOLD)
+    persistUpdateSettings(config, saveConfig)
+    return base
+  }
+
+  const settings = ensureUpdateSettings(config)
+  if (settings.updateCheckFailures) {
+    settings.updateCheckFailures = 0
+    persistUpdateSettings(config, saveConfig)
+  }
+
+  if (!latestVersion) {
+    resetUpdateInstallFailures(config, saveConfig)
+    return base
+  }
+
+  base.latestVersion = latestVersion
+  const failuresBeforeInstall = getUpdateInstallFailureCount(config)
+  if (failuresBeforeInstall >= UPDATE_FAILURE_THRESHOLD) {
+    base.allowedOutdated = true
+    base.failures = failuresBeforeInstall
+    base.warningMessage = buildOutdatedWarningMessage(latestVersion, failuresBeforeInstall)
+    return base
+  }
+
+  console.log(chalk.dim(`  ⬆ New version v${latestVersion} detected for ${surface}; updating automatically...`))
+  const updateResult = runUpdate(latestVersion, { exitOnFailure: false })
+  if (updateResult?.ok) {
+    resetUpdateInstallFailures(config, saveConfig)
+    base.updated = true
+    return base
+  }
+
+  const failures = recordUpdateInstallFailure(config, latestVersion, updateResult?.error, saveConfig)
+  base.failures = failures
+
+  if (failures >= UPDATE_FAILURE_THRESHOLD) {
+    base.allowedOutdated = true
+    base.warningMessage = buildOutdatedWarningMessage(latestVersion, failures)
+    console.log(chalk.red(`  ${base.warningMessage}`))
+    console.log(chalk.dim(`  Manual update: ${getManualInstallCmd(detectPackageManager(), latestVersion)}`))
+    console.log()
+    return base
+  }
+
+  base.blocked = true
+  console.log(chalk.red('  ✖ Mandatory update failed. FCM will retry on the next launch.'))
+  console.log(chalk.dim(`  Attempt ${failures}/${UPDATE_FAILURE_THRESHOLD}. Manual update: ${getManualInstallCmd(detectPackageManager(), latestVersion)}`))
+  console.log()
+  return base
+}
+
 /**
  * 📖 fetchLastReleaseDate: Get the human-readable publish date of the latest npm release.
  * 📖 Used in the TUI footer to show users how fresh the package is.
@@ -265,10 +419,15 @@ function installUpdateCommand(latestVersion, useSudo) {
 /**
  * 📖 runUpdate: Run npm global install to update to latestVersion.
  * 📖 Retries with sudo on permission errors.
- * 📖 Relaunches the process on success, exits with code 1 on failure.
+ * 📖 Relaunches the process on success. Manual update actions keep the historic
+ * 📖 behavior and exit on failure; mandatory startup checks pass exitOnFailure=false
+ * 📖 so they can persist failure counters and decide whether to let the UI start.
  * @param {string} latestVersion
+ * @param {{ exitOnFailure?: boolean, relaunchOnSuccess?: boolean }} [options]
+ * @returns {{ ok: boolean, error?: unknown }}
  */
-export function runUpdate(latestVersion) {
+export function runUpdate(latestVersion, options = {}) {
+  const { exitOnFailure = true, relaunchOnSuccess = true } = options
   console.log()
   console.log(chalk.bold.cyan('  ⬆ Updating free-coding-models to v' + latestVersion + '...'))
   console.log()
@@ -276,6 +435,7 @@ export function runUpdate(latestVersion) {
   const pm = detectPackageManager()
   const { needsSudo, checkedPath } = detectGlobalInstallPermission(pm)
   const sudoAvailable = process.platform !== 'win32' && hasSudoCommand()
+  let lastError = null
 
   if (needsSudo && checkedPath && sudoAvailable) {
     console.log(chalk.yellow(`  ⚠ Global ${pm} path is not writable: ${checkedPath}`))
@@ -288,9 +448,10 @@ export function runUpdate(latestVersion) {
     console.log()
     console.log(chalk.green(`  ✅ Update complete! Version ${latestVersion} installed.`))
     console.log()
-    relaunchCurrentProcess()
-    return
+    if (relaunchOnSuccess) relaunchCurrentProcess()
+    return { ok: true }
   } catch (err) {
+    lastError = err
     const manualCmd = getManualInstallCmd(pm, latestVersion)
     console.log()
     if (isPermissionError(err) && !needsSudo && sudoAvailable) {
@@ -301,9 +462,10 @@ export function runUpdate(latestVersion) {
         console.log()
         console.log(chalk.green(`  ✅ Update complete with sudo! Version ${latestVersion} installed.`))
         console.log()
-        relaunchCurrentProcess()
-        return
-      } catch {
+        if (relaunchOnSuccess) relaunchCurrentProcess()
+        return { ok: true }
+      } catch (sudoErr) {
+        lastError = sudoErr
         console.log()
         console.log(chalk.red('  ✖ Update failed even with sudo. Try manually:'))
         console.log(chalk.dim(`    sudo ${manualCmd}`))
@@ -318,7 +480,9 @@ export function runUpdate(latestVersion) {
       console.log()
     }
   }
-  process.exit(1)
+
+  if (exitOnFailure) process.exit(1)
+  return { ok: false, error: lastError }
 }
 
 

package/src/tui/app.js

@@ -91,11 +91,7 @@
 
 import chalk from 'chalk'
 import { createRequire } from 'module'
-import { fileURLToPath } from 'url'
-import { readFileSync, writeFileSync, existsSync, copyFileSync, mkdirSync } from 'fs'
 import { randomUUID } from 'crypto'
-import { homedir } from 'os'
-import { join, dirname } from 'path'
 import { MODELS, sources } from '../../sources.js'
 import { getAvg, getVerdict, getUptime, getP95, getJitter, getStabilityScore, sortResults, filterByTier, findBestModel, parseArgs, TIER_ORDER, VERDICT_ORDER, TIER_LETTER_MAP, scoreModelForTask, getTopRecommendations, TASK_TYPES, PRIORITY_TYPES, CONTEXT_BUDGETS, formatCtxWindow, labelFromId, formatResultsAsJSON } from '../core/utils.js'
 import { loadConfig, saveConfig, getApiKey, resolveApiKeys, addApiKey, removeApiKey, isProviderEnabled, persistApiKeysForProvider } from '../core/config.js'
@@ -181,7 +177,7 @@ const LOCAL_VERSION = pkg.version
 // ─── OpenCode integration ──────────────────────────────────────────────────────
 // 📖 OpenCode helpers are imported from ../src/opencode.js
 
-export async function runApp(cliArgs, config) {
+export async function runApp(cliArgs, config, startupOptions = {}) {
 
   // 📖 Detect user active terminal theme
   detectActiveTheme(config.settings?.theme || 'auto')
@@ -278,32 +274,12 @@ export async function runApp(cliArgs, config) {
     },
   })
 
-  // 📖 Auto-update detection: check npm registry for new versions at startup.
-  // 📖 If a new version is available, show an interactive prompt (Update / Changelogs / Skip).
-  // 📖 Dev mode (git checkout) skips auto-update to avoid infinite relaunch loops.
-  let latestVersion = null
-  const isDevMode = existsSync(join(dirname(fileURLToPath(import.meta.url)), '..', '.git'))
-  try {
-    latestVersion = await checkForUpdate()
-    // 📖 Reset failure counter on successful check
-    if (config.settings?.updateCheckFailures) {
-      config.settings.updateCheckFailures = 0
-      saveConfig(config)
-    }
-  } catch (err) {
-    const failures = (config.settings?.updateCheckFailures || 0) + 1
-    if (!config.settings) config.settings = {}
-    config.settings.updateCheckFailures = Math.min(failures, 3)
-    saveConfig(config)
-  }
-
-  // 📖 Auto-update: if a new version is available, install it immediately (skip in dev mode)
-  // 📖 runUpdate() will relaunch the process with the new version after install completes
-  if (latestVersion && !isDevMode) {
-    console.log(chalk.dim(`  ⬆ New version v${latestVersion} detected, updating...`))
-    runUpdate(latestVersion)
-    return // 📖 runUpdate relaunches the process — this line is a safety guard
-  }
+  // 📖 Mandatory startup update is enforced in the bin entry before any user-facing
+  // 📖 surface starts. runApp receives the result so the TUI can display the
+  // 📖 two-failure fallback warning without repeating npm registry/install work.
+  const startupUpdate = startupOptions.startupUpdate || {}
+  const latestVersion = startupUpdate.latestVersion || null
+  const isDevMode = startupOptions.isDevMode === true
 
   // 📖 Dynamic OpenRouter free model discovery — fetch live free models from API
   // 📖 Replaces static openrouter entries in MODELS with fresh data.
@@ -363,6 +339,8 @@ export async function runApp(cliArgs, config) {
     sessionId,
     latestVersion,
     isDevMode,
+    updateWarningMessage: startupUpdate.warningMessage || null,
+    updateInstallFailures: startupUpdate.failures || 0,
   })
 
   // 📖 Apply the pre-fetched last release date now that state is initialized
@@ -823,6 +801,7 @@ export async function runApp(cliArgs, config) {
       settingsUpdateLatestVersion: state.settingsUpdateLatestVersion,
       startupLatestVersion: state.startupLatestVersion,
       versionAlertsEnabled: state.versionAlertsEnabled,
+      updateWarningMessage: state.updateWarningMessage,
       favoritesPinnedAndSticky: state.favoritesPinnedAndSticky,
       customTextFilter: state.customTextFilter,
       lastReleaseDate: state.lastReleaseDate,
@@ -914,6 +893,7 @@ export async function runApp(cliArgs, config) {
     settingsUpdateLatestVersion: state.settingsUpdateLatestVersion,
     startupLatestVersion: state.startupLatestVersion,
     versionAlertsEnabled: state.versionAlertsEnabled,
+    updateWarningMessage: state.updateWarningMessage,
     favoritesPinnedAndSticky: state.favoritesPinnedAndSticky,
     customTextFilter: state.customTextFilter,
     lastReleaseDate: state.lastReleaseDate,

package/src/tui/render-table.js

@@ -136,6 +136,7 @@ export const PROVIDER_COLOR = new Proxy({}, {
  *   settingsUpdateLatestVersion: string|null,
  *   startupLatestVersion: string|null,
  *   versionAlertsEnabled: boolean,
+ *   updateWarningMessage?: string|null,
  *   favoritesPinnedAndSticky: boolean,
  *   customTextFilter: string|null,
  *   lastReleaseDate: string|null,
@@ -174,6 +175,7 @@ export function renderTable({
   settingsUpdateLatestVersion = null,
   startupLatestVersion = null,
   versionAlertsEnabled = true,
+  updateWarningMessage = null,
   favoritesPinnedAndSticky = false,
   customTextFilter = null,
   lastReleaseDate = null,
@@ -1073,15 +1075,19 @@ export function renderTable({
   )
 
   if (versionStatus.isOutdated) {
-    const updateMsg = `  🚀⬆️ UPDATE AVAILABLE — v${LOCAL_VERSION} → v${versionStatus.latestVersion}  •  Click here or press Shift+U to update  🚀⬆️  `
+    const updateMsg = updateWarningMessage
+      ? `  ${updateWarningMessage}  •  Press Shift+U to retry update  `
+      : `  🚀⬆️ UPDATE AVAILABLE — v${LOCAL_VERSION} → v${versionStatus.latestVersion}  •  Click here or press Shift+U to update  🚀⬆️  `
     const paddedBanner = terminalCols > 0
       ? updateMsg + ' '.repeat(Math.max(0, terminalCols - displayWidth(updateMsg)))
       : updateMsg
-    const fluoGreenBanner = chalk.bgRgb(57, 255, 20).rgb(0, 0, 0).bold(paddedBanner)
+    const updateBanner = updateWarningMessage
+      ? chalk.bgRed.white.bold(paddedBanner)
+      : chalk.bgRgb(57, 255, 20).rgb(0, 0, 0).bold(paddedBanner)
     const updateBannerRow = lines.length + 1
     _lastLayout.updateBannerRow = updateBannerRow
     footerHotkeys.push({ key: 'update-click', row: updateBannerRow, xStart: 1, xEnd: Math.max(terminalCols, displayWidth(updateMsg)) })
-    lines.push(fluoGreenBanner)
+    lines.push(updateBanner)
   } else {
     _lastLayout.updateBannerRow = 0
   }

package/src/tui/tui-state.js

@@ -70,6 +70,8 @@ export function intervalToPingMode(intervalMs) {
  *   sessionId: string,
  *   latestVersion: string|null,
  *   isDevMode: boolean,
+ *   updateWarningMessage?: string|null,
+ *   updateInstallFailures?: number,
  * }} opts
  * @returns {object} The complete TUI state (mutable)
  */
@@ -80,6 +82,8 @@ export function createTuiState({
   sessionId,
   latestVersion,
   isDevMode,
+  updateWarningMessage = null,
+  updateInstallFailures = 0,
 }) {
   const now = Date.now()
 
@@ -110,6 +114,8 @@ export function createTuiState({
 
     // 📖 Version tracking — startup auto-check + periodic re-check
     startupLatestVersion: latestVersion,
+    updateWarningMessage,
+    updateInstallFailures,
     lastReleaseDate: null,
     versionAlertsEnabled: !isDevMode,