fix(providers): hide offline providers' models from model listings

docs/advanced/resilience.mdx

@@ -189,16 +189,23 @@ Model discovery is re-checked:
 
 ## What happens while a provider is down
 
-When a provider's refresh fails, its previously discovered models are kept
-and marked stale, and the dashboard shows the provider as Degraded
-("previous inventory is still available"):
-
-- **Direct requests** to its models still resolve and are sent to the
-  provider, so callers get an honest `502`/`503` (and manual failover rules
-  can fire) instead of a misleading "model not found".
+When a provider's refresh fails, its previously discovered models are marked
+stale, and the dashboard shows the provider as Offline:
+
+- **Model listings** (`GET /v1/models` and the dashboard model list) hide the
+  provider's models until it recovers, so clients are not offered models that
+  cannot currently be served.
+- **Direct requests** to its models (`provider/model`) still resolve and are
+  sent to the provider, so callers get an honest `502`/`503` (and manual
+  failover rules can fire) instead of a misleading "model not found".
 - **Virtual-model redirects** skip the provider's targets, so a
   load-balanced redirect keeps working through its healthy targets.
 
+Exception: when **every** provider is failing at once (for example, a
+control-plane-only outage where model discovery is unreachable but inference
+still works), the previous inventory is kept as-is and stays listed — hiding
+everything would only turn provider errors into "model not found".
+
 The fast recheck loop re-probes the provider every
 `PROVIDER_RECHECK_INTERVAL` seconds, updating "Last checked" and restoring
 normal routing typically within a minute of the provider coming back. A

docs/providers/overview.mdx

@@ -255,9 +255,10 @@ classification reason and the most recent error.
 | `Healthy` | Model discovery succeeded and recent traffic (if any) looks fine |
 | `Starting` | Configured and awaiting first model discovery |
 | `Configured` | Configured but no models exposed yet |
-| `Degraded` | The latest refresh failed (previous inventory still serves), **or** a specific model's recent requests keep failing |
+| `Degraded` | A specific model's recent requests keep failing, **or** every provider is failing at once and the previous inventory still serves |
 | `Recovering` | The circuit breaker is half-open and probing whether the provider recovered |
 | `Circuit Open` | The circuit breaker is open; traffic to the provider is paused |
+| `Offline` | The latest refresh or availability check failed; the provider's models are hidden from the model list until it recovers |
 | `Unhealthy` | Model discovery failed and no models are available |
 
 Expand a card (the arrow strip at the bottom, or the section-wide

internal/admin/handler_providers.go

@@ -236,19 +236,20 @@ func classifyProviderStatus(cfg providers.SanitizedProviderConfig, runtime provi
 	}
 
 	switch {
+	case runtime.InventoryStale && runtime.DiscoveredModelCount > 0:
+		// The latest refresh or availability probe failed: load balancing
+		// skips the provider and its models are no longer advertised. Only
+		// provider-qualified direct requests still reach it.
+		return "unhealthy", "Offline", "latest check failed; models are hidden from the model list until the provider recovers", lastError
 	case runtime.DiscoveredModelCount > 0 && modelFetchError == "":
-		if runtime.InventoryStale {
-			// An availability probe failed without a model fetch running, so
-			// the inventory was retired from load balancing while the fetch
-			// error stayed empty. Surfacing "healthy" here would contradict
-			// the routing behavior.
-			return "degraded", "Degraded", "latest availability probe failed; previous inventory is still available", lastError
-		}
 		if usingCachedModels {
 			return "degraded", "Starting", "serving cached model inventory while live refresh finishes", lastError
 		}
 		return "healthy", "Healthy", "configured and model discovery succeeded", lastError
 	case modelFetchError != "" && runtime.DiscoveredModelCount > 0:
+		// Refresh failed but the inventory was deliberately kept fresh (no
+		// healthy alternative exists, e.g. a total sweep failure), so models
+		// are still advertised and routable.
 		return "degraded", "Degraded", "latest model refresh failed; previous inventory is still available", lastError
 	case modelFetchError != "":
 		return "unhealthy", "Unhealthy", "model discovery failed and no provider models are currently available", lastError

internal/admin/handler_providers_test.go

@@ -37,8 +37,8 @@ func TestClassifyProviderStatus_HealthyForAllowlistInventory(t *testing.T) {
 
 // A provider retired from load balancing by a failed availability probe has a
 // clean model-fetch record but must not be reported healthy: the routing layer
-// is actively skipping it.
-func TestClassifyProviderStatus_StaleInventoryIsDegraded(t *testing.T) {
+// is actively skipping it and its models are hidden from the model list.
+func TestClassifyProviderStatus_StaleInventoryIsUnhealthy(t *testing.T) {
 	now := time.Now().UTC()
 	cfg := providers.SanitizedProviderConfig{Name: "openai", Type: "openai"}
 	runtime := providers.ProviderRuntimeSnapshot{
@@ -55,11 +55,11 @@ func TestClassifyProviderStatus_StaleInventoryIsDegraded(t *testing.T) {
 	}
 
 	status, label, reason, lastError := classifyProviderStatus(cfg, runtime)
-	if status != "degraded" {
-		t.Fatalf("status = %q, want degraded", status)
+	if status != "unhealthy" {
+		t.Fatalf("status = %q, want unhealthy", status)
 	}
-	if label != "Degraded" {
-		t.Fatalf("label = %q, want Degraded", label)
+	if label != "Offline" {
+		t.Fatalf("label = %q, want Offline", label)
 	}
 	if reason == "" {
 		t.Fatal("reason empty, want stale-inventory explanation")

internal/providers/registry.go

@@ -444,7 +444,19 @@ func (r *ModelRegistry) ModelAvailable(model string) bool {
 	return false
 }
 
-// ListModels returns all models in the registry, sorted by model ID for consistent ordering.
+// providerAdvertisedLocked reports whether providerName's models belong in
+// model listings. A provider whose latest refresh or availability probe
+// failed (inventoryStale) keeps its carried-forward inventory resolvable for
+// direct requests, but offline providers must not advertise models in
+// GET /v1/models, the dashboard, or failover candidate selection.
+// Caller must hold r.mu.
+func (r *ModelRegistry) providerAdvertisedLocked(providerName string) bool {
+	return !r.providerRuntime[providerName].inventoryStale
+}
+
+// ListModels returns all advertised models in the registry, sorted by model ID
+// for consistent ordering. Models whose owning provider's inventory is stale
+// are excluded (see providerAdvertisedLocked).
 // The sorted slice is cached and rebuilt only when the underlying models change.
 // Returns a defensive copy so callers cannot mutate the internal cache.
 func (r *ModelRegistry) ListModels() []core.Model {
@@ -464,6 +476,9 @@ func (r *ModelRegistry) ListModels() []core.Model {
 
 	models := make([]core.Model, 0, len(r.models))
 	for _, info := range r.models {
+		if !r.providerAdvertisedLocked(info.ProviderName) {
+			continue
+		}
 		models = append(models, info.Model)
 	}
 	sort.Slice(models, func(i, j int) bool { return models[i].ID < models[j].ID })
@@ -475,7 +490,7 @@ func (r *ModelRegistry) ListModels() []core.Model {
 // ListPublicModels returns all provider-backed models as public selectors in
 // providerName/modelID form, sorted by public model ID. Models the owning
 // provider cannot actually serve (audio-only models on providers without audio
-// support) are not advertised.
+// support) and models from providers with stale inventory are not advertised.
 func (r *ModelRegistry) ListPublicModels() []core.Model {
 	r.mu.RLock()
 	defer r.mu.RUnlock()
@@ -487,6 +502,9 @@ func (r *ModelRegistry) ListPublicModels() []core.Model {
 
 	result := make([]core.Model, 0, total)
 	for providerName, models := range r.modelsByProvider {
+		if !r.providerAdvertisedLocked(providerName) {
+			continue
+		}
 		for modelID, info := range models {
 			if !providerCanServeModel(info) {
 				continue
@@ -788,6 +806,9 @@ func (r *ModelRegistry) ListModelsWithProvider() []ModelWithProvider {
 
 	result := make([]ModelWithProvider, 0, total)
 	for providerName, providerModels := range r.modelsByProvider {
+		if !r.providerAdvertisedLocked(providerName) {
+			continue
+		}
 		for modelID, info := range providerModels {
 			publicProviderName := providerName
 			if info.ProviderName != "" {
@@ -850,7 +871,10 @@ func (r *ModelRegistry) ListModelsWithProviderByCategory(category core.ModelCate
 	}
 
 	result := make([]ModelWithProvider, 0)
-	for _, providerModels := range r.modelsByProvider {
+	for providerName, providerModels := range r.modelsByProvider {
+		if !r.providerAdvertisedLocked(providerName) {
+			continue
+		}
 		for modelID, info := range providerModels {
 			if info.Model.Metadata == nil || !hasCategory(info.Model.Metadata.Categories, category) {
 				continue
@@ -905,7 +929,10 @@ func (r *ModelRegistry) GetCategoryCounts() []CategoryCount {
 
 	counts := make(map[core.ModelCategory]int)
 	total := 0
-	for _, providerModels := range r.modelsByProvider {
+	for providerName, providerModels := range r.modelsByProvider {
+		if !r.providerAdvertisedLocked(providerName) {
+			continue
+		}
 		for _, info := range providerModels {
 			total++
 			if info.Model.Metadata != nil {

internal/providers/registry_cache.go

@@ -156,6 +156,13 @@ func (r *ModelRegistry) SaveToCache(ctx context.Context) error {
 	cacheBackend := r.cache
 	modelsByProvider := make(map[string]map[string]*ModelInfo, len(r.modelsByProvider))
 	for providerName, models := range r.modelsByProvider {
+		// A stale inventory was carried forward from before the provider went
+		// offline; persisting it would resurrect the offline provider's models
+		// on every restart. The provider re-enters the cache once a refresh
+		// succeeds again.
+		if r.providerRuntime[providerName].inventoryStale {
+			continue
+		}
 		modelsByProvider[providerName] = make(map[string]*ModelInfo, len(models))
 		maps.Copy(modelsByProvider[providerName], models)
 	}

internal/providers/registry_cache_test.go

@@ -3,6 +3,7 @@ package providers
 import (
 	"context"
 	"encoding/json"
+	"errors"
 	"os"
 	"path/filepath"
 	"testing"
@@ -832,3 +833,56 @@ func TestRegisterProviderWithType(t *testing.T) {
 		t.Errorf("expected 1 provider, got %d", registry.ProviderCount())
 	}
 }
+
+// SaveToCache must not persist a stale (carried-forward) inventory: an
+// offline provider's models would otherwise resurrect from the cache on every
+// restart and stay advertised forever (issue #705).
+func TestSaveToCache_SkipsStaleProviderInventory(t *testing.T) {
+	tmpDir := t.TempDir()
+	cacheFile := filepath.Join(tmpDir, "models.json")
+
+	registry, _, beta := registerTwoProviderRegistry(t)
+	registry.SetCache(modelcache.NewLocalCache(cacheFile))
+
+	beta.err = errors.New("connection refused")
+	if err := registry.Initialize(context.Background()); err != nil {
+		t.Fatalf("refresh Initialize() error = %v", err)
+	}
+	if err := registry.SaveToCache(context.Background()); err != nil {
+		t.Fatalf("SaveToCache() error = %v", err)
+	}
+
+	data, err := os.ReadFile(cacheFile)
+	if err != nil {
+		t.Fatalf("failed to read cache file: %v", err)
+	}
+	var modelCache modelcache.ModelCache
+	if err := json.Unmarshal(data, &modelCache); err != nil {
+		t.Fatalf("failed to unmarshal cache: %v", err)
+	}
+	if _, ok := modelCache.Providers["beta"]; ok {
+		t.Error("stale provider beta persisted to cache, want skipped")
+	}
+	if _, ok := modelCache.Providers["alpha"]; !ok {
+		t.Error("healthy provider alpha missing from cache")
+	}
+
+	// After recovery the provider re-enters the cache.
+	beta.err = nil
+	if err := registry.Initialize(context.Background()); err != nil {
+		t.Fatalf("recovery Initialize() error = %v", err)
+	}
+	if err := registry.SaveToCache(context.Background()); err != nil {
+		t.Fatalf("SaveToCache() after recovery error = %v", err)
+	}
+	data, err = os.ReadFile(cacheFile)
+	if err != nil {
+		t.Fatalf("failed to re-read cache file: %v", err)
+	}
+	if err := json.Unmarshal(data, &modelCache); err != nil {
+		t.Fatalf("failed to unmarshal refreshed cache: %v", err)
+	}
+	if _, ok := modelCache.Providers["beta"]; !ok {
+		t.Error("recovered provider beta missing from cache, want persisted again")
+	}
+}

internal/providers/registry_test.go

@@ -1191,6 +1191,93 @@ func TestInitialize_StaleProviderLosesBareModelIDToHealthyDuplicate(t *testing.T
 	}
 }
 
+// A provider that goes offline must disappear from every model listing
+// (GET /v1/models, dashboard model list, category counts) while its
+// carried-forward inventory stays resolvable for direct requests, and it must
+// reappear once the provider recovers (issue #705).
+func TestStaleProviderModelsAreNotAdvertised(t *testing.T) {
+	registry, _, beta := registerTwoProviderRegistry(t)
+
+	listedIDs := func(t *testing.T) map[string]bool {
+		t.Helper()
+		ids := make(map[string]bool)
+		for _, model := range registry.ListPublicModels() {
+			ids["public:"+model.ID] = true
+		}
+		for _, entry := range registry.ListModelsWithProvider() {
+			ids["provider:"+entry.Selector] = true
+		}
+		for _, model := range registry.ListModels() {
+			ids["bare:"+model.ID] = true
+		}
+		return ids
+	}
+
+	categorySelectors := func(t *testing.T) map[string]bool {
+		t.Helper()
+		selectors := make(map[string]bool)
+		for _, entry := range registry.ListModelsWithProviderByCategory(core.CategoryEmbedding) {
+			selectors[entry.Selector] = true
+		}
+		return selectors
+	}
+
+	before := listedIDs(t)
+	for _, key := range []string{"public:beta/beta-model", "provider:beta/beta-model", "bare:beta-model"} {
+		if !before[key] {
+			t.Fatalf("%s missing from listings while beta is healthy", key)
+		}
+	}
+	if !categorySelectors(t)["beta/beta-model"] {
+		t.Fatal("beta/beta-model missing from embedding category while beta is healthy")
+	}
+
+	beta.err = errors.New("connection refused")
+	if err := registry.Initialize(context.Background()); err != nil {
+		t.Fatalf("refresh Initialize() error = %v", err)
+	}
+
+	after := listedIDs(t)
+	for _, key := range []string{"public:beta/beta-model", "provider:beta/beta-model", "bare:beta-model"} {
+		if after[key] {
+			t.Errorf("%s still advertised after beta went offline, want hidden", key)
+		}
+	}
+	for _, key := range []string{"public:alpha/alpha-model", "provider:alpha/alpha-model", "bare:alpha-model"} {
+		if !after[key] {
+			t.Errorf("%s missing from listings, want healthy provider unaffected", key)
+		}
+	}
+	for _, counts := range registry.GetCategoryCounts() {
+		if counts.Category == core.CategoryAll && counts.Count != 1 {
+			t.Errorf("GetCategoryCounts()[all] = %d with beta offline, want 1", counts.Count)
+		}
+	}
+	afterCategory := categorySelectors(t)
+	if afterCategory["beta/beta-model"] {
+		t.Error("beta/beta-model still in embedding category after beta went offline, want hidden")
+	}
+	if !afterCategory["alpha/alpha-model"] {
+		t.Error("alpha/alpha-model missing from embedding category, want healthy provider unaffected")
+	}
+	// Direct requests must still resolve the carried inventory (honest 502 at
+	// the provider instead of "model not found").
+	if !registry.Supports("beta/beta-model") {
+		t.Error("Supports(beta/beta-model) = false, want carried inventory still resolvable")
+	}
+
+	beta.err = nil
+	if err := registry.Initialize(context.Background()); err != nil {
+		t.Fatalf("recovery Initialize() error = %v", err)
+	}
+	recovered := listedIDs(t)
+	for _, key := range []string{"public:beta/beta-model", "provider:beta/beta-model", "bare:beta-model"} {
+		if !recovered[key] {
+			t.Errorf("%s missing from listings after recovery, want advertised again", key)
+		}
+	}
+}
+
 // The fast recheck loop re-probes only providers whose latest refresh failed,
 // so a recovered provider is picked up within the recheck interval instead of
 // waiting for the next full refresh.
@@ -1245,7 +1332,13 @@ func registerTwoProviderRegistry(t *testing.T) (*ModelRegistry, *registryMockPro
 	singleModel := func(owner string) *core.ModelsResponse {
 		return &core.ModelsResponse{
 			Object: "list",
-			Data:   []core.Model{{ID: owner + "-model", Object: "model", OwnedBy: owner}},
+			Data: []core.Model{{
+				ID: owner + "-model", Object: "model", OwnedBy: owner,
+				Metadata: &core.ModelMetadata{
+					Modes:      []string{"embedding"},
+					Categories: []core.ModelCategory{core.CategoryEmbedding},
+				},
+			}},
 		}
 	}
 	alpha := &registryMockProvider{name: "alpha", modelsResponse: singleModel("alpha")}

web/dashboard/src/pages/overview/ProviderStatusCard.svelte

@@ -63,8 +63,10 @@
   <div class="provider-status-meta">
     <div class="provider-status-meta-item">
       <span class="provider-status-meta-label">{m.overview_models_available()}</span>
+      <!-- A stale inventory is carried for direct requests only; the models
+           are hidden from the model list, so advertise 0 here. -->
       <span class="provider-status-meta-value mono"
-      >{formatNumber(provider.runtime?.discovered_model_count)}</span>
+      >{formatNumber(provider.runtime?.inventory_stale ? 0 : provider.runtime?.discovered_model_count)}</span>
     </div>
     <div class="provider-status-meta-item">
       <span class="provider-status-meta-label">{m.overview_last_checked()}</span>