free-coding-models 0.3.22 → 0.3.24

package/src/config.js

@@ -209,6 +209,7 @@ function normalizeSettingsSection(settings) {
   return {
     ...safeSettings,
     hideUnconfiguredModels: typeof safeSettings.hideUnconfiguredModels === 'boolean' ? safeSettings.hideUnconfiguredModels : true,
+    favoritesPinnedAndSticky: typeof safeSettings.favoritesPinnedAndSticky === 'boolean' ? safeSettings.favoritesPinnedAndSticky : false,
     theme: ['dark', 'light', 'auto'].includes(safeSettings.theme) ? safeSettings.theme : 'auto',
   }
 }
@@ -831,7 +832,7 @@ export function isProviderEnabled(config, providerKey) {
 /**
  * 📖 _emptyProfileSettings: Default TUI settings.
  *
- * @returns {{ tierFilter: string|null, sortColumn: string, sortAsc: boolean, pingInterval: number, hideUnconfiguredModels: boolean, preferredToolMode: string }}
+ * @returns {{ tierFilter: string|null, sortColumn: string, sortAsc: boolean, pingInterval: number, hideUnconfiguredModels: boolean, favoritesPinnedAndSticky: boolean, preferredToolMode: string }}
  */
 export function _emptyProfileSettings() {
   return {
@@ -840,6 +841,7 @@ export function _emptyProfileSettings() {
     sortAsc: true,        // 📖 true = ascending (fastest first for latency)
     pingInterval: 10000,  // 📖 default ms between pings in the steady "normal" mode
     hideUnconfiguredModels: true, // 📖 true = default to providers that are actually configured
+    favoritesPinnedAndSticky: false, // 📖 default mode keeps favorites as normal starred rows; press Y to pin+stick them.
     preferredToolMode: 'opencode', // 📖 remember the last Z-selected launcher across app restarts
     theme: 'auto',        // 📖 'auto' follows the terminal/OS theme, override with 'dark' or 'light' if needed
   }
@@ -848,7 +850,7 @@ export function _emptyProfileSettings() {
 /**
  * 📖 normalizeEndpointInstalls keeps the endpoint-install tracking list safe to replay.
  *
- * 📖 Each entry represents one managed catalog install performed through the `Y` flow:
+ * 📖 Each entry represents one managed catalog install performed through Install Endpoints:
  *   - `providerKey`: FCM provider identifier (`nvidia`, `groq`, ...)
  *   - `toolMode`: canonical tool id (`opencode`, `openclaw`, `crush`, `goose`)
  *   - `scope`: `all` or `selected`

package/src/endpoint-installer.js

@@ -3,7 +3,7 @@
  * @description Install and refresh FCM-managed provider catalogs inside external tool configs.
  *
  * @details
- *   📖 This module powers the `Y` hotkey flow in the TUI.
+ *   📖 This module powers the Install Endpoints flow in the TUI.
  *   It lets users pick one configured provider, choose a target tool, then install either:
  *   - the full provider catalog (`all` models), or
  *   - a curated subset of specific models (`selected`)
@@ -48,7 +48,8 @@ import { getApiKey, saveConfig } from './config.js'
 import { ENV_VAR_NAMES, PROVIDER_METADATA } from './provider-metadata.js'
 import { getToolMeta } from './tool-metadata.js'
 
-const DIRECT_INSTALL_UNSUPPORTED_PROVIDERS = new Set(['replicate', 'zai'])
+// 📖 CLI-only providers (rovo, gemini) and Zen-only (opencode-zen) cannot be installed into other tools.
+const DIRECT_INSTALL_UNSUPPORTED_PROVIDERS = new Set(['replicate', 'zai', 'rovo', 'gemini', 'opencode-zen'])
 // 📖 Install Endpoints only lists tools whose persisted config shape is actually supported here.
 // 📖 Claude Code, Codex, and Gemini stay out while their dedicated bridges are being rebuilt.
 const INSTALL_TARGET_MODES = ['opencode', 'opencode-desktop', 'openclaw', 'crush', 'goose', 'pi', 'aider', 'qwen', 'openhands', 'amp']

package/src/key-handler.js

@@ -28,6 +28,7 @@
  */
 
 import { loadChangelog } from './changelog-loader.js'
+import { getToolMeta, isModelCompatibleWithTool, getCompatibleTools, findSimilarCompatibleModels } from './tool-metadata.js'
 import { loadConfig, replaceConfigContents } from './config.js'
 import { cleanupLegacyProxyArtifacts } from './legacy-proxy-cleanup.js'
 import { cycleThemeSetting, detectActiveTheme } from './theme.js'
@@ -247,9 +248,61 @@ export function createKeyHandler(ctx) {
     }
     console.log()
 
-    // 📖 OpenClaw manages API keys inside its own config file. All other tools
-    // 📖 still need a provider key to be useful, so keep the existing warning.
-    if (state.mode !== 'openclaw') {
+    // 📖 CLI-only tool compatibility checks:
+    // 📖 Case A: Active tool mode is CLI-only (rovo/gemini) but selected model doesn't belong to it
+    // 📖 Case B: Selected model belongs to a CLI-only provider but active mode is something else
+    // 📖 Case C: Selected model is from opencode-zen but active mode is not opencode/opencode-desktop
+    const activeMeta = getToolMeta(state.mode)
+    const isActiveModeCliOnly = activeMeta.cliOnly === true
+    const isModelFromCliOnly = selected.providerKey === 'rovo' || selected.providerKey === 'gemini'
+    const isModelFromZen = selected.providerKey === 'opencode-zen'
+    const modelBelongsToActiveMode = selected.providerKey === state.mode
+
+    // 📖 Case A: User is in Rovo/Gemini mode but selected a model from a different provider
+    if (isActiveModeCliOnly && !modelBelongsToActiveMode) {
+      const availableModels = MODELS.filter(m => m[5] === state.mode)
+      console.log(chalk.yellow(`  ⚠ ${activeMeta.label} can only launch its own models.`))
+      console.log(chalk.yellow(`  "${selected.label}" is not a ${activeMeta.label} model.`))
+      console.log()
+      if (availableModels.length > 0) {
+        console.log(chalk.cyan(`  Available ${activeMeta.label} models:`))
+        for (const m of availableModels) {
+          console.log(chalk.white(`    • ${m[1]} (${m[2]} tier, ${m[3]} SWE, ${m[4]} ctx)`))
+        }
+        console.log()
+      }
+      console.log(chalk.dim(`  Switch to another tool mode with Z, or select a ${activeMeta.label} model.`))
+      console.log()
+      process.exit(0)
+    }
+
+    // 📖 Case B: Selected model is from a CLI-only provider but active mode is different
+    if (isModelFromCliOnly && !modelBelongsToActiveMode) {
+      const modelMeta = getToolMeta(selected.providerKey)
+      console.log(chalk.yellow(`  ⚠ ${selected.label} is a ${modelMeta.label}-exclusive model.`))
+      console.log(chalk.yellow(`  Your current tool is: ${activeMeta.label}`))
+      console.log()
+      console.log(chalk.cyan(`  Switching to ${modelMeta.label} and launching...`))
+      setToolMode(selected.providerKey)
+      console.log(chalk.green(`  ✓ Switched to ${modelMeta.label}`))
+      console.log()
+    }
+
+    // 📖 Case C: Zen model selected but active mode is not OpenCode CLI / OpenCode Desktop
+    // 📖 Auto-switch to OpenCode CLI since Zen models only run on OpenCode
+    if (isModelFromZen && state.mode !== 'opencode' && state.mode !== 'opencode-desktop') {
+      console.log(chalk.yellow(`  ⚠ ${selected.label} is an OpenCode Zen model.`))
+      console.log(chalk.yellow(`  Zen models only run on OpenCode CLI or OpenCode Desktop.`))
+      console.log(chalk.yellow(`  Your current tool is: ${activeMeta.label}`))
+      console.log()
+      console.log(chalk.cyan(`  Switching to OpenCode CLI and launching...`))
+      setToolMode('opencode')
+      console.log(chalk.green(`  ✓ Switched to OpenCode CLI`))
+      console.log()
+    }
+
+    // 📖 OpenClaw, CLI-only tools, and Zen models manage auth differently — skip API key warning for them.
+    if (state.mode !== 'openclaw' && !isModelFromCliOnly && !isModelFromZen) {
       const selectedApiKey = getApiKey(state.config, selected.providerKey)
       if (!selectedApiKey) {
         console.log(chalk.yellow(`  Warning: No API key configured for ${selected.providerKey}.`))
@@ -259,6 +312,41 @@ export function createKeyHandler(ctx) {
       }
     }
 
+    // 📖 CLI-only tool auto-install check — verify the CLI binary is available before launch.
+    const toolModeForProvider = selected.providerKey
+    if (isModelFromCliOnly && !isToolInstalled(toolModeForProvider)) {
+      const installPlan = getToolInstallPlan(toolModeForProvider)
+      if (installPlan.supported) {
+        console.log()
+        console.log(chalk.yellow(`  ⚠ ${getToolMeta(toolModeForProvider).label} is not installed.`))
+        console.log(chalk.dim(`  ${installPlan.summary}`))
+        if (installPlan.note) console.log(chalk.dim(`  Note: ${installPlan.note}`))
+        console.log()
+        console.log(chalk.cyan(`  📦 Auto-installing ${getToolMeta(toolModeForProvider).label}...`))
+        console.log()
+
+        const installResult = await installToolWithPlan(installPlan)
+        if (!installResult.ok) {
+          console.log(chalk.red(`  X Tool installation failed with exit code ${installResult.exitCode}.`))
+          if (installPlan.docsUrl) console.log(chalk.dim(`  Docs: ${installPlan.docsUrl}`))
+          console.log()
+          process.exit(installResult.exitCode || 1)
+        }
+
+        // 📖 Verify tool is now installed
+        if (!isToolInstalled(toolModeForProvider)) {
+          console.log(chalk.yellow('  ⚠ The installer finished, but the tool is still not reachable from this terminal session.'))
+          console.log(chalk.dim('  Restart your shell or add the tool bin directory to PATH, then retry the launch.'))
+          if (installPlan.docsUrl) console.log(chalk.dim(`  Docs: ${installPlan.docsUrl}`))
+          console.log()
+          process.exit(1)
+        }
+
+        console.log(chalk.green('  ✓ Tool installed successfully. Continuing with the selected model...'))
+        console.log()
+      }
+    }
+
     let exitCode = 0
     if (state.mode === 'openclaw') {
       exitCode = await startOpenClaw(userSelected, state.config, { launchCli: true })
@@ -519,7 +607,9 @@ export function createKeyHandler(ctx) {
   // 📖 Shared table refresh helper so command-palette and hotkeys keep identical behavior.
   function refreshVisibleSorted({ resetCursor = true } = {}) {
     const visible = state.results.filter(r => !r.hidden)
-    state.visibleSorted = sortResultsWithPinnedFavorites(visible, state.sortColumn, state.sortDirection)
+    state.visibleSorted = sortResultsWithPinnedFavorites(visible, state.sortColumn, state.sortDirection, {
+      pinFavorites: state.favoritesPinnedAndSticky,
+    })
     if (resetCursor) {
       state.cursor = 0
       state.scrollOffset = 0
@@ -600,12 +690,48 @@ export function createKeyHandler(ctx) {
     const modeOrder = getToolModeOrder()
     const currentIndex = modeOrder.indexOf(state.mode)
     const nextIndex = (currentIndex + 1) % modeOrder.length
-    state.mode = modeOrder[nextIndex]
+    setToolMode(modeOrder[nextIndex])
+  }
+
+  // 📖 Keep tool-mode changes centralized so keyboard shortcuts and command palette
+  // 📖 both persist to config exactly the same way.
+  function setToolMode(nextMode) {
+    if (!getToolModeOrder().includes(nextMode)) return
+    state.mode = nextMode
     if (!state.config.settings || typeof state.config.settings !== 'object') state.config.settings = {}
     state.config.settings.preferredToolMode = state.mode
     saveConfig(state.config)
   }
 
+  // 📖 Favorites display mode:
+  // 📖 - true  => favorites stay pinned + always visible (legacy behavior)
+  // 📖 - false => favorites are just starred rows and obey normal sort/filter rules
+  function setFavoritesDisplayMode(nextPinned, { preserveSelection = true } = {}) {
+    const normalizedNextPinned = nextPinned !== false
+    if (state.favoritesPinnedAndSticky === normalizedNextPinned) return
+
+    const selected = preserveSelection ? state.visibleSorted[state.cursor] : null
+    const selectedKey = selected ? toFavoriteKey(selected.providerKey, selected.modelId) : null
+
+    state.favoritesPinnedAndSticky = normalizedNextPinned
+    if (!state.config.settings || typeof state.config.settings !== 'object') state.config.settings = {}
+    state.config.settings.favoritesPinnedAndSticky = state.favoritesPinnedAndSticky
+    saveConfig(state.config)
+
+    applyTierFilter()
+    refreshVisibleSorted({ resetCursor: false })
+
+    if (selectedKey) {
+      const selectedIdx = state.visibleSorted.findIndex((row) => toFavoriteKey(row.providerKey, row.modelId) === selectedKey)
+      if (selectedIdx >= 0) state.cursor = selectedIdx
+      adjustScrollOffset(state)
+    }
+  }
+
+  function toggleFavoritesDisplayMode() {
+    setFavoritesDisplayMode(!state.favoritesPinnedAndSticky)
+  }
+
   function resetViewSettings() {
     state.tierFilterMode = 0
     state.originFilterMode = 0
@@ -631,7 +757,7 @@ export function createKeyHandler(ctx) {
     applyTierFilter()
     refreshVisibleSorted({ resetCursor: false })
 
-    if (wasFavorite) {
+    if (wasFavorite && state.favoritesPinnedAndSticky) {
       state.cursor = 0
       state.scrollOffset = 0
       return
@@ -654,11 +780,28 @@ export function createKeyHandler(ctx) {
   }
 
   function refreshCommandPaletteResults() {
+    const query = (state.commandPaletteQuery || '').trim()
     const tree = buildCommandPaletteTree(state.results || [])
-    const flat = flattenCommandTree(tree, state.commandPaletteExpandedIds)
-    state.commandPaletteResults = filterCommandPaletteEntries(flat, state.commandPaletteQuery)
+    // 📖 Keep collapsed view clean when query is empty, but search across the
+    // 📖 full tree when users type so hidden submenu commands still appear.
+    let flat
+    if (query.length > 0) {
+      const expandedIds = new Set()
+      const collectExpandedIds = (nodes) => {
+        for (const node of nodes || []) {
+          if (Array.isArray(node.children) && node.children.length > 0) {
+            expandedIds.add(node.id)
+            collectExpandedIds(node.children)
+          }
+        }
+      }
+      collectExpandedIds(tree)
+      flat = flattenCommandTree(tree, expandedIds)
+    } else {
+      flat = flattenCommandTree(tree, state.commandPaletteExpandedIds)
+    }
+    state.commandPaletteResults = filterCommandPaletteEntries(flat, query)
 
-    const query = (state.commandPaletteQuery || '').trim()
     if (query.length > 0) {
       state.commandPaletteResults.unshift({
         id: 'filter-custom-text-apply',
@@ -707,6 +850,21 @@ export function createKeyHandler(ctx) {
   function executeCommandPaletteEntry(entry) {
     if (!entry?.id) return
 
+    if (entry.id.startsWith('action-set-ping-') && entry.pingMode) {
+      setPingMode(entry.pingMode, 'manual')
+      return
+    }
+
+    if (entry.id.startsWith('action-set-tool-') && entry.toolMode) {
+      setToolMode(entry.toolMode)
+      return
+    }
+
+    if (entry.id.startsWith('action-favorites-mode-') && typeof entry.favoritesPinned === 'boolean') {
+      setFavoritesDisplayMode(entry.favoritesPinned)
+      return
+    }
+
     if (entry.id.startsWith('filter-tier-')) {
       setTierFilterFromCommand(entry.tier ?? null)
       return
@@ -793,6 +951,7 @@ export function createKeyHandler(ctx) {
         return
       }
       case 'action-toggle-favorite': return toggleFavoriteOnSelectedRow()
+      case 'action-toggle-favorite-mode': return toggleFavoritesDisplayMode()
       case 'action-reset-view': return resetViewSettings()
       default:
         return
@@ -1129,6 +1288,85 @@ export function createKeyHandler(ctx) {
       return
     }
 
+    // 📖 Incompatible fallback overlay: ↑↓ navigate across tool + model sections, Enter confirms, Esc cancels.
+    // 📖 Cursor is a flat index: 0..N-1 = compatible tools, N..N+M-1 = similar models.
+    if (state.incompatibleFallbackOpen) {
+      if (key.ctrl && key.name === 'c') { exit(0); return }
+
+      const tools = state.incompatibleFallbackTools || []
+      const similarModels = state.incompatibleFallbackSimilarModels || []
+      const totalItems = tools.length + similarModels.length
+
+      if (key.name === 'escape') {
+        // 📖 Close the overlay and go back to the main table
+        state.incompatibleFallbackOpen = false
+        state.incompatibleFallbackCursor = 0
+        state.incompatibleFallbackScrollOffset = 0
+        state.incompatibleFallbackModel = null
+        state.incompatibleFallbackTools = []
+        state.incompatibleFallbackSimilarModels = []
+        state.incompatibleFallbackSection = 'tools'
+        return
+      }
+
+      if (key.name === 'up' && totalItems > 0) {
+        state.incompatibleFallbackCursor = state.incompatibleFallbackCursor > 0
+          ? state.incompatibleFallbackCursor - 1
+          : totalItems - 1
+        state.incompatibleFallbackSection = state.incompatibleFallbackCursor < tools.length ? 'tools' : 'models'
+        return
+      }
+
+      if (key.name === 'down' && totalItems > 0) {
+        state.incompatibleFallbackCursor = state.incompatibleFallbackCursor < totalItems - 1
+          ? state.incompatibleFallbackCursor + 1
+          : 0
+        state.incompatibleFallbackSection = state.incompatibleFallbackCursor < tools.length ? 'tools' : 'models'
+        return
+      }
+
+      if (key.name === 'return' && totalItems > 0) {
+        const cursor = state.incompatibleFallbackCursor
+        const fallbackModel = state.incompatibleFallbackModel
+
+        // 📖 Close overlay state first
+        state.incompatibleFallbackOpen = false
+        state.incompatibleFallbackCursor = 0
+        state.incompatibleFallbackScrollOffset = 0
+        state.incompatibleFallbackModel = null
+        state.incompatibleFallbackTools = []
+        state.incompatibleFallbackSimilarModels = []
+        state.incompatibleFallbackSection = 'tools'
+
+        if (cursor < tools.length) {
+          // 📖 Section 1: Switch to the selected compatible tool, then launch the original model
+          const selectedToolKey = tools[cursor]
+          setToolMode(selectedToolKey)
+          // 📖 Find the full result object for the original model to pass to launchSelectedModel
+          const fullModel = state.results.find(
+            r => r.providerKey === fallbackModel.providerKey && r.modelId === fallbackModel.modelId
+          )
+          if (fullModel) {
+            await launchSelectedModel(fullModel)
+          }
+        } else {
+          // 📖 Section 2: Launch the selected similar model instead
+          const modelIdx = cursor - tools.length
+          const selectedSimilar = similarModels[modelIdx]
+          if (selectedSimilar) {
+            const fullModel = state.results.find(
+              r => r.providerKey === selectedSimilar.providerKey && r.modelId === selectedSimilar.modelId
+            )
+            if (fullModel) {
+              await launchSelectedModel(fullModel)
+            }
+          }
+        }
+      }
+
+      return
+    }
+
     // 📖 Feedback overlay: intercept ALL keys while overlay is active.
     // 📖 Enter → send to Discord, Esc → cancel, Backspace → delete char, printable → append to buffer.
     if (state.feedbackOpen) {
@@ -1442,7 +1680,8 @@ export function createKeyHandler(ctx) {
       const providerKeys = Object.keys(sources)
       const updateRowIdx = providerKeys.length
       const themeRowIdx = updateRowIdx + 1
-      const cleanupLegacyProxyRowIdx = themeRowIdx + 1
+      const favoritesModeRowIdx = themeRowIdx + 1
+      const cleanupLegacyProxyRowIdx = favoritesModeRowIdx + 1
       const changelogViewRowIdx = cleanupLegacyProxyRowIdx + 1
         // 📖 Profile system removed - API keys now persist permanently across all sessions
       const maxRowIdx = changelogViewRowIdx
@@ -1523,10 +1762,7 @@ export function createKeyHandler(ctx) {
         setResults(nextResults)
         syncFavoriteFlags(state.results, state.config)
         applyTierFilter()
-        const visible = state.results.filter(r => !r.hidden)
-        state.visibleSorted = sortResultsWithPinnedFavorites(visible, state.sortColumn, state.sortDirection)
-        if (state.cursor >= state.visibleSorted.length) state.cursor = Math.max(0, state.visibleSorted.length - 1)
-        adjustScrollOffset(state)
+        refreshVisibleSorted({ resetCursor: false })
         // 📖 Re-ping all models that were 'noauth' (got 401 without key) but now have a key
         // 📖 This makes the TUI react immediately when a user adds an API key in settings
         const pingModel = getPingModel?.()
@@ -1591,6 +1827,11 @@ export function createKeyHandler(ctx) {
           return
         }
 
+        if (state.settingsCursor === favoritesModeRowIdx) {
+          toggleFavoritesDisplayMode()
+          return
+        }
+
         if (state.settingsCursor === cleanupLegacyProxyRowIdx) {
           runLegacyProxyCleanup()
           return
@@ -1629,6 +1870,10 @@ export function createKeyHandler(ctx) {
           cycleGlobalTheme()
           return
         }
+        if (state.settingsCursor === favoritesModeRowIdx) {
+          toggleFavoritesDisplayMode()
+          return
+        }
         // 📖 Profile system removed - API keys now persist permanently across all sessions
 
         // 📖 Toggle enabled/disabled for selected provider
@@ -1644,6 +1889,7 @@ export function createKeyHandler(ctx) {
         if (
           state.settingsCursor === updateRowIdx
           || state.settingsCursor === themeRowIdx
+          || state.settingsCursor === favoritesModeRowIdx
           || state.settingsCursor === cleanupLegacyProxyRowIdx
           || state.settingsCursor === changelogViewRowIdx
         ) return
@@ -1661,6 +1907,12 @@ export function createKeyHandler(ctx) {
         return
       }
 
+      // 📖 Y toggles favorites display mode directly from Settings.
+      if (key.name === 'y') {
+        toggleFavoritesDisplayMode()
+        return
+      }
+
         // 📖 Profile system removed - API keys now persist permanently across all sessions
 
       if (key.ctrl && key.name === 'c') { exit(0); return }
@@ -1707,9 +1959,20 @@ export function createKeyHandler(ctx) {
       return
     }
 
-    // 📖 Y key freed — Install Endpoints is now accessible only via Settings (P) or Command Palette (Ctrl+P).
+    // 📖 Y key toggles favorites display mode (pinned+sticky vs normal rows).
+    if (key.name === 'y' && !key.ctrl && !key.meta) {
+      toggleFavoritesDisplayMode()
+      return
+    }
 
-    // 📖 Profile system removed - API keys now persist permanently across all sessions
+    // 📖 X clears the active free-text filter set from the command palette.
+    if (key.name === 'x' && !key.ctrl && !key.meta) {
+      if (!state.customTextFilter) return
+      state.customTextFilter = null
+      applyTierFilter()
+      refreshVisibleSorted({ resetCursor: true })
+      return
+    }
 
     // 📖 Profile system removed - API keys now persist permanently across all sessions
 
@@ -1720,7 +1983,8 @@ export function createKeyHandler(ctx) {
     }
 
     // 📖 Sorting keys: R=rank, O=origin, M=model, L=latest ping, A=avg ping, S=SWE-bench, C=context, H=health, V=verdict, B=stability, U=uptime, G=usage
-    // 📖 T is reserved for tier filter cycling. Y is now free (Install Endpoints moved to Settings/Palette).
+    // 📖 T is reserved for tier filter cycling. Y toggles favorites display mode.
+    // 📖 X clears the active custom text filter.
     // 📖 D is now reserved for provider filter cycling
     // 📖 Shift+R is reserved for reset view settings
     const sortKeys = {
@@ -1763,10 +2027,7 @@ export function createKeyHandler(ctx) {
       state.config.settings.hideUnconfiguredModels = state.hideUnconfiguredModels
       saveConfig(state.config)
       applyTierFilter()
-      const visible = state.results.filter(r => !r.hidden)
-      state.visibleSorted = sortResultsWithPinnedFavorites(visible, state.sortColumn, state.sortDirection)
-      state.cursor = 0
-      state.scrollOffset = 0
+      refreshVisibleSorted({ resetCursor: true })
       return
     }
 
@@ -1775,10 +2036,7 @@ export function createKeyHandler(ctx) {
       state.tierFilterMode = (state.tierFilterMode + 1) % TIER_CYCLE.length
       applyTierFilter()
       // 📖 Recompute visible sorted list and reset cursor to avoid stale index into new filtered set
-      const visible = state.results.filter(r => !r.hidden)
-      state.visibleSorted = sortResultsWithPinnedFavorites(visible, state.sortColumn, state.sortDirection)
-      state.cursor = 0
-      state.scrollOffset = 0
+      refreshVisibleSorted({ resetCursor: true })
       persistUiSettings()
       return
     }
@@ -1788,10 +2046,7 @@ export function createKeyHandler(ctx) {
       state.originFilterMode = (state.originFilterMode + 1) % ORIGIN_CYCLE.length
       applyTierFilter()
       // 📖 Recompute visible sorted list and reset cursor to avoid stale index into new filtered set
-      const visible = state.results.filter(r => !r.hidden)
-      state.visibleSorted = sortResultsWithPinnedFavorites(visible, state.sortColumn, state.sortDirection)
-      state.cursor = 0
-      state.scrollOffset = 0
+      refreshVisibleSorted({ resetCursor: true })
       persistUiSettings()
       return
     }
@@ -1854,6 +2109,33 @@ export function createKeyHandler(ctx) {
       // 📖 Use the cached visible+sorted array — guaranteed to match what's on screen
       const selected = state.visibleSorted[state.cursor]
       if (!selected) return // 📖 Guard: empty visible list (all filtered out)
+
+      // 📖 Incompatibility intercept — if the model can't run on the active tool,
+      // 📖 show the fallback overlay instead of launching. Lets user switch tool or pick similar model.
+      if (!isModelCompatibleWithTool(selected.providerKey, state.mode)) {
+        const compatTools = getCompatibleTools(selected.providerKey)
+        const similarModels = findSimilarCompatibleModels(
+          selected.sweScore || '-',
+          state.mode,
+          state.results.filter(r => r.providerKey !== selected.providerKey || r.modelId !== selected.modelId),
+          3
+        )
+        state.incompatibleFallbackOpen = true
+        state.incompatibleFallbackCursor = 0
+        state.incompatibleFallbackScrollOffset = 0
+        state.incompatibleFallbackModel = {
+          modelId: selected.modelId,
+          label: selected.label,
+          tier: selected.tier,
+          providerKey: selected.providerKey,
+          sweScore: selected.sweScore || '-',
+        }
+        state.incompatibleFallbackTools = compatTools
+        state.incompatibleFallbackSimilarModels = similarModels
+        state.incompatibleFallbackSection = 'tools'
+        return
+      }
+
       if (shouldCheckMissingTool(state.mode) && !isToolInstalled(state.mode)) {
         state.toolInstallPromptOpen = true
         state.toolInstallPromptCursor = 0