fix(health): surface ollama endpoint diagnosis

apps/api/src/api/v1/health.py

@@ -47,6 +47,11 @@ class ComponentHealth(BaseModel):
     status: Literal["up", "down", "degraded"]
     latency_ms: float | None = None
     error: str | None = None
+    provider_name: str | None = None
+    diagnosis_code: str | None = None
+    retry_after_seconds: float | None = None
+    cooldown_remaining_seconds: float | None = None
+    is_cooldown: bool = False
 
 
 class HealthResponse(BaseModel):
@@ -194,16 +199,47 @@ async def _ollama_endpoint_health_check(name: str, url: str) -> ComponentHealth:
         return ComponentHealth(
             status="down",
             error=f"recent endpoint failure cooldown: {cooldown_remaining:.0f}s",
+            provider_name=name,
+            diagnosis_code="endpoint_cooldown",
+            retry_after_seconds=round(cooldown_remaining, 1),
+            cooldown_remaining_seconds=round(cooldown_remaining, 1),
+            is_cooldown=True,
         )
 
     result = await _http_health_check(name, url, "/api/tags")
+    result.provider_name = name
     if result.status == "up":
+        result.diagnosis_code = "endpoint_reachable"
         record_ollama_endpoint_success(url)
     else:
+        result.diagnosis_code = _classify_ollama_endpoint_failure(name, result.error)
         record_ollama_endpoint_failure(url)
     return result
 
 
+def _classify_ollama_endpoint_failure(
+    provider_name: str,
+    error: str | None,
+) -> str:
+    """Return a stable diagnosis code for UI/alert rendering."""
+    normalized_error = (error or "").lower()
+    if "cooldown" in normalized_error:
+        return "endpoint_cooldown"
+    if "502" in normalized_error or "bad gateway" in normalized_error:
+        return (
+            "local_proxy_upstream_unreachable"
+            if provider_name == "ollama_local"
+            else "proxy_upstream_unreachable"
+        )
+    if "timeout" in normalized_error:
+        return "endpoint_timeout"
+    if "connection refused" in normalized_error:
+        return "endpoint_connection_refused"
+    if "no route to host" in normalized_error or "network is unreachable" in normalized_error:
+        return "endpoint_network_unreachable"
+    return "endpoint_unreachable"
+
+
 async def check_openclaw() -> ComponentHealth:
     """Async OpenClaw health check via /health"""
     return await _http_health_check("openclaw", settings.OPENCLAW_URL, "/health")