Add searchable model selection to the Admin UI (#1121)

## Problem

Admin model routing fields required users to construct provider-prefixed
model slugs. Optional tier overrides represented inheritance as an
unexplained blank value.

## Changes

| Before | After |
| --- | --- |
| Model inputs only gained suggestions after an individual provider
refresh. | Model inputs load configured and discovered canonical slugs
from one Admin catalog. |
| Model routing looked like unrestricted text entry. | Model routing
uses the browser's searchable model dropdown while retaining manual
entry. |
| Tier overrides displayed an empty value for fallback routing. | Tier
overrides display **None** and persist it as an unset override. |
| Model refresh returned provider-shaped cache internals. | Model
refresh returns the same canonical catalog consumed by the Admin UI. |
| Users inferred the provider/model slug format from examples. | The
Admin UI and README define and present complete provider/model slugs. |

<!-- greptile_comment -->

<details open><summary><h3>Greptile Summary</h3></summary>

This PR adds searchable model selection to the Admin UI. The main
changes are:

- Adds a canonical catalog of configured and discovered model slugs.
- Adds searchable model inputs while preserving manual entry.
- Represents unset tier overrides as **None**.
- Reports provider-specific model refresh failures.
- Reconciles cached models when provider settings change.
- Updates documentation, package metadata, and tests.
</details>

<h3>Confidence Score: 5/5</h3>

This looks safe to merge.

Catalog failures no longer stop the rest of the Admin UI from loading.
Partial provider refreshes now produce a visible warning. Removed
credential-backed providers are pruned from the shared cache, and later
stale writes are rejected. No blocking issues remain in the changed
code.

<details><summary><h3><a href="https://www.greptile.com/trex"><img
alt="T-Rex"
src="https://greptile-static-assets.s3.amazonaws.com/trex/trex_green.svg"
height="20" align="absmiddle"></a> T-Rex Logs</h3></summary>

**What T-Rex did**
- T-Rex ran the requested verification for the pull request checks.
- The verification completed, but local artifact references were not
uploaded.

_{<a href="https://www.greptile.com/trex"><img alt="T-Rex"
src="https://greptile-static-assets.s3.amazonaws.com/trex/trex_green.svg"
height="14" align="absmiddle"></a> Ran code and verified through
T-Rex}
</details>

<details open><summary><h3>Important Files Changed</h3></summary>

| Filename | Overview |
|----------|----------|
| src/free_claude_code/api/admin_static/admin.js | Adds searchable model
fields, optional catalog hydration, refresh warnings, and None-to-unset
conversion. |
| src/free_claude_code/api/admin_routes.py | Adds canonical model
catalog endpoints and provider refresh failure metadata. |
| src/free_claude_code/providers/runtime/discovery.py | Tracks provider
refresh outcomes and separates cache eligibility from discovery
eligibility. |
| src/free_claude_code/providers/runtime/model_cache.py | Scopes cached
model metadata to currently available providers and removes stale remote
entries. |
| src/free_claude_code/runtime/provider_manager.py | Reconciles cache
scope during runtime replacement and returns explicit refresh results. |

</details>

_{Reviews (2): Last reviewed commit: ["Fix model catalog refresh
lifecycle"](https://github.com/alishahryar1/free-claude-code/commit/d16e170055f5389e538e18dece269a5f7a8c599d)
| [Re-trigger
Greptile](https://app.greptile.com/api/retrigger?id=44373795)}

<!-- /greptile_comment -->

README.md

@@ -108,7 +108,7 @@ Use the port shown in your terminal if it differs from `8082`.
 1. Create an API key at [build.nvidia.com/settings/api-keys](https://build.nvidia.com/settings/api-keys).
 2. Open the Admin UI URL from the server log.
 3. Paste the key into `NVIDIA_NIM_API_KEY`.
-4. Leave `MODEL` on the default `nvidia_nim/nvidia/nemotron-3-super-120b-a12b`, or select another model.
+4. Leave `MODEL` on the default `nvidia_nim/nvidia/nemotron-3-super-120b-a12b`, or search the model dropdown and select another model.
 5. Click **Validate**, then **Apply**.
 
 <div align="center">
@@ -145,7 +145,7 @@ fcc-codex exec "hello"
 
 ## Choose A Provider
 
-Enter the listed setting in the Admin UI, set `MODEL` to a provider-prefixed model ID, then click **Validate** and **Apply**. Provider names link to their key, model, or setup pages.
+Enter the listed setting in the Admin UI, open **Model Config**, then search the `MODEL` dropdown and select a model. FCC constructs each slug as `<provider-id>/<exact-provider-model-id>`; free-text entry remains available when a provider cannot list a model. Click **Validate** and **Apply**. Provider names link to their key, model, or setup pages.
 
 | Provider | Admin UI setting | Example `MODEL` |
 | --- | --- | --- |
@@ -209,7 +209,7 @@ Use the tag shown by `ollama list` with the `ollama/` prefix. `OLLAMA_BASE_URL`
 
 ### Optional Model-Tier Routing
 
-`MODEL` is the fallback for every request. Set `MODEL_FABLE`, `MODEL_OPUS`, `MODEL_SONNET`, or `MODEL_HAIKU` to override individual Claude Code tiers; leave a tier blank to inherit `MODEL`.
+`MODEL` is the fallback for every request. Select a model for `MODEL_FABLE`, `MODEL_OPUS`, `MODEL_SONNET`, or `MODEL_HAIKU` to override an individual Claude Code tier; select **None** to use `MODEL`.
 
 For example, route Opus to `nvidia_nim/moonshotai/kimi-k2.6`, Sonnet to `open_router/openrouter/free`, Haiku to `lmstudio/qwen3.5-coder`, and keep `MODEL` on `zai/glm-5.2`.
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "free-claude-code"
-version = "4.5.2"
+version = "4.6.1"
 description = "Local proxy connecting coding agents to OpenAI-compatible AI providers"
 readme = "README.md"
 requires-python = ">=3.14.0"

src/free_claude_code/api/admin_routes.py

@@ -10,9 +10,11 @@ from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException, Request
 from fastapi.responses import FileResponse
 from pydantic import BaseModel, Field
 
+from free_claude_code.application.model_metadata import ProviderModelRefreshResult
 from free_claude_code.config.admin.manifest import FIELD_BY_KEY
 from free_claude_code.config.admin.persistence import validate_updates
 from free_claude_code.config.admin.values import load_config_response
+from free_claude_code.config.model_refs import configured_chat_model_refs
 
 from .dependencies import get_services
 from .ports import ApiServices
@@ -143,13 +145,44 @@ async def test_provider(
     return await services.admin.test_provider(provider_id)
 
 
+@router.get("/admin/api/models")
+async def models(
+    request: Request,
+    services: ApiServices = Depends(get_services),
+):
+    require_loopback_admin(request)
+    return _model_options(services)
+
+
 @router.post("/admin/api/models/refresh")
 async def refresh_models(
     request: Request,
     services: ApiServices = Depends(get_services),
 ):
     require_loopback_admin(request)
-    return await services.admin.refresh_models()
+    result = await services.admin.refresh_models()
+    return _model_options(services, refresh_result=result)
+
+
+def _model_options(
+    services: ApiServices,
+    *,
+    refresh_result: ProviderModelRefreshResult | None = None,
+) -> dict[str, list[str]]:
+    configured = {
+        ref.model_ref
+        for ref in configured_chat_model_refs(services.requests.current_settings())
+    }
+    discovered = {
+        info.model_id for info in services.requests.cached_prefixed_model_infos()
+    }
+    failed_provider_ids = (
+        refresh_result.failed_provider_ids if refresh_result is not None else ()
+    )
+    return {
+        "models": sorted(configured | discovered, key=str.casefold),
+        "failed_providers": list(failed_provider_ids),
+    }
 
 
 def _filtered_values(values: dict[str, Any]) -> dict[str, Any]:

src/free_claude_code/api/admin_static/admin.css

@@ -494,21 +494,6 @@ textarea:focus-visible,
   padding-right: 36px;
 }
 
-/* Custom Dropdown Styling for Datalist Input Elements (Model Routing) */
-.field input[list] {
-  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' fill='none' viewBox='0 0 24 24' stroke='%239ca3af' stroke-width='2.5'%3E%3Cpath stroke-linecap='round' stroke-linejoin='round' d='M19.5 8.25l-7.5 7.5-7.5-7.5'/%3E%3C/svg%3E");
-  background-repeat: no-repeat;
-  background-position: right 14px center;
-  background-size: 14px;
-  padding-right: 36px;
-}
-
-/* Hide WebKit's native picker indicator to avoid double arrow icons */
-.field input[list]::-webkit-calendar-picker-indicator {
-  display: none !important;
-}
-
-
 .field input:focus,
 .field select:focus,
 .field textarea:focus {
@@ -628,6 +613,11 @@ textarea:focus-visible,
   font-weight: 600;
 }
 
+.message-area.warn {
+  color: var(--warn);
+  font-weight: 600;
+}
+
 .action-buttons {
   display: flex;
   gap: 12px;

src/free_claude_code/api/admin_static/admin.js

@@ -84,6 +84,7 @@ async function load() {
   renderProviders(config.provider_status);
   renderSections(config.sections, config.fields);
   byId("configPath").textContent = config.paths.managed;
+  await hydrateModelOptions();
   await validate(false);
   await refreshLocalStatus();
   updateDirtyState();
@@ -210,6 +211,14 @@ function renderSections(sections, fields) {
       const heading = document.createElement("div");
       heading.className = "section-heading";
       heading.innerHTML = `<div><h3>${section.label}</h3><p>${section.description}</p></div>`;
+      if (section.id === "models") {
+        const refreshButton = document.createElement("button");
+        refreshButton.type = "button";
+        refreshButton.className = "secondary-button";
+        refreshButton.textContent = "Refresh models";
+        refreshButton.addEventListener("click", () => refreshModelOptions(refreshButton));
+        heading.appendChild(refreshButton);
+      }
       sectionEl.appendChild(heading);
 
       const grid = document.createElement("div");
@@ -261,9 +270,18 @@ function renderField(field) {
   input.dataset.original = field.value || "";
   input.dataset.secret = field.secret ? "true" : "false";
   input.dataset.configured = field.configured ? "true" : "false";
+  input.dataset.fieldType = field.type;
   input.disabled = field.locked;
   input.addEventListener("input", updateDirtyState);
   input.addEventListener("change", updateDirtyState);
+  if (field.type === "optional_model") {
+    input.addEventListener("blur", () => {
+      if (!input.value.trim() || input.value.trim().toLowerCase() === "none") {
+        input.value = "None";
+        updateDirtyState();
+      }
+    });
+  }
 
   wrapper.append(label, input);
   if (field.description) {
@@ -308,6 +326,18 @@ function inputForField(field) {
     return textarea;
   }
 
+  if (field.type === "model" || field.type === "optional_model") {
+    const input = document.createElement("input");
+    input.type = "text";
+    input.value = field.value || (field.type === "optional_model" ? "None" : "");
+    input.setAttribute(
+      "list",
+      field.type === "optional_model" ? "optional-model-options" : "model-options",
+    );
+    input.autocomplete = "off";
+    return input;
+  }
+
   const input = document.createElement("input");
   input.type = field.type === "number" ? "number" : "text";
   if (field.type === "secret") {
@@ -320,9 +350,6 @@ function inputForField(field) {
   } else {
     input.value = field.value || "";
   }
-  if (field.key.startsWith("MODEL")) {
-    input.setAttribute("list", "model-options");
-  }
   return input;
 }
 
@@ -335,6 +362,12 @@ function option(value, label) {
 
 function readFieldValue(input) {
   if (input.type === "checkbox") return input.checked ? "true" : "false";
+  if (
+    input.dataset.fieldType === "optional_model" &&
+    input.value.trim().toLowerCase() === "none"
+  ) {
+    return "";
+  }
   if (input.dataset.secret === "true" && input.dataset.configured === "true") {
     return input.value ? input.value : MASKED_SECRET;
   }
@@ -434,13 +467,10 @@ async function testProvider(providerId, button) {
         `${result.models.length} models`,
         result.models.slice(0, 3).join(", ") || "No models returned",
       );
-      state.modelOptions = Array.from(
-        new Set([
-          ...state.modelOptions,
-          ...result.models.map((model) => `${providerId}/${model}`),
-        ]),
-      ).sort();
-      syncModelDatalist();
+      setModelOptions([
+        ...state.modelOptions,
+        ...result.models.map((model) => `${providerId}/${model}`),
+      ]);
     } else {
       updateProviderCard(providerId, "offline", result.error_type, result.error_type);
     }
@@ -450,15 +480,74 @@ async function testProvider(providerId, button) {
   }
 }
 
-function syncModelDatalist() {
-  let datalist = byId("model-options");
+async function hydrateModelOptions() {
+  try {
+    await loadModelOptions();
+  } catch {
+    // Model fields remain editable when optional catalog hydration is unavailable.
+  }
+}
+
+async function loadModelOptions(refresh = false) {
+  const result = await api("/admin/api/models" + (refresh ? "/refresh" : ""), {
+    method: refresh ? "POST" : "GET",
+  });
+  setModelOptions(result.models);
+  return result;
+}
+
+async function refreshModelOptions(button) {
+  const original = button.textContent;
+  button.disabled = true;
+  button.textContent = "Refreshing";
+  try {
+    const result = await loadModelOptions(true);
+    const failedProviders = result.failed_providers || [];
+    if (failedProviders.length) {
+      const labels = failedProviders.map(providerDisplayName).join(", ");
+      showMessage(
+        `${state.modelOptions.length} models available; could not refresh ${labels}`,
+        "warn",
+      );
+    } else {
+      showMessage(`${state.modelOptions.length} models available`, "ok");
+    }
+  } catch (error) {
+    showMessage(`Could not refresh models: ${error.message}`, "error");
+  } finally {
+    button.disabled = false;
+    button.textContent = original;
+  }
+}
+
+function providerDisplayName(providerId) {
+  const provider = state.config?.provider_status?.find(
+    (candidate) => candidate.provider_id === providerId,
+  );
+  return provider?.display_name || providerId;
+}
+
+function setModelOptions(models) {
+  state.modelOptions = Array.from(
+    new Set(models.filter((model) => typeof model === "string" && model.trim())),
+  ).sort((left, right) => left.localeCompare(right));
+  syncModelDatalists();
+}
+
+function syncModelDatalist(id, values) {
+  let datalist = byId(id);
   if (!datalist) {
     datalist = document.createElement("datalist");
-    datalist.id = "model-options";
+    datalist.id = id;
     document.body.appendChild(datalist);
   }
   datalist.innerHTML = "";
-  state.modelOptions.forEach((model) => datalist.appendChild(option(model, model)));
+  values.forEach((model) => datalist.appendChild(option(model, model)));
+}
+
+function syncModelDatalists() {
+  syncModelDatalist("model-options", state.modelOptions);
+  syncModelDatalist("optional-model-options", ["None", ...state.modelOptions]);
 }
 
 function showMessage(message, kind = "") {

src/free_claude_code/api/ports.py

@@ -4,6 +4,7 @@ from collections.abc import Mapping
 from dataclasses import dataclass
 from typing import Any, Protocol
 
+from free_claude_code.application.model_metadata import ProviderModelRefreshResult
 from free_claude_code.application.ports import RequestRuntimePort, TaskController
 
 
@@ -18,7 +19,7 @@ class AdminRuntimePort(Protocol):
 
     async def test_provider(self, provider_id: str) -> dict[str, Any]: ...
 
-    async def refresh_models(self) -> dict[str, Any]: ...
+    async def refresh_models(self) -> ProviderModelRefreshResult: ...
 
     async def request_restart(self) -> None: ...
 

src/free_claude_code/application/model_metadata.py

@@ -9,3 +9,11 @@ class ProviderModelInfo:
 
     model_id: str
     supports_thinking: bool | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderModelRefreshResult:
+    """Per-provider outcome of one model-catalog refresh."""
+
+    refreshed_provider_ids: tuple[str, ...] = ()
+    failed_provider_ids: tuple[str, ...] = ()

src/free_claude_code/config/admin/manifest.py

@@ -14,6 +14,8 @@ FieldType = Literal[
     "number",
     "boolean",
     "tri_boolean",
+    "model",
+    "optional_model",
     "select",
     "textarea",
 ]
@@ -56,7 +58,7 @@ SECTIONS: tuple[ConfigSectionSpec, ...] = (
     ConfigSectionSpec(
         "models",
         "Model Routing",
-        "Provider-prefixed models used for Claude model tiers.",
+        "Search discovered provider models or enter a provider/model slug.",
     ),
     ConfigSectionSpec(
         "thinking",
@@ -103,6 +105,7 @@ _NON_PROVIDER_FIELDS: tuple[ConfigFieldSpec, ...] = (
         "MODEL",
         "Default Model",
         "models",
+        "model",
         settings_attr="model",
         default="nvidia_nim/nvidia/nemotron-3-super-120b-a12b",
         description="Fallback provider/model route for all Claude model names.",
@@ -111,29 +114,33 @@ _NON_PROVIDER_FIELDS: tuple[ConfigFieldSpec, ...] = (
         "MODEL_FABLE",
         "Fable Override",
         "models",
+        "optional_model",
         settings_attr="model_fable",
-        description="Optional provider/model route for Fable requests.",
+        description="Select None to use the Default Model for Fable requests.",
     ),
     ConfigFieldSpec(
         "MODEL_OPUS",
         "Opus Override",
         "models",
+        "optional_model",
         settings_attr="model_opus",
-        description="Optional provider/model route for Opus requests.",
+        description="Select None to use the Default Model for Opus requests.",
     ),
     ConfigFieldSpec(
         "MODEL_SONNET",
         "Sonnet Override",
         "models",
+        "optional_model",
         settings_attr="model_sonnet",
-        description="Optional provider/model route for Sonnet requests.",
+        description="Select None to use the Default Model for Sonnet requests.",
     ),
     ConfigFieldSpec(
         "MODEL_HAIKU",
         "Haiku Override",
         "models",
+        "optional_model",
         settings_attr="model_haiku",
-        description="Optional provider/model route for Haiku requests.",
+        description="Select None to use the Default Model for Haiku requests.",
     ),
     ConfigFieldSpec(
         "ENABLE_MODEL_THINKING",

src/free_claude_code/providers/runtime/discovery.py

@@ -5,7 +5,10 @@ from collections.abc import Callable
 
 from loguru import logger
 
-from free_claude_code.application.model_metadata import ProviderModelInfo
+from free_claude_code.application.model_metadata import (
+    ProviderModelInfo,
+    ProviderModelRefreshResult,
+)
 from free_claude_code.config.model_refs import configured_chat_model_refs
 from free_claude_code.config.provider_catalog import PROVIDER_CATALOG
 from free_claude_code.config.settings import Settings
@@ -23,21 +26,27 @@ def referenced_provider_ids(settings: Settings) -> frozenset[str]:
     return frozenset(ref.provider_id for ref in configured_chat_model_refs(settings))
 
 
+def model_cache_provider_ids_for_settings(settings: Settings) -> tuple[str, ...]:
+    """Return providers whose model metadata is valid for these settings."""
+    return tuple(
+        provider_id
+        for provider_id, descriptor in PROVIDER_CATALOG.items()
+        if descriptor.local
+        or (
+            descriptor.credential_env is not None
+            and provider_credential(descriptor, settings).strip()
+        )
+    )
+
+
 def model_list_provider_ids_for_settings(settings: Settings) -> tuple[str, ...]:
     """Return providers worth discovering for this process configuration."""
     referenced_ids = referenced_provider_ids(settings)
-    provider_ids: list[str] = []
-    for provider_id, descriptor in PROVIDER_CATALOG.items():
-        if descriptor.local:
-            if provider_id in referenced_ids:
-                provider_ids.append(provider_id)
-            continue
-        if (
-            descriptor.credential_env is not None
-            and provider_credential(descriptor, settings).strip()
-        ):
-            provider_ids.append(provider_id)
-    return tuple(provider_ids)
+    return tuple(
+        provider_id
+        for provider_id in model_cache_provider_ids_for_settings(settings)
+        if not PROVIDER_CATALOG[provider_id].local or provider_id in referenced_ids
+    )
 
 
 class ProviderModelDiscovery:
@@ -53,7 +62,9 @@ class ProviderModelDiscovery:
         self._provider_resolver = provider_resolver
         self._model_cache = model_cache
 
-    async def refresh_model_list_cache(self, *, only_missing: bool = False) -> None:
+    async def refresh_model_list_cache(
+        self, *, only_missing: bool = False
+    ) -> ProviderModelRefreshResult:
         """Best-effort refresh of model lists for usable providers."""
         provider_ids = model_list_provider_ids_for_settings(self._settings)
         if only_missing:
@@ -62,34 +73,46 @@ class ProviderModelDiscovery:
                 for provider_id in provider_ids
                 if not self._model_cache.has_provider(provider_id)
             )
-        await self._refresh_model_infos(provider_ids)
+        return await self._refresh_model_infos(provider_ids)
 
-    async def _refresh_model_infos(self, provider_ids: tuple[str, ...]) -> None:
+    async def _refresh_model_infos(
+        self, provider_ids: tuple[str, ...]
+    ) -> ProviderModelRefreshResult:
+        failed_provider_ids: list[str] = []
         tasks: dict[str, asyncio.Task[frozenset[ProviderModelInfo]]] = {}
         for provider_id in provider_ids:
             try:
                 provider = self._provider_resolver(provider_id)
             except Exception as exc:
                 self._log_discovery_failure(provider_id, exc)
+                failed_provider_ids.append(provider_id)
                 continue
             tasks[provider_id] = asyncio.create_task(provider.list_model_infos())
 
-        if not tasks:
-            return
-
-        results = await asyncio.gather(*tasks.values(), return_exceptions=True)
-        for (provider_id, _task), result in zip(tasks.items(), results, strict=True):
-            if isinstance(result, BaseException):
-                if isinstance(result, asyncio.CancelledError):
-                    raise result
-                self._log_discovery_failure(provider_id, result)
-                continue
-            self._model_cache.cache_model_infos(provider_id, result)
-            logger.info(
-                "Provider model discovery cached: provider={} models={}",
-                provider_id,
-                len(result),
-            )
+        refreshed_provider_ids: list[str] = []
+        if tasks:
+            results = await asyncio.gather(*tasks.values(), return_exceptions=True)
+            for (provider_id, _task), result in zip(
+                tasks.items(), results, strict=True
+            ):
+                if isinstance(result, BaseException):
+                    if isinstance(result, asyncio.CancelledError):
+                        raise result
+                    self._log_discovery_failure(provider_id, result)
+                    failed_provider_ids.append(provider_id)
+                    continue
+                self._model_cache.cache_model_infos(provider_id, result)
+                refreshed_provider_ids.append(provider_id)
+                logger.info(
+                    "Provider model discovery cached: provider={} models={}",
+                    provider_id,
+                    len(result),
+                )
+
+        return ProviderModelRefreshResult(
+            refreshed_provider_ids=tuple(refreshed_provider_ids),
+            failed_provider_ids=tuple(failed_provider_ids),
+        )
 
     def _log_discovery_failure(self, provider_id: str, exc: BaseException) -> None:
         logger.warning(

src/free_claude_code/providers/runtime/model_cache.py

@@ -10,7 +10,11 @@ from free_claude_code.providers.model_listing import model_infos_from_ids
 class ProviderModelCache:
     """Store provider model metadata for instant model-list responses."""
 
-    def __init__(self) -> None:
+    def __init__(
+        self,
+        available_provider_ids: Iterable[str] = SUPPORTED_PROVIDER_IDS,
+    ) -> None:
+        self._available_provider_ids = frozenset(available_provider_ids)
         self._model_infos_by_provider: dict[str, dict[str, ProviderModelInfo]] = {}
 
     def cache_model_ids(self, provider_id: str, model_ids: Iterable[str]) -> None:
@@ -21,11 +25,22 @@ class ProviderModelCache:
         self, provider_id: str, model_infos: Iterable[ProviderModelInfo]
     ) -> None:
         """Store provider model metadata by raw provider model id."""
+        if provider_id not in self._available_provider_ids:
+            return
         clean_infos = {
             info.model_id: info for info in model_infos if info.model_id.strip()
         }
         self._model_infos_by_provider[provider_id] = clean_infos
 
+    def set_available_providers(self, provider_ids: Iterable[str]) -> None:
+        """Replace the provider scope and discard entries outside it."""
+        self._available_provider_ids = frozenset(provider_ids)
+        self._model_infos_by_provider = {
+            provider_id: infos
+            for provider_id, infos in self._model_infos_by_provider.items()
+            if provider_id in self._available_provider_ids
+        }
+
     def cached_model_ids(self) -> dict[str, frozenset[str]]:
         """Return cached raw provider model ids by provider."""
         return {

src/free_claude_code/providers/runtime/validation.py

@@ -81,8 +81,8 @@ class ConfiguredModelValidator:
                         self._format_provider_query_failures(provider_refs, result)
                     )
                     continue
+                model_ids = frozenset(info.model_id for info in result)
                 self._model_cache.cache_model_infos(provider_id, result)
-                model_ids = self._model_cache.cached_model_ids()[provider_id]
                 failures.extend(
                     self._format_missing_model_failure(ref)
                     for ref in provider_refs

src/free_claude_code/runtime/application.py

@@ -14,6 +14,7 @@ import free_claude_code.cli.managed as cli_managed
 import free_claude_code.messaging.session as messaging_session
 import free_claude_code.messaging.workflow as messaging_workflow_module
 from free_claude_code.application.errors import ApplicationUnavailableError
+from free_claude_code.application.model_metadata import ProviderModelRefreshResult
 from free_claude_code.application.ports import StopResult
 from free_claude_code.config.admin.persistence import (
     PreparedAdminUpdate,
@@ -244,14 +245,8 @@ class ApplicationRuntime:
             "models": sorted(info.model_id for info in infos),
         }
 
-    async def refresh_models(self) -> dict[str, Any]:
-        await self.provider_manager.refresh_model_list_cache()
-        return {
-            "cached_models": {
-                provider_id: sorted(model_ids)
-                for provider_id, model_ids in self.provider_manager.cached_model_ids().items()
-            }
-        }
+    async def refresh_models(self) -> ProviderModelRefreshResult:
+        return await self.provider_manager.refresh_model_list_cache()
 
     async def request_restart(self) -> None:
         callback = self._restart_callback

src/free_claude_code/runtime/provider_manager.py

@@ -7,12 +7,18 @@ from dataclasses import dataclass, field
 from loguru import logger
 
 from free_claude_code.application.errors import ApplicationUnavailableError
-from free_claude_code.application.model_metadata import ProviderModelInfo
+from free_claude_code.application.model_metadata import (
+    ProviderModelInfo,
+    ProviderModelRefreshResult,
+)
 from free_claude_code.config.settings import Settings
 from free_claude_code.core.trace import trace_event
 from free_claude_code.providers.base import BaseProvider
 from free_claude_code.providers.runtime import ProviderRuntime
-from free_claude_code.providers.runtime.discovery import ProviderModelDiscovery
+from free_claude_code.providers.runtime.discovery import (
+    ProviderModelDiscovery,
+    model_cache_provider_ids_for_settings,
+)
 from free_claude_code.providers.runtime.model_cache import ProviderModelCache
 from free_claude_code.providers.runtime.validation import ConfiguredModelValidator
 
@@ -86,7 +92,9 @@ class ProviderRuntimeManager:
         self._runtime_factory = runtime_factory
         self._replace_lock = asyncio.Lock()
         self._close_lock = asyncio.Lock()
-        self._model_cache = ProviderModelCache()
+        self._model_cache = ProviderModelCache(
+            model_cache_provider_ids_for_settings(settings)
+        )
         self._refresh_task: asyncio.Task[None] | None = None
         self._next_generation_id = 2
         self._retired: dict[int, _ProviderGeneration] = {}
@@ -153,16 +161,16 @@ class ProviderRuntimeManager:
             return
         generation = self._current
         self._refresh_task = asyncio.create_task(
-            self._refresh_generation(generation, only_missing=True)
+            self._refresh_generation_in_background(generation, only_missing=True)
         )
 
-    async def refresh_model_list_cache(self) -> None:
+    async def refresh_model_list_cache(self) -> ProviderModelRefreshResult:
         """Run an explicit full refresh without racing replacement."""
         async with self._replace_lock:
             if self._closing or self._closed:
                 raise ApplicationUnavailableError("Provider runtime is shutting down.")
             await self._cancel_refresh()
-            await self._refresh_generation(self._current, only_missing=False)
+            return await self._refresh_generation(self._current, only_missing=False)
 
     async def replace(
         self,
@@ -205,13 +213,16 @@ class ProviderRuntimeManager:
                 runtime=candidate_runtime,
             )
             self._current = candidate
+            self._model_cache.set_available_providers(
+                model_cache_provider_ids_for_settings(settings)
+            )
             previous.retired = True
             self._retired[previous.generation_id] = previous
             self._trace_published(candidate, previous=previous, reason=reason)
             self._trace_retired(previous, reason=reason)
 
             self._refresh_task = asyncio.create_task(
-                self._refresh_generation(candidate, only_missing=False)
+                self._refresh_generation_in_background(candidate, only_missing=False)
             )
             if previous.active_leases == 0:
                 await self._close_generation(previous, forced=False)
@@ -262,9 +273,9 @@ class ProviderRuntimeManager:
         generation: _ProviderGeneration,
         *,
         only_missing: bool,
-    ) -> None:
+    ) -> ProviderModelRefreshResult:
         if generation.closed:
-            return
+            return ProviderModelRefreshResult()
         generation.active_leases += 1
         generation.drained.clear()
         try:
@@ -273,7 +284,18 @@ class ProviderRuntimeManager:
                 generation.runtime.resolve_provider,
                 self._model_cache,
             )
-            await discovery.refresh_model_list_cache(only_missing=only_missing)
+            return await discovery.refresh_model_list_cache(only_missing=only_missing)
+        finally:
+            await self._release(generation)
+
+    async def _refresh_generation_in_background(
+        self,
+        generation: _ProviderGeneration,
+        *,
+        only_missing: bool,
+    ) -> None:
+        try:
+            await self._refresh_generation(generation, only_missing=only_missing)
         except asyncio.CancelledError:
             raise
         except Exception as exc:
@@ -281,8 +303,6 @@ class ProviderRuntimeManager:
                 "Provider model discovery task failed: exc_type={}",
                 type(exc).__name__,
             )
-        finally:
-            await self._release(generation)
 
     async def _cancel_refresh(self) -> None:
         task = self._refresh_task

tests/api/test_admin.py

@@ -1,14 +1,18 @@
 from pathlib import Path
-from unittest.mock import patch
+from unittest.mock import AsyncMock, patch
 
 import httpx
 import pytest
 from fastapi.testclient import TestClient
 
+from free_claude_code.application.model_metadata import (
+    ProviderModelInfo,
+    ProviderModelRefreshResult,
+)
 from free_claude_code.config.admin.values import MASKED_SECRET
 from free_claude_code.config.server_urls import local_admin_url
 from free_claude_code.config.settings import Settings
-from tests.api.support import create_test_app
+from tests.api.support import create_test_app, provider_manager_for_app
 
 
 def _local_client(app):
@@ -103,6 +107,22 @@ def test_admin_static_hides_managed_source_label():
     assert "sourceEl.textContent = source" in script
 
 
+def test_admin_static_loads_searchable_model_options_and_maps_none_to_unset():
+    script = Path("src/free_claude_code/api/admin_static/admin.js").read_text(
+        encoding="utf-8"
+    )
+
+    assert 'api("/admin/api/models" + (refresh ? "/refresh" : "")' in script
+    assert 'field.type === "model" || field.type === "optional_model"' in script
+    assert '"optional-model-options", ["None", ...state.modelOptions]' in script
+    assert 'input.dataset.fieldType === "optional_model"' in script
+    assert 'return "";' in script
+    assert "await hydrateModelOptions();" in script
+    assert "Model fields remain editable" in script
+    assert "result.failed_providers || []" in script
+    assert '"warn"' in script
+
+
 def test_admin_config_masks_secrets_and_exposes_manifest(monkeypatch, tmp_path):
     _set_home(monkeypatch, tmp_path)
     _clear_process_config(monkeypatch)
@@ -148,6 +168,19 @@ def test_admin_config_masks_secrets_and_exposes_manifest(monkeypatch, tmp_path):
     assert open_browser_field["type"] == "boolean"
     assert open_browser_field["value"] == "true"
     assert open_browser_field["restart_required"] is False
+    model_field_types = {
+        field["key"]: field["type"]
+        for field in body["fields"]
+        if field["key"]
+        in {"MODEL", "MODEL_FABLE", "MODEL_OPUS", "MODEL_SONNET", "MODEL_HAIKU"}
+    }
+    assert model_field_types == {
+        "MODEL": "model",
+        "MODEL_FABLE": "optional_model",
+        "MODEL_OPUS": "optional_model",
+        "MODEL_SONNET": "optional_model",
+        "MODEL_HAIKU": "optional_model",
+    }
     restart_required = {
         field["key"] for field in body["fields"] if field["restart_required"] is True
     }
@@ -163,6 +196,80 @@ def test_admin_config_masks_secrets_and_exposes_manifest(monkeypatch, tmp_path):
     } <= restart_required
 
 
+def test_admin_models_include_configured_and_cached_canonical_slugs():
+    settings = Settings()
+    settings.model = "nvidia_nim/configured-model"
+    settings.model_opus = "open_router/anthropic/configured-opus"
+    settings.open_router_api_key = "open-router-key"
+    app = create_test_app(settings)
+    provider_manager_for_app(app).cache_model_infos(
+        "open_router",
+        {
+            ProviderModelInfo("anthropic/configured-opus"),
+            ProviderModelInfo("meta/llama-3.3"),
+        },
+    )
+
+    response = _local_client(app).get("/admin/api/models")
+
+    assert response.status_code == 200
+    assert response.json() == {
+        "models": [
+            "nvidia_nim/configured-model",
+            "open_router/anthropic/configured-opus",
+            "open_router/meta/llama-3.3",
+        ],
+        "failed_providers": [],
+    }
+
+
+def test_admin_model_refresh_returns_the_updated_canonical_catalog():
+    settings = Settings()
+    settings.model = "deepseek/deepseek-chat"
+    settings.deepseek_api_key = "deepseek-key"
+    app = create_test_app(settings)
+    runtime = app.state.services.admin
+
+    async def refresh_models() -> ProviderModelRefreshResult:
+        provider_manager_for_app(app).cache_model_infos(
+            "deepseek",
+            {ProviderModelInfo("deepseek-reasoner")},
+        )
+        return ProviderModelRefreshResult(refreshed_provider_ids=("deepseek",))
+
+    runtime.refresh_models = AsyncMock(side_effect=refresh_models)
+
+    response = _local_client(app).post("/admin/api/models/refresh")
+
+    assert response.status_code == 200
+    assert response.json() == {
+        "models": ["deepseek/deepseek-chat", "deepseek/deepseek-reasoner"],
+        "failed_providers": [],
+    }
+    runtime.refresh_models.assert_awaited_once_with()
+
+
+def test_admin_model_refresh_reports_partial_provider_failures():
+    settings = Settings()
+    settings.model = "deepseek/deepseek-chat"
+    app = create_test_app(settings)
+    runtime = app.state.services.admin
+    runtime.refresh_models = AsyncMock(
+        return_value=ProviderModelRefreshResult(
+            refreshed_provider_ids=("deepseek",),
+            failed_provider_ids=("open_router",),
+        )
+    )
+
+    response = _local_client(app).post("/admin/api/models/refresh")
+
+    assert response.status_code == 200
+    assert response.json() == {
+        "models": ["deepseek/deepseek-chat"],
+        "failed_providers": ["open_router"],
+    }
+
+
 def test_admin_config_preserves_managed_env_source_contract(monkeypatch, tmp_path):
     _set_home(monkeypatch, tmp_path)
     _clear_process_config(monkeypatch)

tests/api/test_model_listing.py

@@ -19,6 +19,9 @@ def _settings(
         model_sonnet=None,
         model_haiku=model_haiku,
         anthropic_auth_token="",
+        deepseek_api_key="deepseek-key",
+        open_router_api_key="open-router-key",
+        wafer_api_key="wafer-key",
     )
 
 

tests/providers/test_model_validation.py

@@ -367,7 +367,11 @@ class FakeProvider(BaseProvider):
 
 @pytest.mark.asyncio
 async def test_runtime_validation_succeeds_for_all_configured_models() -> None:
-    settings = _settings(model_opus="open_router/anthropic/claude-opus")
+    settings = _settings(
+        model_opus="open_router/anthropic/claude-opus",
+        nvidia_nim_api_key="nim-key",
+        open_router_api_key="open-router-key",
+    )
     runtime = _manager(
         settings,
         {
@@ -468,12 +472,14 @@ async def test_runtime_refresh_model_list_cache_uses_configured_remote_keys_and_
         },
     )
 
-    await runtime.refresh_model_list_cache()
+    result = await runtime.refresh_model_list_cache()
 
     assert runtime.cached_model_ids() == {
         "open_router": frozenset({"anthropic/claude-sonnet"}),
         "lmstudio": frozenset({"local-qwen"}),
     }
+    assert result.refreshed_provider_ids == ("open_router", "lmstudio")
+    assert result.failed_provider_ids == ()
 
 
 @pytest.mark.asyncio
@@ -491,9 +497,11 @@ async def test_runtime_refresh_model_list_cache_keeps_prior_cache_on_failure() -
         {ProviderModelInfo("cached-model")},
     )
 
-    await runtime.refresh_model_list_cache()
+    result = await runtime.refresh_model_list_cache()
 
     assert runtime.cached_model_ids() == {"nvidia_nim": frozenset({"cached-model"})}
+    assert result.refreshed_provider_ids == ()
+    assert result.failed_provider_ids == ("nvidia_nim",)
 
 
 def test_runtime_metadata_cache_exposes_ids_and_prefixed_infos() -> None:
@@ -519,6 +527,21 @@ def test_runtime_metadata_cache_exposes_ids_and_prefixed_infos() -> None:
     )
 
 
+def test_runtime_metadata_cache_enforces_replaced_provider_scope() -> None:
+    cache = ProviderModelCache({"open_router", "lmstudio"})
+    cache.cache_model_ids("open_router", {"old-model"})
+    cache.cache_model_ids("lmstudio", {"local-model"})
+
+    cache.set_available_providers({"deepseek", "lmstudio"})
+    cache.cache_model_ids("open_router", {"late-old-model"})
+    cache.cache_model_ids("deepseek", {"new-model"})
+
+    assert cache.cached_model_ids() == {
+        "deepseek": frozenset({"new-model"}),
+        "lmstudio": frozenset({"local-model"}),
+    }
+
+
 def test_runtime_model_id_cache_keeps_unknown_thinking_support() -> None:
     cache = ProviderModelCache()
     cache.cache_model_ids("open_router", {"plain-model"})

tests/runtime/test_provider_manager.py

@@ -325,7 +325,7 @@ async def test_failed_candidate_cleanup_is_retried_at_shutdown() -> None:
     assert factory.runtimes[1].cleanup_calls == 1
     assert manager._unpublished == {factory.runtimes[1]}
 
-    manager.cache_model_infos("nvidia_nim", {ProviderModelInfo("cached")})
+    manager.cache_model_infos("lmstudio", {ProviderModelInfo("cached")})
     with pytest.raises(
         RuntimeError,
         match="One or more provider runtimes failed to close",
@@ -335,7 +335,7 @@ async def test_failed_candidate_cleanup_is_retried_at_shutdown() -> None:
     assert "private cleanup detail" not in str(exc_info.value)
     assert manager._closed is False
     assert manager._unpublished == {factory.runtimes[1]}
-    assert manager.cached_model_ids() == {"nvidia_nim": frozenset({"cached"})}
+    assert manager.cached_model_ids() == {"lmstudio": frozenset({"cached"})}
 
     factory.runtimes[1].cleanup_error = None
     await manager.close()
@@ -554,7 +554,7 @@ async def test_failed_shutdown_cleanup_is_retryable() -> None:
         _settings("nvidia_nim/one"),
         runtime_factory=factory,
     )
-    manager.cache_model_infos("nvidia_nim", {ProviderModelInfo("cached")})
+    manager.cache_model_infos("lmstudio", {ProviderModelInfo("cached")})
     factory.runtimes[0].cleanup_error = RuntimeError("private provider detail")
 
     with pytest.raises(
@@ -566,7 +566,7 @@ async def test_failed_shutdown_cleanup_is_retryable() -> None:
     assert "private provider detail" not in str(exc_info.value)
     assert manager._closed is False
     assert 1 in manager._retired
-    assert manager.cached_model_ids() == {"nvidia_nim": frozenset({"cached"})}
+    assert manager.cached_model_ids() == {"lmstudio": frozenset({"cached"})}
     assert factory.runtimes[0].cleanup_calls == 1
 
     factory.runtimes[0].cleanup_error = None
@@ -582,21 +582,40 @@ async def test_failed_shutdown_cleanup_is_retryable() -> None:
 async def test_application_catalog_survives_generation_replacement() -> None:
     factory = RuntimeFactory()
     manager = ProviderRuntimeManager(
-        _settings("open_router/one"),
+        _settings("nvidia_nim/one"),
         runtime_factory=factory,
     )
     manager.cache_model_infos(
-        "open_router",
+        "lmstudio",
         {ProviderModelInfo("persisted", supports_thinking=True)},
     )
 
     await manager.replace(
-        _settings("open_router/two"),
+        _settings("nvidia_nim/two"),
+        commit=lambda: None,
+    )
+
+    assert manager.cached_model_ids() == {"lmstudio": frozenset({"persisted"})}
+    assert manager.cached_model_supports_thinking("lmstudio", "persisted") is True
+    await manager.close()
+
+
+@pytest.mark.asyncio
+async def test_replacement_prunes_and_rejects_removed_remote_provider_cache() -> None:
+    factory = RuntimeFactory()
+    first_settings = _settings("open_router/one").model_copy(
+        update={"open_router_api_key": "open-router-key"}
+    )
+    manager = ProviderRuntimeManager(first_settings, runtime_factory=factory)
+    manager.cache_model_infos("open_router", {ProviderModelInfo("old-model")})
+
+    await manager.replace(
+        _settings("nvidia_nim/two"),
         commit=lambda: None,
     )
+    manager.cache_model_infos("open_router", {ProviderModelInfo("late-old-model")})
 
-    assert manager.cached_model_ids() == {"open_router": frozenset({"persisted"})}
-    assert manager.cached_model_supports_thinking("open_router", "persisted") is True
+    assert "open_router" not in manager.cached_model_ids()
     await manager.close()
 
 

uv.lock

@@ -561,7 +561,7 @@ wheels = [
 
 [[package]]
 name = "free-claude-code"
-version = "4.5.2"
+version = "4.6.1"
 source = { editable = "." }
 dependencies = [
     { name = "aiohttp" },