fix: start provider heartbeat and guard initial state

api/providers.py

@@ -428,15 +428,17 @@ async def debug_timing(role: AuthRole = Depends(require_role(AuthRole.MACHINE)))
 @router.get("/api/providers/heartbeat")
 async def providers_heartbeat(role: AuthRole = Depends(require_role(AuthRole.MACHINE))):  # GAP-1-fix
     now = int(time.time())
+    # Il primo ciclo async potrebbe non essere ancora partito: la route di health
+    # deve restituire uno snapshot coerente, non propagare un KeyError come HTTP 500.
     return {
-        "status":          _heartbeat_state["status"],
-        "best_provider":   _heartbeat_state["best_provider"],
-        "best_latency_ms": _heartbeat_state["best_latency_ms"],
-        "providers":       _heartbeat_state["providers"],
-        "last_run_at":     _heartbeat_state["last_run_at"],
-        "next_run_at":     _heartbeat_state["next_run_at"],
-        "runs":            _heartbeat_state["runs"],
-        "error":           _heartbeat_state["error"],
+        "status":          _heartbeat_state.get("status", "idle"),
+        "best_provider":   _heartbeat_state.get("best_provider"),
+        "best_latency_ms": _heartbeat_state.get("best_latency_ms"),
+        "providers":       _heartbeat_state.get("providers", []),
+        "last_run_at":     _heartbeat_state.get("last_run_at"),
+        "next_run_at":     _heartbeat_state.get("next_run_at"),
+        "runs":            _heartbeat_state.get("runs", 0),
+        "error":           _heartbeat_state.get("error"),
         "interval_s":      _HEARTBEAT_INTERVAL_S,
         "server_time":     now,
     }

api/state.py

@@ -138,6 +138,10 @@ _AGENT_TASK_MAX    = 200
 _ai_health_cache: dict = {"data": None, "at": 0.0}
 _AI_HEALTH_TTL = 60.0
 _heartbeat_state: dict = {
+    # Stato completo disponibile già al boot: le route di osservabilità non
+    # devono dipendere dal primo ciclo async per avere le chiavi di risposta.
+    "status":          "idle",
+    "error":           None,
     "last_run_at":     None,
     "next_run_at":     None,
     "best_provider":   None,

main.py

@@ -215,6 +215,12 @@ async def startup_event():
     except Exception as e:
         _logger.warning(f"⚠️ BOOT: apply_rls_fix_sync() fallito (non bloccante): {e}")
     asyncio.create_task(_run_auto_migration())
+    try:
+        from api.providers import start_heartbeat
+        start_heartbeat()
+        _logger.info("✅ BOOT: provider heartbeat avviato.")
+    except Exception as e:
+        _logger.warning(f"⚠️ BOOT: avvio provider heartbeat fallito (non bloccante): {e}")
     if not any(arg in sys.argv for arg in ["--task", "-t"]):
         try:
             from api.job_queue import start_job_queue_consumer

tests/test_provider_heartbeat_state.py

@@ -0,0 +1,43 @@
+import asyncio
+import unittest
+
+from api import providers, state
+
+
+class ProviderHeartbeatStateTests(unittest.IsolatedAsyncioTestCase):
+    async def test_endpoint_returns_safe_snapshot_for_partial_legacy_state(self):
+        original = dict(state._heartbeat_state)
+        try:
+            # Simula uno stato parziale proveniente da un deploy precedente o
+            # dalla finestra di boot prima del primo ciclo heartbeat.
+            state._heartbeat_state.clear()
+            state._heartbeat_state.update({"providers": [], "runs": 0})
+
+            payload = await providers.providers_heartbeat(role=None)
+
+            self.assertEqual(payload["status"], "idle")
+            self.assertIsNone(payload["error"])
+            self.assertEqual(payload["providers"], [])
+            self.assertEqual(payload["runs"], 0)
+            self.assertIn("server_time", payload)
+        finally:
+            state._heartbeat_state.clear()
+            state._heartbeat_state.update(original)
+
+    async def test_start_heartbeat_creates_a_single_background_task(self):
+        original_task = providers._heartbeat_task
+        providers._heartbeat_task = None
+        try:
+            providers.start_heartbeat()
+            task = providers._heartbeat_task
+            self.assertIsNotNone(task)
+            self.assertFalse(task.done())
+            task.cancel()
+            with self.assertRaises(asyncio.CancelledError):
+                await task
+        finally:
+            providers._heartbeat_task = original_task
+
+
+if __name__ == "__main__":
+    unittest.main()