sync: 190 file da Baida98/AI@977dd543 (2026-08-26 10:41 UTC) [deploy-all]

.gitattributes

@@ -0,0 +1,35 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

Dockerfile

@@ -38,4 +38,4 @@ COPY --chown=user . /home/user/app/
 
 EXPOSE 7860
 
-CMD ["sh", "-c", "uvicorn main:app --host 0.0.0.0 --port ${PORT:-7860} --workers ${WEB_CONCURRENCY:-2}"]
+CMD ["sh", "-c", "uvicorn main:app --host 0.0.0.0 --port ${PORT:-7860} --workers 1"]

REBUILD_TRIGGER

@@ -0,0 +1 @@
+rebuild

agents/audit_semantic_l2.py

@@ -0,0 +1,303 @@
+"""
+audit_semantic_l2.py — S303: Audit Semantico L2 (Critico Senior) su Nodo D.
+
+L1 (goal_verifier.py) valida se la risposta *aderisce* al goal.
+L2 (questo file) verifica la *coerenza logica interna* dell'output:
+  - Nessuna contraddizione auto-referenziale
+  - Claim verificabili non inventati (anti-hallucination guard)
+  - Completezza rispetto ai sotto-obiettivi esplicitati nel goal
+  - Stato outcome: PASS / FAIL / UNKNOWN — mai forzare PASS
+
+Integrazione: chiamato DOPO GoalVerifier L1 in unified_loop_fallback.py.
+Se L1 = FAIL → L2 non viene invocato (risparmio token).
+Se L1 = PASS o UNKNOWN → L2 aggiunge una seconda garanzia semantica.
+
+Output: AuditL2Result (dataclass) con status, issues[], confidence, repair_hint.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import re
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Optional
+
+_logger = logging.getLogger("agents.audit_l2")
+
+
+class AuditStatus(str, Enum):
+    PASS    = "PASS"
+    FAIL    = "FAIL"
+    UNKNOWN = "UNKNOWN"
+
+
+@dataclass
+class AuditL2Result:
+    status:      AuditStatus
+    confidence:  float = 0.0          # 0.0 – 1.0
+    issues:      list[str] = field(default_factory=list)
+    repair_hint: str = ""
+    engine:      str = "heuristic"    # "heuristic" | "llm"
+
+
+# ── Pattern anti-hallucination ────────────────────────────────────────────────
+# Claim di azioni che l'agente NON può eseguire da solo senza tool confirmation.
+# Copre IT / EN / ES / FR — le 4 lingue attive nel cluster.
+_HALLUCINATION_PATTERNS: list[tuple[re.Pattern, str]] = [
+    # Deploy / publish
+    (re.compile(
+        r"\b(ho deployato|ho pubblicato|ho pushato|ho committato|ho inviato|"
+        r"ho caricato|ho aggiornato il server|ho rilasciato|"
+        r"i deployed|i pushed|i committed|i published|i sent|i uploaded|i released|"
+        r"he desplegado|he publicado|he enviado|he subido|he lanzado|"
+        r"j'ai déployé|j'ai publié|j'ai envoyé|j'ai poussé|j'ai mis en ligne)\b",
+        re.I),
+     "claim di deploy/push/send non verificato da tool"),
+
+    # Stato esterno live
+    (re.compile(
+        r"\b(il sito è live|the site is live|ora funziona|it now works|"
+        r"è online|is online|è andato live|went live|"
+        r"the app is running|l'app è in esecuzione|"
+        r"el sitio está en vivo|el sistema funciona ahora|"
+        r"le site est en ligne|l'application fonctionne maintenant)\b",
+        re.I),
+     "claim di stato esterno non verificabile"),
+
+    # Assunzioni sull'utente
+    (re.compile(
+        r"\b(l'utente ha|the user has|hai già|you already|"
+        r"your database (is|has)|il tuo database (è|ha)|"
+        r"el usuario ya|vous avez déjà)\b",
+        re.I),
+     "assunzione su stato dell'utente non verificabile"),
+
+    # Test / CI passati senza prova
+    (re.compile(
+        r"\b(tutti i test passano|all tests pass|i test sono verdi|tests are green|"
+        r"la CI è verde|CI is green|build successful|build riuscita|"
+        r"todos los tests pasan|tous les tests passent)\b",
+        re.I),
+     "claim di test/CI passati senza esecuzione verificata"),
+]
+
+# ── Pattern contraddizione interna ────────────────────────────────────────────
+_CONTRADICTION_PAIRS: list[tuple[str, str]] = [
+    ("errore", "nessun errore"),
+    ("error", "no error"),
+    ("fallito", "completato con successo"),
+    ("failed", "completed successfully"),
+    ("non trovato", "trovato correttamente"),
+    ("not found", "found correctly"),
+    ("timeout", "risposta ricevuta"),
+    ("timeout", "response received"),
+    ("impossibile", "funziona"),
+    ("impossible", "works"),
+    ("non funziona", "funziona correttamente"),
+    ("doesn't work", "works correctly"),
+    ("eccezione", "nessuna eccezione"),
+    ("exception", "no exception"),
+    ("crash", "stabile"),
+    ("crash", "stable"),
+]
+
+
+def _check_hallucinations(text: str) -> list[str]:
+    issues = []
+    for pattern, label in _HALLUCINATION_PATTERNS:
+        if pattern.search(text):
+            issues.append(f"Possibile hallucination: {label}")
+    return issues
+
+
+def _check_contradictions(text: str) -> list[str]:
+    issues = []
+    text_lower = text.lower()
+    for a, b in _CONTRADICTION_PAIRS:
+        if a in text_lower and b in text_lower:
+            issues.append(f"Contraddizione interna: '{a}' e '{b}' co-presenti")
+    return issues
+
+
+def _check_completeness(goal: str, answer: str) -> list[str]:
+    """
+    Controlla che i sotto-obiettivi espliciti del goal (identificati da liste numerate
+    o bullet points) siano almeno menzionati nella risposta.
+    """
+    issues = []
+    sub_goals = re.findall(
+        r"(?:^|\n)\s*(?:\d+\.|[-*•])\s+(.+?)(?:\n|$)", goal
+    )
+    if not sub_goals:
+        return []
+    answer_lower = answer.lower()
+    missing = []
+    for sg in sub_goals[:8]:  # max 8 sotto-obiettivi
+        words = [w for w in sg.lower().split() if len(w) > 4][:4]
+        if words and sum(1 for w in words if w in answer_lower) < max(1, len(words) // 2):
+            missing.append(sg.strip()[:60])
+    if missing:
+        issues.append(f"Sotto-obiettivi non indirizzati: {missing[:3]}")
+    return issues
+
+
+def _heuristic_audit(goal: str, answer: str) -> AuditL2Result:
+    """Audit euristico: pattern matching su testo, senza LLM."""
+    issues: list[str] = []
+    issues.extend(_check_hallucinations(answer))
+    issues.extend(_check_contradictions(answer))
+    issues.extend(_check_completeness(goal, answer))
+
+    if not issues:
+        return AuditL2Result(
+            status=AuditStatus.PASS,
+            confidence=0.75,
+            engine="heuristic",
+        )
+    # Gravi (hallucination o contraddizione) → FAIL; solo completeness → UNKNOWN
+    has_severe = any(
+        "hallucination" in i or "Contraddizione" in i or "contradiction" in i.lower()
+        for i in issues
+    )
+    return AuditL2Result(
+        status=AuditStatus.FAIL if has_severe else AuditStatus.UNKNOWN,
+        confidence=0.82 if has_severe else 0.55,
+        issues=issues,
+        repair_hint="Rivedere e rimuovere claim non verificati o contraddizioni.",
+        engine="heuristic",
+    )
+
+
+_AUDIT_SYSTEM = (
+    "Sei un Critico Senior che verifica la coerenza logica delle risposte di un agente AI. "
+    "Rispondi SOLO con JSON valido, senza markdown. Formato:\n"
+    '{"status":"PASS"|"FAIL"|"UNKNOWN","confidence":0.0-1.0,'
+    '"issues":["..."],"repair_hint":"..."}\n\n'
+    "Regole: FAIL solo per problemi gravi (hallucination, contraddizioni). "
+    "UNKNOWN per incertezze moderate. PASS se la risposta è coerente. "
+    "Mai forzare PASS se ci sono dubbi fondati."
+)
+
+
+def _build_audit_prompt(goal: str, answer: str) -> str:
+    # Tronca intelligentemente: preserva inizio e fine dell'answer
+    max_ans = 1400
+    if len(answer) > max_ans:
+        half = max_ans // 2
+        answer_trunc = answer[:half] + "\n[...]\n" + answer[-half:]
+    else:
+        answer_trunc = answer
+    return (
+        f"GOAL ORIGINALE:\n{goal[:500]}\n\n"
+        f"RISPOSTA AGENTE:\n{answer_trunc}\n\n"
+        "VERIFICA (rispondi solo con JSON):\n"
+        "1. Ci sono claim di azioni esterne non verificabili (deploy/push/send/test-pass senza tool proof)?\n"
+        "2. Ci sono contraddizioni interne (es. 'errore' e 'completato con successo' co-presenti)?\n"
+        "3. La risposta indirizza almeno i sotto-obiettivi espliciti del goal?\n"
+    )
+
+
+class SemanticAuditorL2:
+    """
+    S303 — Audit Semantico L2.
+    Istanziato come singleton.
+    Usato in unified_loop_fallback.py dopo GoalVerifier L1 (solo se L1 ≠ FAIL).
+    """
+
+    def __init__(self, ai_client: Any = None, timeout_s: float = 12.0):
+        self.ai_client = ai_client
+        self.timeout_s = timeout_s
+
+    async def audit(self, goal: str, answer: str) -> AuditL2Result:
+        """
+        Punto di ingresso principale.
+        1. Prova audit LLM se ai_client disponibile.
+        2. Fallback a audit euristico in caso di errore o timeout.
+        """
+        if not goal or not answer:
+            return AuditL2Result(status=AuditStatus.UNKNOWN, confidence=0.0,
+                                 issues=["goal o answer vuoti"])
+
+        # Euristico sempre eseguito — base line gratuita
+        heuristic_result = _heuristic_audit(goal, answer)
+
+        # Se euristico ha già trovato problemi gravi, non invocare LLM per efficienza
+        if heuristic_result.status == AuditStatus.FAIL and len(heuristic_result.issues) >= 2:
+            _logger.debug("[AuditL2] heuristic FAIL con %d issues — skip LLM", len(heuristic_result.issues))
+            return heuristic_result
+
+        if self.ai_client is not None:
+            try:
+                result = await asyncio.wait_for(
+                    self._llm_audit(goal, answer),
+                    timeout=self.timeout_s
+                )
+                if result:
+                    # Merge: se LLM dice PASS ma euristico ha trovato issue → UNKNOWN
+                    if result.status == AuditStatus.PASS and heuristic_result.issues:
+                        result.status = AuditStatus.UNKNOWN
+                        result.issues = heuristic_result.issues
+                        result.confidence = min(result.confidence, 0.65)
+                    return result
+            except asyncio.TimeoutError:
+                _logger.warning("[AuditL2] timeout LLM (%.1fs) — fallback euristico", self.timeout_s)
+            except Exception as e:
+                _logger.warning("[AuditL2] errore LLM (%s) — fallback euristico", type(e).__name__)
+
+        return heuristic_result
+
+    async def _llm_audit(self, goal: str, answer: str) -> Optional[AuditL2Result]:
+        """Chiamata LLM reale per l'audit semantico."""
+        prompt = _build_audit_prompt(goal, answer)
+        # Preferisce modello veloce/economico (8B) — audit non richiede ragionamento profondo
+        _model = getattr(self.ai_client, "_audit_model", None) or "llama-3.1-8b-instant"
+        response = await self.ai_client.chat.completions.create(
+            model=_model,
+            messages=[
+                {"role": "system", "content": _AUDIT_SYSTEM},
+                {"role": "user",   "content": prompt},
+            ],
+            max_tokens=256,
+            temperature=0.0,  # deterministico
+        )
+        raw = response.choices[0].message.content or ""
+        match = re.search(r"\{[\s\S]*?\}", raw)
+        if not match:
+            _logger.warning("[AuditL2] risposta LLM non contiene JSON: %.80s", raw)
+            return None
+        try:
+            parsed = json.loads(match.group(0))
+        except json.JSONDecodeError as _je:
+            _logger.warning("[AuditL2] JSON decode error: %s", _je)
+            return None
+        status_raw = parsed.get("status", "UNKNOWN").upper()
+        try:
+            status = AuditStatus(status_raw)
+        except ValueError:
+            status = AuditStatus.UNKNOWN
+        return AuditL2Result(
+            status=status,
+            confidence=float(parsed.get("confidence", 0.70)),
+            issues=parsed.get("issues", []),
+            repair_hint=parsed.get("repair_hint", ""),
+            engine="llm",
+        )
+
+
+# ── Singleton ─────────────────────────────────────────────────────────────────
+_auditor: Optional[SemanticAuditorL2] = None
+
+def get_auditor(ai_client: Any = None, timeout_s: float = 12.0) -> SemanticAuditorL2:
+    """
+    Ritorna o crea il singleton SemanticAuditorL2.
+    Se chiamato con ai_client=<client> e il singleton esiste già senza client,
+    aggiorna il client sul singleton esistente (upgrade lazy).
+    """
+    global _auditor
+    if _auditor is None:
+        _auditor = SemanticAuditorL2(ai_client=ai_client, timeout_s=timeout_s)
+    elif ai_client is not None and _auditor.ai_client is None:
+        _auditor.ai_client = ai_client  # upgrade: inserisce client dopo init
+    return _auditor

agents/executor.py

@@ -292,39 +292,15 @@ class Executor:
                 _t0          = _time_mod.monotonic()
                 result       = await asyncio.wait_for(fn(**inputs), timeout=_adaptive_to)
                 _timeout_tracker.record(tool_name, _time_mod.monotonic() - _t0)
-
-                # Il tool ha già prodotto il side effect: la persistenza memoria
-                # è osservabilità e non deve riaprire il retry del tool.
-                _memory_persisted = True
-                _memory_error = None
                 if self.memory:
-                    try:
-                        # S577→S600: inputs 100→500 — parity con altri handler
-                        await self.memory.save_episode(
-                            "tool",
-                            f"{tool_name}: {str(inputs)[:500]}",
-                            str(result)[:500],
-                            True,
-                        )
-                    except Exception as _memory_exc:
-                        _memory_persisted = False
-                        _memory_error = f"{type(_memory_exc).__name__}: {str(_memory_exc)[:240]}"
-                        _logger.warning(
-                            "[executor] tool %s completato ma save_episode fallito; "
-                            "nessun retry del side effect: %s",
-                            tool_name,
-                            _memory_error,
-                        )
-                response = {
-                    "success": True,
-                    "tool": tool_name,
-                    "output": result,
-                    "attempt": attempt + 1,
-                    "memory_persisted": _memory_persisted,
-                }
-                if _memory_error:
-                    response["memory_error"] = _memory_error
-                return response
+                    # S577→S600: inputs 100→500 — parity con altri handler
+                    await self.memory.save_episode(
+                        "tool",
+                        f"{tool_name}: {str(inputs)[:500]}",
+                        str(result)[:500],
+                        True,
+                    )
+                return {"success": True, "tool": tool_name, "output": result, "attempt": attempt + 1}
 
             except asyncio.TimeoutError:
                 # FIX-GAP2: registra il timeout come durata massima per shrink futuro

agents/fallback_healer.py

@@ -0,0 +1,59 @@
+"""fallback_healer.py — Logica di Self-Healing strategico per il loop di fallback.
+Estratto da unified_loop_fallback.py (split 2026-06-30).
+"""
+import logging
+import re
+
+_logger = logging.getLogger("api.agent.healer")
+
+class StrategicHealer:
+    @staticmethod
+    def analyze_errors(exec_errors: list, exec_warn: list) -> None:
+        """
+        Analizza gli errori ripetuti e inietta messaggi di 'CAMBIO STRATEGIA' (GAP-SELFHEAL v2).
+        """
+        if not exec_errors:
+            return
+
+        # Fingerprinting degli errori (Dual-mode: raw + error-class)
+        _selfheal_raw = {}
+        _selfheal_cls = {}
+        
+        for _err in exec_errors:
+            if not isinstance(_err, str): continue
+            # Mode 1: raw fingerprinting
+            _fp = _err[:120]
+            _selfheal_raw[_fp] = _selfheal_raw.get(_fp, 0) + 1
+            # Mode 2: error-class extraction
+            _m = re.search(r"([A-Z][a-z]+Error):", _err)
+            if _m:
+                _c = _m.group(1).lower()
+                _selfheal_cls[_c] = _selfheal_cls.get(_c, 0) + 1
+
+        _selfheal_raw_max = max(_selfheal_raw.values()) if _selfheal_raw else 0
+        _selfheal_cls_max = max(_selfheal_cls.values()) if _selfheal_cls else 0
+        _selfheal_max = max(_selfheal_raw_max, _selfheal_cls_max)
+
+        if _selfheal_max >= 2:
+            _ERRCLASS_HINTS = {
+                "typeerror": "Controlla i tipi degli argomenti, aggiungi conversioni esplicite.",
+                "keyerror": "Usa .get(key, default) invece di [], controlla l'esistenza.",
+                "attributeerror": "Controlla che l'oggetto non sia None.",
+                "nameerror": "Controlla typo nel nome variabile/funzione.",
+                "syntaxerror": "Controlla la sintassi o le quote del comando.",
+                "memoryerror": "Processa in chunk, riduci dimensione dati.",
+            }
+            
+            _dom_cls = max(_selfheal_cls, key=_selfheal_cls.get) if _selfheal_cls else ""
+            _specific = _ERRCLASS_HINTS.get(_dom_cls, "Usa un approccio completamente diverso.")
+            
+            _selfheal_msg = (
+                f"⚠️ CAMBIO STRATEGIA OBBLIGATORIO [{_dom_cls or 'errore ripetuto'}×{_selfheal_max}]: "
+                f"Hint specifico: {_specific} "
+                "NON ripetere lo stesso metodo — cambia libreria o pattern."
+            )
+
+            # Evita doppia iniezione
+            if not any(isinstance(w, str) and "CAMBIO STRATEGIA" in w for w in exec_warn):
+                exec_warn.insert(0, _selfheal_msg)
+                _logger.info("GAP-SELFHEAL: Strategia di healing iniettata per %s", _dom_cls or "errore raw")

agents/fallback_utils.py

@@ -0,0 +1,26 @@
+"""fallback_utils.py — Funzioni di utilità per il loop di fallback.
+Estratto da unified_loop_fallback.py (split 2026-06-30).
+"""
+import re
+
+def _is_refusal(text: str) -> bool:
+    """Verifica se la risposta del modello è un rifiuto (S129)."""
+    if not text: return False
+    refusals = ["mi dispiace", "non posso", "i apologize", "i cannot", "unauthorized", "access denied"]
+    t = text.lower()
+    return any(r in t for r in refusals)
+
+def _s759_bjac(a: str, b: str) -> float:
+    """Calcola la somiglianza di Jaccard tra due stringhe (S759)."""
+    if not a or not b: return 0.0
+    set_a = set(a.lower().split())
+    set_b = set(b.lower().split())
+    intersection = len(set_a.intersection(set_b))
+    union = len(set_a.union(set_b))
+    return intersection / union if union > 0 else 0.0
+
+def _avg10(lst: list) -> float:
+    """Calcola la media degli ultimi 10 elementi di una lista."""
+    if not lst: return 0.0
+    sub = lst[-10:]
+    return sum(sub) / len(sub)

agents/grid_rag.py

@@ -0,0 +1,124 @@
+"""
+backend/agents/grid_rag.py — Grid-Enhanced RAG (S766-GRID-4)
+
+Sistema RAG (Retrieval-Augmented Generation) avanzato che indicizza:
+- Memoria distribuita (Supabase A, B, C, D)
+- Log di sistema e di Railway
+- Documentazione interna (.agents/memory/)
+
+Architettura:
+- GridIndexer: Indicizza i dati provenienti da diverse fonti
+- ContextRetriever: Recupera il contesto più rilevante per il goal corrente
+- KnowledgeGraph: Mappa le relazioni tra i diversi profili e i loro stati
+"""
+
+import os
+import asyncio
+import logging
+from typing import List, Dict, Any, Optional
+from datetime import datetime
+import json
+
+_logger = logging.getLogger("grid_rag")
+
+# ── Configurazione ─────────────────────────────────────────────────────────
+RAG_INDEX_SIZE = 100  # Numero di elementi da mantenere nel buffer RAG
+RAG_SIMILARITY_THRESHOLD = 0.75
+
+
+class GridIndexer:
+    """Indicizzatore per la Grid."""
+
+    def __init__(self):
+        self.index = []
+        self._lock = asyncio.Lock()
+
+    async def add_to_index(self, source: str, content: str, metadata: Dict):
+        """Aggiunge un elemento all'indice RAG."""
+        async with self._lock:
+            entry = {
+                "source": source,
+                "content": content,
+                "metadata": metadata,
+                "timestamp": datetime.now().isoformat(),
+            }
+            self.index.append(entry)
+            # Mantieni dimensione fissa
+            if len(self.index) > RAG_INDEX_SIZE:
+                self.index.pop(0)
+
+    async def index_railway_logs(self, profile: str, logs: str):
+        """Indicizza i log di Railway per identificare crash passati."""
+        lines = logs.split("\n")
+        for line in lines[-50:]:  # Ultime 50 righe
+            if "error" in line.lower() or "crash" in line.lower() or "failed" in line.lower():
+                await self.add_to_index(
+                    source=f"railway_logs_{profile}",
+                    content=line,
+                    metadata={"type": "log_error", "profile": profile}
+                )
+
+
+class ContextRetriever:
+    """Recuperatore di contesto per l'agente."""
+
+    def __init__(self, indexer: GridIndexer):
+        self.indexer = indexer
+
+    async def retrieve_relevant_context(self, query: str) -> List[Dict]:
+        """
+        Recupera il contesto rilevante basato sulla query.
+        Attualmente usa keyword matching semplice (potenziabile con embeddings).
+        """
+        relevant = []
+        keywords = query.lower().split()
+        
+        async with self.indexer._lock:
+            for entry in self.indexer.index:
+                content = entry["content"].lower()
+                score = sum(1 for kw in keywords if kw in content)
+                
+                if score > 0:
+                    entry_with_score = entry.copy()
+                    entry_with_score["score"] = score
+                    relevant.append(entry_with_score)
+        
+        # Ordina per score decrescente
+        relevant.sort(key=lambda x: x["score"], reverse=True)
+        return relevant[:10]  # Ritorna i top 10
+
+
+class GridRAG:
+    """Interfaccia principale per il RAG della Grid."""
+
+    def __init__(self):
+        self.indexer = GridIndexer()
+        self.retriever = ContextRetriever(self.indexer)
+
+    async def prepare_agent_context(self, goal: str) -> str:
+        """
+        Prepara il contesto per l'agente unificando i dati RAG.
+        """
+        context_items = await self.retriever.retrieve_relevant_context(goal)
+        
+        if not context_items:
+            return ""
+
+        context_str = "\n--- GRID RAG CONTEXT ---\n"
+        for item in context_items:
+            context_str += f"[{item['source']}] {item['content']}\n"
+        context_str += "------------------------\n"
+        
+        return context_str
+
+
+# ── Singleton globale ──────────────────────────────────────────────────────
+_grid_rag_instance: Optional[GridRAG] = None
+
+
+def get_grid_rag() -> GridRAG:
+    """Restituisce l'istanza globale del GridRAG."""
+    global _grid_rag_instance
+    if _grid_rag_instance is None:
+        _grid_rag_instance = GridRAG()
+    return _grid_rag_instance

agents/html_fast_path.py

@@ -1,60 +0,0 @@
-"""Classificazione locale del fast path per mini-app HTML a file singolo.
-
-Il classificatore è deliberatamente conservativo: in caso di dubbio restituisce
-False. Non usa LLM, rete o stato globale e quindi non aggiunge latenza misurabile.
-"""
-from __future__ import annotations
-
-from dataclasses import dataclass
-import re
-
-
-@dataclass(frozen=True)
-class HtmlFastPathDecision:
-    eligible: bool
-    reason: str
-    path: str = "index.html"
-
-
-_HTML_RE = re.compile(r"\b(?:html5?|html|pagina\s+web|single[- ]page|landing\s+page)\b", re.I)
-_CREATE_RE = re.compile(r"\b(?:crea|genera|scrivi|realizza|implementa|build|create|generate|make)\b", re.I)
-_SINGLE_FILE_RE = re.compile(
-    r"\b(?:un\s+solo\s+file|singolo\s+file|one\s+file|single\s+file|file\s+unico)\b", re.I
-)
-_PATH_RE = re.compile(r"(?<![\w./-])([\w./-]+\.html)(?![\w.-])", re.I)
-_FORBIDDEN_RE = re.compile(
-    r"\b(?:deploy|pubblica|publish|rilascia|release|github|git|npm|pnpm|yarn|install|"
-    r"api|backend|server|database|db|auth|login|pagamento|payment|webhook|secret|token|"
-    r"shell|bash|terminal|esegui\s+comandi|execute\s+commands|multi[- ]file|pi[uù]\s+file|"
-    r"react|vue|angular|next(?:\.js)?|vite|typescript|python|sql)\b",
-    re.I,
-)
-_EXTERNAL_RE = re.compile(r"\b(?:fetch|axios|websocket|stripe|supabase|firebase|oauth)\b|https?://", re.I)
-
-
-def classify_html_fast_path(goal: str) -> HtmlFastPathDecision:
-    """Return an eligible decision only for a safe, self-contained HTML request."""
-    text = " ".join(str(goal or "").split())
-    if not text:
-        return HtmlFastPathDecision(False, "empty_goal")
-    if len(text) > 500:
-        return HtmlFastPathDecision(False, "goal_too_long")
-    if not _HTML_RE.search(text):
-        return HtmlFastPathDecision(False, "not_html_goal")
-    if not _CREATE_RE.search(text):
-        return HtmlFastPathDecision(False, "not_creation_goal")
-    if not _SINGLE_FILE_RE.search(text):
-        return HtmlFastPathDecision(False, "single_file_not_explicit")
-    if _FORBIDDEN_RE.search(text):
-        return HtmlFastPathDecision(False, "contains_project_or_sensitive_operation")
-    if _EXTERNAL_RE.search(text):
-        return HtmlFastPathDecision(False, "external_dependency_or_network")
-
-    paths = _PATH_RE.findall(text)
-    path = paths[0] if paths else "index.html"
-    if "/" in path or path.startswith("."):
-        return HtmlFastPathDecision(False, "nested_path_not_allowed", path)
-    return HtmlFastPathDecision(True, "self_contained_single_html", path)
-
-
-__all__ = ["HtmlFastPathDecision", "classify_html_fast_path"]

agents/unified_loop.py

@@ -214,46 +214,37 @@ class UnifiedAgentLoop(DirectToolsMixin, PromptBuilderMixin, LLMSelectionMixin,
             _logger.debug("[unified_loop] state callback silenced: %s", _state_callback_error)
 
     async def _rollback_writes(self, on_step=None) -> None:
-        """Restore all writes from this run or report an incomplete rollback.
-
-        A None snapshot means the file did not exist and must be removed.
-        Failed restores remain tracked so a supervisor can retry or block the run.
+        """
+        GAP-3: ripristina i file sovrascritti se il loop si interrompe a metà.
+        Chiama dopo un errore grave che ha lasciato il progetto in stato inconsistente.
+        Ogni file in _write_snapshots viene ripristinato al suo contenuto originale.
+        File che non esistevano (snapshot=None) vengono ignorati (non possiamo eliminarli in modo sicuro).
         """
         if not self._write_snapshots or not self.executor:
             return
         if on_step:
             await _maybe_await(on_step({
                 "action": "text_chunk",
-                "token": f"\u23ea Rollback di {len(self._write_snapshots)} file modificati...\n",
+                "token":  f"\u23ea Rollback di {len(self._write_snapshots)} file modificati...\n",
                 "status": "streaming",
             }))
-
-        remaining: dict[str, str | None] = {}
-        rolled = 0
-        for path, original in list(self._write_snapshots.items()):
-            tool_name = "delete_file" if original is None else "write_file"
-            inputs = {"path": path} if original is None else {"path": path, "content": original}
+        _rolled = 0
+        for path, original in self._write_snapshots.items():
+            if original is None:
+                continue  # file non esisteva prima — saltiamo (non eliminiamo)
             try:
-                result = await asyncio.wait_for(
-                    self.executor.run_tool(tool_name, inputs),
+                await asyncio.wait_for(
+                    self.executor.run_tool("write_file", {"path": path, "content": original}),
                     timeout=10.0,
                 )
-                payload = result.get("output") if isinstance(result, dict) else None
-                nested_failed = isinstance(payload, dict) and payload.get("ok") is False
-                if not isinstance(result, dict) or not result.get("success") or nested_failed:
-                    error = (payload or {}).get("error") if isinstance(payload, dict) else None
-                    raise RuntimeError(error or result.get("error", "rollback tool failed"))
-                rolled += 1
-            except Exception as exc:
-                remaining[path] = original
-                _logger.error("GAP-3 rollback fallito per %s: %s", path, str(exc)[:240])
-
-        total = len(self._write_snapshots)
-        self._write_snapshots = remaining
-        _logger.info("GAP-3 rollback: %d/%d file ripristinati", rolled, total)
-        if remaining:
-            raise RuntimeError(f"VFS rollback incompleto: {len(remaining)}/{total} file non ripristinati")
+                _rolled += 1
+            except Exception:
+                pass  # non-fatal — best effort rollback
+        _total = len(self._write_snapshots)  # salva prima del clear
+        self._write_snapshots = {}
+        _logger.info("GAP-3 rollback: %d/%d file ripristinati", _rolled, _total)
 
+    # ── GAP-NEW-4: Git VFS auto-snapshot ────────────────────────────────────────
     async def _vfs_git_backup(self) -> None:
         """GAP-NEW-4: Push _session_files al branch vfs-backup su GitHub.
 
@@ -559,29 +550,9 @@ class UnifiedAgentLoop(DirectToolsMixin, PromptBuilderMixin, LLMSelectionMixin,
         # F17+B7: planner per task di progettazione/implementazione — soglia ridotta a 10 chars
         # Bug: "crea app react" (14 chars) non attivava mai il planner (soglia era 50).
         # _NEEDS_PLAN_RE filtra già query semplici — len guard serve solo per 1-8 char input.
-        try:
-            from agents.html_fast_path import classify_html_fast_path
-            _html_fast_decision = classify_html_fast_path(state.goal)
-        except Exception as _html_cls_exc:
-            _logger.debug("[html-fast-path] classifier unavailable: %s", type(_html_cls_exc).__name__)
-            _html_fast_decision = None
-        _html_fast_plan = None
-        if _html_fast_decision is not None and _html_fast_decision.eligible and not tool_results:
-            _html_fast_plan = {
-                "summary": "Piano locale mini-app HTML a file singolo",
-                "goal": state.goal,
-                "subtasks": [
-                    {"id": 1, "description": f"Scrivi {_html_fast_decision.path}: {state.goal}", "tool": "write_file", "requires": []},
-                    {"id": 2, "description": f"Rileggi {_html_fast_decision.path} e verifica la scrittura", "tool": "read_file", "requires": [1]},
-                ],
-                "complexity": "low",
-                "source": "local_html_fast_path",
-            }
-            _logger.info("[html-fast-path] planner bypass: %s", _html_fast_decision.path)
         _should_plan = (
             self.planner
             and not tool_results
-            and _html_fast_plan is None
             and bool(self._NEEDS_PLAN_RE.search(state.goal[:200]))
             and len(state.goal) > 10
         )
@@ -598,7 +569,7 @@ class UnifiedAgentLoop(DirectToolsMixin, PromptBuilderMixin, LLMSelectionMixin,
             }
             _logger.info("S-FMT-ORCH fast-fix: piano sintetico iniettato, skip ARCHITECT")
         _t0_plan = asyncio.get_running_loop().time()  # Sprint 5 ITEM 13: plan_ms timing
-        if _should_plan or _html_fast_plan is not None:
+        if _should_plan:
             if on_step:
                 await _maybe_await(on_step({
                     "loop": 0, "action": "plan", "status": "started",
@@ -607,10 +578,7 @@ class UnifiedAgentLoop(DirectToolsMixin, PromptBuilderMixin, LLMSelectionMixin,
                 }))
             # S640: timeout planner + S-FMT-ORCH fast-fix bypass
             # Se _fast_fix_plan disponibile, salta ARCHITECT (~15s risparmiati)
-            if _html_fast_plan is not None:
-                plan = _html_fast_plan
-                _logger.info("[html-fast-path] ARCHITECT bypassato")
-            elif _fast_fix_plan is not None:
+            if _fast_fix_plan is not None:
                 plan = _fast_fix_plan
                 _logger.info("S-FMT-ORCH fast-fix: ARCHITECT bypassato")
             else:
@@ -1328,28 +1296,18 @@ class UnifiedAgentLoop(DirectToolsMixin, PromptBuilderMixin, LLMSelectionMixin,
                                 {"path": _wf_path, "content": _wf_generated} if rn == "write_file"
                                 else {"path": _wf_path, "patch": _wf_generated}
                             )
-                            # GAP-3: snapshot pre-write; read errors are not "file absent".
+                            # GAP-3: snapshot pre-write — cattura originale per rollback atomico
                             if rn == "write_file" and _wf_path not in self._write_snapshots:
-                                _snap_r = await asyncio.wait_for(
-                                    self.executor.run_tool("read_file", {"path": _wf_path}),
-                                    timeout=4.0,
-                                )
-                                _snap_payload = _snap_r.get("output") if isinstance(_snap_r, dict) else None
-                                _snap_failed = isinstance(_snap_payload, dict) and _snap_payload.get("ok") is False
-                                if isinstance(_snap_payload, dict):
-                                    _snap_content = _snap_payload.get("content")
-                                    _snap_error = str(_snap_payload.get("error", ""))
-                                else:
-                                    _snap_content = _snap_payload
-                                    _snap_error = str(_snap_r.get("error", "")) if isinstance(_snap_r, dict) else ""
-                                if isinstance(_snap_content, str) and not _snap_failed:
-                                    self._write_snapshots[_wf_path] = _snap_content
-                                elif "File non trovato" in _snap_error or "File not found" in _snap_error:
-                                    self._write_snapshots[_wf_path] = None
-                                else:
-                                    raise RuntimeError(
-                                        f"Snapshot VFS non disponibile per {_wf_path}: {_snap_error[:240]}"
+                                try:
+                                    _snap_r = await asyncio.wait_for(
+                                        self.executor.run_tool("read_file", {"path": _wf_path}),
+                                        timeout=4.0,
+                                    )
+                                    self._write_snapshots[_wf_path] = (
+                                        _snap_r.get("output") if _snap_r.get("success") else None
                                     )
+                                except Exception:
+                                    self._write_snapshots[_wf_path] = None  # file non esisteva
                             # GAP-VFS: lock per-path — serializza scritture parallele sullo stesso file
                             _vfs_lock = self._get_vfs_lock(_wf_path)
                             async with _vfs_lock:
@@ -3576,12 +3534,6 @@ class UnifiedAgentLoop(DirectToolsMixin, PromptBuilderMixin, LLMSelectionMixin,
                 }
 
             state.errors.append(error_text)
-            if getattr(self, "_write_snapshots", None):
-                try:
-                    await self._rollback_writes(on_step)
-                except Exception as rollback_error:
-                    state.errors.append(str(rollback_error)[:500])
-                    _logger.error("[unified_loop] rollback inatteso incompleto: %s", rollback_error)
             previous = state.state_machine.current
             if previous != AgentState.FAILED:
                 try:
@@ -3739,12 +3691,6 @@ class UnifiedAgentLoop(DirectToolsMixin, PromptBuilderMixin, LLMSelectionMixin,
 
         async def _finish(result: dict[str, Any]) -> dict[str, Any]:
             next_state = AgentState.COMPLETED if result.get("success", True) else AgentState.FAILED
-            if next_state == AgentState.FAILED and getattr(self, "_write_snapshots", None):
-                try:
-                    await self._rollback_writes(on_step)
-                except Exception as rollback_error:
-                    result.setdefault("errors", []).append(str(rollback_error)[:500])
-                    result["rollback_incomplete"] = True
             try:
                 await self._transition_state(state, next_state, on_step)
             finally:
@@ -3831,6 +3777,29 @@ class UnifiedAgentLoop(DirectToolsMixin, PromptBuilderMixin, LLMSelectionMixin,
         except Exception:
             pass  # decision_memory non disponibile — continua normalmente
 
+        # B5-ORDER: una spiegazione completa e non operativa è già un intento
+        # sufficiente. Deve bypassare le guardie di ambiguità, che sono riservate a
+        # comandi realmente vaghi; le guardie in _is_pure_explanation() proteggono
+        # file, mutazioni, dati realtime e richieste troppo lunghe.
+        # Sprint 5 ITEM 13: classify_ms — tempo routing/classificazione goal (sync, <1ms)
+        _t0_classify = _time.monotonic()
+        if self._is_pure_explanation(goal):
+            try:
+                from api.state import record_timing as _rtcB5
+                _rtcB5("classify_ms", (_time.monotonic() - _t0_classify) * 1000)
+            except Exception:
+                pass
+            await self._transition_state(state, AgentState.THINKING, on_step)
+            _r = await _finish(await self._run_fallback(state, on_step))
+            _r["timing_ms"] = int((_time.monotonic() - _t_run) * 1000)
+            _r["effective_max_steps"] = state.max_steps
+            if _sid_token is not None:
+                try: _sid_var.reset(_sid_token)
+                except Exception: pass
+            if self._session_files:
+                asyncio.ensure_future(self._vfs_git_backup())
+            return _r
+
         # P29-B1: gate ambiguità strutturale — _is_goal_ambiguous() era P28-B2 dead code (mai chiamata).
         # Zero LLM, <0.1ms. Lingua-aware via self._run_lang (P28-B1). Fires dopo blacklist e prima del routing.
         if _is_goal_ambiguous(goal):
@@ -3994,9 +3963,6 @@ class UnifiedAgentLoop(DirectToolsMixin, PromptBuilderMixin, LLMSelectionMixin,
             return _r_bl
 
 
-        # Sprint 5 ITEM 13: classify_ms — tempo routing/classificazione goal (sync, <1ms)
-        _t0_classify = _time.monotonic()
-
         # S402: Fast Path — greeting/ack/identità semplice → bypass tutto l'overhead
         if self._is_simple_query(goal):
             try:
@@ -4046,27 +4012,6 @@ class UnifiedAgentLoop(DirectToolsMixin, PromptBuilderMixin, LLMSelectionMixin,
         # già — "direct tools + fallback" — ma il codice faceva solo _run_fallback senza tool).
         # Bug: query meteo/news/cerca non chiamavano mai i tool reali → LLM allucinava i dati
         # → ResponseVerifier girava su risposta inventata → retry → 20-60s inutili.
-        # B5: query spiegazione pura → _run_fallback diretta (-20-30s risparmio)
-        # Scenari: "cos'è X", "spiegami Y", "how does Z work?", "explain W"
-        # Fail-open: se regex troppo larga → path normale (nessuna perdita)
-        if self._is_pure_explanation(goal):
-            try:
-                from api.state import record_timing as _rtcB5
-                _rtcB5("classify_ms", (_time.monotonic() - _t0_classify) * 1000)
-            except Exception:
-                pass
-            await self._transition_state(state, AgentState.THINKING, on_step)
-            _r = await _finish(await self._run_fallback(state, on_step))
-            _r["timing_ms"] = int((_time.monotonic() - _t_run) * 1000)
-            _r["effective_max_steps"] = state.max_steps
-            if _sid_token is not None:
-                try: _sid_var.reset(_sid_token)
-                except Exception: pass
-            if self._session_files:
-                asyncio.ensure_future(self._vfs_git_backup())
-            return _r
-
-
         # P36: Hybrid Execution Router — Python code analysis fast path.
         # Se goal contiene keyword analisi + codice Python nel context/goal,
         # chiama python_analyze direttamente (<5ms) saltando planner+LLM (5-15s).

agents/unified_loop_delegate.py

@@ -0,0 +1,192 @@
+"""unified_loop_delegate.py — DelegateMixin: debug riflessivo, replan, delega in-loop.
+
+Estratto da unified_loop.py per ridurre il file principale.
+
+Contiene:
+  _reflective_debug(goal, errors):   BGAP-GUARD diagnosi breve da errori tool
+  _budget_replan_check(state, step): BGAP-1 replan probabilistico su budget critico
+  _DELEGATE_RESEARCH_RE:             regex riconoscimento sub-goal tipo ricerca
+  _run_in_loop_delegate(sub_goal):   GAP-1 micro-agente specializzato in-loop
+
+Invariante B1: nessun corpo duplicato con unified_loop.py.
+MRO garantisce che DelegateMixin._budget_replan_check sovrascriva HelpersMixin
+(DelegateMixin precede HelpersMixin nella lista basi di UnifiedAgentLoop).
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+import re
+from typing import Any
+
+from agents.unified_loop_types import StepCallback, UnifiedLoopState, _maybe_await
+
+_logger = logging.getLogger("agente_ai")
+
+
+class DelegateMixin:
+    async def _reflective_debug(
+        self, goal: str = "", errors: Any = None, **kwargs: Any
+    ) -> str:
+        """Reflective debug: analizza errori e propone diagnosi in max 2 frasi.
+        Chiamato dopo tool failures per arricchire state.context con ipotesi fix.
+        Fail-open: non blocca mai il loop in caso di errore LLM."""
+        try:
+            _ctx = f"Goal: {str(goal)[:200]}\nErrori: {'; '.join(str(e)[:300] for e in (errors if isinstance(errors, list) else [errors])[:3])}"  # S573: 150→300
+            _fast = self._get_fast_llm()
+            _diag = await asyncio.wait_for(
+                _fast.chat([{"role": "user", "content": f"Diagnosi breve (max 2 frasi):\n{_ctx}"}], max_tokens=300),  # S586: 120->180->300
+                timeout=5.0,
+            )
+            return (str(_diag) if _diag else "").strip()[:300]
+        except Exception:
+            pass  # fail-open
+        return ""
+
+    # ── BGAP-1: Probabilistic Re-planning Trigger ────────────────────────────
+    async def _budget_replan_check(
+        self, state: Any, step_count: int, on_step: Any = None
+    ) -> str:
+        """BGAP-1: probabilistic re-planning trigger.
+        Guards: skip se _n_err < 2 OR _budget_ratio < 0.6.
+        Usa _get_fast_llm() con max_tokens=120. Fail-open."""
+        _n_err = len(state.errors) if getattr(state, 'errors', None) else 0
+        if _n_err < 2:
+            return ''
+        _budget_ratio = step_count / max(state.max_steps, 1)
+        if _budget_ratio < 0.6:
+            return ''
+        # dedup guard [GAP-1-REPLAN]: skip se già replanned in questo loop
+        if '[GAP-1-REPLAN]' in (state.context or ''):
+            return ''
+        try:
+            _fast_llm = self._get_fast_llm()
+            _prompt = (
+                f'Task ha avuto {_n_err} errori e usato {_budget_ratio:.0%} del budget. '
+                f'Suggerisci UN approccio alternativo in max 2 frasi. Goal: {state.goal[:500]}'  # S597: 200->300->500
+            )
+            _hint = await asyncio.wait_for(
+                _fast_llm.chat([{'role': 'user', 'content': _prompt}], max_tokens=120),
+                timeout=5.0,
+            )
+            return (str(_hint) if _hint else '').strip()[:200]
+        except Exception:
+            pass  # fail-open totale
+        return ''
+
+    # ── GAP-1: Delega Dinamica In-Loop ─────────────────────────────────────
+    _DELEGATE_RESEARCH_RE = re.compile(
+        r'\b(cerca|research|trova|web|url|leggi|analisi|analizza|documenta|'
+        r'news|notizie|fetch|scrape|pagina|sito|http)\b',
+        re.IGNORECASE,
+    )
+
+    async def _run_in_loop_delegate(self, sub_goal: str, timeout: float = 40.0) -> dict:
+        """GAP-1: Delega Dinamica In-Loop.
+        Lancia un micro-agente specializzato per sub_goal DURANTE il loop principale.
+        Architettura:
+          - Stesso executor del parent  → accesso ai tool reali (write_file, run_python, ...)
+          - LLM selezionato per ruolo   → RESEARCHER, CODER o REASONER in base al goal
+          - _is_delegate_child = True   → blocca ricorsione (max 1 livello di delega)
+          - max_steps = 4               → micro-agente leggero, non un loop completo
+          - output troncato a 4000 chars → evita context-window explosion nel parent
+        """
+        # P18: defensive anti-recursion guard at entry point
+        if getattr(self, '_is_delegate_child', False):
+            _logger.debug("[delegate] anti-recursion guard triggered at _run_in_loop_delegate entry")
+            return {"output": "[DELEGATE] Ricorsione bloccata: _is_delegate_child=True.", "steps": [], "goal_met": False}
+        try:
+            from models.role_router import RoleRouter as _RR_d, Role as _Role_d
+            # Seleziona LLM specializzato in base al tipo di sotto-obiettivo
+            if self._DELEGATE_RESEARCH_RE.search(sub_goal[:300]):
+                _sub_llm = _RR_d.get_client(_Role_d.RESEARCHER)   # Gemini 2.5-flash
+            elif self._CODE_RE.search(sub_goal[:300]):
+                _sub_llm = _RR_d.get_client(_Role_d.CODER)        # Llama 4 Scout
+            else:
+                _sub_llm = _RR_d.get_client(_Role_d.REASONER)     # Cerebras 120B
+        except Exception:
+            _sub_llm = self.llm  # fallback: usa LLM del parent
+
+        # Crea loop figlio: stessi executor/planner/memory, LLM specializzato
+        _sub_loop = UnifiedAgentLoop(
+            llm_client=_sub_llm,
+            planner=self.planner,
+            executor=self.executor,
+            critic=None,    # no critic — micro-agente leggero
+            memory=self.memory,
+            verifier=None,  # no verifier — massima velocità
+        )
+        # Anti-ricorsione: il figlio non può delegare ulteriormente
+        _sub_loop._is_delegate_child = True
+        # Propaga session_id per isolare sandbox backend-exec
+        _sub_loop._run_task_id = self._run_task_id + "_d"
+        # GAP-6: condividi dict mutabile _session_files con il parent loop
+        # Prima: delegate inizializzava _session_files={} -> file scritti non visibili al parent
+        # Ora: stessa referenza -> parent vede automaticamente tutti i file scritti dal delegate
+        _sub_loop._session_files = self._session_files
+
+        # P17-F1: buffer output parziale via on_step — sopravvive al timeout
+        _partial_steps: list[dict] = []
+        async def _capture_partial(step: dict) -> None:
+            if step.get("output") or step.get("explanation"):
+                _partial_steps.append(step)
+
+        try:
+            _res = await asyncio.wait_for(
+                _sub_loop.run(sub_goal, max_steps=4, on_step=_capture_partial),
+                timeout=timeout,
+            )
+            _out = (_res.get("output") or "")[:4000]
+            _logger.info(
+                "GAP-1 delegate OK [%s] steps=%d: %s",
+                _res.get("engine", "?"), len(_res.get("steps", [])), sub_goal[:60],
+            )
+            return {
+                "success": _res.get("success", False),
+                "output":  _out,
+                "engine":  _res.get("engine", "delegate"),
+                "steps":   len(_res.get("steps", [])),
+            }
+        except asyncio.TimeoutError:
+            # P17-F1: esponi stato parziale invece di stringa vuota
+            # _session_files già condiviso con parent → parent vede file scritti
+            _partial_files = list(getattr(_sub_loop, "_session_files", {}).keys())
+            _partial_out = " ".join(
+                (s.get("output") or s.get("explanation") or "")[:300]
+                for s in _partial_steps[-3:]
+            ).strip()[:1500]
+            _logger.warning(
+                "GAP-1 delegate timeout (%.0fs, %d steps, %d files): %s",
+                timeout, len(_partial_steps), len(_partial_files), sub_goal[:60],
+            )
+            # S-PARTIAL: emetti evento SSE partial_output al frontend PRIMA di restituire
+            # così l'utente vede il chip "⚠ output parziale — riprendo" in tempo reale
+            if on_step:
+                await _maybe_await(on_step({
+                    "event":          "partial_output",
+                    "action":         "partial_output",
+                    "visibility":     "progress",
+                    "partial":        True,
+                    "steps_done":     len(_partial_steps),
+                    "partial_files":  _partial_files,
+                    "partial_output": _partial_out,
+                    "output":         _partial_out,
+                    "explanation":    f"Output parziale dopo {timeout:.0f}s — l'agente sta recuperando",
+                    "status":         "warning",
+                }))
+            return {
+                "success":       False,
+                "output":        _partial_out,
+                "error":         f"delegate timeout ({timeout:.0f}s) — risultato parziale",
+                "partial":       True,
+                "partial_files": _partial_files,
+                "steps_done":    len(_partial_steps),
+            }
+        except Exception as _de:
+            _logger.warning("GAP-1 delegate error: %s", _de)
+            return {"success": False, "output": "", "error": str(_de)[:200]}
+
+    # ── S362: Role routing helpers ─────────────────────────────────────────────
+
+    # S427: ampliato con verbi IT/EN mancanti + framework/pattern aggiuntivi.
+    # Stesso set di goal_verifier._CODE_RE + keyword tecnologiche per routing CODER LLM.

agents/unified_loop_routing.py

@@ -0,0 +1,82 @@
+"""unified_loop_routing.py — RoutingMixin: regex CODE, estrazione file da output LLM.
+
+Estratto da unified_loop.py per ridurre il file principale.
+
+Contiene:
+  _CODE_RE:                   regex riconoscimento goal di tipo codice (S362/S427)
+  _EXT:                       pattern estensioni file supportate (S416/S422)
+  _FILE_BLOCK_RE:             regex estrazione blocchi file da risposta LLM (S422-Fix1)
+  _extract_written_files(answer): classmethod — estrae dict path→content da output LLM
+
+Invariante B1: nessun corpo duplicato con unified_loop.py.
+"""
+from __future__ import annotations
+
+import re
+
+
+class RoutingMixin:
+    _CODE_RE = re.compile(
+        r'\b(scrivi|crea|genera|implementa|refactor|bug|fix|debug|test|codice|'
+        r'funzione|classe|componente|api|endpoint|typescript|javascript|python|'
+        r'react|vue|swift|kotlin|write|create|generate|implement|code|function|'
+        r'class|component|frontend|backend|server|client|hook|store|type|'
+        r'interface|migration|query|schema|dockerfile|workflow|'
+        # S427: verbi italiani azione-codice mancanti
+        r'sistema|sistemi|correggi|corregge|debugga|patch|patcha|rinomina|'
+        r'sostituisci|rimpiazza|ottimizza|refactorizza|ristruttura|'
+        r'aggiungi|aggiorna|integra|rimuovi|elimina|cancella|inserisci|'
+        # S427: verbi inglesi azione-codice mancanti
+        r'rename|replace|remove|delete|patch|optimize|restructure|'
+        r'add|update|integrate|insert|scaffold|bootstrap|deploy|'
+        # S427: framework/librerie/pattern aggiuntivi
+        r'svelte|angular|next\.?js|nuxt|remix|astro|nest\.?js|'
+        r'fastapi|flask|django|express|rails|laravel|spring|'
+        r'graphql|grpc|websocket|rest|sql|nosql|'
+        r'prisma|drizzle|sqlalchemy|mongoose|sequelize|'
+        r'css|scss|sass|html|rust|go|java|kotlin|dart|flutter|'
+        r'service|repository|controller|middleware|utility|helper|'
+        r'decorator|enum|zod|vite|webpack|eslint|prettier|jest|vitest)\b',
+        re.IGNORECASE,
+    )
+
+    # S416-Fix1: estrae path→content dei file scritti nella risposta LLM
+    # Pattern: "path/file.ext:" o "### file.ext" o "FILE: file.ext" seguito da code block
+    # S422-Fix1: esteso con 4 formati aggiuntivi (bold, inline code, lista, commento inline)
+    # Copre 9/9 formati LLM più comuni — S416 era silenziosamente rotto al 60-70%
+    _EXT = r'(?:tsx?|jsx?|py|css|html|md|json|ya?ml|sh|toml|sql|go|rs|rb|java|kt|swift|vue|svelte)'
+    _FILE_BLOCK_RE = re.compile(
+        r'(?:'
+        # p1: FILE: path o ## FILE: path
+        r'(?:^|\n)\s*(?:#{1,3}\s*)?(?:FILE|file|File):\s*[`"]?(?P<p1>[\w./\-]+\.\w+)[`"]?\s*\n'
+        # p2: path: o path- (solo con estensione nota)
+        r'|(?:^|\n)\s*[`"]?(?P<p2>[\w./\-]+\.' + _EXT + r')[`"]?\s*[:\-–]\s*\n'
+        # p3: ## path (markdown heading)
+        r'|(?:^|\n)#{1,3}\s+(?P<p3>[\w./\-]+\.' + _EXT + r')\s*\n'
+        # p4: **path** (bold) — formato più comune GPT/OpenRouter/Claude
+        r'|(?:^|\n)\s*\*\*(?P<p4>[\w./\-]+\.' + _EXT + r')\*\*\s*.*?\n'
+        # p5: `path` (inline code) prima del blocco
+        r'|(?:^|\n)\s*`(?P<p5>[\w./\-]+\.' + _EXT + r')`\s*.*?\n'
+        # p6: 1. **path** o - **path** (lista)
+        r'|(?:^|\n)\s*(?:\d+\.|[-*])\s+\*\*?(?P<p6>[\w./\-]+\.' + _EXT + r')\*?\*?\s*.*?\n'
+        r')'
+        # blocco codice — opzionale commento // path o # path come prima riga (p7)
+        r'```(?:\w+\n(?:(?://|#)\s*(?P<p7>[\w./\-]+\.' + _EXT + r')\s*\n))?'
+        r'(?P<content>.+?)```',
+        re.DOTALL | re.MULTILINE,
+    )
+
+    @classmethod
+    def _extract_written_files(cls, answer: str) -> dict[str, str]:
+        """S422-Fix1: estrae file path→content dall'output LLM per iniettarli come contesto.
+        Copre tutti i formati comuni: FILE:, ##, **bold**, `inline`, lista, commento inline."""
+        result: dict[str, str] = {}
+        for m in cls._FILE_BLOCK_RE.finditer(answer):
+            path = (m.group("p1") or m.group("p2") or m.group("p3") or
+                    m.group("p4") or m.group("p5") or m.group("p6") or
+                    m.group("p7") or "")
+            content = m.group("content") or ""
+            if path and content.strip():
+                result[path.strip()] = content.strip()[:3000]
+        return result
+

agents/unified_loop_vfs.py

@@ -0,0 +1,156 @@
+"""unified_loop_vfs.py — VFSMixin: scritture VFS, git backup, lock per path.
+
+Estratto da unified_loop.py per ridurre il file principale.
+
+Contiene:
+  _rollback_writes(on_step):  GAP-3 rollback atomico scritture parziali
+  _vfs_git_backup():          GAP-NEW-4 push session_files su branch vfs-backup GitHub
+  _get_vfs_lock(path):        GAP-VFS per-path asyncio.Lock (lazy init)
+
+Invariante B1: nessun corpo duplicato con unified_loop.py.
+MRO Python garantisce self._write_snapshots / self._session_files / self.executor
+siano risolti su UnifiedAgentLoop.
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any
+
+from agents.unified_loop_types import _maybe_await
+
+_logger = logging.getLogger("agente_ai")
+
+
+class VFSMixin:
+    async def _rollback_writes(self, on_step=None) -> None:
+        """
+        GAP-3: ripristina i file sovrascritti se il loop si interrompe a metà.
+        Chiama dopo un errore grave che ha lasciato il progetto in stato inconsistente.
+        Ogni file in _write_snapshots viene ripristinato al suo contenuto originale.
+        File che non esistevano (snapshot=None) vengono ignorati (non possiamo eliminarli in modo sicuro).
+        """
+        if not self._write_snapshots or not self.executor:
+            return
+        if on_step:
+            await _maybe_await(on_step({
+                "action": "text_chunk",
+                "token":  f"\u23ea Rollback di {len(self._write_snapshots)} file modificati...\n",
+                "status": "streaming",
+            }))
+        _rolled = 0
+        for path, original in self._write_snapshots.items():
+            if original is None:
+                continue  # file non esisteva prima — saltiamo (non eliminiamo)
+            try:
+                await asyncio.wait_for(
+                    self.executor.run_tool("write_file", {"path": path, "content": original}),
+                    timeout=10.0,
+                )
+                _rolled += 1
+            except Exception:
+                pass  # non-fatal — best effort rollback
+        _total = len(self._write_snapshots)  # salva prima del clear
+        self._write_snapshots = {}
+        _logger.info("GAP-3 rollback: %d/%d file ripristinati", _rolled, _total)
+
+    # ── GAP-NEW-4: Git VFS auto-snapshot ────────────────────────────────────────
+    async def _vfs_git_backup(self) -> None:
+        """GAP-NEW-4: Push _session_files al branch vfs-backup su GitHub.
+
+        Fire-and-forget — non blocca mai il loop principale, non solleva eccezioni.
+        Requisiti env: GH_TOKEN (o GITHUB_TOKEN) + GITHUB_REPO = "owner/repo".
+        Crea automaticamente il branch vfs-backup se non esiste.
+        Force-push consentito su vfs-backup (non è main — nessun rischio di perdita).
+        """
+        import os as _os_vfs
+        gh_token = (_os_vfs.getenv("GH_TOKEN") or _os_vfs.getenv("GITHUB_TOKEN", "")).strip()
+        gh_repo  = _os_vfs.getenv("GITHUB_REPO", "").strip()
+        if not gh_token or not gh_repo:
+            return
+        files = dict(self._session_files)  # snapshot immutabile
+        if not files:
+            return
+        run_id = self._run_task_id[:8] or "unknown"
+        try:
+            import httpx as _hx4
+            headers = {
+                "Authorization": f"Bearer {gh_token}",
+                "Accept":        "application/vnd.github+json",
+                "User-Agent":    "agente-ai-vfs/1.0",
+            }
+            base = f"https://api.github.com/repos/{gh_repo}"
+            async with _hx4.AsyncClient(timeout=20.0) as _cli:
+                # 1. Leggi (o crea) branch vfs-backup
+                r_ref = await _cli.get(f"{base}/git/ref/heads/vfs-backup", headers=headers)
+                if r_ref.status_code == 404:
+                    r_main = await _cli.get(f"{base}/git/ref/heads/main", headers=headers)
+                    if r_main.status_code != 200:
+                        return
+                    r_cr = await _cli.post(f"{base}/git/refs", headers=headers,
+                        json={"ref": "refs/heads/vfs-backup", "sha": r_main.json()["object"]["sha"]})
+                    if r_cr.status_code not in (200, 201):
+                        return
+                    backup_head = r_main.json()["object"]["sha"]
+                elif r_ref.status_code == 200:
+                    backup_head = r_ref.json()["object"]["sha"]
+                else:
+                    return
+
+                # 2. Leggi base tree del backup HEAD
+                r_c = await _cli.get(f"{base}/git/commits/{backup_head}", headers=headers)
+                if r_c.status_code != 200:
+                    return
+                base_tree = r_c.json()["tree"]["sha"]
+
+                # 3. Crea blob per ogni file (max 20 per backup, max 50KB per file)
+                tree_items = []
+                for _path, _content in list(files.items())[:20]:
+                    rb = await _cli.post(f"{base}/git/blobs", headers=headers,
+                        json={"content": str(_content)[:50_000], "encoding": "utf-8"})
+                    if rb.status_code == 201:
+                        tree_items.append({
+                            "path":  f"vfs/{_path.lstrip('/')}",
+                            "mode":  "100644",
+                            "type":  "blob",
+                            "sha":   rb.json()["sha"],
+                        })
+
+                if not tree_items:
+                    return
+
+                # 4. Tree + commit + force-push su vfs-backup
+                rt = await _cli.post(f"{base}/git/trees", headers=headers,
+                    json={"base_tree": base_tree, "tree": tree_items})
+                if rt.status_code != 201:
+                    return
+                rc = await _cli.post(f"{base}/git/commits", headers=headers,
+                    json={
+                        "message": f"vfs-backup: {len(tree_items)} file (run {run_id})",
+                        "tree":    rt.json()["sha"],
+                        "parents": [backup_head],
+                    })
+                if rc.status_code != 201:
+                    return
+                # force=True consentito: vfs-backup non è main, nessun rischio
+                await _cli.patch(f"{base}/git/refs/heads/vfs-backup", headers=headers,
+                    json={"sha": rc.json()["sha"], "force": True})
+                _logger.info(
+                    "GAP-NEW-4: vfs-backup aggiornato — %d file, run %s",
+                    len(tree_items), run_id,
+                )
+        except Exception as _vfs_err:
+            # Silent: il backup non deve MAI bloccare o crashare il loop principale
+            _logger.debug("GAP-NEW-4 _vfs_git_backup skip: %s", str(_vfs_err)[:80])
+
+    # ── GAP-VFS: per-path write lock ─────────────────────────────────────────
+    def _get_vfs_lock(self, path: str) -> asyncio.Lock:
+        """GAP-VFS: restituisce (o crea) il Lock asyncio per un path VFS.
+        Previene race condition quando subtask paralleli (asyncio.gather)
+        scrivono lo stesso file contemporaneamente.
+        Lock creato lazy: zero overhead per run che non usano write paralleli."""
+        if path not in self._vfs_write_locks:
+            self._vfs_write_locks[path] = asyncio.Lock()
+        return self._vfs_write_locks[path]
+
+    # ── BGAP-GUARD: Reflective Debug (no-regression invariante) ────────────────

agents/watchdog.py

@@ -0,0 +1,67 @@
+"""
+watchdog.py — S-WATCHDOG: Bidirectional Self-Healing Heartbeat.
+Monitora il loop agentico e interviene in caso di stallo o deviazione dal goal.
+"""
+import asyncio
+import logging
+import time
+from typing import Callable, Awaitable, Optional
+
+_logger = logging.getLogger("agente_ai.agents.watchdog")
+
+class BidirectionalWatchdog:
+    def __init__(self, 
+                 timeout_seconds: float = 45.0, 
+                 on_stale_callback: Optional[Callable[[], Awaitable[None]]] = None):
+        self.timeout = timeout_seconds
+        self.on_stale = on_stale_callback
+        self.last_heartbeat = time.monotonic()
+        self._running = False
+        self._monitor_task = None
+
+    def heartbeat(self):
+        """Segnala che l'agente è ancora attivo e progredisce."""
+        self.last_heartbeat = time.monotonic()
+        _logger.debug("[Watchdog] Heartbeat ricevuto.")
+
+    async def start(self):
+        """Avvia il monitoraggio in background."""
+        if self._running:
+            return
+        self._running = True
+        self.last_heartbeat = time.monotonic()
+        self._monitor_task = asyncio.create_task(self._monitor_loop())
+        _logger.info(f"[Watchdog] Monitoraggio avviato (timeout: {self.timeout}s)")
+
+    async def stop(self):
+        """Ferma il monitoraggio."""
+        self._running = False
+        if self._monitor_task:
+            self._monitor_task.cancel()
+            try:
+                await self._monitor_task
+            except asyncio.CancelledError:
+                pass
+        _logger.info("[Watchdog] Monitoraggio fermato.")
+
+    async def _monitor_loop(self):
+        while self._running:
+            await asyncio.sleep(5.0)
+            elapsed = time.monotonic() - self.last_heartbeat
+            if elapsed > self.timeout:
+                _logger.warning(f"[Watchdog] Rilevato stallo! Nessun heartbeat da {elapsed:.1f}s.")
+                if self.on_stale:
+                    try:
+                        await self.on_stale()
+                        # Resetta il timer dopo l'intervento per evitare interventi a raffica
+                        self.heartbeat()
+                    except Exception as e:
+                        _logger.error(f"[Watchdog] Errore durante l'intervento di self-healing: {e}")
+
+    async def self_check(self, state_summary: str) -> bool:
+        """
+        L'agente chiama questo metodo per un controllo esterno di coerenza.
+        """
+        _logger.info(f"[Watchdog] Eseguo Self-Check dello stato: {state_summary[:100]}...")
+        # Implementazione futura: chiamata a un modello critico esterno (Critic Layer)
+        return True

api/TELEGRAM_MODULES.md

@@ -0,0 +1,172 @@
+# backend/api — Moduli Telegram (M2 Split)
+
+> **Refactor M2 — 2 Luglio 2026**
+> Il monolite `telegram_webhook.py` (2844 righe, 5 hotfix consecutivi) è stato
+> spezzato in 6 moduli a responsabilità singola. Hotfix futuri toccano **un solo file**.
+
+---
+
+## Grafo delle dipendenze
+
+```
+telegram_tg_client.py          (stdlib + httpx only)
+        │
+        ├──► telegram_keyboards.py     (solo costanti/dict — zero import interni)
+        │           │
+        │           ├──► telegram_cmd_monitoring.py
+        │           │           └──► (esposto via telegram_webhook.py)
+        │           │
+        │           ├──► telegram_cmd_ai.py
+        │           │           └──► (esposto via telegram_webhook.py)
+        │           │
+        │           └──► telegram_callbacks.py
+        │                       ├── importa _cmd_do, _cmd_autofix ... da telegram_cmd_ai
+        │                       └── importa _cmd_help, _cmd_status ... da telegram_cmd_monitoring
+        │
+        └──► telegram_webhook.py       (router FastAPI puro — importa da tutti)
+                    └──► montato in backend/main.py come _tg_webhook_router
+```
+
+---
+
+## Moduli
+
+### `telegram_tg_client.py` — 276 righe
+**Ruolo:** Telegram Bot API puro. Layer 0 senza dipendenze interne.
+
+| Simbolo | Descrizione |
+|---------|-------------|
+| `_get_bot_token()` | Legge `TELEGRAM_BOT_TOKEN` dall'env |
+| `_log_tg_exc(task)` | Log eccezioni fire-and-forget (Gap-2.6) |
+| `_fmt_elapsed(sec)` | Formatta durata in human-readable |
+| `_tg_reply(chat_id, text)` | Invia messaggio con parse_mode=HTML |
+| `_tg_send(chat_id, text)` | Come reply, ritorna `message_id` |
+| `_tg_edit(chat_id, msg_id, text)` | Modifica messaggio esistente |
+| `_tg_photo(chat_id, url, caption)` | Invia foto via URL |
+| `_tg_typing(chat_id)` | Invia `sendChatAction typing` |
+| `_tg_react(chat_id, msg_id, emoji)` | Imposta reaction emoji |
+| `_tg_answer_callback(callback_id)` | Risponde a `callback_query` (≤3s) |
+
+**Import:** `asyncio, html, logging, os, time, httpx`
+
+---
+
+### `telegram_keyboards.py` — 109 righe
+**Ruolo:** Costanti UI e keyboards. Zero logica, zero import interni.
+
+| Simbolo | Tipo | Descrizione |
+|---------|------|-------------|
+| `_QUICK_PICK_KB` | `dict` | Inline keyboard selezione task rapida |
+| `_MAIN_KB` | `dict` | Reply keyboard principale |
+| `_BENCH_ACTION_KB` | `dict` | Keyboard post-benchmark |
+| `_TASK_MENU_KB` | `dict` | Sub-menu task |
+| `_STATUS_MENU_KB` | `dict` | Sub-menu stato sistema |
+| `_PERF_MENU_KB` | `dict` | Sub-menu performance |
+| `_HEALTH_MENU_KB` | `dict` | Sub-menu health |
+| `_DEV_MENU_KB` | `dict` | Sub-menu developer |
+| `_LAST_GOAL` | `dict[int,str]` | Memoria per bottone 🔁 Rifai |
+| `_BENCH_CACHE` | `dict[int,dict]` | Ultimo run benchmark per chat |
+| `_after_task_kb(chat_id)` | func | Keyboard dinamica post-task |
+
+**Import:** solo `from __future__ import annotations`
+
+---
+
+### `telegram_cmd_monitoring.py` — 456 righe
+**Ruolo:** Comandi di monitoraggio, stato e diagnostica.
+
+| Comando / Funzione | Trigger Telegram |
+|--------------------|-----------------|
+| `_cmd_help(chat_id)` | `/start` `/help` `tgw_help` |
+| `_cmd_logs(chat_id)` | `/logs` `tgw_logs` |
+| `_cmd_status(chat_id)` | `/stato` `tgw_status` |
+| `_cmd_commit_summary(chat_id)` | `/commit` `tgw_commits` |
+| `_cmd_check(chat_id)` | `/salute` `tgw_health` |
+| `_cmd_tasks(chat_id)` | `/attività` `tgw_tasks` |
+| `_cmd_git(chat_id, args)` | `/git` `tgw_git` |
+| `_cmd_coord(chat_id)` | `/coord` `tgw_coord` |
+| `_cmd_scan_now(chat_id)` | `/scan` `tgw_scan` |
+| `_cmd_telemetry(chat_id)` | `/telemetria` `tgw_telemetry` |
+
+**Import:** stdlib + `telegram_tg_client` + `telegram_keyboards`
+
+---
+
+### `telegram_cmd_ai.py` — 1152 righe
+**Ruolo:** Comandi AI, LLM e operativi. Modulo più pesante — contiene lo streaming loop.
+
+| Comando / Funzione | Trigger Telegram |
+|--------------------|-----------------|
+| `_cmd_do(chat_id, goal)` | `/avvia` — lancia task AI con streaming |
+| `_cmd_autofix(chat_id)` | `/fix` `tgw_autofix` |
+| `_cmd_nota(chat_id, text)` | `/nota` `tgw_nota` |
+| `_cmd_cerca(chat_id, query)` | `/cerca` `tgw_cerca` |
+| `_cmd_meteo(chat_id, city)` | `/meteo` `tgw_meteo` |
+| `_cmd_riepilogo(chat_id)` | `/riepilogo` `tgw_briefing` |
+| `_cmd_score(chat_id)` | `/score` `tgw_score` |
+| `_cmd_bench(chat_id)` | `/bench` `tgw_bench` |
+| `_cmd_improve(chat_id, target)` | `/migliora` `tgw_improve` |
+
+**Import:** stdlib + `telegram_tg_client` + `telegram_keyboards`
+
+---
+
+### `telegram_callbacks.py` — 353 righe
+**Ruolo:** Smista `callback_query` e `inline_query` in arrivo da Telegram.
+
+| Funzione | Descrizione |
+|----------|-------------|
+| `_handle_inline(iq, token)` | Risponde alle inline query (`@ARJagent_ap_bot testo`) |
+| `_handle_callback(cb, token)` | Dispatch per tutti i `callback_data` `tgw_*` / `agent` / `qp_*` |
+
+**Import:** `telegram_tg_client` + `telegram_keyboards` + `telegram_cmd_ai` + `telegram_cmd_monitoring`
+
+> ⚠️ **Questo modulo crea dipendenze circolari potenziali** — non importare
+> `telegram_callbacks` da `telegram_cmd_ai` o `telegram_cmd_monitoring`.
+
+---
+
+### `telegram_webhook.py` — 605 righe  *(era 2844)*
+**Ruolo:** Router FastAPI puro. Solo endpoint HTTP, zero logica di business.
+
+| Endpoint | Metodo | Descrizione |
+|----------|--------|-------------|
+| `/api/telegram/webhook` | POST | Ricezione update getUpdates (polling daemon) |
+| `/api/telegram/process` | POST | Endpoint alternativo per CF Pages proxy |
+| `/api/telegram/config/invalidate` | POST | Invalida cache config bot |
+
+**Import:** FastAPI + tutti i 5 moduli sopra
+**Montato in:** `backend/main.py` → `app.include_router(_tg_webhook_router)`
+
+---
+
+## Regole per gli hotfix
+
+| Vuoi cambiare... | Tocca solo... |
+|------------------|---------------|
+| Aspetto di un bottone / label | `telegram_keyboards.py` |
+| Risposta a un comando /help, /stato… | `telegram_cmd_monitoring.py` |
+| Logica task AI / streaming / bench | `telegram_cmd_ai.py` |
+| Routing dei bottoni inline (tgw_*) | `telegram_callbacks.py` |
+| Helpers HTTP verso api.telegram.org | `telegram_tg_client.py` |
+| Routing endpoint FastAPI | `telegram_webhook.py` |
+
+---
+
+## Daemon Node.js (scripts/lib/daemon-callbacks.mjs)
+
+Il daemon usa **getUpdates polling** (non webhook registrato).
+Riceve gli update, li smista ai command handler Python via HTTP interno.
+Il flusso `callback_data tgw_*` viene elaborato da `telegram_callbacks.py::_handle_callback`.
+
+```
+Telegram ──► getUpdates daemon ──► POST /api/telegram/process
+                                          │
+                                    telegram_webhook.py (router)
+                                          │
+                              ┌───────────┴───────────┐
+                         message?                callback_query?
+                              │                        │
+                    telegram_cmd_*.py        telegram_callbacks.py
+                                                  ::_handle_callback
+```

api/_agent_helpers.py

@@ -0,0 +1,127 @@
+"""backend/api/_agent_helpers.py — Funzioni helper condivise tra i sub-router agent.
+
+Estratto da agent_loop_routes / agent_task_routes / agent_checkpoint_routes
+per eliminare le triplicazioni create dallo split S359 (2026-06-30).
+
+Esportazioni:
+  _RE_SURROGATES         — regex surrogati UTF-16
+  _ss(s)                 — sanitizza string (rimuove surrogati)
+  _log_task_exc(task)    — done-callback asyncio con log eccezioni
+  _PERSONA_KEYWORD_MAP   — dict globale (regex per persona routing)
+  _PERSONA_CLIENT_CACHE  — dict globale (cache LLM client per persona)
+  _build_persona_kw_map  — costruisce _PERSONA_KEYWORD_MAP (P17-F5)
+  _classify_persona_server — classifica persona via regex scoring (zero LLM)
+  _get_persona_llm_client  — ritorna LLM client persona-appropriato
+"""
+from __future__ import annotations
+import re
+import logging
+from fastapi import APIRouter
+
+_logger = logging.getLogger("api.agent")
+
+_RE_SURROGATES = re.compile(r"[\uD800-\uDFFF]", re.UNICODE)
+def _ss(s: object) -> str:
+    if not isinstance(s, str):
+        return s
+    try:
+        cleaned = _RE_SURROGATES.sub("", s)
+        cleaned = cleaned.encode("utf-8", errors="replace").decode("utf-8", errors="replace")
+    except Exception:
+        cleaned = s
+    return cleaned
+def _log_task_exc(task):
+    if not task.cancelled():
+        exc = task.exception()
+        if exc:
+            _logger.warning("[agent] background task raised %s: %s", type(exc).__name__, exc)
+try:
+    from .telegram_notify import notify_task_done as _tg_done, notify_task_error as _tg_error, notify_task_start as _tg_start, notify_task_step as _tg_step
+except Exception:
+    async def _tg_done(*_a, **_kw): pass  # type: ignore[misc]
+    async def _tg_error(*_a, **_kw): pass  # type: ignore[misc]
+    async def _tg_start(*_a, **_kw): pass  # type: ignore[misc]
+    async def _tg_step(*_a, **_kw):  pass  # type: ignore[misc]
+
+router = APIRouter()
+
+@router.post('/run_loop', deprecated=True)
+async def run_loop():
+    """Deprecated — use /agent/task instead."""
+    from fastapi.responses import JSONResponse
+    return JSONResponse(status_code=410, content={"detail": {"error": "Gone", "migration": "/api/agent/tasks"}})
+
+
+# ─── P17-F5: Persona helpers ──────────────────────────────────────────────────
+import re as _re_persona
+
+_PERSONA_KEYWORD_MAP: dict = {}
+
+def _build_persona_kw_map() -> dict:
+    import re
+    return {
+        'researcher': re.compile(
+            r'\b(cerca|ricerca|research|trova|notizie|news|url|leggi|articolo|wikipedia|'
+            r'google|fonte|source|scrape|fetch|sito|pagina|web|http|verifica|fact.?check)\b',
+            re.IGNORECASE
+        ),
+        'coder': re.compile(
+            r'\b(codice|code|funzione|function|bug|script|implementa|python|javascript|'
+            r'typescript|refactor|debug|test|classe|class|api|endpoint|sql|database|html|'
+            r'css|react|app|applicazione|programma|sviluppa)\b',
+            re.IGNORECASE
+        ),
+        'reasoner': re.compile(
+            r'\b(analizza|pianifica|strategia|decide|ragiona|valuta|confronta|'
+            r'piano|roadmap|architettura|valutazione|decisione|ottimale|consiglia)\b',
+            re.IGNORECASE
+        ),
+        'analyst': re.compile(
+            r'\b(dati|statistiche|grafico|dataset|csv|dataframe|pandas|matplotlib|'
+            r'metriche|kpi|trend|visualizza|dashboard|excel|tabella|percentuale|distribuzione)\b',
+            re.IGNORECASE
+        ),
+    }
+
+def _classify_persona_server(goal: str) -> str:
+    """P17-F5: classifica la persona dal goal via regex scoring. Zero LLM — zero latency."""
+    global _PERSONA_KEYWORD_MAP
+    if not _PERSONA_KEYWORD_MAP:
+        _PERSONA_KEYWORD_MAP = _build_persona_kw_map()
+    if not goal or len(goal) < 4:
+        return ''
+    best, best_score = '', 0
+    for persona_id, pattern in _PERSONA_KEYWORD_MAP.items():
+        score = len(pattern.findall(goal))
+        if score > best_score:
+            best_score, best = score, persona_id
+    return best if best_score >= 1 else ''
+
+_PERSONA_CLIENT_CACHE: dict = {}
+
+def _get_persona_llm_client(persona: str, default_client: object) -> object:
+    """P17-F5: ritorna il client LLM persona-appropriate via role_router.
+    Fallback silente su default_client se la chiave API manca o role_router fallisce.
+    Cache in-process — zero overhead dopo il primo accesso.""";
+    if not persona:
+        return default_client
+    if persona in _PERSONA_CLIENT_CACHE:
+        return _PERSONA_CLIENT_CACHE[persona]
+    _ROLE_MAP = {'researcher': 'RESEARCHER', 'analyst': 'RESEARCHER',
+                 'coder': 'CODER', 'reasoner': 'REASONER', 'architect': 'ARCHITECT'}
+    role_name = _ROLE_MAP.get(persona.lower())
+    if not role_name:
+        return default_client
+    try:
+        from models.role_router import RoleRouter, Role as _Role
+        role = getattr(_Role, role_name, None)
+        if role is None:
+            return default_client
+        client = RoleRouter.get_client(role)
+        _PERSONA_CLIENT_CACHE[persona] = client
+        return client
+    except Exception:
+        return default_client
+
+
+

api/advanced_complex_benchmark.py

@@ -0,0 +1,108 @@
+"""
+backend/api/advanced_complex_benchmark.py — Stress test per task complessi e concorrenza.
+"""
+import asyncio
+import time
+import random
+import statistics
+from .execution_fabric import ExecutionFabric, DispatchRequest, ProviderKind, ProviderSpec, AlwaysOn, ProviderHealth
+from .token_rotator import rotator
+
+class AdvancedBenchmark:
+    def __init__(self):
+        self.fabric = ExecutionFabric()
+        self.metrics = {
+            "complex_reasoning": [],
+            "data_heavy_sync": [],
+            "multi_provider_chain": [],
+            "failures": 0,
+            "successes": 0
+        }
+
+    async def setup(self):
+        # Configurazione flotta
+        for char in ['a', 'b', 'c', 'd']:
+            self.fabric._specs[f"sb-{char}"] = ProviderSpec(
+                provider_id=f"sb-{char}", name=f"Supabase {char.upper()}", kind=ProviderKind.LOCAL,
+                capabilities=["memory"], always_on=AlwaysOn.YES
+            )
+            self.fabric._states[f"sb-{char}"] = type('State', (), {"health": ProviderHealth.OK})()
+        
+        self.fabric._specs["oracle-core"] = ProviderSpec(
+            provider_id="oracle-core", name="Oracle Core", kind=ProviderKind.ORACLE,
+            capabilities=["reasoning", "sandbox"], always_on=AlwaysOn.YES, timeout=60.0
+        )
+        self.fabric._states["oracle-core"] = type('State', (), {"health": ProviderHealth.OK})()
+
+        self.fabric._specs["railway-core"] = ProviderSpec(
+            provider_id="railway-core", name="Railway Space E", kind=ProviderKind.RAILWAY,
+            capabilities=["reasoning", "sandbox"], always_on=AlwaysOn.YES
+        )
+        self.fabric._states["railway-core"] = type('State', (), {"health": ProviderHealth.OK})()
+        
+        self.fabric._initialized = True
+
+    async def _simulate_call(self, spec, req):
+        # Simula complessità variabile
+        if "reasoning" in spec.capabilities:
+            await asyncio.sleep(random.uniform(0.5, 2.0)) # Calcolo pesante
+        if random.random() < 0.05: # 5% probabilità di errore casuale
+            raise Exception("Random Provider Glitch")
+        if spec.provider_id == "sb-a" and random.random() < 0.3:
+            return {"status_code": 402} # 30% probabilità rate limit su A
+        return {"status": "ok", "provider": spec.name}
+
+    async def run_complex_task(self, name, capability, count=20):
+        print(f"⚙️ Esecuzione: {name} ({count} task)...")
+        tasks = []
+        for _ in range(count):
+            req = DispatchRequest(capability=capability, payload={"complexity": "high"})
+            tasks.append(self.fabric.dispatch(req))
+        
+        t0 = time.time()
+        results = await asyncio.gather(*tasks)
+        duration = (time.time() - t0) * 1000
+        
+        latencies = []
+        for r in results:
+            if r.status == "executed":
+                self.metrics["successes"] += 1
+                latencies.append(r.latency_ms)
+            else:
+                self.metrics["failures"] += 1
+        
+        self.metrics[name] = latencies
+
+    def print_stats(self):
+        print("\n" + "="*50)
+        print("📊 REPORT AVANZATO PRESTAZIONI SISTEMA")
+        print("="*50)
+        
+        total = self.metrics["successes"] + self.metrics["failures"]
+        print(f"Success Rate Totale: {(self.metrics['successes']/total)*100:.2f}% ({self.metrics['successes']}/{total})")
+        
+        for name in ["complex_reasoning", "data_heavy_sync"]:
+            data = self.metrics.get(name, [])
+            if data:
+                print(f"\n[{name.upper()}]")
+                print(f"  - Media Latenza: {statistics.mean(data):.2f}ms")
+                print(f"  - P95: {statistics.quantiles(data, n=20)[18]:.2f}ms")
+                print(f"  - P99: {max(data):.2f}ms")
+                print(f"  - Efficienza: {len(data)} task completati con successo")
+        
+        print("\n" + "="*50)
+
+    async def run(self):
+        await self.setup()
+        self.fabric._call_provider = self._simulate_call
+        
+        # Scenario 1: Ragionamento Complesso (Oracle/Railway)
+        await self.run_complex_task("complex_reasoning", "reasoning", count=30)
+        
+        # Scenario 2: Sincronizzazione Dati (Supabase A-D)
+        await self.run_complex_task("data_heavy_sync", "memory", count=50)
+        
+        self.print_stats()
+
+if __name__ == "__main__":
+    asyncio.run(AdvancedBenchmark().run())

api/agent.py

@@ -42,21 +42,8 @@ def _sanitize_for_json(obj: object) -> object:
 from fastapi import APIRouter, Depends, HTTPException, Request, Body
 from fastapi.responses import StreamingResponse
 from .auth_guard import require_role, AuthRole
-from pydantic import BaseModel, TypeAdapter, ValidationError, field_validator
+from pydantic import BaseModel, field_validator
 from typing import Literal
-
-# P0 JSON contract: expose structured JSON only after schema validation.
-_STRUCTURED_JSON_ADAPTER = TypeAdapter(dict[str, object] | list[object])
-
-def _validated_response_json(output: object) -> dict[str, object] | list[object] | None:
-    if not isinstance(output, str) or not output.strip():
-        return None
-    try:
-        parsed = json.loads(output)
-        return _STRUCTURED_JSON_ADAPTER.validate_python(parsed)
-    except (json.JSONDecodeError, ValidationError, TypeError, ValueError):
-        return None
-
 from .state import (
     _agent_tasks, _task_ai_clients, _task_checkpoints, _loop_registry, _run_stream_tasks,
     _prune_agent_tasks, _prune_checkpoints, _prune_loop_registry,
@@ -102,83 +89,6 @@ except Exception:
 router = APIRouter()
 
 
-class _LLMAdmission:
-    """Bounded in-process admission control for LLM loops."""
-    def __init__(self) -> None:
-        self.max_concurrency = max(1, int(os.getenv('LLM_MAX_CONCURRENCY', '2')))
-        self.max_queue = max(0, int(os.getenv('LLM_MAX_QUEUE', '8')))
-        self._condition = asyncio.Condition()
-        self._active = 0
-        self._queued = 0
-
-    async def reserve(self) -> bool:
-        async with self._condition:
-            if self._active + self._queued >= self.max_concurrency + self.max_queue:
-                return False
-            self._queued += 1
-            return True
-
-    async def acquire(self) -> None:
-        async with self._condition:
-            try:
-                while self._active >= self.max_concurrency:
-                    await self._condition.wait()
-                self._queued = max(0, self._queued - 1)
-                self._active += 1
-            except BaseException:
-                self._queued = max(0, self._queued - 1)
-                self._condition.notify(1)
-                raise
-
-    async def cancel(self) -> None:
-        async with self._condition:
-            self._queued = max(0, self._queued - 1)
-            self._condition.notify(1)
-
-    async def release(self) -> None:
-        async with self._condition:
-            self._active = max(0, self._active - 1)
-            self._condition.notify(1)
-
-    async def snapshot(self) -> dict[str, int]:
-        async with self._condition:
-            return {
-                'active': self._active,
-                'queued': self._queued,
-                'max_concurrency': self.max_concurrency,
-                'max_queue': self.max_queue,
-            }
-
-
-_LLM_ADMISSION = _LLMAdmission()
-
-
-async def _record_phase(phase: str, duration_ms: float = 0.0,
-                       outcome: str = 'ok', error_class: str | None = None) -> None:
-    try:
-        from .agent_telemetry import record_runtime_phase
-        await record_runtime_phase(phase, duration_ms, outcome, error_class)
-    except Exception:
-        pass
-
-
-def _queue_full_error() -> HTTPException:
-    return HTTPException(
-        status_code=429,
-        detail={
-            'error': 'llm_queue_full',
-            'message': 'Coda LLM satura. Riprova tra pochi secondi.',
-            'retry_after_seconds': 5,
-        },
-        headers={'Retry-After': '5'},
-    )
-
-
-@router.get('/api/agent/queue-status')
-async def agent_queue_status(role: AuthRole = Depends(require_role(AuthRole.MACHINE))):
-    return await _LLM_ADMISSION.snapshot()
-
-
 def _attach_byok_client(task_id: str, credentials: object) -> None:
     """Create a task-scoped LLM client without persisting or logging credentials."""
     if credentials is None:
@@ -294,17 +204,10 @@ async def agent_run_stream(
     body: ReasonLoopIn, request: Request,
     role: AuthRole = Depends(require_role(AuthRole.MACHINE)),  # GAP-1-fix: era fail-open
 ):
-    await _record_phase('auth')
-    if not await _LLM_ADMISSION.reserve():
-        await _record_phase('queue', outcome='rejected', error_class='queue_full')
-        raise _queue_full_error()
-    await _record_phase('queue')
     async def generate():
         queue: asyncio.Queue = asyncio.Queue()
 
         async def step_cb(step: dict) -> None:
-            if str(step.get('action', '')).startswith(('tool', 'executor:')):
-                await _record_phase('tool', outcome='ok')
             await queue.put(step)
 
         async def run_loop() -> None:
@@ -344,19 +247,16 @@ async def agent_run_stream(
                 _neg_c = getattr(body, 'negative_constraints', '') or ''
                 if _neg_c:
                     context_str = f"[VINCOLI OPERATIVI APPRESI — NON VIOLARE]\n{_neg_c}\n\n{context_str}".strip()
-                _provider_started = time.perf_counter()
                 result = await loop.run(
                     goal=body.goal, context=context_str,
                     max_steps=body.max_steps, on_step=step_cb,
                     session_id=getattr(body, "session_id", "") or "",
                 )
-                await _record_phase('provider', (time.perf_counter() - _provider_started) * 1000)
                 await queue.put({
                     '__done__': True,
                     'result':   result.get('output',  ''),
                     'engine':   result.get('engine',  'fallback'),
                     'success':  result.get('success', False),
-                    'response_json': _validated_response_json(result.get('output', '')),
                 })
             except Exception as exc:
                 # GAP-A1: log incident in registry (fire-and-forget, non-blocking)
@@ -370,13 +270,7 @@ async def agent_run_stream(
                     _logger.debug("[agent] silenced %s", type(_exc).__name__)  # noqa: BLE001
                 await queue.put({'__error__': str(exc)})
 
-        async def _admitted_run_loop():
-            await _LLM_ADMISSION.acquire()
-            try:
-                await run_loop()
-            finally:
-                await _LLM_ADMISSION.release()
-        task    = asyncio.create_task(_admitted_run_loop())
+        task    = asyncio.create_task(run_loop())
         task.add_done_callback(_log_task_exc)  # BUG-CB-1
         task_id = str(uuid.uuid4())
         # ABORT-1: registra task + queue per permettere cancellazione via POST /api/agent/abort
@@ -439,13 +333,7 @@ async def agent_run_stream(
                                           _err_detail = _ss(item.get('error', ''))
                                           _final_res = (f"\u26a0\ufe0f {_err_detail}" if _err_detail
                                                         else "\u26a0\ufe0f Tutti i provider AI sono temporaneamente indisponibili (rate limit). Riprova tra qualche minuto.")
-                                      _done_payload = {
-                                          'type': 'task_done', 'taskId': task_id, 'result': _final_res,
-                                          'engine': item.get('engine', 'fallback'), 'success': item.get('success', False),
-                                      }
-                                      if item.get('response_json') is not None:
-                                          _done_payload['response_json'] = _sanitize_for_json(item['response_json'])
-                                      yield f"data: {json.dumps(_done_payload)}\n\n"
+                                      yield f"data: {json.dumps({'type': 'task_done', 'taskId': task_id, 'result': _final_res, 'engine': item.get('engine', 'fallback'), 'success': item.get('success', False)})}\n\n"
                                       break
                 # S393 Priority 1: Narrative Streaming — arricchisce step_done con explanation
                 _NARR_QUICK = {
@@ -568,19 +456,7 @@ async def reason_loop(body: ReasonLoopIn, role: AuthRole = Depends(require_role(
                 'action': step_data.get('action', ''),
                 'output': str(step_data.get('output', ''))[:400],  # S577: 200→400
             })
-        if not await _LLM_ADMISSION.reserve():
-            raise _queue_full_error()
-        await _LLM_ADMISSION.acquire()
-        _provider_started = time.perf_counter()
-        try:
-            result = await loop.run(goal=body.goal, context=context_str, max_steps=body.max_steps, on_step=_on_step, session_id=getattr(body, "session_id", "") or "")
-        except Exception as exc:
-            await _record_phase('provider', (time.perf_counter() - _provider_started) * 1000, 'error', type(exc).__name__)
-            raise
-        else:
-            await _record_phase('provider', (time.perf_counter() - _provider_started) * 1000)
-        finally:
-            await _LLM_ADMISSION.release()
+        result = await loop.run(goal=body.goal, context=context_str, max_steps=body.max_steps, on_step=_on_step, session_id=getattr(body, "session_id", "") or "")
         if isinstance(result, dict):
             output_text = result.get('output', '') or ''
             engine_used = result.get('engine', 'unknown')
@@ -589,7 +465,6 @@ async def reason_loop(body: ReasonLoopIn, role: AuthRole = Depends(require_role(
             output_text = str(result)
             engine_used = 'unknown'
             errors_list = []
-        response_json = _validated_response_json(output_text)
         return {
             'ok':     bool(output_text and output_text.strip()),
             'success': bool(output_text and output_text.strip()),  # alias compat frontend
@@ -599,7 +474,6 @@ async def reason_loop(body: ReasonLoopIn, role: AuthRole = Depends(require_role(
             'engine': engine_used,
             'errors': errors_list,
             'steps':  _steps_log,  # N-2-FIX: step intermedi per debug/telemetria frontend
-            **({'response_json': response_json} if response_json is not None else {}),
         }
     except Exception as e:
         _logger.error("[reason/loop] Error: %s", e)
@@ -731,7 +605,7 @@ async def _create_task_internal(task_id: str, goal: str, job: dict) -> dict:
 
 
 @router.post('/api/agent/tasks')
-async def create_agent_task(body: AgentTaskIn, request: Request, role: AuthRole = Depends(require_role(AuthRole.MACHINE))):  # GAP-1-fix
+async def create_agent_task(body: AgentTaskIn, role: AuthRole = Depends(require_role(AuthRole.MACHINE))):  # GAP-1-fix
     """
     Crea o recupera un task agent.
 
@@ -739,27 +613,11 @@ async def create_agent_task(body: AgentTaskIn, request: Request, role: AuthRole
     il task viene ripristinato dallo store persistente invece di essere riavviato.
     Questo preserva lo stato SUCCESS/ERROR precedente senza sprecare token.
     """
-    await _record_phase('auth')
     _prune_agent_tasks()
-    raw_idempotency_key = (body.idempotency_key or request.headers.get('Idempotency-Key') or '').strip()
-    if len(raw_idempotency_key) > 200:
-        raise HTTPException(400, detail={'error': 'invalid_idempotency_key'})
-    task_id = body.taskId or (
-        str(uuid.uuid5(uuid.NAMESPACE_URL, f'baida98-ai:{body.session_id or ""}:{raw_idempotency_key}'))
-        if raw_idempotency_key else str(uuid.uuid4())
-    )
-    _idempotency_claimed = False
-    if raw_idempotency_key and task_id not in _agent_tasks:
-        # Claim before the first await: concurrent retries in this worker see the
-        # same task immediately and cannot create a second provider loop/write.
-        _agent_tasks[task_id] = {
-            'id': task_id, 'status': 'CREATING',
-            'idempotency_key': raw_idempotency_key,
-        }
-        _idempotency_claimed = True
+    task_id = body.taskId or str(uuid.uuid4())
 
     # Already in memory → return immediately (normal path, includes S358 reconnect)
-    if task_id in _agent_tasks and not _idempotency_claimed:
+    if task_id in _agent_tasks:
         if task_id not in _task_ai_clients:
             _attach_byok_client(task_id, body.provider_credentials)
         return {'taskId': task_id, 'status': _agent_tasks[task_id]['status']}
@@ -790,7 +648,6 @@ async def create_agent_task(body: AgentTaskIn, request: Request, role: AuthRole
         'resume_from_step':  body.resume_from_step, # P16-F3: passo resume dalla coda
         'persona':           body.persona,           # P17-F5: expertise persona hint
         'session_id':        body.session_id or '',   # P17-F2: BB session key (normalize None→'')
-        'idempotency_key':   raw_idempotency_key,
         'forbid_tools':       _tool_policy.forbid_tools,
         'literal_response':   _tool_policy.literal_response,
         'allow_local_csv_conversion': _tool_policy.allow_local_csv_conversion,
@@ -798,6 +655,7 @@ async def create_agent_task(body: AgentTaskIn, request: Request, role: AuthRole
     # Le credenziali BYOK restano in una mappa runtime separata dai metadata task
     # e non raggiungono Supabase, checkpoint o buffer SSE.
     _attach_byok_client(task_id, body.provider_credentials)
+
     # BG-4: restore cross-session handoff context (async, non-blocking)
     if body.session_id:
         _hctx = await sb_restore_handoff_context(body.session_id)
@@ -808,7 +666,6 @@ async def create_agent_task(body: AgentTaskIn, request: Request, role: AuthRole
     asyncio.create_task(
         sb_upsert_task(task_id, body.goal, 'QUEUED', body.max_steps, body.context, created_at)
     ).add_done_callback(_log_task_exc)
-    await _record_phase('persistence')
     # S361: gli strumenti speculativi sono consentiti solo quando il messaggio
     # utente non li vieta esplicitamente. La policy è fail-closed per questo task.
     if not _tool_policy.forbid_tools:
@@ -959,7 +816,6 @@ async def stream_agent_task(task_id: str, request: Request, resume: int = 0, rol
       - Task era RUNNING   → replay buffer parziale + evento task_interrupted.
       - Task non trovato   → prova sb_restore_task prima di 404.
     """
-    await _record_phase('auth')
     # S359: se task_id non è in memoria, prova il restore da Supabase
     if task_id not in _agent_tasks:
         restored = await sb_restore_task(task_id)
@@ -993,8 +849,8 @@ async def stream_agent_task(task_id: str, request: Request, resume: int = 0, rol
         # tool. È il backstop per client SSE che non applicano il fast path UI.
         _literal_response = task.get('literal_response')
         if isinstance(_literal_response, str) and _literal_response:
-            _agent_tasks[task_id]['status'] = 'COMPLETED'
-            asyncio.create_task(sb_update_status(task_id, 'COMPLETED')).add_done_callback(_log_task_exc)
+            _agent_tasks[task_id]['status'] = 'SUCCESS'
+            asyncio.create_task(sb_update_status(task_id, 'SUCCESS')).add_done_callback(_log_task_exc)
             literal_event = json.dumps(_sanitize_for_json({
                 'event': 'task_done', 'taskId': task_id, 'result': _literal_response,
             }))
@@ -1043,7 +899,7 @@ async def stream_agent_task(task_id: str, request: Request, resume: int = 0, rol
         sb_events = await sb_get_events(task_id)
         if sb_events:
             task_status = task.get('status', 'UNKNOWN')
-            terminal    = task_status in ('COMPLETED', 'SUCCESS', 'ERROR', 'CANCELLED')
+            terminal    = task_status in ('SUCCESS', 'ERROR', 'CANCELLED')
             # Replay buffer from resume point
             for evt_str in sb_events[_resume_from:]:
                 yield evt_str
@@ -1096,18 +952,6 @@ async def stream_agent_task(task_id: str, request: Request, resume: int = 0, rol
                     yield "data: [DONE]\n\n"
                     return
         # ── Case 3: nuova esecuzione ──────────────────────────────────────────────
-        if not await _LLM_ADMISSION.reserve():
-            await _record_phase('queue', outcome='rejected', error_class='queue_full')
-            _agent_tasks[task_id]['status'] = 'RATE_LIMITED'
-            _rate_limited = json.dumps(_sanitize_for_json({
-                'event': 'task_error', 'taskId': task_id,
-                'statusCode': 429, 'retryAfter': 5,
-                'error': 'llm_queue_full',
-            }))
-            yield f'data: {_rate_limited}\n\n'
-            yield 'data: [DONE]\n\n'
-            return
-        await _record_phase('queue')
         _prune_loop_registry()
         reg_entry: dict = {
             'asyncio_task':      None,
@@ -1161,8 +1005,8 @@ async def stream_agent_task(task_id: str, request: Request, resume: int = 0, rol
                 # È emesso direttamente nello stream affinché i client SSE non possano bypassarlo.
                 _literal_response = task.get('literal_response')
                 if isinstance(_literal_response, str) and _literal_response:
-                    _agent_tasks[task_id]['status'] = 'COMPLETED'
-                    asyncio.create_task(sb_update_status(task_id, 'COMPLETED')).add_done_callback(_log_task_exc)
+                    _agent_tasks[task_id]['status'] = 'SUCCESS'
+                    asyncio.create_task(sb_update_status(task_id, 'SUCCESS')).add_done_callback(_log_task_exc)
                     _sse('task_done', {'taskId': task_id, 'result': _literal_response})
                     return
 
@@ -1202,24 +1046,6 @@ async def stream_agent_task(task_id: str, request: Request, resume: int = 0, rol
                     "Il frontend mostrerà automaticamente un pulsante 'Connetti' all'utente."
                 )
                 context_str = f"{context_str}\n\n{_connector_hint}".strip() if context_str else _connector_hint
-                # ARTIFACT-CONTRACT: le richieste di pagina/app richiedono un
-                # artifact reale, non una risposta narrativa. Il frontend committa
-                # solo file_written + vfs_sync_complete, quindi l'agente deve
-                # scrivere e rileggere almeno un file prima di dichiarare successo.
-                _artifact_goal = bool(re.search(
-                    r"\b(?:pagina|sito|website|webapp|app|mini[- ]app|ui|interfaccia)\b",
-                    task.get('goal', ''), re.IGNORECASE,
-                ))
-                if _artifact_goal:
-                    _artifact_hint = (
-                        "[CONTRATTO ARTIFACT UI]\n"
-                        "Per questa richiesta devi creare davvero i file nel workspace usando write_file "
-                        "(non limitarti a proporre codice in chat). Dopo la scrittura, usa read_file o "
-                        "un controllo equivalente per verificare il contenuto. Dichiara completamento "
-                        "solo se la scrittura è riuscita; in caso contrario segnala l'errore senza inventare "
-                        "un link o un'anteprima."
-                    )
-                    context_str = f"{_artifact_hint}\n\n{context_str}".strip()
                 # GAP-SYNC-FIX: inject _resume_context (set da stream_agent_task su reconnect con checkpoint)
                 # Bug: _resume_context era settato su task{} ma mai letto qui → context perduto su resume.
                 _resume_ctx = task.get('_resume_context', '')
@@ -1311,19 +1137,13 @@ async def stream_agent_task(task_id: str, request: Request, resume: int = 0, rol
                 # soltanto quelli con contenuto così il commit atomico può avvenire
                 # una sola volta dopo un task riuscito.
                 _vfs_written_paths: set[str] = set()
-                # Accumula soltanto i token realmente emessi per poter riconciliare
-                # il testo in streaming con l'output autorevole del finalizer.
-                _streamed_chunks: list[str] = []
 
                 async def step_cb(step_data: dict) -> None:
                     step_idx[0] += 1
                     _action = step_data.get('action', f'Step {step_idx[0]}')
                     # S420: streaming token — emetti direttamente senza passare dal buffer step
                     if _action == 'text_chunk':
-                        _token = _ss(step_data.get('token', ''))
-                        if _token:
-                            _streamed_chunks.append(_token)
-                        _sse('text_chunk', {'taskId': task_id, 'token': _token})
+                        _sse('text_chunk', {'taskId': task_id, 'token': _ss(step_data.get('token', ''))})
                         return
                     # RECOV-P1: engineering_state event — forward projection to frontend
                     if _action == 'engineering_state':
@@ -1557,7 +1377,6 @@ async def stream_agent_task(task_id: str, request: Request, resume: int = 0, rol
                     except Exception:
                         pass  # S364: skeleton injection is optional
 
-                _provider_started = time.perf_counter()
                 result = await loop.run(
                     goal=task['goal'],
                     context=context_str,
@@ -1565,64 +1384,10 @@ async def stream_agent_task(task_id: str, request: Request, resume: int = 0, rol
                     on_step=step_cb,
                     session_id=task.get('session_id', '') or '',
                     allow_tools=not bool(task.get('forbid_tools', False)),
-                                        allow_local_csv_conversion=bool(task.get('allow_local_csv_conversion', False)),
+                    allow_local_csv_conversion=bool(task.get('allow_local_csv_conversion', False)),
                 )
-                await _record_phase('provider', (time.perf_counter() - _provider_started) * 1000)
-                # ARTIFACT-CONTRACT-FALLBACK: alcuni provider restituiscono codice HTML
-                # nella risposta finale dopo aver narrato una scrittura, senza produrre
-                # il tool event `file_written`. Non committiamo mai una falsa positività:
-                # se il goal è UI, proviamo solo a materializzare un documento HTML
-                # completo già presente nell'output, usando l'executor VFS autenticato.
-                # Se non troviamo un documento completo o la scrittura fallisce, il task
-                # resta senza artifact e il frontend non riceve alcun sync inventato.
-                if _artifact_goal and not _vfs_written_paths and getattr(loop, 'executor', None):
-                    _artifact_output = str(result.get('output', result) if isinstance(result, dict) else result)
-                    _html_match = re.search(r'(?is)(<!doctype\s+html\b.*?</html>)', _artifact_output)
-                    if not _html_match:
-                        _html_match = re.search(r'(?is)(<html(?:\s[^>]*)?>.*?</html>)', _artifact_output)
-                    if _html_match:
-                        _artifact_content = _html_match.group(1).strip()
-                        _artifact_path = 'index.html'
-                        _path_match = re.search(r'(?i)(?:/|\b)([\w.-]+\.html)\b', _artifact_output)
-                        if _path_match:
-                            _artifact_path = _path_match.group(1)
-                        try:
-                            _write_result = await asyncio.wait_for(
-                                loop.executor.run_tool('write_file', {
-                                    'path': _artifact_path,
-                                    'content': _artifact_content,
-                                }),
-                                timeout=25.0,
-                            )
-                            _write_ok = not (isinstance(_write_result, dict) and _write_result.get('error'))
-                            if _write_ok:
-                                _vfs_written_paths.add(_artifact_path)
-                                await step_cb({
-                                    'action': 'file_written', 'status': 'done',
-                                    'path': _artifact_path, 'content': _artifact_content,
-                                    'result': f'Artifact materializzato: {_artifact_path}',
-                                })
-                                _read_result = await asyncio.wait_for(
-                                    loop.executor.run_tool('read_file', {'path': _artifact_path}),
-                                    timeout=15.0,
-                                )
-                                _read_ok = not (isinstance(_read_result, dict) and _read_result.get('error'))
-                                await step_cb({
-                                    'action': 'read_file',
-                                    'status': 'done' if _read_ok else 'error',
-                                    'path': _artifact_path,
-                                    'result': f'Verifica artifact: {_artifact_path}' if _read_ok else str(_read_result)[:300],
-                                })
-                        except Exception as _artifact_exc:
-                            _logger.warning('[agent] artifact fallback failed: %s', type(_artifact_exc).__name__)
-
-                # Lifecycle separato: l'esecuzione primaria è completa quando VFS e risultato
-                # sono confermati; la verifica qualità successiva non deve tenere il task RUNNING.
-                _agent_tasks[task_id]['status'] = 'COMPLETED'
-                _agent_tasks[task_id]['quality_status'] = (
-                    'QUALITY_CHECK_PENDING' if _run_quality_check else 'NOT_REQUIRED'
-                )
-                asyncio.create_task(sb_update_status(task_id, 'COMPLETED')).add_done_callback(_log_task_exc)
+                _agent_tasks[task_id]['status'] = 'SUCCESS'
+                asyncio.create_task(sb_update_status(task_id, 'SUCCESS')).add_done_callback(_log_task_exc)
                 # ARCH-K2.2: pubblica lifecycle event via Kernel
                 if _KERNEL_AVAILABLE and _kernel is not None:
                     asyncio.create_task(_kernel.publish_event(
@@ -1638,56 +1403,17 @@ async def stream_agent_task(task_id: str, request: Request, resume: int = 0, rol
                     # confermato il task. Su errore/cancellazione lo staging rimane
                     # intenzionalmente non committato.
                     _sse('vfs_sync_complete', _vfs_commit)
-                if _run_quality_check:
-                    _sse('quality_check_pending', {
-                        'taskId': task_id,
-                        'status': 'QUALITY_CHECK_PENDING',
-                        'primaryStatus': 'COMPLETED',
-                    })
-                _streamed_text = ''.join(_streamed_chunks)
-                if _streamed_text and _result_text != _streamed_text:
-                    # Il finalizer può riparare/normalizzare la risposta dopo gli
-                    # ultimi chunk. Notifica esplicitamente la sostituzione così il
-                    # client non mostra un testo parziale o divergente.
-                    _sse('text_replace', {
-                        'taskId': task_id,
-                        'text': _result_text[:8000],
-                        'reason': 'authoritative_finalizer_output',
-                    })
-                _sse('task_done', {
-                    'taskId': task_id,
-                    'result': _result_text[:8000],
-                    'status': 'COMPLETED',
-                    'qualityStatus': _agent_tasks[task_id].get('quality_status', 'NOT_REQUIRED'),
-                })
+                _sse('task_done', {'taskId': task_id, 'result': _result_text[:8000]})
                 asyncio.create_task(_tg_done(task_id, task.get('goal', ''), _result_text[:500], _task_started_ms)).add_done_callback(_log_task_exc)
 
-                # Quality check non bloccante: aggiorna solo quality_status, mai lo stato
-                # primario del task e mai il commit VFS già confermato.
+                # S363: fire-and-forget quality check when code detected in output
                 if _run_quality_check:
                     _qg_result = str(result.get('output', result) if isinstance(result, dict) else result)
-                    if len(_qg_result) > 500 and _qg_result.count('```') >= 2:
-                        async def _run_quality_background() -> None:
-                            try:
-                                await _run_quality_check(
-                                    task_id, task['goal'], _qg_result,
-                                    on_event=lambda ev: _sse(ev.get('type', 'test_result'), ev),
-                                )
-                                _agent_tasks.get(task_id, {})['quality_status'] = 'QUALITY_CHECK_DONE'
-                                _sse('quality_check_done', {
-                                    'taskId': task_id,
-                                    'status': 'QUALITY_CHECK_DONE',
-                                    'primaryStatus': 'COMPLETED',
-                                })
-                            except Exception as _q_exc:
-                                _agent_tasks.get(task_id, {})['quality_status'] = 'QUALITY_CHECK_ERROR'
-                                _sse('quality_check_done', {
-                                    'taskId': task_id,
-                                    'status': 'QUALITY_CHECK_ERROR',
-                                    'primaryStatus': 'COMPLETED',
-                                    'error': type(_q_exc).__name__,
-                                })
-                        asyncio.create_task(_run_quality_background()).add_done_callback(_log_task_exc)
+                    if len(_qg_result) > 500 and _qg_result.count('```') >= 2:  # S373: threshold raised — evita QG su snippet brevi
+                        asyncio.create_task(_run_quality_check(
+                            task_id, task['goal'], _qg_result,
+                            on_event=lambda ev: _sse(ev.get('type', 'test_result'), ev),
+                        )).add_done_callback(_log_task_exc)
 
 
             except asyncio.CancelledError:
@@ -1702,8 +1428,8 @@ async def stream_agent_task(task_id: str, request: Request, resume: int = 0, rol
                 _sse('task_cancelled', {'taskId': task_id})
 
             except (ImportError, ModuleNotFoundError):
-                _agent_tasks[task_id]['status'] = 'COMPLETED'
-                asyncio.create_task(sb_update_status(task_id, 'COMPLETED')).add_done_callback(_log_task_exc)
+                _agent_tasks[task_id]['status'] = 'SUCCESS'
+                asyncio.create_task(sb_update_status(task_id, 'SUCCESS')).add_done_callback(_log_task_exc)
                 _sse('step_done', {'taskId': task_id, 'step': {'name': 'Ragionamento', 'index': 0}})
                 _sse('task_done', {'taskId': task_id, 'result': (
                     f'Goal ricevuto: {task["goal"]}\n\n'
@@ -1736,13 +1462,7 @@ async def stream_agent_task(task_id: str, request: Request, resume: int = 0, rol
                     except Exception as _exc:
                         _logger.debug("[agent] silenced %s", type(_exc).__name__)  # noqa: BLE001
 
-        async def _admitted_run_loop():
-            await _LLM_ADMISSION.acquire()
-            try:
-                await run_loop()
-            finally:
-                await _LLM_ADMISSION.release()
-        reg_entry['asyncio_task'] = asyncio.create_task(_admitted_run_loop())
+        reg_entry['asyncio_task'] = asyncio.create_task(run_loop())
         reg_entry['asyncio_task'].add_done_callback(_log_task_exc)  # BUG-CB-2
 
         try:

api/agent_checkpoint_routes.py

@@ -0,0 +1,279 @@
+"""agent_checkpoint_routes.py — Checkpoint, debug/timing, skill-stats, circuit-status.
+
+Estratto da agent.py (split 2026-06-30).
+Route coperte:
+  POST   /api/agent/tasks/{task_id}/checkpoint
+  GET    /api/agent/tasks/{task_id}/checkpoint
+  DELETE /api/agent/tasks/{task_id}/checkpoint
+  GET    /api/agent/checkpoints
+  GET    /debug/timing
+  GET    /api/agent/skill-stats/{session_id}
+  GET    /api/agent/skill-stats
+  GET    /api/agent/circuit-status/{session_id}
+"""
+from __future__ import annotations
+import os, asyncio, json, uuid, time, re
+import re as _re_persona
+from fastapi import APIRouter, HTTPException, Request, Body
+from fastapi.responses import StreamingResponse
+from pydantic import BaseModel, field_validator
+from typing import Literal
+from .state import (
+    _agent_tasks, _task_checkpoints, _loop_registry, _run_stream_tasks,
+    _prune_agent_tasks, _prune_checkpoints, _prune_loop_registry,
+    _get_mem_manager, _get_mem_manager_async, _get_executor, _get_planner, _get_ai_client,
+    ReasonLoopIn, AgentTaskIn,
+    write_ahead_task_created,
+)
+from .speculative import fire_speculative_tools
+try:
+    from .quality_guardian import run_quality_check as _run_quality_check
+except Exception:
+    _run_quality_check = None
+import logging
+_logger = logging.getLogger("api.agent")
+from .persistence import (
+    sb_upsert_task, sb_update_status, sb_append_event,
+    sb_restore_task, sb_get_events, sb_delete_task_events,
+    sb_list_tasks, sb_save_checkpoint, sb_get_checkpoint,
+    sb_restore_handoff_context, sb_upsert_handoff, sb_delete_handoff,
+)
+from ._agent_helpers import _RE_SURROGATES, _ss, _log_task_exc
+try:
+    from .telegram_notify import notify_task_done as _tg_done, notify_task_error as _tg_error, notify_task_start as _tg_start, notify_task_step as _tg_step
+except Exception:
+    async def _tg_done(*_a, **_kw): pass  # type: ignore[misc]
+    async def _tg_error(*_a, **_kw): pass  # type: ignore[misc]
+    async def _tg_start(*_a, **_kw): pass  # type: ignore[misc]
+    async def _tg_step(*_a, **_kw):  pass  # type: ignore[misc]
+
+router = APIRouter()
+
+
+
+# ── Task checkpoints ───────────────────────────────────────────────────────────
+
+class CheckpointIn(BaseModel):
+    taskId:     str
+    step:       int
+    goal:       str
+    plan:       list[str] = []
+    logs:       list[str] = []
+    artifacts:  list[str] = []
+    retryCount: int = 0
+    extra:      dict = {}
+
+
+@router.post('/api/agent/tasks/{task_id}/checkpoint')
+async def save_checkpoint(task_id: str, body: CheckpointIn):
+    _prune_checkpoints()
+    _task_checkpoints[task_id] = {
+        'taskId':     task_id,
+        'step':       body.step,
+        'goal':       body.goal,
+        'plan':       body.plan,
+        'logs':       body.logs[-50:],
+        'artifacts':  body.artifacts,
+        'retryCount': body.retryCount,
+        'extra':      body.extra,
+        'savedAt':    int(time.time() * 1000),
+    }
+    asyncio.create_task(sb_save_checkpoint(task_id, _task_checkpoints[task_id])).add_done_callback(_log_task_exc)
+    return {'saved': True, 'taskId': task_id, 'step': body.step}
+
+
+@router.get('/api/agent/tasks/{task_id}/checkpoint')
+async def get_checkpoint(task_id: str):
+    _prune_checkpoints()
+    cp = _task_checkpoints.get(task_id)
+    if not cp:
+        cp = await sb_get_checkpoint(task_id)
+    if not cp:
+        raise HTTPException(404, detail={'error': 'checkpoint_not_found', 'taskId': task_id})
+    return cp
+
+
+@router.delete('/api/agent/tasks/{task_id}/checkpoint')
+async def delete_checkpoint(task_id: str):
+    _task_checkpoints.pop(task_id, None)
+    return {'deleted': task_id}
+
+
+@router.get('/api/agent/checkpoints')
+async def list_checkpoints():
+    _prune_checkpoints()
+    now = int(time.time() * 1000)
+    return {
+        'count': len(_task_checkpoints),
+        'checkpoints': [
+            {'taskId': k, 'step': v['step'], 'goal': v['goal'][:300], 'age_ms': now - v['savedAt']}  # S606: 200→300
+            for k, v in _task_checkpoints.items()
+        ],
+    }
+
+
+# ─── Sprint 5 ITEM 15: /debug/timing — telemetria timing + qualità agente ────
+# Usato da TelemetryDashboard.tsx (frontend) per la sezione "Qualità agente".
+# Espone: timing_stats (avg/count per fase) + repair_stats (contatori qualità).
+# Non richiede auth — dati aggregati, nessun dato sensibile.
+@router.get('/debug/timing')
+async def get_debug_timing():
+    """
+    Espone timing breakdown per fase (classify/plan/coder/verifier/browser)
+    e contatori qualità (goal_success, repair_success, tool_failure, req_engine).
+    Formato: { timing_stats: {label: {avg, count}}, repair_stats: {key: count} }
+    """
+    try:
+        from api.state import _TIMING_STORE, _REPAIR_STATS
+        timing_stats: dict = {}
+        for label, samples in _TIMING_STORE.items():
+            if samples:
+                avg_val = round(sum(samples) / len(samples), 1)
+            else:
+                avg_val = None
+            timing_stats[label] = {"avg": avg_val, "count": len(samples)}
+        return {
+            "timing_stats": timing_stats,
+            "repair_stats": dict(_REPAIR_STATS),
+        }
+    except Exception as exc:
+        return {"timing_stats": {}, "repair_stats": {}, "error": str(exc)}
+
+
+# ─── GAP-SKILL-SYNC: /api/agent/skill-stats — statistiche tool adattive ──────
+# Espone i dati del SkillTracker (session-scoped success/fail per tool)
+# al frontend per merge con skillRegistry Dexie — vista cross-runtime unificata.
+@router.get('/api/agent/skill-stats/{session_id}')
+async def get_skill_stats(session_id: str):
+    """Success/fail rate + Wilson score per ogni tool nella sessione.
+
+    Il frontend usa questa API per arricchire i dati Dexie di skillRegistry.ts
+    con le stats backend: confidence reale (server-side) vs contatori browser-only.
+    """
+    try:
+        from agents.skill_tracker import get_skill_tracker
+        return {
+            "session_id": session_id,
+            "stats":      get_skill_tracker().get_stats(session_id),
+        }
+    except Exception as exc:
+        return {"session_id": session_id, "stats": {}, "error": str(exc)}
+
+
+@router.get('/api/agent/skill-stats')
+async def list_all_skill_sessions():
+    """Debug: panoramica di tutte le sessioni SkillTracker attive (tool count, call count)."""
+    try:
+        from agents.skill_tracker import get_skill_tracker
+        return get_skill_tracker().get_all_sessions()
+    except Exception as exc:
+        return {"error": str(exc)}
+
+# ── /api/agent/circuit-status/{session_id} — circuit breaker live status ──────
+# Espone per ogni tool tracciato in sessione: stato circuito, Wilson score,
+# recovery calls effettuate — utile per debug e monitoring real-time.
+@router.get('/api/agent/circuit-status/{session_id}')
+async def get_circuit_status(session_id: str):
+    """
+    Stato real-time del circuit breaker per ogni tool di una sessione.
+
+    Per ogni tool tracciato, classifica il circuito come:
+      - open   → Wilson score < 0.15 AND total_count >= 3 AND tool ha fallback
+                 (il tool viene bypassato — routing automatico ai fallback)
+      - closed → performance sufficiente o dati insufficienti per aprire il circuit
+
+    Campi per tool:
+      wilson_score:     lower bound dell'intervallo di confidenza al 95% (0–1)
+      success_count:    successi registrati nella sessione
+      fail_count:       fallimenti registrati nella sessione
+      total_count:      chiamate totali
+      success_rate:     raw rate (NON usato dal circuit — solo informativo)
+      avg_latency_ms:   latenza media (ms)
+      has_fallbacks:    True se TOOL_REGISTRY definisce fallback per il tool
+      recovery_calls:   quante volte il recovery credit ha concesso un tentativo
+      circuit_state:    "open" | "closed" | "no_data" | "insufficient_data"
+
+    Thresholds (from executor.py):
+      circuit_open_threshold: 0.15   (Wilson score sotto cui il circuit si apre)
+      min_calls_for_circuit:  3      (chiamate minime prima che il circuit possa aprirsi)
+      recovery_interval:      5      (ogni N call con circuit open → recovery attempt)
+    """
+    try:
+        from agents.skill_tracker import get_skill_tracker
+        from tools.registry import TOOL_REGISTRY
+        from api.state import _get_executor
+        from agents.executor import (
+            _CIRCUIT_OPEN_THRESHOLD,
+            _MIN_CALLS_FOR_CIRCUIT,
+            _RECOVERY_INTERVAL,
+        )
+
+        stats = get_skill_tracker().get_stats(session_id)
+
+        # Recovery counts vivono nell'istanza Executor singleton
+        executor    = _get_executor()
+        rec_counts: dict = {}
+        if executor is not None:
+            rec_counts = getattr(executor, '_circuit_recovery_counts', {})
+
+        circuits_open: list[dict]   = []
+        circuits_closed: list[dict] = []
+
+        for tool_name, s in stats.items():
+            has_fallbacks = bool(TOOL_REGISTRY.get(tool_name, {}).get('fallbacks'))
+            recovery_calls = rec_counts.get(tool_name, 0)
+
+            # Replica logica _is_circuit_open() di executor.py
+            if s['total_count'] == 0:
+                state = 'no_data'
+            elif s['total_count'] < _MIN_CALLS_FOR_CIRCUIT:
+                state = 'insufficient_data'
+            elif s['wilson_score'] < _CIRCUIT_OPEN_THRESHOLD and has_fallbacks:
+                state = 'open'
+            else:
+                state = 'closed'
+
+            entry = {
+                'tool':            tool_name,
+                'circuit_state':   state,
+                'wilson_score':    s['wilson_score'],
+                'success_count':   s['success_count'],
+                'fail_count':      s['fail_count'],
+                'total_count':     s['total_count'],
+                'success_rate':    s['success_rate'],
+                'avg_latency_ms':  s['avg_latency_ms'],
+                'has_fallbacks':   has_fallbacks,
+                'recovery_calls':  recovery_calls,
+            }
+            if state == 'open':
+                circuits_open.append(entry)
+            else:
+                circuits_closed.append(entry)
+
+        # Ordina open per Wilson score asc (peggiori prima), closed per desc (migliori prima)
+        circuits_open.sort(key=lambda x: x['wilson_score'])
+        circuits_closed.sort(key=lambda x: x['wilson_score'], reverse=True)
+
+        return {
+            'session_id':            session_id,
+            'total_tools_tracked':   len(stats),
+            'circuits_open_count':   len(circuits_open),
+            'circuits_closed_count': len(circuits_closed),
+            'circuits_open':         circuits_open,
+            'circuits_closed':       circuits_closed,
+            'thresholds': {
+                'circuit_open_threshold': _CIRCUIT_OPEN_THRESHOLD,
+                'min_calls_for_circuit':  _MIN_CALLS_FOR_CIRCUIT,
+                'recovery_interval':      _RECOVERY_INTERVAL,
+            },
+        }
+    except Exception as exc:
+        return {
+            'session_id':          session_id,
+            'total_tools_tracked': 0,
+            'circuits_open_count': 0,
+            'circuits_open':       [],
+            'circuits_closed':     [],
+            'error':               str(exc),
+        }
+

api/agent_fsm.py

@@ -0,0 +1,375 @@
+"""
+backend/api/agent_fsm.py — AgentLoop come Macchina a Stati (ARCH-I4.5)
+
+Rifactorizza il flusso dell'AgentLoop come FSM (Finite State Machine) esplicita.
+Stati: IDLE → PLAN → THINK → TOOL → WAIT → OBSERVE → DECIDE → DONE | FAILED
+
+Vantaggi rispetto all'implementazione implicita in agent.py:
+  - Testabilità: ogni transizione è una funzione pura
+  - Osservabilità: stato corrente sempre visibile via API
+  - Idempotenza: ogni stato ha guard di entry/exit
+  - Debuggabilità: history completa delle transizioni
+
+Integrazione con agent.py:
+  - AgentFSM NON sostituisce agent.py (troppo rischio regressione)
+  - Viene usato come orchestratore esterno per nuovi task creati via Kernel
+  - agent.py esistente continua a funzionare invariato
+
+ADR: S10 S16 S21 S27
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+import uuid
+from enum import Enum
+from typing import Any, Callable, Coroutine
+
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel, Field
+
+from .auth_guard import AuthRole, require_role
+
+_logger = logging.getLogger("api.agent_fsm")
+
+# ── Guards ──────────────────────────────────────────────────────────────────────
+try:
+    from .brain_planner import planner as _planner, PlanRequest as _PlanReq
+    _PLANNER_AVAILABLE = True
+except Exception:
+    _planner = None; _PlanReq = None; _PLANNER_AVAILABLE = False  # type: ignore
+
+try:
+    from .tool_engine import tool_executor as _tool_exec, ToolExecuteRequest as _TExecReq
+    _TOOL_ENGINE_AVAILABLE = True
+except Exception:
+    _tool_exec = None; _TExecReq = None; _TOOL_ENGINE_AVAILABLE = False  # type: ignore
+
+try:
+    from .kernel import kernel as _kernel
+    _KERNEL_AVAILABLE = True
+except Exception:
+    _kernel = None; _KERNEL_AVAILABLE = False  # type: ignore
+
+# ── States ──────────────────────────────────────────────────────────────────────
+
+class AgentState(str, Enum):
+    IDLE    = "idle"      # in attesa di un goal
+    PLAN    = "plan"      # BrainPlanner genera WorkflowPlan
+    THINK   = "think"     # LLM reasoning: analisi contesto, scelta prossimo tool
+    TOOL    = "tool"      # esecuzione tool via ToolEngine
+    WAIT    = "wait"      # attesa risultato asincrono (polling)
+    OBSERVE = "observe"   # elaborazione risultato tool, aggiornamento contesto
+    DECIDE  = "decide"    # decide se DONE, se re-THINK, o se FAILED
+    DONE    = "done"      # goal raggiunto
+    FAILED  = "failed"    # errore non recuperabile
+
+# Transizioni valide: stato → [stati raggiungibili]
+_TRANSITIONS: dict[AgentState, list[AgentState]] = {
+    AgentState.IDLE:    [AgentState.PLAN],
+    AgentState.PLAN:    [AgentState.THINK, AgentState.FAILED],
+    AgentState.THINK:   [AgentState.TOOL, AgentState.DECIDE, AgentState.FAILED],
+    AgentState.TOOL:    [AgentState.WAIT, AgentState.OBSERVE, AgentState.FAILED],
+    AgentState.WAIT:    [AgentState.OBSERVE, AgentState.FAILED],
+    AgentState.OBSERVE: [AgentState.DECIDE, AgentState.FAILED],
+    AgentState.DECIDE:  [AgentState.THINK, AgentState.DONE, AgentState.FAILED],
+    AgentState.DONE:    [],
+    AgentState.FAILED:  [],
+}
+
+# ── Models ──────────────────────────────────────────────────────────────────────
+
+class StateTransition(BaseModel):
+    from_state:  AgentState
+    to_state:    AgentState
+    reason:      str           = ""
+    ts:          float         = Field(default_factory=time.time)
+    metadata:    dict[str, Any] = Field(default_factory=dict)
+
+
+class AgentContext(BaseModel):
+    """Contesto condiviso tra tutti gli stati della FSM."""
+    session_id:     str            = Field(default_factory=lambda: str(uuid.uuid4()))
+    goal:           str            = ""
+    plan_id:        str | None     = None
+    messages:       list[dict]     = Field(default_factory=list)
+    tool_results:   list[dict]     = Field(default_factory=list)
+    current_step:   int            = 0
+    max_steps:      int            = 10
+    last_tool:      str | None     = None
+    last_result:    Any            = None
+    error:          str | None     = None
+    metadata:       dict[str, Any] = Field(default_factory=dict)
+
+
+class FSMRunRequest(BaseModel):
+    goal:           str
+    session_id:     str | None     = None
+    max_steps:      int            = 10
+    hints:          list[str]      = Field(default_factory=list,
+                                           description="Capability/tool suggeriti")
+    correlation_id: str            = Field(default_factory=lambda: str(uuid.uuid4()))
+
+
+class FSMStatus(BaseModel):
+    fsm_id:      str
+    state:       AgentState
+    context:     AgentContext
+    history:     list[StateTransition]
+    started_at:  float
+    updated_at:  float
+    done:        bool
+
+
+# ── AgentFSM ────────────────────────────────────────────────────────────────────
+
+class AgentFSM:
+    """
+    Istanza di FSM per un singolo run dell'agente.
+    Ogni run ha il proprio fsm_id, contesto e history.
+    """
+
+    def __init__(self, fsm_id: str, goal: str, max_steps: int = 10,
+                 hints: list[str] | None = None) -> None:
+        self.fsm_id     = fsm_id
+        self.state      = AgentState.IDLE
+        self.context    = AgentContext(goal=goal, max_steps=max_steps,
+                                       metadata={"hints": hints or []})
+        self.history:   list[StateTransition] = []
+        self.started_at = time.time()
+        self.updated_at = time.time()
+
+    def can_transition(self, to: AgentState) -> bool:
+        return to in _TRANSITIONS.get(self.state, [])
+
+    def transition(self, to: AgentState, reason: str = "", metadata: dict | None = None) -> None:
+        if not self.can_transition(to):
+            raise ValueError(f"Transizione non valida: {self.state} → {to}")
+        t = StateTransition(from_state=self.state, to_state=to,
+                            reason=reason, metadata=metadata or {})
+        self.history.append(t)
+        _logger.debug("[fsm:%s] %s → %s (%s)", self.fsm_id, self.state.value, to.value, reason)
+        self.state      = to
+        self.updated_at = time.time()
+
+    @property
+    def done(self) -> bool:
+        return self.state in (AgentState.DONE, AgentState.FAILED)
+
+    def to_status(self) -> FSMStatus:
+        return FSMStatus(
+            fsm_id=self.fsm_id, state=self.state, context=self.context,
+            history=self.history, started_at=self.started_at,
+            updated_at=self.updated_at, done=self.done)
+
+
+# ── AgentFSMRunner ──────────────────────────────────────────────────────────────
+
+class AgentFSMRunner:
+    """
+    Esegue la FSM step-by-step.
+    Ogni stato chiama il componente appropriato (Planner, LLM, ToolEngine).
+    """
+
+    async def run(self, fsm: AgentFSM) -> FSMStatus:
+        """Esegue la FSM fino a DONE o FAILED."""
+        try:
+            # IDLE → PLAN
+            fsm.transition(AgentState.PLAN, "starting run")
+            await self._state_plan(fsm)
+
+            while not fsm.done:
+                if fsm.context.current_step >= fsm.context.max_steps:
+                    fsm.transition(AgentState.FAILED, f"max_steps={fsm.context.max_steps} raggiunto")
+                    break
+
+                if fsm.state == AgentState.THINK:
+                    await self._state_think(fsm)
+                elif fsm.state == AgentState.TOOL:
+                    await self._state_tool(fsm)
+                elif fsm.state == AgentState.WAIT:
+                    await self._state_wait(fsm)
+                elif fsm.state == AgentState.OBSERVE:
+                    await self._state_observe(fsm)
+                elif fsm.state == AgentState.DECIDE:
+                    await self._state_decide(fsm)
+                else:
+                    fsm.transition(AgentState.FAILED, f"stato sconosciuto: {fsm.state}")
+                    break
+        except Exception as exc:
+            _logger.error("[fsm:%s] unhandled error: %s", fsm.fsm_id, exc)
+            if not fsm.done:
+                fsm.context.error = str(exc)
+                try:
+                    fsm.transition(AgentState.FAILED, f"unhandled: {exc}")
+                except Exception as _te:
+                    _logger.debug("[fsm:%s] transition→FAILED fallito: %s", fsm.fsm_id, _te)
+        return fsm.to_status()
+
+    async def _state_plan(self, fsm: AgentFSM) -> None:
+        """PLAN: chiama BrainPlanner per generare il piano."""
+        if _PLANNER_AVAILABLE and _planner is not None and _PlanReq is not None:
+            try:
+                plan = await _planner.plan(_PlanReq(
+                    goal   = fsm.context.goal,
+                    hints  = fsm.context.metadata.get("hints", []),
+                    max_steps = fsm.context.max_steps,
+                ))
+                fsm.context.plan_id = plan.plan_id
+                # Carica capabilities come "tool queue" nel contesto
+                fsm.context.metadata["tool_queue"] = [
+                    {"capability": s.capability, "payload": s.payload, "step_id": s.step_id}
+                    for s in plan.steps
+                ]
+                fsm.transition(AgentState.THINK, f"piano generato: {len(plan.steps)} step")
+                return
+            except Exception as exc:
+                _logger.warning("[fsm:%s] planner error: %s", fsm.fsm_id, exc)
+        # Fallback: THINK diretto senza piano
+        fsm.transition(AgentState.THINK, "planner non disponibile, THINK diretto")
+
+    async def _state_think(self, fsm: AgentFSM) -> None:
+        """THINK: seleziona il prossimo tool da eseguire."""
+        tool_queue = fsm.context.metadata.get("tool_queue", [])
+        if not tool_queue:
+            fsm.transition(AgentState.DECIDE, "tool queue vuota → DECIDE")
+            return
+        next_tool = tool_queue.pop(0)
+        fsm.context.metadata["current_tool"] = next_tool
+        fsm.context.last_tool = next_tool.get("capability")
+        fsm.context.current_step += 1
+        fsm.transition(AgentState.TOOL, f"eseguo tool: {next_tool.get('capability')}")
+
+    async def _state_tool(self, fsm: AgentFSM) -> None:
+        """TOOL: esegui il tool selezionato in THINK."""
+        current = fsm.context.metadata.get("current_tool", {})
+        cap     = current.get("capability", "llm")
+        payload = current.get("payload", {})
+
+        if _TOOL_ENGINE_AVAILABLE and _tool_exec is not None and _TExecReq is not None:
+            try:
+                result = await _tool_exec.execute(_TExecReq(
+                    tool_name = cap, payload = payload,
+                    correlation_id = fsm.fsm_id,
+                ))
+                fsm.context.last_result = result.model_dump()
+                fsm.context.tool_results.append({"tool": cap, "result": fsm.context.last_result})
+                fsm.transition(AgentState.OBSERVE, f"tool {cap} eseguito: {result.status}")
+                return
+            except Exception as exc:
+                fsm.context.error = str(exc)
+                _logger.warning("[fsm:%s] tool %s error: %s", fsm.fsm_id, cap, exc)
+        # Fallback: submit via Kernel
+        if _KERNEL_AVAILABLE and _kernel is not None:
+            result = await _kernel.submit_task({"capability": cap, **payload})
+            fsm.context.last_result = result.model_dump() if hasattr(result, "model_dump") else str(result)
+            fsm.context.tool_results.append({"tool": cap, "result": fsm.context.last_result})
+            fsm.transition(AgentState.OBSERVE, f"kernel submit: {cap}")
+        else:
+            fsm.transition(AgentState.OBSERVE, f"tool {cap} skipped (no executor)")
+
+    async def _state_wait(self, fsm: AgentFSM) -> None:
+        """WAIT: attende risultato asincrono (polling con backoff)."""
+        await asyncio.sleep(1)
+        fsm.transition(AgentState.OBSERVE, "wait complete")
+
+    async def _state_observe(self, fsm: AgentFSM) -> None:
+        """OBSERVE: elabora risultato, aggiorna messages."""
+        result = fsm.context.last_result
+        if result:
+            fsm.context.messages.append({
+                "role": "tool", "content": str(result)[:2000],  # truncate
+                "tool": fsm.context.last_tool,
+            })
+        fsm.transition(AgentState.DECIDE, "osservazione completata")
+
+    async def _state_decide(self, fsm: AgentFSM) -> None:
+        """DECIDE: goal raggiunto? Continua o termina."""
+        tool_queue = fsm.context.metadata.get("tool_queue", [])
+        if tool_queue:
+            fsm.transition(AgentState.THINK, f"coda non vuota: {len(tool_queue)} step rimanenti")
+        elif fsm.context.error:
+            fsm.transition(AgentState.FAILED, fsm.context.error)
+        else:
+            fsm.transition(AgentState.DONE, "tutti gli step completati")
+
+
+# ── AgentFSMManager (registry delle FSM attive) ─────────────────────────────────
+
+class AgentFSMManager:
+    def __init__(self) -> None:
+        self._instances: dict[str, AgentFSM]   = {}
+        self._runner     = AgentFSMRunner()
+        self._tasks:     dict[str, asyncio.Task] = {}
+        self._lock       = asyncio.Lock()
+        self._MAX_STORE  = 200
+
+    async def start(self, req: FSMRunRequest) -> FSMStatus:
+        fsm_id = str(uuid.uuid4())
+        fsm    = AgentFSM(fsm_id, req.goal, req.max_steps, req.hints)
+        if req.session_id:
+            fsm.context.session_id = req.session_id
+        async with self._lock:
+            self._instances[fsm_id] = fsm
+            if len(self._instances) > self._MAX_STORE:
+                oldest = sorted(self._instances, key=lambda k: self._instances[k].started_at)
+                for k in oldest[:10]:
+                    self._instances.pop(k, None)
+
+        task = asyncio.create_task(self._runner.run(fsm))
+        self._tasks[fsm_id] = task
+        _logger.info("[fsm-manager] started fsm_id=%s goal=%s", fsm_id, req.goal[:60])
+        return fsm.to_status()
+
+    def get(self, fsm_id: str) -> FSMStatus | None:
+        fsm = self._instances.get(fsm_id)
+        return fsm.to_status() if fsm else None
+
+    def list_active(self, limit: int = 20) -> list[FSMStatus]:
+        all_fsm = sorted(self._instances.values(), key=lambda f: f.started_at, reverse=True)
+        return [f.to_status() for f in all_fsm[:limit]]
+
+    def status(self) -> dict:
+        instances = list(self._instances.values())
+        return {
+            "total": len(instances),
+            "running": sum(1 for f in instances if not f.done),
+            "done":    sum(1 for f in instances if f.state == AgentState.DONE),
+            "failed":  sum(1 for f in instances if f.state == AgentState.FAILED),
+        }
+
+
+# ── Singletons ──────────────────────────────────────────────────────────────────
+fsm_manager = AgentFSMManager()
+
+# ── HTTP Router ──────────────────────────────────────────────────────────────────
+router = APIRouter(
+    prefix="/api/agent-fsm",
+    tags=["agent-fsm"],
+    dependencies=[Depends(require_role(AuthRole.MACHINE))],
+)
+
+
+@router.post("/run", summary="Avvia un AgentFSM run (goal → DONE|FAILED in background)")
+async def route_run(req: FSMRunRequest) -> FSMStatus:
+    return await fsm_manager.start(req)
+
+
+@router.get("/runs/{fsm_id}", summary="Stato di un AgentFSM run")
+async def route_get(fsm_id: str) -> FSMStatus:
+    status = fsm_manager.get(fsm_id)
+    if not status:
+        raise HTTPException(404, f"FSM '{fsm_id}' non trovata")
+    return status
+
+
+@router.get("/runs", summary="Lista AgentFSM runs attivi")
+async def route_list(limit: int = 20) -> dict:
+    runs = fsm_manager.list_active(limit)
+    return {"count": len(runs), "runs": [r.model_dump() for r in runs]}
+
+
+@router.get("/status", summary="Stato aggregato AgentFSM manager")
+async def route_status() -> dict:
+    return fsm_manager.status()

api/agent_loop_routes.py

@@ -0,0 +1,410 @@
+"""agent_loop_routes.py — Route SSE legacy, persona helpers, reason/unified/loop, agent-kernel.
+
+Estratto da agent.py (split 2026-06-30).
+Route coperte:
+  POST /run_loop                  (deprecated 410)
+  POST /api/agent/run-stream      (SSE legacy loop)
+  POST /api/reason/loop
+  POST /api/unified/loop
+  GET  /api/agent-kernel/status
+  POST /api/agent-kernel/dispatch
+"""
+from __future__ import annotations
+import os, asyncio, json, uuid, time, re
+import re as _re_persona
+from fastapi import APIRouter, HTTPException, Request, Body
+router = APIRouter()
+from fastapi.responses import StreamingResponse
+from pydantic import BaseModel, field_validator
+from typing import Literal
+from .state import (
+    _agent_tasks, _task_checkpoints, _loop_registry, _run_stream_tasks,
+    _prune_agent_tasks, _prune_checkpoints, _prune_loop_registry,
+    _get_mem_manager, _get_mem_manager_async, _get_executor, _get_planner, _get_ai_client,
+    ReasonLoopIn, AgentTaskIn,
+    write_ahead_task_created,
+)
+from .speculative import fire_speculative_tools
+try:
+    from .quality_guardian import run_quality_check as _run_quality_check
+except Exception as _qg_err:
+    import logging as _qg_log; _qg_log.getLogger(__name__).warning("[routes] quality_guardian import failed: %s", _qg_err)
+    _run_quality_check = None
+import logging
+_logger = logging.getLogger("api.agent")
+from .persistence import (
+    sb_upsert_task, sb_update_status, sb_append_event,
+    sb_restore_task, sb_get_events, sb_delete_task_events,
+    sb_list_tasks, sb_save_checkpoint, sb_get_checkpoint,
+    sb_restore_handoff_context, sb_upsert_handoff, sb_delete_handoff,
+)
+from ._agent_helpers import (
+    _RE_SURROGATES, _ss, _log_task_exc,
+    _PERSONA_KEYWORD_MAP, _PERSONA_CLIENT_CACHE,
+    _build_persona_kw_map, _classify_persona_server, _get_persona_llm_client,
+)
+async def run_loop_removed():
+    """S352: endpoint rimosso. Usare POST /api/agent/tasks + GET /api/agent/tasks/{id}/stream."""
+    raise HTTPException(
+        status_code=410,
+        detail={
+            "error": "Gone",
+            "message": "Endpoint rimosso. Usare POST /api/agent/tasks + GET /api/agent/tasks/{id}/stream",
+            "migration": "/api/agent/tasks",
+        },
+    )
+
+
+# ── SSE run-stream ────────────────────────────────────────────────────────────
+
+@router.post('/api/agent/run-stream')
+async def agent_run_stream(body: ReasonLoopIn, request: Request):
+    # S-BENCH: auth guard — consistente con /api/exec e /api/execute-shell
+    _itok = os.getenv('INTERNAL_TOKEN', '')
+    if _itok and request.headers.get('X-Internal-Token') != _itok:
+        raise HTTPException(401, 'Unauthorized')
+    async def generate():
+        queue: asyncio.Queue = asyncio.Queue()
+
+        async def step_cb(step: dict) -> None:
+            await queue.put(step)
+
+        async def run_loop() -> None:
+            try:
+                from agents.unified_loop import UnifiedAgentLoop
+                # S388: usa singleton _get_ai_client() — nessuna re-istanziazione OpenAI() per request
+                client = _get_ai_client()
+                try:
+                    from agents.critic import Critic
+                    from agents.response_verifier import ResponseVerifier
+                    _critic   = Critic(llm_client=client)
+                    _verifier = ResponseVerifier()
+                except Exception as _cv_err:
+                    _logger.warning("[routes] Critic/Verifier init failed: %s", _cv_err)
+                    _critic   = None
+                    _verifier = None
+                # Resume automatico: inietta contesto checkpoint se disponibile (Case 2.5 fall-through)
+                _resume_ctx = getattr(body, '_resume_context', None)
+                _resume_max = getattr(body, '_resume_max_steps', None) or body.max_steps
+                context_str = '\n'.join(m.get('content', '') for m in body.context) if body.context else ''
+                # Bug-5-FIX: resume context iniettato DOPO che context_str è definito (era NameError)
+                if _resume_ctx:
+                    context_str = f"[RIPRESA AUTOMATICA]\n{_resume_ctx}\n\n{context_str}".strip()
+
+                loop = UnifiedAgentLoop(
+                    llm_client=client, critic=_critic, verifier=_verifier,
+                    memory=await _get_mem_manager_async(), executor=_get_executor(), planner=_get_planner(),
+                )
+                # S456-X5: prepend project context (projectMemory.getContext() dal frontend)
+                if body.project_context:
+                    context_str = f"[PROGETTO CORRENTE]\n{body.project_context}\n\n{context_str}".strip()
+                # S456-X4: inject top failure patterns appresi dal selfLearning frontend
+                if body.learning_hints:
+                    # S591: learning_hints[:3]→[:5] — più pattern appresi nel context
+                    hints_str = "\n".join(f"- {h}" for h in body.learning_hints[:5])
+                    context_str = f"{context_str}\n\n[PATTERN DI ERRORE APPRESI]\n{hints_str}".strip()
+                # P35: vincoli negativi dal frontend (agentConstraints.ts → VFS /.agent/constraints.json)
+                _neg_c = getattr(body, 'negative_constraints', '') or ''
+                if _neg_c:
+                    context_str = f"[VINCOLI OPERATIVI APPRESI — NON VIOLARE]\n{_neg_c}\n\n{context_str}".strip()
+                result = await loop.run(
+                    goal=body.goal, context=context_str,
+                    max_steps=body.max_steps, on_step=step_cb,
+                    session_id=getattr(body, "session_id", "") or "",
+                )
+                await queue.put({
+                    '__done__': True,
+                    'result':   result.get('output',  ''),
+                    'engine':   result.get('engine',  'fallback'),
+                    'success':  result.get('success', False),
+                })
+            except Exception as exc:
+                # GAP-A1: log incident in registry (fire-and-forget, non-blocking)
+                try:
+                    from api.incident_registry import log_incident as _log_inc
+                    asyncio.create_task(_log_inc(
+                        task_id=body.goal[:32].replace(' ', '_'),
+                        goal=body.goal, error=str(exc), source="agent",
+                    )).add_done_callback(_log_task_exc)
+                except Exception as _exc:
+                    _logger.debug("[agent] silenced %s", type(_exc).__name__)  # noqa: BLE001
+                await queue.put({'__error__': str(exc)})
+
+        task    = asyncio.create_task(run_loop())
+        task_id = body.goal[:32].replace(' ', '_')
+        # ABORT-1: registra task + queue per permettere cancellazione via POST /api/agent/abort
+        _run_stream_tasks[task_id] = {"task": task, "queue": queue}
+        yield "retry: 3000\n\n"
+        yield f"data: {json.dumps({'type': 'task_start', 'taskId': task_id})}\n\n"
+
+        # S386: fast-fail — se tutti i provider sono down (heartbeat lo sa già),
+        # non aspettare 120s di tentativi: rispondi subito con errore chiaro.
+        try:
+            from api.state import _heartbeat_state
+            _providers = _heartbeat_state.get("providers", [])
+            if _providers and not any(p.get("ok") for p in _providers):
+                task.cancel()
+                _names = ", ".join(p["name"] for p in _providers)
+                yield f"data: {json.dumps({'type': 'task_aborted', 'taskId': task_id, 'abort_reason': 'system', 'abort_source': 'no_providers', 'error': f'Nessun provider AI disponibile ({_names})'})}\n\n"  # MX18-ABORT: no providers → system abort
+                yield "data: [DONE]\n\n"
+                return
+        except Exception as _hb_err:
+            _logger.debug("[routes] heartbeat skip silenced: %s", type(_hb_err).__name__)  # non inizializzato, prosegui normalmente
+
+        # S386: timeout ridotto 120→60s — risposta entro 1 minuto o errore esplicito
+        timeout_secs    = float(os.getenv('AGENT_STREAM_TIMEOUT', '60'))
+        heartbeat_secs  = 15.0
+        elapsed         = 0.0
+        try:
+            while True:
+                try:
+                    item    = await asyncio.wait_for(queue.get(), timeout=heartbeat_secs)
+                    elapsed = 0.0
+                except asyncio.TimeoutError:
+                    elapsed += heartbeat_secs
+                    if elapsed >= timeout_secs:
+                        yield f"data: {json.dumps({'type': 'task_aborted', 'taskId': task_id, 'abort_reason': 'timeout', 'abort_source': 'stream_timeout'})}\n\n"  # MX18-ABORT: timeout → task_aborted
+                        break
+                    yield 'data: {"type":"ping"}\n\n'
+                    continue
+                # ABORT-2: segnale abort dall'endpoint POST /api/agent/abort
+                if "__abort__" in item:
+                    _ar  = item.get('abort_reason', 'user_stop')   # MX18-ABORT: dynamic reason
+                    _src = item.get('abort_source', 'backend_abort_queue')
+                    yield f"data: {json.dumps({'type': 'task_aborted', 'taskId': task_id, 'abort_reason': _ar, 'abort_source': _src})}\n\n"  # MX16+MX18-ABORT
+                    break
+                if '__error__' in item:
+                    yield f"data: {json.dumps({'type': 'task_error', 'taskId': task_id, 'error': _ss(item['__error__'])})}\n\n"
+                    break
+                # S420: streaming token — emetti subito al frontend senza accumulare
+                if item.get('action') == 'text_chunk':
+                    yield f"data: {json.dumps({'type': 'text_chunk', 'token': _ss(item.get('token', '')), 'taskId': task_id})}\n\n"
+                    continue
+                # S758-P4.1: tool_use — chip pre-esecuzione (agent_run_stream path)
+                _rs_act = item.get('action', '')
+                _rs_st  = item.get('status', '')
+                if ((_rs_act == 'tool_start' and _rs_st == 'running') or
+                        (_rs_act.startswith('executor:') and _rs_st == 'started')):
+                    _rs_tool = _rs_act.replace('executor:', '') if _rs_act.startswith('executor:') else _rs_act
+                    yield f"data: {json.dumps({'type': 'tool_use', 'taskId': task_id, 'tool': _rs_tool, 'name': _rs_tool, 'label': item.get('title', _rs_tool.replace('_', ' ').capitalize())})}\n\n"
+                if '__done__' in item:
+                    yield f"data: {json.dumps({'type': 'task_done', 'taskId': task_id, 'result': _ss(item['result']), 'engine': item['engine'], 'success': item['success']})}\n\n"
+                    break
+                # S393 Priority 1: Narrative Streaming — arricchisce step_done con explanation
+                _NARR_QUICK = {
+                    'llm': 'Elaborazione risposta AI',
+                    'direct_tools': 'Strumenti diretti',
+                    'web_search': 'Ricerca web', 'get_weather': 'Dati meteo',
+                    'read_page': 'Lettura pagina', 'calculate': 'Calcolo matematico',
+                    'generate_image': 'Generazione immagine AI',
+                    'execution_validator_fix': 'Auto-correzione codice (S393)',
+                    'tool_governor_skip': 'Tool già eseguito — risultato riutilizzato',
+                    # S661: label narrative per tool aggiunti in S648-S659 — prima usavano
+                    # _act_q.replace('_',' ').capitalize() → "Apply patch", "Call api" (generico)
+                    'apply_patch':   'Applico patch al file…',
+                    'call_api':      'Chiamo API REST…',
+                    'send_email':    'Invio email…',
+                    'create_pdf':    'Genero documento PDF…',
+                    'web_research':  'Ricerca multi-fonte…',
+                    'write_file':    'Scrivo file…',
+                    'read_file':     'Leggo file…',
+                    'execute_shell': 'Eseguo comando shell…',
+                    'analyze_image': 'Analizzo immagine…',
+                    'run_python':    'Eseguo Python (Pyodide)…',
+                    # S-GAP1: narrative fasi strategiche
+                    'plan':             'Analizzo la richiesta e preparo un piano di esecuzione…',
+                    'reflective_debug': 'Ho incontrato un ostacolo — ricalcolo una strategia più efficiente…',
+                    'fallback':         'Adotto un approccio alternativo per completare il task…',
+                    'smolagents':       'Orchestro gli strumenti necessari…',
+                }
+                _act_q = item.get('action', '')
+                if 'explanation' not in item:
+                    item['explanation'] = _NARR_QUICK.get(_act_q, _act_q.replace('_', ' ').capitalize())
+                if 'title' not in item:
+                    item['title'] = item['explanation']
+
+                # S403: SSE Visibility Guard — classifica ogni step event:
+                # "internal"  → mai visibile (pipeline internals: planner, llm, reflection)
+                # "progress"  → visibile come progress card (tool reali, auto-fix)
+                # "debug"     → visibile solo in dev mode (direct_tools, fast_path)
+                # Il frontend filtra per visibility — solo "progress" mostrato all'utente.
+                _STEP_VISIBILITY: dict[str, str] = {
+                    # Internal pipeline — never shown to user
+                    'plan':              'progress',   # S-GAP1
+                    'llm':               'internal',
+                    'smolagents':        'internal',
+                    'fallback':          'progress',   # S-GAP1
+                    'reflective_debug':  'progress',   # S-GAP1
+                    'fast_path':         'internal',
+                    'executor':          'internal',
+                    # Progress — shown as step cards (user-visible)
+                    'tool_start':              'progress',
+                    'execution_validator_fix': 'progress',
+                    'goal_verifier':           'progress',
+                    'web_search':              'progress',
+                    'get_weather':             'progress',
+                    'read_page':               'progress',
+                    'calculate':               'progress',
+                    'generate_image':          'progress',
+                    'run_python':              'progress',
+                    'tool_governor_skip':      'progress',
+                    # S660: tool aggiunti in S648-S659 mancanti da _STEP_VISIBILITY →
+                    # fallback rule: _act_q.startswith('tool_') era False per questi →
+                    # classificati 'debug' → nascosti all'utente durante esecuzione.
+                    'apply_patch':   'progress',
+                    'call_api':      'progress',
+                    'send_email':    'progress',
+                    'create_pdf':    'progress',
+                    'web_research':  'progress',
+                    'write_file':    'progress',
+                    'read_file':     'progress',
+                    'execute_shell': 'progress',
+                    'analyze_image': 'progress',
+                    # Debug — shown only when devMode active
+                    'direct_tools':     'debug',
+                    # S-LOOP2: fase esecuzione avanzata — visibili come progress card
+                    'reasoning_core':    'progress',  # S-LOOP2: ReasoningCore multi-step
+                    'browser_verifier':  'progress',  # S-LOOP2: Browser Goal Verification live
+                }
+                # Fallback: azioni sconosciute con "tool_" prefix → progress; resto → debug
+                _vis = _STEP_VISIBILITY.get(_act_q)
+                if _vis is None:
+                    _vis = 'progress' if _act_q.startswith('tool_') or _act_q.startswith('executor:') else 'debug'
+                item['visibility'] = _vis
+
+                yield f"data: {json.dumps({'type': 'step_done', 'step': item, 'taskId': task_id})}\n\n"
+        finally:
+            task.cancel()
+            # ABORT-3: cleanup registro — libera memoria e impedisce abort su task già terminati
+            _run_stream_tasks.pop(task_id, None)
+            yield "data: [DONE]\n\n"
+
+    return StreamingResponse(generate(), media_type="text/event-stream",
+        headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"})
+
+
+# ── Reason loop / Unified loop ─────────────────────────────────────────────────
+
+@router.post('/api/reason/loop')
+async def reason_loop(body: ReasonLoopIn):
+    try:
+        from agents.unified_loop import UnifiedAgentLoop
+        # S388: singleton — riusa il client già inizializzato
+        client = _get_ai_client()
+        try:
+            from agents.critic import Critic
+            from agents.response_verifier import ResponseVerifier
+            _critic   = Critic(llm_client=client)
+            _verifier = ResponseVerifier()
+        except Exception as _cv_err:
+            _logger.warning("[routes] Critic/Verifier init failed: %s", _cv_err)
+            _critic   = None
+            _verifier = None
+        loop = UnifiedAgentLoop(
+            llm_client=client, critic=_critic, verifier=_verifier,
+            memory=await _get_mem_manager_async(), executor=_get_executor(), planner=_get_planner(),
+        )
+        context_str = '\n'.join(m.get('content', '') for m in body.context) if body.context else ''
+        # N-2-FIX: accumula step intermedi tramite on_step — inclusi nel response JSON per debug frontend
+        _steps_log: list[dict] = []
+        async def _on_step(step_data: dict) -> None:
+            _steps_log.append({
+                'action': step_data.get('action', ''),
+                'output': str(step_data.get('output', ''))[:400],  # S577: 200→400
+            })
+        result = await loop.run(goal=body.goal, context=context_str, max_steps=body.max_steps, on_step=_on_step, session_id=getattr(body, "session_id", "") or "")
+        if isinstance(result, dict):
+            output_text = result.get('output', '') or result.get('answer', '') or ''
+            engine_used = result.get('engine', 'ambiguity-gate' if result.get('answer') else 'unknown')
+            errors_list = result.get('errors', [])
+        else:
+            output_text = str(result)
+            engine_used = 'unknown'
+            errors_list = []
+        return {
+            'ok':     bool(output_text and output_text.strip()),
+            'success': bool(output_text and output_text.strip()),  # alias compat frontend
+            'output':  output_text,                                  # alias compat frontend
+            'result': output_text,
+            'source': 'backend_loop',
+            'engine': engine_used,
+            'errors': errors_list,
+            'steps':  _steps_log,  # N-2-FIX: step intermedi per debug/telemetria frontend
+        }
+    except Exception as e:
+        _logger.error("[reason/loop] Error: %s", e)
+        return {
+            'ok':     False,
+            'result': f'Backend reasoning non disponibile: {e}. Il loop browser continua normalmente.',
+            'source': 'fallback',
+            'steps':  [],
+        }
+
+
+@router.post('/api/unified/loop')
+async def unified_loop(body: ReasonLoopIn):
+    """Alias di /api/reason/loop — compatibilità con tutte le versioni frontend."""
+    return await reason_loop(body)
+
+
+# ── Agent kernel ───────────────────────────────────────────────────────────────
+
+@router.get('/api/agent-kernel/status')
+async def agent_kernel_status():
+    gh_token = os.getenv('GITHUB_TOKEN') or os.getenv('GH_TOKEN', '')
+    return {
+        'dispatch_available': bool(gh_token),
+        'workflow_url': 'https://github.com/Baida98/AI/actions/workflows/agent-kernel.yml',
+        'mobile_url':   'https://github.com/Baida98/AI/actions',
+        'secrets_needed': ['OPENROUTER_API_KEY', 'GROQ_API_KEY', 'GEMINI_API_KEY', 'HF_TOKEN', 'NVIDIA_API_KEY'],
+        'usage': 'Vai su GitHub Actions → Agent Kernel — no PC → Run workflow → inserisci il goal',
+    }
+
+
+# S442-FIX3: modello Pydantic per agent_kernel_dispatch.
+# Prima: body: dict grezzo → mode non validato, goal controllato solo dopo estrazione.
+# Ora: validazione in ingresso → 422 chiaro invece di 500 a runtime.
+class AgentKernelDispatchIn(BaseModel):
+    goal: str
+    mode: Literal["plan", "execute", "analyze"] = "plan"
+
+    @field_validator('goal', mode='before')
+    @classmethod
+    def validate_goal(cls, v: object) -> str:
+        if not isinstance(v, str) or not str(v).strip():
+            raise ValueError('goal must be a non-empty string')
+        return str(v).strip()
+
+
+@router.post('/api/agent-kernel/dispatch')
+async def agent_kernel_dispatch(body: AgentKernelDispatchIn):
+    gh_token = os.getenv('GITHUB_TOKEN') or os.getenv('GH_TOKEN', '')
+    if not gh_token:
+        raise HTTPException(503, detail={
+            'error': 'no_github_token',
+            'message': 'GITHUB_TOKEN non configurato nel backend.',
+        })
+    goal = body.goal
+    mode = body.mode
+    import httpx as _httpx
+    try:
+        async with _httpx.AsyncClient(timeout=15) as _hc:
+            _resp = await _hc.post(
+                'https://api.github.com/repos/Baida98/AI/actions/workflows/agent-kernel.yml/dispatches',
+                json={'ref': 'main', 'inputs': {'goal': goal, 'mode': mode, 'commit_memory': 'true'}},
+                headers={
+                    'Authorization':       f'Bearer {gh_token}',
+                    'Accept':              'application/vnd.github+json',
+                    'X-GitHub-Api-Version': '2022-11-28',
+                },
+            )
+        if _resp.status_code >= 400:
+            raise HTTPException(_resp.status_code, detail=_resp.text[:500])
+        return {'ok': True, 'status': _resp.status_code, 'goal': goal, 'mode': mode}
+    except _httpx.HTTPError as e:
+        raise HTTPException(502, detail=str(e)[:500])
+
+
+# ── Agent tasks (FASE 2.1 + S359 persistence) ──────────────────────────────────
+
+

api/agent_task_routes.py

@@ -0,0 +1,800 @@
+"""agent_task_routes.py — Task CRUD: crea, lista, cancella, stato, stream SSE.
+
+Estratto da agent.py (split 2026-06-30).
+Route coperte:
+  POST   /api/agent/tasks
+  GET    /api/agent/tasks
+  DELETE /api/agent/tasks/{task_id}
+  GET    /api/agent/tasks/{task_id}/status
+  GET    /api/agent/tasks/{task_id}/stream   (SSE principale, S359 persist)
+"""
+from __future__ import annotations
+import os, asyncio, json, uuid, time, re
+import re as _re_persona
+from fastapi import APIRouter, HTTPException, Request, Body
+from fastapi.responses import StreamingResponse
+from pydantic import BaseModel, field_validator
+from typing import Literal
+from .state import (
+    _agent_tasks, _task_checkpoints, _loop_registry, _run_stream_tasks,
+    _prune_agent_tasks, _prune_checkpoints, _prune_loop_registry,
+    _get_mem_manager, _get_mem_manager_async, _get_executor, _get_planner, _get_ai_client,
+    ReasonLoopIn, AgentTaskIn,
+    write_ahead_task_created,
+)
+from .speculative import fire_speculative_tools
+from .prewarm import fire_predictive_prewarm  # S950
+try:
+    from .quality_guardian import run_quality_check as _run_quality_check
+except Exception:
+    _run_quality_check = None
+import logging
+_logger = logging.getLogger("api.agent")
+from .persistence import (
+    sb_upsert_task, sb_update_status, sb_append_event,
+    sb_restore_task, sb_get_events, sb_delete_task_events,
+    sb_list_tasks, sb_save_checkpoint, sb_get_checkpoint,
+    sb_restore_handoff_context, sb_upsert_handoff, sb_delete_handoff,
+)
+from ._agent_helpers import (
+    _RE_SURROGATES, _ss, _log_task_exc,
+    _PERSONA_KEYWORD_MAP, _PERSONA_CLIENT_CACHE,
+    _build_persona_kw_map, _classify_persona_server, _get_persona_llm_client,
+)
+router = APIRouter()
+
+@router.post('/api/agent/tasks')
+async def create_agent_task(body: AgentTaskIn):
+    """
+    Crea o recupera un task agent.
+
+    S359: se task_id non è in memoria ma esiste su Supabase (backend ha riavviato),
+    il task viene ripristinato dallo store persistente invece di essere riavviato.
+    Questo preserva lo stato SUCCESS/ERROR precedente senza sprecare token.
+    """
+    _prune_agent_tasks()
+    task_id = body.taskId or str(uuid.uuid4())
+
+    # Already in memory → return immediately (normal path, includes S358 reconnect)
+    if task_id in _agent_tasks:
+        return {'taskId': task_id, 'status': _agent_tasks[task_id]['status']}
+
+    # S359: try Supabase lazy restore (only hit network after backend restart)
+    restored = await sb_restore_task(task_id)
+    if restored:
+        # Put restored metadata back into memory so stream_agent_task can use it.
+        # Use context from the incoming request (not persisted to save space).
+        restored['context'] = body.context
+        _agent_tasks[task_id] = restored
+        return {'taskId': task_id, 'status': restored['status'], 'restored': True}
+
+    # Brand new task
+    created_at = int(time.time() * 1000)
+    _agent_tasks[task_id] = {
+        'id':              task_id,
+        'status':          'QUEUED',
+        'goal':            body.goal,
+        'context':         body.context,
+        'max_steps':       body.max_steps,
+        'created_at':      created_at,
+        'project_context':   body.project_context,  # S456-X5
+        'learning_hints':    body.learning_hints,   # S456-X4
+        'resume_from_step':  body.resume_from_step, # P16-F3: passo resume dalla coda
+        'persona':           body.persona,           # P17-F5: expertise persona hint
+        'session_id':        body.session_id or '',   # P17-F2: BB session key (normalize None→'')
+    }
+    # WRITE-AHEAD: persiste il task su Supabase immediatamente, prima del checkpoint
+    # periodico (15-60s). Finestra di perdita per la fase di creazione → zero.
+    asyncio.create_task(write_ahead_task_created(task_id, body.goal)).add_done_callback(_log_task_exc)
+    # BG-4: restore cross-session handoff context (async, non-blocking)
+    if body.session_id:
+        _hctx = await sb_restore_handoff_context(body.session_id)
+        if _hctx:
+            _agent_tasks[task_id]['_handoff_context'] = _hctx
+            asyncio.create_task(sb_delete_handoff(body.session_id)).add_done_callback(_log_task_exc)
+    # Persist asynchronously — never block the response
+    asyncio.create_task(
+        sb_upsert_task(task_id, body.goal, 'QUEUED', body.max_steps, body.context, created_at)
+    ).add_done_callback(_log_task_exc)
+    # S361: Speculative Tool Firing — pre-fires read-only tools in parallel
+    # while the main model processes. Results cached for _run_direct_tools to consume.
+    asyncio.create_task(fire_speculative_tools(task_id, body.goal)).add_done_callback(_log_task_exc)
+    # S950: Predictive Pre-warming cluster 4x4
+    fire_predictive_prewarm(body.goal)
+    return {'taskId': task_id, 'status': 'QUEUED'}
+
+
+# ── S369: List agent tasks (in-memory + Supabase merge) ─────────────────────
+
+@router.get('/api/agent/tasks')
+async def list_agent_tasks(limit: int = 50, status: str = ''):
+    """
+    S369 — Lista tutti i task agent: unione di in-memory (_agent_tasks) e
+    Supabase (ultimi N task persistiti). In-memory ha sempre precedenza.
+
+    Query params:
+      limit  — max task da Supabase (default 50, max 200)
+      status — filtra per status (es. RUNNING, SUCCESS, ERROR); vuoto = tutti
+    """
+    _prune_agent_tasks()
+    now_ms = int(time.time() * 1000)
+    limit  = min(max(limit, 1), 200)
+
+    # 1. Task in-memory (live)
+    mem_tasks = []
+    for tid, t in _agent_tasks.items():
+        reg   = _loop_registry.get(tid)
+        is_live = reg is not None and not reg.get('done', True)
+        mem_tasks.append({
+            'taskId':    tid,
+            'goal':      (t.get('goal') or '')[:300],  # S606: 200→300
+            'status':    t.get('status', 'UNKNOWN'),
+            'maxSteps':  t.get('max_steps', 8),
+            'createdAt': t.get('created_at', 0),
+            'ageMs':     now_ms - t.get('created_at', now_ms),
+            'source':    'memory',
+            'isLive':    is_live,
+        })
+
+    mem_ids = {t['taskId'] for t in mem_tasks}
+
+    # 2. Supabase recent tasks (only if Supabase available)
+    sb_tasks = []
+    try:
+        sb_rows = await sb_list_tasks(limit=limit, status_filter=status or None)
+        for r in sb_rows:
+            if r['task_id'] in mem_ids:
+                continue  # already included from memory
+            sb_tasks.append({
+                'taskId':    r['task_id'],
+                'goal':      (r.get('goal') or '')[:300],  # S606: 200→300
+                'status':    r.get('status', 'UNKNOWN'),
+                'maxSteps':  r.get('max_steps', 8),
+                'createdAt': r.get('created_at', 0),
+                'ageMs':     now_ms - r.get('created_at', now_ms),
+                'source':    'supabase',
+                'isLive':    False,
+            })
+    except Exception as _exc:
+        _logger.debug("[agent] silenced %s", type(_exc).__name__)  # noqa: BLE001
+
+    all_tasks = mem_tasks + sb_tasks
+    # Apply status filter to in-memory tasks too
+    if status:
+        all_tasks = [t for t in all_tasks if t['status'] == status.upper()]
+
+    # Sort by createdAt desc (newest first)
+    all_tasks.sort(key=lambda t: t['createdAt'], reverse=True)
+
+    return {
+        'count':   len(all_tasks),
+        'memory':  len(mem_tasks),
+        'supabase': len(sb_tasks),
+        'tasks':   all_tasks[:limit],
+    }
+
+
+@router.delete('/api/agent/tasks/{task_id}')
+async def cancel_agent_task(task_id: str):
+    if task_id in _agent_tasks:
+        _agent_tasks[task_id]['status'] = 'CANCELLED'
+    reg = _loop_registry.get(task_id)
+    if reg and not reg.get('done'):
+        at = reg.get('asyncio_task')
+        if at and not at.done():
+            at.cancel()
+    # Persist status + clean up events
+    asyncio.create_task(sb_update_status(task_id, 'CANCELLED')).add_done_callback(_log_task_exc)
+    asyncio.create_task(sb_delete_task_events(task_id)).add_done_callback(_log_task_exc)
+    # S361: clean speculative cache for cancelled task
+    try:
+        goal = _agent_tasks.get(task_id, {}).get('goal', '')
+        if goal:
+            from .speculative import purge_speculative
+            purge_speculative(goal)
+    except Exception as _exc:
+        _logger.debug("[agent] silenced %s", type(_exc).__name__)  # noqa: BLE001
+    return {'cancelled': task_id}
+
+
+
+@router.get('/api/agent/tasks/{task_id}/status')
+async def get_agent_task_status(task_id: str):
+    """
+    Controlla lo stato di un task agent senza aprire un SSE stream.
+    Usato dal frontend per recovery al boot: verifica se un task in sospeso
+    e` ancora in esecuzione, completato, o scomparso dopo riavvio HF Space.
+    Returns: {taskId, status, goal, source: 'memory'|'supabase'|'not_found'}
+    """
+    if task_id in _agent_tasks:
+        t = _agent_tasks[task_id]
+        return {'taskId': task_id, 'status': t.get('status', 'UNKNOWN'),
+                'goal': (t.get('goal') or '')[:300], 'source': 'memory'}
+    restored = await sb_restore_task(task_id)
+    if restored:
+        return {'taskId': task_id, 'status': restored.get('status', 'UNKNOWN'),
+                'goal': (restored.get('goal') or '')[:300], 'source': 'supabase'}
+    return {'taskId': task_id, 'status': 'NOT_FOUND', 'source': None}
+
+
+@router.get('/api/agent/tasks/{task_id}/stream')
+async def stream_agent_task(task_id: str, request: Request, resume: int = 0):
+    """
+    SSE stream per un task agent.
+
+    S358: reconnect-safe via _loop_registry fanout (no re-run mentre il backend gira).
+    S359: lazy restore da Supabase dopo restart HF Space:
+      - Task SUCCESS/ERROR → replay event buffer da Supabase → chiusura immediata.
+      - Task era RUNNING   → replay buffer parziale + evento task_interrupted.
+      - Task non trovato   → prova sb_restore_task prima di 404.
+    """
+    # S359: se task_id non è in memoria, prova il restore da Supabase
+    if task_id not in _agent_tasks:
+        restored = await sb_restore_task(task_id)
+        if restored:
+            restored['context'] = []
+            _agent_tasks[task_id] = restored
+        else:
+            raise HTTPException(404, detail=f'Task {task_id} non trovato')
+
+    task = _agent_tasks[task_id]
+    _last_event_id = request.headers.get("Last-Event-ID") or request.headers.get("last-event-id")
+    _resume_from   = int(_last_event_id) if (_last_event_id and _last_event_id.isdigit()) else resume
+
+    sub_q: asyncio.Queue[str | None] = asyncio.Queue()
+
+    async def generate():
+        yield "retry: 3000\n\n"
+
+        reg = _loop_registry.get(task_id)
+
+        is_done_reconnect = reg is not None and reg.get('done', False)
+        is_reconnect      = reg is not None and not reg.get('done', False)
+
+        # ── Case 1: loop già finito in questa sessione → replay buffer in-memory ──
+        if is_done_reconnect:
+            for evt_str in reg['event_buffer'][_resume_from:]:
+                yield evt_str
+            yield "data: [DONE]\n\n"
+            return
+
+        # ── Case 2: loop attivo in questa sessione → reconnect SSE (S358) ─────────
+        if is_reconnect:
+            join_idx = len(reg['event_buffer'])
+            reg['subscriber_queues'].append(sub_q)
+            try:
+                for evt_str in reg['event_buffer'][_resume_from:join_idx]:
+                    yield evt_str
+                while True:
+                    if _agent_tasks.get(task_id, {}).get('status') == 'CANCELLED':
+                        break
+                    try:
+                        item = await asyncio.wait_for(sub_q.get(), timeout=15.0)
+                        if item is None:
+                            break
+                        yield item
+                    except asyncio.TimeoutError:
+                        yield ': heartbeat\n\n'
+            finally:
+                try:
+                    reg['subscriber_queues'].remove(sub_q)
+                except ValueError as _exc:
+                    _logger.debug("[agent] silenced %s", type(_exc).__name__)  # noqa: BLE001
+            yield "data: [DONE]\n\n"
+            return
+
+        # ── Case 2.5 (S359): backend riavviato → prova Supabase event buffer ──────
+        sb_events = await sb_get_events(task_id)
+        if sb_events:
+            task_status = task.get('status', 'UNKNOWN')
+            terminal    = task_status in ('SUCCESS', 'ERROR', 'CANCELLED')
+            # Replay buffer from resume point
+            for evt_str in sb_events[_resume_from:]:
+                yield evt_str
+            if terminal:
+                # Task già completato → niente da fare, client ha tutto
+                yield "data: [DONE]\n\n"
+                return
+            else:
+                # Task era in esecuzione quando il backend è crashato — prova resume automatico
+                _cp_sb = _task_checkpoints.get(task_id) or await sb_get_checkpoint(task_id)
+                _can_resume = (
+                    _cp_sb is not None and
+                    len(_cp_sb.get('plan', [])) >= 1 and
+                    len(_cp_sb.get('logs', [])) >= 2
+                )
+                if _can_resume:
+                    # GAP-SYNC-FIX: usa _backend_steps se disponibili (context preciso per resume)
+                    _bsteps = _cp_sb.get('_backend_steps', [])
+                    if _bsteps:
+                        _steps_text = '\n'.join(
+                            f"  Passo {s['step']}: {s['action']} → {s['result'][:80]}"
+                            for s in _bsteps[-8:]
+                        )
+                        _rctx = (
+                            f"[RESUME AUTOMATICO] Step già completati dal backend:\n{_steps_text}\n"
+                            f"Riprendi dal passo {_cp_sb.get('step', 0)+1} senza ripetere quelli già eseguiti."
+                        )
+                    else:
+                        # Fallback: context semantico (piano + log riassuntivi)
+                        _rctx = (
+                            f"Piano già definito: {' | '.join((_cp_sb.get('plan') or [])[:5])}\n"
+                            f"Log fin qui: {' | '.join((_cp_sb.get('logs') or [])[-5:])}\n"
+                            f"Riprendi dal passo {_cp_sb.get('step', 0)} senza ripetere gli step già fatti."
+                        )
+                    task['_resume_context']   = _rctx
+                    task['_resume_max_steps'] = max(1, task.get('max_steps', 8) - _cp_sb.get('step', 0))
+                    # Fall through a Case 3 — NON fare return
+                else:
+                    # Nessun checkpoint utile → fallback onesto (comportamento precedente)
+                    interrupted_evt = json.dumps({
+                        'event':   'task_interrupted',
+                        'taskId':  task_id,
+                        'reason':  'backend_restarted',
+                        'message': 'Il backend si è riavviato durante l\'esecuzione. '
+                                   'Premi "Riprova" per rieseguire il task.',
+                    })
+                    yield f"data: {interrupted_evt}\n\n"
+                    _agent_tasks[task_id]['status'] = 'ERROR'
+                    asyncio.create_task(sb_update_status(task_id, 'ERROR')).add_done_callback(_log_task_exc)
+                    yield "data: [DONE]\n\n"
+                    return
+        # ── Case 3: nuova esecuzione ──────────────────────────────────────────────
+        _prune_loop_registry()
+        reg_entry: dict = {
+            'asyncio_task':      None,
+            'event_buffer':      [],
+            'subscriber_queues': [sub_q],
+            'done':              False,
+            'finished_at':       0.0,
+        }
+        _loop_registry[task_id] = reg_entry
+        _ctr = [0]
+
+        def _sse(event: str, data: dict) -> None:
+            """Emit one SSE frame: buffer it, fanout to all subscribers, persist async."""
+            _ctr[0] += 1
+            s = f"id: {_ctr[0]}\ndata: {json.dumps({'event': event, **data})}\n\n"
+            # GAP-3-FIX: text_chunk bypass buffer — fanout diretto, no persist.
+            # 800 token x 1 evento/token saturerebbero il cap da 500 evictando step cruciali.
+            # Su reconnect iOS i token non servono replay (streaming completato o ricominciato).
+            if event == 'text_chunk':
+                for q in list(reg_entry['subscriber_queues']):
+                    try:
+                        q.put_nowait(s)
+                    except Exception as _exc:
+                        _logger.debug("[agent] silenced %s", type(_exc).__name__)  # noqa: BLE001
+                return
+            reg_entry['event_buffer'].append(s)
+            # N-5-FIX: cap buffer a 500 eventi — evita crescita illimitata su task lunghi
+            if len(reg_entry['event_buffer']) > 500:
+                reg_entry['event_buffer'] = reg_entry['event_buffer'][-500:]
+            for q in list(reg_entry['subscriber_queues']):
+                try:
+                    q.put_nowait(s)
+                except Exception as _exc:
+                    _logger.debug("[agent] silenced %s", type(_exc).__name__)  # noqa: BLE001
+            # S359: persist event asynchronously (fire-and-forget)
+            asyncio.create_task(sb_append_event(task_id, _ctr[0], s)).add_done_callback(_log_task_exc)
+
+        _agent_tasks[task_id]['status'] = 'RUNNING'
+        asyncio.create_task(sb_update_status(task_id, 'RUNNING')).add_done_callback(_log_task_exc)
+        _prune_agent_tasks()
+
+        async def run_loop() -> None:
+            try:
+                from agents.unified_loop import UnifiedAgentLoop
+                # S388: singleton — evita OpenAI() per ogni task
+                client = _get_ai_client()
+                try:
+                    from agents.critic import Critic
+                    from agents.response_verifier import ResponseVerifier
+                    _critic   = Critic(llm_client=client)
+                    _verifier = ResponseVerifier()
+                except Exception:
+                    _critic   = None
+                    _verifier = None
+
+                context_str = '\n'.join(m.get('content', '') for m in task['context']) if task['context'] else ''
+                # S456-X5/X4: inject project context + learning hints stored at task creation
+                _proj_ctx = task.get('project_context', '')
+                if _proj_ctx:
+                    context_str = f"[PROGETTO CORRENTE]\n{_proj_ctx}\n\n{context_str}".strip()
+                _hints = task.get('learning_hints', [])
+                if _hints:
+                    # S591: _hints[:3]→[:5] — più pattern appresi nel context (task replay)
+                    hints_str = "\n".join(f"- {h}" for h in _hints[:5])
+                    context_str = f"{context_str}\n\n[PATTERN DI ERRORE APPRESI]\n{hints_str}".strip()
+                # P16-F3: inject resume hint if task was promoted from queue at a specific step
+                _resume_step = task.get('resume_from_step')
+                if _resume_step:
+                    context_str = f"[RIPRESA DA PASSO {_resume_step}] Riprendi dall'iterazione {_resume_step} del task.\n\n{context_str}".strip()
+                # P39-UX: Tocco Finale Manus — spiega all'agente come segnalare OAuth mancante
+                _connector_hint = (
+                    "[CONNETTORI OAUTH]\n"
+                    "Se durante il task hai bisogno di un accesso OAuth (GitHub, Google Calendar, Instagram)\n"
+                    "ma non hai il token disponibile, includi nella tua risposta finale o parziale:\n"
+                    "  [CONNECTOR_NEEDED:github] oppure [CONNECTOR_NEEDED:google] oppure [CONNECTOR_NEEDED:instagram]\n"
+                    "Il frontend mostrerà automaticamente un pulsante 'Connetti' all'utente."
+                )
+                context_str = f"{context_str}\n\n{_connector_hint}".strip() if context_str else _connector_hint
+                # GAP-SYNC-FIX: inject _resume_context (set da stream_agent_task su reconnect con checkpoint)
+                # Bug: _resume_context era settato su task{} ma mai letto qui → context perduto su resume.
+                _resume_ctx = task.get('_resume_context', '')
+                if _resume_ctx:
+                    context_str = f"{_resume_ctx}\n\n{context_str}".strip()
+                # P17-F5: inject Expertise Persona hint se specificato
+                _PERSONA_HINTS = {
+                    "researcher": (
+                        "[PERSONA: RICERCATORE ESPERTO]\n"
+                        "- Priorizza sempre la ricerca web aggiornata prima di rispondere\n"
+                        "- Cita fonti specifiche (URL, titolo, data) per ogni claim importante\n"
+                        "- Struttura le risposte: Sommario → Dettaglio → Fonti\n"
+                        "- Verifica incrociando più fonti prima di concludere\n"
+                        "- Strumenti preferiti: web_search, read_page, fetch_url, research"
+                    ),
+                    "coder": (
+                        "[PERSONA: SENIOR ENGINEER]\n"
+                        "- Scrivi codice production-ready: tipizzato, documentato, con error handling\n"
+                        "- Esegui il codice per verificare il funzionamento prima di rispondere\n"
+                        "- Preferisci soluzioni robuste e testate su approcci creativi ma fragili\n"
+                        "- Documenta funzioni e classi con docstring/JSDoc\n"
+                        "- Strumenti preferiti: run_python, write_file, read_file, pip_install"
+                    ),
+                    "architect": (
+                        "[PERSONA: ARCHITECT]\n"
+                        "- Priorizza analisi, design di sistema e decisioni strategiche\n"
+                        "- Struttura l'architettura in componenti chiari e mantenibili\n"
+                        "- Considera scalabilità, manutenibilità e trade-off tecnici\n"
+                        "- Documenta le decisioni architetturali e il loro razionale"
+                    ),
+                    "reasoner": (
+                        "[PERSONA: RAGIONATORE STRATEGICO]\n"
+                        "- Usa ragionamento step-by-step esplicito: mostra il processo di pensiero\n"
+                        "- Analizza ogni prospettiva prima di concludere\n"
+                        "- Struttura la risposta: Analisi → Pro/Contro → Raccomandazione\n"
+                        "- Considera le implicazioni di lungo termine delle scelte"
+                    ),
+                    "analyst": (
+                        "[PERSONA: ANALISTA DATI]\n"
+                        "- Usa Python per elaborare e analizzare dati quando disponibili\n"
+                        "- Produci visualizzazioni chiare (grafici, tabelle) ove possibile\n"
+                        "- Interpreta i risultati con rigore: distingui correlazione da causalità\n"
+                        "- Struttura i report: Executive Summary → Metodologia → Risultati → Conclusioni\n"
+                        "- Strumenti preferiti: run_python, web_search, vision"
+                    ),
+                }
+                _persona = task.get('persona') or ''
+                # P17-F5-IMPROVED: server-side classification se persona vuota/auto
+                _persona_auto = False
+                if not _persona:
+                    _persona = _classify_persona_server(task.get('goal', ''))
+                    if _persona:
+                        _persona_auto = True
+                        task['persona'] = _persona  # persist per history/resume
+                _persona_hint = _PERSONA_HINTS.get(_persona.lower().strip(), '')
+                if _persona_hint:
+                    context_str = f"{_persona_hint}\n\n{context_str}".strip()
+                # P17-F5: emit persona_classified SSE event — UI badge feedback
+                if _persona:
+                    _persona_conf = 0.85 if not _persona_auto else 0.78
+                    _sse('persona_classified', {
+                        'taskId':     task_id,
+                        'persona':    _persona,
+                        'confidence': _persona_conf,
+                        'auto':       _persona_auto,
+                    })
+                # BG-4: inject cross-session handoff context if available
+                _hctx = task.get("_handoff_context", "")
+                if _hctx:
+                    context_str = f"{_hctx}\n\n{context_str}".strip()
+                # P17-F5: route primary LLM to persona-appropriate client
+                _persona_client = _get_persona_llm_client(_persona, client)
+                loop = UnifiedAgentLoop(
+                    llm_client=_persona_client, critic=_critic, verifier=_verifier,
+                    memory=await _get_mem_manager_async(), executor=_get_executor(), planner=_get_planner(),
+                )
+                step_idx = [0]
+                _backend_steps: list[dict] = []  # GAP-SYNC-FIX: log step per resume preciso
+
+                async def step_cb(step_data: dict) -> None:
+                    step_idx[0] += 1
+                    _action = step_data.get('action', f'Step {step_idx[0]}')
+                    # S420: streaming token — emetti direttamente senza passare dal buffer step
+                    if _action == 'text_chunk':
+                        _sse('text_chunk', {'taskId': task_id, 'token': _ss(step_data.get('token', ''))})
+                        return
+
+                    # S363-Blueprint: Narrative Streaming — explanation lookup for ALL step_done events
+                    # S376: _STEP_NARRATIONS espanso — aggiunge 12 tool mancanti
+                    # Il fallback `_action.replace('_', ' ').capitalize()` è troppo generico
+                    # per tool composti — narrativa esplicita migliora la UX del LiveStreamBlock
+                    _STEP_NARRATIONS = {
+                        'plan': 'Analisi del goal e creazione piano di azione',
+                        'llm': 'Elaborazione risposta AI',
+                        'fallback': 'Completamento task',
+                        'smolagents': 'Esecuzione agente autonomo con strumenti',
+                        'web_search': 'Cerco informazioni aggiornate sul web',
+                        'read_page': 'Leggo il contenuto della pagina web',
+                        'fetch_url': 'Recupero dati dall\'URL richiesto',
+                        'fetch_url_content': 'Scarico il contenuto dell\'URL',
+                        'run_code': 'Eseguo il codice nel sandbox',
+                        'write_file': 'Scrivo il file nel progetto',
+                        'read_file': 'Leggo il file dal VFS',
+                        'delete_file': 'Rimuovo il file dal progetto',
+                        'create_file': 'Creo il file nel progetto',
+                        'list_files': 'Elenco i file del progetto',
+                        'search_github': 'Cerco codice e repository su GitHub',
+                        'search_github_code': 'Cerco snippet di codice su GitHub',
+                        'search_wikipedia': 'Consulto Wikipedia per informazioni',
+                        'get_weather': 'Recupero le previsioni meteo',
+                        'get_news': 'Carico le ultime notizie',
+                        'get_currency': 'Consulto il tasso di cambio',
+                        'get_location': 'Rilevo la posizione geografica',
+                        'calculate': 'Calcolo l\'espressione matematica',
+                        'math_eval': 'Valuto l\'espressione matematica',
+                        'generate_image': 'Genero l\'immagine con AI (Pollinations)',
+                        'remember': 'Salvo informazioni in memoria',
+                        'recall': 'Recupero informazioni dalla memoria',
+                        'direct_tools': 'Utilizzo strumenti diretti',
+                        'critic_retry': 'Auto-correzione risposta (Quality Gate)',
+                        'execution_validator_fix': 'Auto-fix codice rilevato (ExecutionValidator)',
+                        '__thinking__': 'Ragionamento interno in corso',
+                        '__plan__': 'Pianificazione step successivo',
+                        '__verify__': 'Verifica e validazione risposta',
+                        'reflective_debug': 'Analisi root cause errore (Chain-of-Verification)',
+                        'lint_result': 'Validazione sintattica file',
+                        'lint_code': 'Analisi statica del codice',
+                        'project_skeleton': 'Mappa aggiornata del progetto',
+                        'tool_governor_skip': 'Tool già eseguito — risultato riutilizzato',
+                        'severity_retry': 'Retry adattivo per tipologia errore (S376)',
+                        # S-LOOP2: narrations per fasi avanzate
+                        'reasoning_core':   'Ragionamento multi-step (ReasoningCore attivo)',
+                        'browser_verifier':  'Verifica app live in tempo reale (Playwright)',
+                    }
+                    _tool_key_narr = _action.replace('executor:', '') if _action.startswith('executor:') else _action
+                    _narration = _STEP_NARRATIONS.get(_tool_key_narr,
+                        _action.replace('executor:', '').replace('_', ' ').capitalize())
+                    # P16-B4: propaga 'truncated' dal loop (finish_reason==length) → frontend
+                    _step_truncated = bool(step_data.get('truncated', False))
+                    _sse('step_done', {
+                        'taskId': task_id,
+                        'step': {
+                            'name':        _action,
+                            'index':       step_idx[0],
+                            'status':      step_data.get('status', 'done'),
+                            'result':      str(step_data.get('result', step_data.get('output', '')))[:500],
+                            'explanation': _narration,  # S363-Blueprint: narrative field
+                            'truncated':   _step_truncated,  # P16-B4: segnala max_tokens raggiunto
+                        },
+                    })
+                    # P39-UX: rileva [CONNECTOR_NEEDED:provider] nel result → emetti SSE connector_needed
+                    import re as _re_cn
+                    _cn_result = str(step_data.get('result', step_data.get('output', '')))
+                    _cn_matches = _re_cn.findall(r'\[CONNECTOR_NEEDED:([\w]+)\]', _cn_result)
+                    for _cn_prov in _cn_matches:
+                        _PROVIDER_LABELS = {'github': 'GitHub', 'google': 'Google Calendar', 'instagram': 'Instagram'}
+                        _cn_label = _PROVIDER_LABELS.get(_cn_prov.lower(), _cn_prov.capitalize())
+                        _sse('connector_needed', {
+                            'taskId':   task_id,
+                            'provider': _cn_prov.lower(),
+                            'label':    _cn_label,
+                            'message':  f"Per completare il task ho bisogno di accedere a {_cn_label}. Connettiti con un tap.",
+                        })
+                    # GAP-SYNC-FIX: accumula step results per resume preciso (checkpoint backend-side)
+                    _backend_steps.append({
+                        'step':   step_idx[0],
+                        'action': _action,
+                        'result': str(step_data.get('result', step_data.get('output', '')))[:150],
+                        'ok':     step_data.get('status', 'done') not in ('error', 'failed'),
+                    })
+                    # Ogni 2 step: persisti il log su Supabase (non saturare Supabase su loop lunghi)
+                    if step_idx[0] % 2 == 0:
+                        asyncio.create_task(
+                            sb_save_checkpoint(task_id, step_idx[0], {
+                                '_backend_steps': _backend_steps[-10:],  # ultime 10 step
+                                'step':           step_idx[0],
+                            })
+                        ).add_done_callback(_log_task_exc)
+                    # TG-STEP: notifica step intermedio rilevante (fire-and-forget, rate-limited 30s)
+                    asyncio.create_task(_tg_step(task_id, _action, _narration)).add_done_callback(_log_task_exc)
+                    # S362: emit vfs_update when a file operation is detected
+                    # SYNC-1: file_written (da unified_loop GAP-1) incluso + content forwarding
+                    _VFS_ACTIONS = ('write_file', 'file_write', 'create_file', 'delete_file', 'file_delete', 'file_written')
+                    if _action in _VFS_ACTIONS or step_data.get('file_path'):
+                        # S581: 120→200 — path file spesso 120-200 chars
+                        # S596: 200→400 — result/output può contenere path completo di progetto
+                        # S604: 400→500 — parity con altri campi step
+                        # SYNC-1: file_written porta path in 'path', non 'file_path'
+                        _vfs_file = (step_data.get('path') or
+                                     step_data.get('file_path') or
+                                     step_data.get('result', '')[:500] or
+                                     step_data.get('output', '')[:500])
+                        _vfs_op = 'delete' if 'delete' in _action else 'write'
+                        _vfs_evt: dict = {'taskId': task_id, 'file': str(_vfs_file)[:500], 'op': _vfs_op}
+                        # SYNC-1: includi content nel SSE event per file_written (≤60KB)
+                        # Frontend scrive direttamente nel VFS locale senza fetch aggiuntivo
+                        if _action == 'file_written' and step_data.get('content'):
+                            _vfs_evt['content'] = str(step_data['content'])[:60_000]
+                        _sse('vfs_update', _vfs_evt)
+
+                    # S363-UI: thought event — emitted when planner completes
+                    if _action == 'plan' and step_data.get('status') == 'done':
+                        _plan_obj = step_data.get('result', step_data.get('output', ''))
+                        _thought = (_plan_obj.get('goal', '') if isinstance(_plan_obj, dict) else str(_plan_obj))[:400]  # S604: 280→400
+                        if _thought:
+                            _sse('thought', {'taskId': task_id, 'text': _thought,
+                                             'complexity': _plan_obj.get('complexity') if isinstance(_plan_obj, dict) else None})
+                        # S367: plan_update — structured subtask list for live plan tracking UI
+                        if isinstance(_plan_obj, dict) and _plan_obj.get('subtasks'):
+                            _sse('plan_update', {
+                                'taskId': task_id,
+                                'subtasks': [
+                                    {
+                                        'id':          s.get('id', _si + 1),
+                                        'description': s.get('description', '')[:200],  # S581: 80→200
+                                        'tool':        s.get('tool', ''),
+                                        'status':      'pending',
+                                    }
+                                    for _si, s in enumerate(_plan_obj['subtasks'])
+                                ],
+                                'goal': _plan_obj.get('goal', ''),
+                            })
+
+                    # S367: subtask_done — mark individual subtask complete for live checkbox update
+                    if step_data.get('subtask_id') and step_data.get('status') == 'done':
+                        _sse('plan_update', {
+                            'taskId':      task_id,
+                            'subtask_done': step_data['subtask_id'],
+                        })
+
+                    # S363-UI: action event — tool execution phase
+                    _TOOL_EXPLAINS_S363 = {
+                        'web_search': 'Cerco informazioni in rete',
+                        'get_weather': 'Recupero dati meteo',
+                        'get_news': 'Carico notizie recenti',
+                        'search_wikipedia': 'Consulto Wikipedia',
+                        'fetch_url': 'Leggo la pagina web',
+                        'search_github': 'Cerco su GitHub',
+                        'run_code': 'Eseguo il codice',
+                        'write_file': 'Scrivo il file',
+                        'read_file': 'Leggo il file',
+                        'direct_tools': 'Eseguo strumenti diretti',
+                    }
+                    _tool_key = _action.replace('executor:', '') if _action.startswith('executor:') else _action
+                    if _action.startswith('executor:') or _tool_key in _TOOL_EXPLAINS_S363:
+                        _sse('action', {
+                            'taskId': task_id,
+                            'log': _tool_key.upper().replace('_', ' ')[:30],
+                            'explain': _TOOL_EXPLAINS_S363.get(_tool_key, f'Esecuzione: {_tool_key}'),
+                        })
+                    # S758-P4.1: tool_use — chip pre-esecuzione (stream_agent_task path)
+                    _is_pre_exec = (
+                        (_action == 'tool_start' and step_data.get('status') == 'running') or
+                        (_action.startswith('executor:') and step_data.get('status') == 'started')
+                    )
+                    if _is_pre_exec:
+                        _sse('tool_use', {
+                            'taskId': task_id,
+                            'tool':   _tool_key,
+                            'name':   _tool_key,
+                            'label':  (step_data.get('title') or
+                                       _TOOL_EXPLAINS_S363.get(_tool_key,
+                                       _tool_key.replace('_', ' ').capitalize())),
+                            'args':   {},
+                        })
+                    # S758-P4.1: task_thinking — chip ragionamento LLM
+                    if (_action in ('__thinking__', 'reflective_debug') and
+                            step_data.get('status') in ('started', 'running', 'running_deep')):
+                        _sse('task_thinking', {
+                            'taskId':  task_id,
+                            'message': (step_data.get('explanation') or step_data.get('title') or
+                                       "L’agente sta elaborando…"),
+                        })
+
+                _sse('task_start', {'taskId': task_id, 'goal': task['goal']})
+                _task_started_ms = int(time.time() * 1000)  # NOTIFY-BOT: elapsed tracking
+                asyncio.create_task(_tg_start(task_id, task['goal'])).add_done_callback(_log_task_exc)
+                _sse('step_start', {'taskId': task_id, 'step': {'name': 'Analisi goal', 'index': 0}})
+
+                # S364: inject project skeleton into context from VFS (Gap 4)
+                if task.get('conversation_id'):
+                    try:
+                        from api.project_manifest import build_manifest_from_vfs, get_skeleton
+                        await asyncio.wait_for(
+                            build_manifest_from_vfs(task['conversation_id']),
+                            timeout=3.0,
+                        )
+                        _skeleton = await get_skeleton(task['conversation_id'])
+                        if _skeleton:
+                            context_str = (_skeleton + '\n\n' + context_str).strip()
+                    except Exception:
+                        pass  # S364: skeleton injection is optional
+
+                result = await loop.run(
+                    goal=task['goal'],
+                    context=context_str,
+                    max_steps=task.get('_resume_max_steps', task.get('max_steps', 8)),  # AG-BUG-1: _resume_max mai definito in questo scope
+                    on_step=step_cb,
+                    session_id=task.get('session_id', '') or '',
+                )
+                _agent_tasks[task_id]['status'] = 'SUCCESS'
+                asyncio.create_task(sb_update_status(task_id, 'SUCCESS')).add_done_callback(_log_task_exc)
+                _result_text = str(result.get('output', result) if isinstance(result, dict) else result)
+                _sse('task_done', {'taskId': task_id, 'result': _result_text[:8000]})
+                asyncio.create_task(_tg_done(task_id, task.get('goal', ''), _result_text[:500], _task_started_ms)).add_done_callback(_log_task_exc)
+
+                # S363: fire-and-forget quality check when code detected in output
+                if _run_quality_check:
+                    _qg_result = str(result.get('output', result) if isinstance(result, dict) else result)
+                    if len(_qg_result) > 500 and _qg_result.count('```') >= 2:  # S373: threshold raised — evita QG su snippet brevi
+                        asyncio.create_task(_run_quality_check(
+                            task_id, task['goal'], _qg_result,
+                            on_event=lambda ev: _sse(ev.get('type', 'test_result'), ev),
+                        )).add_done_callback(_log_task_exc)
+
+
+            except asyncio.CancelledError:
+                _agent_tasks[task_id]['status'] = 'CANCELLED'
+                asyncio.create_task(sb_update_status(task_id, 'CANCELLED')).add_done_callback(_log_task_exc)
+                _sse('task_cancelled', {'taskId': task_id})
+
+            except (ImportError, ModuleNotFoundError):
+                _agent_tasks[task_id]['status'] = 'SUCCESS'
+                asyncio.create_task(sb_update_status(task_id, 'SUCCESS')).add_done_callback(_log_task_exc)
+                _sse('step_done', {'taskId': task_id, 'step': {'name': 'Ragionamento', 'index': 0}})
+                _sse('task_done', {'taskId': task_id, 'result': (
+                    f'Goal ricevuto: {task["goal"]}\n\n'
+                    'Il backend non ha il modulo agents.unified_loop. '
+                    'Configura HuggingFace Spaces con smolagents per l\'esecuzione autonoma.'
+                )})
+
+            except Exception as err:
+                _agent_tasks[task_id]['status'] = 'ERROR'
+                asyncio.create_task(sb_update_status(task_id, 'ERROR')).add_done_callback(_log_task_exc)
+                _logger.error('[agent/stream] %s error: %s', task_id, err, exc_info=True)
+                _sse('task_error', {'taskId': task_id, 'error': str(err)[:1000]})
+                asyncio.create_task(_tg_error(task_id, task.get('goal', ''), str(err))).add_done_callback(_log_task_exc)
+
+            finally:
+                reg_entry['done'] = True
+                reg_entry['finished_at'] = time.time()
+                for q in list(reg_entry['subscriber_queues']):
+                    try:
+                        q.put_nowait(None)
+                    except Exception as _exc:
+                        _logger.debug("[agent] silenced %s", type(_exc).__name__)  # noqa: BLE001
+
+        reg_entry['asyncio_task'] = asyncio.create_task(run_loop())
+
+        try:
+            while True:
+                if _agent_tasks.get(task_id, {}).get('status') == 'CANCELLED':
+                    at = reg_entry.get('asyncio_task')
+                    if at and not at.done():
+                        at.cancel()
+                    break
+                try:
+                    item = await asyncio.wait_for(sub_q.get(), timeout=15.0)
+                    if item is None:
+                        break
+                    yield item
+                except asyncio.TimeoutError:
+                    yield ': heartbeat\n\n'
+        finally:
+            try:
+                reg_entry['subscriber_queues'].remove(sub_q)
+            except ValueError as _exc:
+                _logger.debug("[agent] silenced %s", type(_exc).__name__)  # noqa: BLE001
+
+        yield "data: [DONE]\n\n"
+
+    return StreamingResponse(
+        generate(),
+        media_type='text/event-stream',
+        headers={
+            'Cache-Control':     'no-cache',
+            'X-Accel-Buffering': 'no',
+        }
+    )
+

api/agent_telemetry.py

@@ -34,52 +34,6 @@ _MAX_STORE  = 500  # max entry totali prima del pruning
 # lo stesso store e si sovrascriverebbero. asyncio.Lock() è safe a livello di modulo
 # in Python 3.10+ (non richiede event loop attivo all'init del modulo).
 _store_lock = asyncio.Lock()
-_RUNTIME_PHASES = ('auth', 'queue', 'provider', 'tool', 'persistence')
-_RUNTIME_MAX_SAMPLES = 200
-_runtime_lock = asyncio.Lock()
-_runtime_store: dict[str, dict] = {
-    phase: {'samples_ms': [], 'ok': 0, 'errors': {}}
-    for phase in _RUNTIME_PHASES
-}
-
-
-async def record_runtime_phase(phase: str, duration_ms: float = 0.0,
-                               outcome: str = 'ok', error_class: str | None = None) -> None:
-    if phase not in _runtime_store:
-        return
-    async with _runtime_lock:
-        bucket = _runtime_store[phase]
-        samples = bucket['samples_ms']
-        samples.append(max(0.0, round(float(duration_ms), 2)))
-        if len(samples) > _RUNTIME_MAX_SAMPLES:
-            del samples[:-_RUNTIME_MAX_SAMPLES]
-        if outcome == 'ok':
-            bucket['ok'] += 1
-        else:
-            key = error_class or outcome or 'unknown'
-            bucket['errors'][key] = bucket['errors'].get(key, 0) + 1
-
-
-def _percentile(samples: list[float], percentile: float) -> float:
-    if not samples:
-        return 0.0
-    ordered = sorted(samples)
-    index = min(len(ordered) - 1, int(round((percentile / 100) * (len(ordered) - 1))))
-    return ordered[index]
-
-
-async def runtime_snapshot() -> dict[str, dict]:
-    async with _runtime_lock:
-        return {
-            phase: {
-                'count': len(bucket['samples_ms']),
-                'ok': bucket['ok'],
-                'errors': dict(bucket['errors']),
-                'p50_ms': _percentile(bucket['samples_ms'], 50),
-                'p95_ms': _percentile(bucket['samples_ms'], 95),
-            }
-            for phase, bucket in _runtime_store.items()
-        }
 
 # ─── Store helpers ────────────────────────────────────────────────────────────
 
@@ -161,11 +115,6 @@ class TelemetrySyncBody(BaseModel):
 
 # ─── Endpoints ────────────────────────────────────────────────────────────────
 
-@router.get("/api/agent-telemetry/runtime")
-async def get_runtime_telemetry() -> JSONResponse:
-    return JSONResponse({'ok': True, 'phases': await runtime_snapshot(), 'server_ts': int(time.time() * 1000)})
-
-
 @router.post("/api/agent-telemetry/sync")
 async def post_agent_telemetry(body: TelemetrySyncBody) -> JSONResponse:
     """

api/auth_managed.py

@@ -11,7 +11,7 @@ I CLIENT_ID/SECRET vanno nei secret HF Spaces (mai nel codice).
 
 Cifratura token: Fernet(PBKDF2HMAC-SHA256, 260k iter, salt fisso) — richiede cryptography>=42.
 """
-import os, time, secrets, json, logging, asyncio, hashlib
+import os, time, secrets, json, logging, asyncio
 from typing import Optional
 from fastapi import APIRouter, Depends, Request, HTTPException
 from .auth_guard import require_role, AuthRole
@@ -21,29 +21,6 @@ import httpx
 _logger = logging.getLogger('api.auth_managed')
 router  = APIRouter()
 
-_DIAGNOSTIC_SECRET_NAMES = (
-    'ADMIN_DIAGNOSTICS_TOKEN', 'INTERNAL_TOKEN', 'PUBLIC_API_TOKEN',
-    'PRIVATE_STATE_INTERNAL_TOKEN', 'SUPABASE_SERVICE_ROLE_KEY',
-    'SUPABASE_SERVICE_ROLE_KEY_B', 'GROQ_API_KEY', 'HF_TOKEN',
-    'GEMINI_API_KEY', 'CEREBRAS_API_KEY', 'SAMBANOVA_API_KEY',
-    'OPENROUTER_API_KEY', 'OPENROUTER_API_KEY_B', 'OPENROUTER_API_KEY_C',
-    'OPENROUTER_PROFILES_JSON', 'NVIDIA_API_KEY', 'NVIDIA_API_KEY_B',
-)
-
-
-def _secret_fingerprint(name: str) -> dict[str, object]:
-    value = os.getenv(name, '').strip()
-    return {
-        'configured': bool(value),
-        'length': len(value),
-        'sha256': hashlib.sha256(value.encode('utf-8')).hexdigest()[:16] if value else None,
-    }
-
-
-@router.get('/api/admin/secret-fingerprint')
-async def secret_fingerprint(role: AuthRole = Depends(require_role(AuthRole.MACHINE))):
-    return {'secrets': {name: _secret_fingerprint(name) for name in _DIAGNOSTIC_SECRET_NAMES}}
-
 # ── Fernet encryption setup ──────────────────────────────────────────────────
 # Salt statico pubblico: accettabile per chiave macchina (non password utente).
 # Il VAULT_KEY è il segreto; il salt previene rainbow-table cross-application.

api/background_tasks.py

@@ -1,53 +0,0 @@
-"""Supervision utilities for long-lived background asyncio tasks."""
-from __future__ import annotations
-
-import asyncio
-import logging
-from collections.abc import Awaitable
-from typing import Any
-
-_logger = logging.getLogger("agente_ai.background_tasks")
-_tasks: dict[str, asyncio.Task[Any]] = {}
-
-
-def spawn_background_task(coro: Awaitable[Any], *, name: str) -> asyncio.Task[Any]:
-    """Start one named background task and retain it for lifecycle shutdown.
-
-    A live task with the same name is reused. The passed coroutine is closed in
-    that case so duplicate startup calls do not leak an un-awaited coroutine.
-    """
-    current = _tasks.get(name)
-    if current is not None and not current.done():
-        close = getattr(coro, "close", None)
-        if close is not None:
-            close()
-        return current
-
-    task = asyncio.create_task(coro, name=name)
-    _tasks[name] = task
-
-    def _report(task_result: asyncio.Task[Any]) -> None:
-        if task_result.cancelled():
-            return
-        try:
-            error = task_result.exception()
-        except asyncio.CancelledError:
-            return
-        if error is not None:
-            _logger.error("background task %s failed: %s", name, error, exc_info=error)
-
-    task.add_done_callback(_report)
-    return task
-
-
-async def shutdown_background_tasks() -> None:
-    """Cancel and await all supervised background tasks."""
-    tasks = [task for task in _tasks.values() if not task.done()]
-    for task in tasks:
-        task.cancel()
-    if tasks:
-        await asyncio.gather(*tasks, return_exceptions=True)
-    _tasks.clear()
-
-
-__all__ = ["spawn_background_task", "shutdown_background_tasks"]

api/benchmarks_hub.py

@@ -0,0 +1,100 @@
+"""
+backend/api/benchmarks_hub.py — Gap 3: router per i 3 benchmark standalone
+
+Espone come endpoint HTTP le classi benchmark finora orfane:
+  POST /api/debug/benchmark/advanced   ← AdvancedBenchmark (concorrenza)
+  POST /api/debug/benchmark/fabric     ← FabricBenchmark   (token rotation)
+  POST /api/debug/benchmark/extended   ← ExtendedBenchmark (multi-scenario)
+
+Tutti usano mock interni (asyncio.sleep + dict simulati) — sicuri da eseguire
+in produzione senza side-effect su provider reali.
+"""
+import asyncio, logging, time
+from fastapi import APIRouter
+from fastapi.responses import JSONResponse
+
+router  = APIRouter()
+_logger = logging.getLogger("api.benchmarks_hub")
+
+
+@router.post("/api/debug/benchmark/advanced")
+async def run_advanced() -> JSONResponse:
+    """Stress test concorrenza: 3 scenari × N task simulati."""
+    t0 = time.monotonic()
+    try:
+        from api.advanced_complex_benchmark import AdvancedBenchmark
+        b = AdvancedBenchmark()
+        await b.setup()
+        await asyncio.gather(
+            b.run_complex_task("complex_reasoning",  "reasoning", count=5),
+            b.run_complex_task("data_heavy_sync",    "memory",    count=5),
+            b.run_complex_task("multi_provider_chain","compute",  count=5),
+        )
+        elapsed = round((time.monotonic() - t0) * 1000)
+        total   = b.metrics["successes"] + b.metrics["failures"]
+        return JSONResponse({
+            "ok":           True,
+            "type":         "advanced",
+            "elapsed_ms":   elapsed,
+            "success_rate": round(b.metrics["successes"] / max(1, total) * 100, 1),
+            "total_calls":  total,
+            "successes":    b.metrics["successes"],
+            "failures":     b.metrics["failures"],
+            "latencies": {
+                k: {"avg_ms": round(sum(v) / len(v), 1), "max_ms": round(max(v), 1), "n": len(v)}
+                for k, v in b.metrics.items() if isinstance(v, list) and v
+            },
+        })
+    except Exception as exc:
+        _logger.exception("[advanced_bench]")
+        return JSONResponse({"ok": False, "type": "advanced", "error": str(exc)}, status_code=500)
+
+
+@router.post("/api/debug/benchmark/fabric")
+async def run_fabric() -> JSONResponse:
+    """Benchmark rotazione token e fallback provider."""
+    t0 = time.monotonic()
+    try:
+        from api.fabric_benchmark import FabricBenchmark
+        b = FabricBenchmark()
+        await b.setup_simulated_environment()
+        await b.run_benchmark()
+        elapsed = round((time.monotonic() - t0) * 1000)
+        lats    = b.stats.get("latencies", [])
+        return JSONResponse({
+            "ok":            True,
+            "type":          "fabric",
+            "elapsed_ms":    elapsed,
+            "rotations":     b.stats.get("rotations", 0),
+            "fallbacks":     b.stats.get("fallbacks", 0),
+            "errors":        len(b.stats.get("errors", [])),
+            "avg_latency_ms": round(sum(lats) / len(lats), 1) if lats else None,
+        })
+    except Exception as exc:
+        _logger.exception("[fabric_bench]")
+        return JSONResponse({"ok": False, "type": "fabric", "error": str(exc)}, status_code=500)
+
+
+@router.post("/api/debug/benchmark/extended")
+async def run_extended() -> JSONResponse:
+    """Multi-scenario: normal load + cascading failure + oracle stress."""
+    t0 = time.monotonic()
+    try:
+        from api.extended_benchmark import ExtendedBenchmark
+        b = ExtendedBenchmark()
+        await b.setup()
+        await asyncio.gather(
+            b.scenario_normal_load(),
+            b.scenario_cascading_failure(),
+            b.scenario_oracle_stress(),
+        )
+        elapsed = round((time.monotonic() - t0) * 1000)
+        return JSONResponse({
+            "ok":        True,
+            "type":      "extended",
+            "elapsed_ms": elapsed,
+            "scenarios": b.results,
+        })
+    except Exception as exc:
+        _logger.exception("[extended_bench]")
+        return JSONResponse({"ok": False, "type": "extended", "error": str(exc)}, status_code=500)

api/bootstrap_tools.py

@@ -0,0 +1,44 @@
+"""
+backend/api/bootstrap_tools.py — Inizializza e registra i tool predefiniti all'avvio.
+"""
+import logging
+from .tool_engine import tool_registry, ToolDescriptor
+
+_logger = logging.getLogger("api.bootstrap_tools")
+
+async def bootstrap_all_tools():
+    """
+    Registra i tool fondamentali nel ToolEngine.
+    Questi tool diventano capability disponibili per il Brain.
+    """
+    tools = [
+        ToolDescriptor(
+            name="web_search",
+            description="Cerca informazioni sul web in tempo reale",
+            provider_id="hf-space-1",
+            input_schema={"type": "object", "properties": {"query": {"type": "string"}}},
+            tags=["search", "web"]
+        ),
+        ToolDescriptor(
+            name="python_interpreter",
+            description="Esegue codice Python in una sandbox sicura",
+            provider_id="oracle-cloud-vm-01",
+            input_schema={"type": "object", "properties": {"code": {"type": "string"}}},
+            tags=["code", "sandbox"]
+        ),
+        ToolDescriptor(
+            name="vision_analysis",
+            description="Analizza immagini e screenshot tramite OCR e modelli Vision",
+            provider_id="hf-space-2",
+            input_schema={"type": "object", "properties": {"image_url": {"type": "string"}}},
+            tags=["vision", "ocr"]
+        )
+    ]
+    
+    for tool in tools:
+        try:
+            await tool_registry.register(tool, force=True)
+        except Exception as e:
+            _logger.error(f"Errore registrazione tool {tool.name}: {e}")
+
+    _logger.info(f"Bootstrap completato: {len(tools)} tool registrati.")

api/brain_planner.py

@@ -0,0 +1,253 @@
+"""
+backend/api/brain_planner.py — Brain Planner (ARCH-I4.1)
+
+Componente Planner del Brain: reasoning, planning, decomposition, reflection.
+Produce WorkflowPlan (lista ordinata di PlanStep) senza sapere come eseguirli.
+
+Il Brain è ora separato in:
+  BrainPlanner  → "cosa fare e in che ordine" (questo file)
+  BrainExecutor → "come eseguire lo stato" (brain_executor.py)
+
+Flusso:
+  Kernel.submit_task(payload, capability="plan") → BrainPlanner.plan(goal)
+  → WorkflowPlan(steps=[PlanStep,...])
+  → BrainExecutor.execute_plan(plan) → [Kernel.submit_task per ogni step]
+
+Invarianti ADR:
+  S4:  Brain non conosce l'infrastruttura
+  S9:  Planner ignora come Executor esegue
+  S21: Brain dipende solo dal Kernel
+  S27: ogni piano tracciato via plan_id
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+import uuid
+from typing import Any, Literal
+
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel, Field
+
+from .auth_guard import AuthRole, require_role
+
+_logger = logging.getLogger("api.brain_planner")
+
+# ── Resolver guard ─────────────────────────────────────────────────────────────
+try:
+    from .capability_resolver import resolver as _resolver, ResolveRequest as _RReq
+    _RESOLVER_AVAILABLE = True
+except Exception:
+    _resolver = None   # type: ignore[assignment]
+    _RESOLVER_AVAILABLE = False
+
+# ── Models ──────────────────────────────────────────────────────────────────────
+
+class PlanStep(BaseModel):
+    """Singolo step del piano — capability + payload + dipendenze."""
+    step_id:      str            = Field(default_factory=lambda: str(uuid.uuid4()))
+    capability:   str            = Field(..., description="Capability richiesta per questo step")
+    description:  str            = Field("", description="Descrizione human-readable")
+    payload:      dict[str, Any] = Field(default_factory=dict)
+    depends_on:   list[str]      = Field(default_factory=list,
+                                         description="step_id degli step da completare prima")
+    timeout_s:    int            = Field(60)
+    retry_max:    int            = Field(2)
+    optional:     bool           = Field(False, description="Se True, fallimento non blocca il piano")
+    requires_gpu: bool           = Field(False)
+    metadata:     dict[str, Any] = Field(default_factory=dict)
+
+
+class WorkflowPlan(BaseModel):
+    """Piano di esecuzione prodotto dal Planner — input per il Workflow Engine."""
+    plan_id:     str             = Field(default_factory=lambda: str(uuid.uuid4()))
+    goal:        str             = Field(..., description="Obiettivo originale")
+    strategy:    Literal["sequential", "parallel", "dag"] = Field(
+                                   "sequential",
+                                   description="sequential=step uno alla volta, "
+                                               "parallel=tutti in parallelo, "
+                                               "dag=dipendenze esplicite tra step")
+    steps:       list[PlanStep]  = Field(default_factory=list)
+    context:     dict[str, Any]  = Field(default_factory=dict,
+                                         description="Contesto condiviso tra gli step")
+    created_at:  float           = Field(default_factory=time.time)
+    metadata:    dict[str, Any]  = Field(default_factory=dict)
+
+    def validate_dag(self) -> list[str]:
+        """Verifica che il DAG non abbia cicli. Ritorna errori (lista vuota = ok)."""
+        step_ids = {s.step_id for s in self.steps}
+        errors   = []
+        for step in self.steps:
+            for dep in step.depends_on:
+                if dep not in step_ids:
+                    errors.append(f"Step {step.step_id}: dipende da {dep} che non esiste nel piano")
+        return errors
+
+
+class PlanRequest(BaseModel):
+    goal:           str            = Field(..., description="Obiettivo da pianificare")
+    context:        dict[str, Any] = Field(default_factory=dict)
+    strategy:       Literal["sequential", "parallel", "dag"] = "sequential"
+    max_steps:      int            = Field(10, description="Numero massimo di step nel piano")
+    session_id:     str | None     = None
+    correlation_id: str            = Field(default_factory=lambda: str(uuid.uuid4()))
+    hints:          list[str]      = Field(default_factory=list,
+                                           description="Capability suggerite dal caller")
+
+
+class ReflectRequest(BaseModel):
+    """Richiesta di reflection su un piano eseguito (per migliorare piani futuri)."""
+    plan_id:        str
+    outcome:        Literal["success", "partial", "failure"]
+    failed_steps:   list[str]      = Field(default_factory=list)
+    notes:          str            = ""
+    correlation_id: str            = Field(default_factory=lambda: str(uuid.uuid4()))
+
+
+# ── BrainPlanner singleton ──────────────────────────────────────────────────────
+
+class BrainPlanner:
+    """
+    Planner del Brain: data un goal, produce un WorkflowPlan.
+
+    Strategia di planning (senza LLM, rule-based per ora):
+      1. Decomposizione goal → capability necessarie (via Resolver + hints)
+      2. Ordinamento step (sequenziale per default, DAG se dipendenze esplicite)
+      3. Validazione piano (no cicli, capabilities disponibili)
+      4. Reflection store (memorizza piani e outcome per futuro miglioramento)
+
+    Nota: la versione LLM-based (reasoning con modello) sarà ARCH-I4.1 Phase 2.
+    Questa implementazione è rule-based e serve a definire il contratto.
+    """
+
+    def __init__(self) -> None:
+        self._plans:      dict[str, WorkflowPlan]  = {}   # plan_id → plan
+        self._reflections: list[dict[str, Any]]    = []   # storia reflection
+        self._lock        = asyncio.Lock()
+
+    # ── Plan ──────────────────────────────────────────────────────────────────
+
+    async def plan(self, req: PlanRequest) -> WorkflowPlan:
+        """
+        Produce un WorkflowPlan dal goal.
+
+        Step logic (rule-based):
+          - Se hints presenti: crea uno step per ogni hint
+          - Altrimenti: step singolo con capability "llm" (Brain decide runtime)
+          - Verifica che ogni capability sia risolvibile dal Resolver
+        """
+        capabilities = req.hints if req.hints else ["llm"]
+        # Verifica capabilities via Resolver
+        verified_caps = []
+        for cap in capabilities[:req.max_steps]:
+            if _RESOLVER_AVAILABLE and _resolver is not None:
+                if _resolver.can_resolve(cap):
+                    verified_caps.append(cap)
+                else:
+                    _logger.warning("[planner] capability '%s' non risolvibile — esclusa dal piano", cap)
+            else:
+                verified_caps.append(cap)   # no resolver: trust hints
+
+        if not verified_caps:
+            verified_caps = ["llm"]   # fallback sempre
+
+        # Costruisci steps
+        steps = []
+        prev_id: str | None = None
+        for cap in verified_caps:
+            step = PlanStep(
+                capability  = cap,
+                description = f"Esegui capability '{cap}' per goal: {req.goal[:80]}",
+                payload     = {"goal": req.goal, **req.context},
+                depends_on  = [prev_id] if (req.strategy == "sequential" and prev_id) else [],
+                timeout_s   = 120,
+            )
+            steps.append(step)
+            prev_id = step.step_id
+
+        plan = WorkflowPlan(
+            goal     = req.goal,
+            strategy = req.strategy,
+            steps    = steps,
+            context  = req.context,
+            metadata = {"session_id": req.session_id, "correlation_id": req.correlation_id},
+        )
+
+        # Validate DAG
+        errors = plan.validate_dag()
+        if errors:
+            raise ValueError("Piano DAG non valido: " + "; ".join(errors))
+
+        async with self._lock:
+            self._plans[plan.plan_id] = plan
+        _logger.info("[planner] plan created plan_id=%s goal=%s steps=%d strategy=%s",
+                     plan.plan_id, req.goal[:40], len(steps), req.strategy)
+        return plan
+
+    def get_plan(self, plan_id: str) -> WorkflowPlan | None:
+        return self._plans.get(plan_id)
+
+    # ── Reflect ───────────────────────────────────────────────────────────────
+
+    async def reflect(self, req: ReflectRequest) -> dict:
+        """Registra l'outcome di un piano — base per miglioramento futuro."""
+        plan = self._plans.get(req.plan_id)
+        entry = {
+            "plan_id":     req.plan_id,
+            "goal":        plan.goal if plan else "unknown",
+            "outcome":     req.outcome,
+            "failed_steps": req.failed_steps,
+            "notes":       req.notes,
+            "ts":          time.time(),
+        }
+        async with self._lock:
+            self._reflections.append(entry)
+            if len(self._reflections) > 500:   # cap
+                self._reflections = self._reflections[-500:]
+        _logger.info("[planner] reflect plan=%s outcome=%s", req.plan_id, req.outcome)
+        return {"reflected": True, "plan_id": req.plan_id, "outcome": req.outcome}
+
+    def status(self) -> dict:
+        return {
+            "total_plans":      len(self._plans),
+            "total_reflections": len(self._reflections),
+            "resolver_available": _RESOLVER_AVAILABLE,
+        }
+
+
+# ── Singleton ───────��────────────────────────────────────────────────────────────
+planner = BrainPlanner()
+
+# ── HTTP Router ──────────────────────────────────────────────────────────────────
+router = APIRouter(
+    prefix="/api/brain",
+    tags=["brain-planner"],
+    dependencies=[Depends(require_role(AuthRole.MACHINE))],
+)
+
+
+@router.post("/plan", summary="Pianifica un goal → WorkflowPlan")
+async def route_plan(req: PlanRequest) -> WorkflowPlan:
+    try:
+        return await planner.plan(req)
+    except ValueError as exc:
+        raise HTTPException(400, str(exc))
+
+
+@router.get("/plan/{plan_id}", summary="Recupera un piano esistente")
+async def route_get_plan(plan_id: str) -> WorkflowPlan:
+    p = planner.get_plan(plan_id)
+    if not p:
+        raise HTTPException(404, f"Piano '{plan_id}' non trovato")
+    return p
+
+
+@router.post("/reflect", summary="Reflection su un piano eseguito")
+async def route_reflect(req: ReflectRequest) -> dict:
+    return await planner.reflect(req)
+
+
+@router.get("/planner/status", summary="Stato del BrainPlanner")
+async def route_status() -> dict:
+    return planner.status()

api/cache_endpoints.py

@@ -0,0 +1,164 @@
+"""
+cache_endpoints.py — Endpoint API per Gestione Cache
+
+Endpoint:
+  GET  /api/cache/stats           — Statistiche cache
+  POST /api/cache/invalidate      — Invalida un entry
+  GET  /api/cache/health          — Health check cache
+  POST /api/cache/reset-stats     — Resetta statistiche
+"""
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+from typing import Optional
+import logging
+
+# Import cache manager
+try:
+    from backend.api.cache_manager import (
+        get_cache_stats,
+        reset_cache_stats,
+        invalidate_cache,
+        CacheStrategy,
+        CACHE_ENABLED,
+    )
+except ImportError:
+    from cache_manager import (
+        get_cache_stats,
+        reset_cache_stats,
+        invalidate_cache,
+        CacheStrategy,
+        CACHE_ENABLED,
+    )
+
+_logger = logging.getLogger("cache_endpoints")
+
+router = APIRouter(prefix="/api/cache", tags=["cache"])
+
+
+# ── Modelli Pydantic ──────────────────────────────────────────────────────
+class InvalidateCacheRequest(BaseModel):
+    strategy: str  # "query", "memory", "embedding", "conversation", "analytics"
+    identifier: str
+
+
+class CacheStatsResponse(BaseModel):
+    enabled: bool
+    hits: int
+    misses: int
+    sets: int
+    deletes: int
+    evictions: int
+    hit_rate_percent: float
+    total_requests: int
+
+
+class CacheHealthResponse(BaseModel):
+    ok: bool
+    cache_enabled: bool
+    message: str
+
+
+# ── Endpoint: Statistiche Cache ────────────────────────────────────────────
+@router.get("/stats", response_model=CacheStatsResponse)
+async def cache_stats():
+    """Ritorna le statistiche del cache layer."""
+    try:
+        stats = get_cache_stats()
+        return CacheStatsResponse(**stats)
+    except Exception as exc:
+        _logger.error(f"Error fetching cache stats: {exc}")
+        raise HTTPException(500, "Error fetching cache stats")
+
+
+# ── Endpoint: Invalida Cache ──────────────────────────────────────────────
+@router.post("/invalidate")
+async def invalidate_cache_entry(req: InvalidateCacheRequest):
+    """Invalida un entry specifico dalla cache."""
+    try:
+        # Valida strategy
+        try:
+            strategy = CacheStrategy(req.strategy)
+        except ValueError:
+            raise HTTPException(
+                400,
+                f"Invalid strategy. Must be one of: {', '.join([s.value for s in CacheStrategy])}",
+            )
+        
+        # Invalida
+        success = await invalidate_cache(strategy, req.identifier)
+        
+        return {
+            "ok": success,
+            "strategy": req.strategy,
+            "identifier": req.identifier,
+            "message": "Cache entry invalidated" if success else "Failed to invalidate cache entry",
+        }
+    except HTTPException:
+        raise
+    except Exception as exc:
+        _logger.error(f"Error invalidating cache: {exc}")
+        raise HTTPException(500, "Error invalidating cache")
+
+
+# ── Endpoint: Health Check ────────────────────────────────────────────────
+@router.get("/health", response_model=CacheHealthResponse)
+async def cache_health():
+    """Health check per il cache layer."""
+    try:
+        stats = get_cache_stats()
+        
+        return CacheHealthResponse(
+            ok=True,
+            cache_enabled=CACHE_ENABLED,
+            message=f"Cache layer operational. Hit rate: {stats.get('hit_rate_percent', 0):.1f}%",
+        )
+    except Exception as exc:
+        _logger.error(f"Cache health check failed: {exc}")
+        return CacheHealthResponse(
+            ok=False,
+            cache_enabled=CACHE_ENABLED,
+            message=f"Cache health check failed: {str(exc)}",
+        )
+
+
+# ── Endpoint: Reset Statistiche ───────────────────────────────────────────
+@router.post("/reset-stats")
+async def reset_stats():
+    """Resetta le statistiche del cache."""
+    try:
+        reset_cache_stats()
+        return {
+            "ok": True,
+            "message": "Cache statistics reset",
+        }
+    except Exception as exc:
+        _logger.error(f"Error resetting cache stats: {exc}")
+        raise HTTPException(500, "Error resetting cache stats")
+
+
+# ── Endpoint: Info Cache ──────────────────────────────────────────────────
+@router.get("/info")
+async def cache_info():
+    """Ritorna informazioni sulla configurazione del cache."""
+    try:
+        from cache_manager import (
+            CACHE_ENABLED,
+            CACHE_TTL_DEFAULT,
+            CACHE_MAX_SIZE,
+            CACHE_TTL_BY_STRATEGY,
+            SUPABASE_A_URL,
+            SUPABASE_B_URL,
+        )
+        
+        return {
+            "enabled": CACHE_ENABLED,
+            "ttl_default_seconds": CACHE_TTL_DEFAULT,
+            "max_size": CACHE_MAX_SIZE,
+            "ttl_by_strategy": {k.value: v for k, v in CACHE_TTL_BY_STRATEGY.items()},
+            "supabase_a_configured": bool(SUPABASE_A_URL),
+            "supabase_b_configured": bool(SUPABASE_B_URL),
+        }
+    except Exception as exc:
+        _logger.error(f"Error fetching cache info: {exc}")
+        raise HTTPException(500, "Error fetching cache info")

api/cache_manager.py

@@ -0,0 +1,400 @@
+"""
+cache_manager.py — Cache Layer Distribuito su Supabase A
+
+Architettura:
+  - Supabase A funge da archivio cache distribuito (read-only, non-critical)
+  - TTL configurabile per invalidazione automatica
+  - Fallback a B se A non disponibile
+  - Supporta cache per query, memoria, embeddings, conversazioni
+
+Strategie di Caching:
+  1. Query Cache: Risultati query SELECT memorizzati con TTL
+  2. Memory Cache: Memoria agente memorizzata per accesso veloce
+  3. Embedding Cache: Embeddings pre-calcolati per RAG
+  4. Conversation Cache: Conversazioni recenti per accesso veloce
+
+Invalidazione:
+  - TTL-based: Scadenza automatica dopo TTL
+  - Event-based: Invalidazione su INSERT/UPDATE/DELETE su B
+  - Manual: Invalidazione esplicita via API
+
+Statistiche:
+  - Hit rate: % di richieste servite da cache
+  - Miss rate: % di richieste non in cache
+  - Eviction rate: % di entry rimosse per TTL
+"""
+
+import os
+import asyncio
+import logging
+import hashlib
+import json
+from typing import Optional, Dict, List, Any, Callable
+from datetime import datetime, timedelta
+from enum import Enum
+import time
+
+_logger = logging.getLogger("cache_manager")
+
+# ── Configurazione Cache ───────────────────────────────────────────────────
+CACHE_ENABLED = os.getenv("SUPABASE_CACHE_ENABLED", "true").lower() == "true"
+CACHE_TTL_DEFAULT = int(os.getenv("SUPABASE_CACHE_TTL", "3600"))  # 1 ora
+CACHE_MAX_SIZE = int(os.getenv("SUPABASE_CACHE_MAX_SIZE", "10000"))  # max entries
+CACHE_STATS_ENABLED = os.getenv("SUPABASE_CACHE_STATS_ENABLED", "true").lower() == "true"
+
+# ── Enumerazione Strategie Cache ───────────────────────────────────────────
+class CacheStrategy(str, Enum):
+    QUERY = "query"  # Cache risultati query
+    MEMORY = "memory"  # Cache memoria agente
+    EMBEDDING = "embedding"  # Cache embeddings
+    CONVERSATION = "conversation"  # Cache conversazioni
+    ANALYTICS = "analytics"  # Cache analytics/reporting
+
+
+# ── TTL per Strategia ─────────────────────────────────────────────────────
+CACHE_TTL_BY_STRATEGY = {
+    CacheStrategy.QUERY: int(os.getenv("CACHE_TTL_QUERY", "600")),  # 10 min
+    CacheStrategy.MEMORY: int(os.getenv("CACHE_TTL_MEMORY", "1800")),  # 30 min
+    CacheStrategy.EMBEDDING: int(os.getenv("CACHE_TTL_EMBEDDING", "7200")),  # 2 ore
+    CacheStrategy.CONVERSATION: int(os.getenv("CACHE_TTL_CONVERSATION", "3600")),  # 1 ora
+    CacheStrategy.ANALYTICS: int(os.getenv("CACHE_TTL_ANALYTICS", "300")),  # 5 min
+}
+
+# ── Configurazione Supabase A ──────────────────────────────────────────────
+SUPABASE_A_URL = os.getenv("SUPABASE_URL_A", "")
+SUPABASE_A_KEY = os.getenv("SUPABASE_KEY_A", "")
+SUPABASE_B_URL = os.getenv("SUPABASE_URL", "")
+SUPABASE_B_KEY = os.getenv("SUPABASE_KEY", "")
+
+
+# ── Client Cache ───────────────────────────────────────────────────────────
+class CacheClient:
+    """Client per gestire cache su Supabase A."""
+    
+    def __init__(self, url: str, key: str):
+        self.url = url
+        self.key = key
+        self.base_url = f"{url}/rest/v1" if url else None
+        self._stats = {
+            "hits": 0,
+            "misses": 0,
+            "sets": 0,
+            "deletes": 0,
+            "evictions": 0,
+        }
+    
+    def _generate_cache_key(self, strategy: str, identifier: str) -> str:
+        """Genera una chiave cache univoca."""
+        combined = f"{strategy}:{identifier}"
+        return hashlib.sha256(combined.encode()).hexdigest()[:32]
+    
+    async def get(self, strategy: CacheStrategy, identifier: str) -> Optional[Dict]:
+        """Recupera un valore dalla cache."""
+        if not CACHE_ENABLED or not self.base_url:
+            return None
+        
+        cache_key = self._generate_cache_key(strategy.value, identifier)
+        
+        try:
+            import httpx
+            
+            url = f"{self.base_url}/cache_entries?cache_key=eq.{cache_key}"
+            headers = {
+                "apikey": self.key,
+                "Authorization": f"Bearer {self.key}",
+                "Content-Type": "application/json",
+            }
+            
+            async with httpx.AsyncClient() as client:
+                response = await client.get(url, headers=headers, timeout=5.0)
+                
+                if response.status_code == 200:
+                    rows = response.json()
+                    if rows:
+                        entry = rows[0]
+                        
+                        # Verifica TTL
+                        if self._is_expired(entry):
+                            # Elimina entry scaduta
+                            await self._delete_entry(cache_key)
+                            if CACHE_STATS_ENABLED:
+                                self._stats["evictions"] += 1
+                            return None
+                        
+                        # Hit
+                        if CACHE_STATS_ENABLED:
+                            self._stats["hits"] += 1
+                        
+                        return {
+                            "value": entry.get("value"),
+                            "cached_at": entry.get("created_at"),
+                            "ttl_remaining": self._get_ttl_remaining(entry),
+                        }
+                
+                # Miss
+                if CACHE_STATS_ENABLED:
+                    self._stats["misses"] += 1
+                return None
+        
+        except Exception as exc:
+            _logger.error(f"Cache get error: {exc}")
+            return None
+    
+    async def set(
+        self,
+        strategy: CacheStrategy,
+        identifier: str,
+        value: Any,
+        ttl: Optional[int] = None,
+    ) -> bool:
+        """Memorizza un valore nella cache."""
+        if not CACHE_ENABLED or not self.base_url:
+            return False
+        
+        cache_key = self._generate_cache_key(strategy.value, identifier)
+        ttl = ttl or CACHE_TTL_BY_STRATEGY.get(strategy, CACHE_TTL_DEFAULT)
+        
+        try:
+            import httpx
+            
+            url = f"{self.base_url}/cache_entries"
+            headers = {
+                "apikey": self.key,
+                "Authorization": f"Bearer {self.key}",
+                "Content-Type": "application/json",
+            }
+            
+            data = {
+                "cache_key": cache_key,
+                "strategy": strategy.value,
+                "identifier": identifier,
+                "value": json.dumps(value) if not isinstance(value, str) else value,
+                "ttl_seconds": ttl,
+                "created_at": datetime.now().isoformat(),
+                "expires_at": (datetime.now() + timedelta(seconds=ttl)).isoformat(),
+            }
+            
+            async with httpx.AsyncClient() as client:
+                response = await client.post(url, json=data, headers=headers, timeout=5.0)
+                
+                if response.status_code in (200, 201):
+                    if CACHE_STATS_ENABLED:
+                        self._stats["sets"] += 1
+                    return True
+                else:
+                    _logger.warning(f"Cache set failed: {response.status_code}")
+                    return False
+        
+        except Exception as exc:
+            _logger.error(f"Cache set error: {exc}")
+            return False
+    
+    async def delete(self, strategy: CacheStrategy, identifier: str) -> bool:
+        """Elimina un valore dalla cache."""
+        if not CACHE_ENABLED or not self.base_url:
+            return False
+        
+        cache_key = self._generate_cache_key(strategy.value, identifier)
+        return await self._delete_entry(cache_key)
+    
+    async def _delete_entry(self, cache_key: str) -> bool:
+        """Elimina un entry dalla cache per chiave."""
+        try:
+            import httpx
+            
+            url = f"{self.base_url}/cache_entries?cache_key=eq.{cache_key}"
+            headers = {
+                "apikey": self.key,
+                "Authorization": f"Bearer {self.key}",
+            }
+            
+            async with httpx.AsyncClient() as client:
+                response = await client.delete(url, headers=headers, timeout=5.0)
+                
+                if response.status_code in (200, 204):
+                    if CACHE_STATS_ENABLED:
+                        self._stats["deletes"] += 1
+                    return True
+                return False
+        
+        except Exception as exc:
+            _logger.error(f"Cache delete error: {exc}")
+            return False
+    
+    def _is_expired(self, entry: Dict) -> bool:
+        """Verifica se un entry è scaduto."""
+        expires_at = entry.get("expires_at")
+        if not expires_at:
+            return False
+        
+        try:
+            expires_dt = datetime.fromisoformat(expires_at)
+            return datetime.now() > expires_dt
+        except:
+            return False
+    
+    def _get_ttl_remaining(self, entry: Dict) -> int:
+        """Calcola il TTL rimanente in secondi."""
+        expires_at = entry.get("expires_at")
+        if not expires_at:
+            return 0
+        
+        try:
+            expires_dt = datetime.fromisoformat(expires_at)
+            remaining = (expires_dt - datetime.now()).total_seconds()
+            return max(0, int(remaining))
+        except:
+            return 0
+    
+    def get_stats(self) -> Dict[str, Any]:
+        """Ritorna statistiche cache."""
+        total = self._stats["hits"] + self._stats["misses"]
+        hit_rate = (self._stats["hits"] / total * 100) if total > 0 else 0
+        
+        return {
+            "enabled": CACHE_ENABLED,
+            "hits": self._stats["hits"],
+            "misses": self._stats["misses"],
+            "sets": self._stats["sets"],
+            "deletes": self._stats["deletes"],
+            "evictions": self._stats["evictions"],
+            "hit_rate_percent": round(hit_rate, 2),
+            "total_requests": total,
+        }
+    
+    def reset_stats(self):
+        """Resetta le statistiche."""
+        self._stats = {
+            "hits": 0,
+            "misses": 0,
+            "sets": 0,
+            "deletes": 0,
+            "evictions": 0,
+        }
+
+
+# ── Cache Wrapper con Fallback ─────────────────────────────────────────────
+class CacheManager:
+    """Gestore cache con fallback intelligente."""
+    
+    def __init__(self):
+        self.cache_client = CacheClient(SUPABASE_A_URL, SUPABASE_A_KEY) if SUPABASE_A_URL else None
+        self.fallback_client = CacheClient(SUPABASE_B_URL, SUPABASE_B_KEY) if SUPABASE_B_URL else None
+    
+    async def get_or_fetch(
+        self,
+        strategy: CacheStrategy,
+        identifier: str,
+        fetch_fn: Callable,
+        ttl: Optional[int] = None,
+    ) -> Any:
+        """
+        Recupera valore da cache o lo genera con fetch_fn.
+        
+        Logica:
+        1. Prova a leggere da cache A
+        2. Se miss, chiama fetch_fn
+        3. Memorizza risultato in cache A
+        4. Ritorna valore
+        """
+        # Prova cache A
+        if self.cache_client:
+            cached = await self.cache_client.get(strategy, identifier)
+            if cached:
+                _logger.debug(f"Cache hit: {strategy.value}:{identifier}")
+                return json.loads(cached["value"]) if isinstance(cached["value"], str) else cached["value"]
+        
+        # Cache miss → fetch
+        _logger.debug(f"Cache miss: {strategy.value}:{identifier}, fetching...")
+        try:
+            value = await fetch_fn() if asyncio.iscoroutinefunction(fetch_fn) else fetch_fn()
+        except Exception as exc:
+            _logger.error(f"Fetch error: {exc}")
+            return None
+        
+        # Memorizza in cache A
+        if self.cache_client and value is not None:
+            ttl = ttl or CACHE_TTL_BY_STRATEGY.get(strategy, CACHE_TTL_DEFAULT)
+            await self.cache_client.set(strategy, identifier, value, ttl)
+        
+        return value
+    
+    async def invalidate(self, strategy: CacheStrategy, identifier: str) -> bool:
+        """Invalida un entry cache."""
+        if self.cache_client:
+            return await self.cache_client.delete(strategy, identifier)
+        return False
+    
+    async def invalidate_pattern(self, strategy: CacheStrategy, pattern: str) -> int:
+        """Invalida tutti gli entry che corrispondono a un pattern."""
+        # TODO: Implementare pattern matching
+        return 0
+    
+    def get_stats(self) -> Dict[str, Any]:
+        """Ritorna statistiche cache."""
+        if self.cache_client:
+            return self.cache_client.get_stats()
+        return {"enabled": False}
+    
+    def reset_stats(self):
+        """Resetta statistiche."""
+        if self.cache_client:
+            self.cache_client.reset_stats()
+
+
+# ── Istanza Globale ───────────────────────────────────────────────────────
+_cache_manager = CacheManager()
+
+
+# ── Funzioni Pubbliche ────────────────────────────────────────────────────
+async def get_cached(
+    strategy: CacheStrategy,
+    identifier: str,
+    fetch_fn: Callable,
+    ttl: Optional[int] = None,
+) -> Any:
+    """Recupera valore da cache o lo genera."""
+    return await _cache_manager.get_or_fetch(strategy, identifier, fetch_fn, ttl)
+
+
+async def invalidate_cache(strategy: CacheStrategy, identifier: str) -> bool:
+    """Invalida un entry cache."""
+    return await _cache_manager.invalidate(strategy, identifier)
+
+
+def get_cache_stats() -> Dict[str, Any]:
+    """Ritorna statistiche cache."""
+    return _cache_manager.get_stats()
+
+
+def reset_cache_stats():
+    """Resetta statistiche cache."""
+    _cache_manager.reset_stats()
+
+
+# ── Decorator per Caching Automatico ───────────────────────────────────────
+def cached(strategy: CacheStrategy, ttl: Optional[int] = None):
+    """
+    Decorator per caching automatico di funzioni.
+    
+    Uso:
+        @cached(CacheStrategy.QUERY, ttl=600)
+        async def get_user_data(user_id: str):
+            return await fetch_user_from_db(user_id)
+    """
+    def decorator(func: Callable):
+        async def wrapper(*args, **kwargs):
+            # Genera identifier da args/kwargs
+            identifier = f"{func.__name__}:{str(args)}:{str(kwargs)}"
+            
+            # Usa cache manager
+            return await _cache_manager.get_or_fetch(
+                strategy,
+                identifier,
+                lambda: func(*args, **kwargs),
+                ttl,
+            )
+        
+        return wrapper
+    
+    return decorator

api/capability_catalog.py

@@ -0,0 +1,348 @@
+"""
+backend/api/capability_catalog.py — Capability Marketplace Catalog (ARCH-E3.1)
+
+Catalogo dinamico dove ogni Worker registra le proprie capabilities con metadati
+completi: versione, SLA, latenza target, GPU, costo, tag, disponibilità, regione.
+
+Il Brain NON conosce i Worker — chiede una capability, il Kernel + Fabric scelgono.
+Il Catalog è il registro centrale di discovery; il Fabric usa il Catalog per lo scoring.
+
+Flusso:
+  Worker  → POST /api/catalog/register              → entry creata/aggiornata con TTL
+  Worker  → POST /api/catalog/heartbeat             → TTL rinnovato
+  Fabric  → (auto) register all'init                → fleet registrata automaticamente
+  Client  → GET  /api/catalog/capabilities          → lista capabilities vive
+  Client  → GET  /api/catalog/capabilities/{name}   → providers per una capability
+  Client  → GET  /api/catalog/status                → diagnostica + contatori
+
+Invarianti ADR:
+  S9:  ogni servizio ignora l'impl interna degli altri
+  S19: nessun vendor lock-in — qualsiasi Worker può registrarsi
+  S20: routing intent-based, non hardcoded
+  S27: ogni capability tracciabile via provider_id + correlation_id
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from typing import Any
+
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel, Field
+
+from .auth_guard import AuthRole, require_role
+
+_logger = logging.getLogger("api.capability_catalog")
+
+# ── TTL / cleanup config ────────────────────────────────────────────────────────
+_ENTRY_TTL_S:       float = float(__import__("os").getenv("CATALOG_TTL_S",       "300"))   # 5 min
+_CLEANUP_INTERVAL_S: int  = int(__import__("os").getenv("CATALOG_CLEANUP_S",      "60"))   # 1 min
+
+# ── Models ──────────────────────────────────────────────────────────────────────
+
+class CapabilityDescriptor(BaseModel):
+    """Descrittore completo di una singola capability offerta da un provider."""
+    name:            str            = Field(...,       description="Nome capability, es. 'browser', 'python_sandbox'")
+    version:         str            = Field("1.0.0",  description="Versione semantica (semver)")
+    provider_id:     str            = Field(...,       description="ID univoco del provider")
+    provider_name:   str            = Field("",        description="Nome human-readable del provider")
+    description:     str            = Field("",        description="Descrizione funzionale breve")
+    tags:            list[str]      = Field(default_factory=list, description="Tag per discovery intent-based")
+    requires_gpu:    bool           = Field(False,     description="Richiede GPU")
+    sla_ms:          float          = Field(5000.0,   description="Target latency SLA in ms (p95)")
+    max_payload_kb:  int            = Field(1024,      description="Payload massimo accettato in KB")
+    cost_unit:       float          = Field(0.0,       description="Costo per invocazione (0 = free)")
+    region:          str            = Field("us",      description="Regione di deployment")
+    always_on:       bool           = Field(True,      description="Provider sempre attivo (no cold start)")
+    registered_at:   float          = Field(default_factory=time.time)
+    last_heartbeat:  float          = Field(default_factory=time.time)
+    metadata:        dict[str, Any] = Field(default_factory=dict, description="Metadati extra provider-specifici")
+
+
+class RegisterRequest(BaseModel):
+    descriptors: list[CapabilityDescriptor] = Field(
+        ..., description="Lista capability da registrare per questo provider"
+    )
+
+
+class HeartbeatRequest(BaseModel):
+    provider_id:      str
+    capability_names: list[str] | None = None   # None = tutte le capability del provider
+
+
+# ── CapabilityCatalog singleton ─────────────────────────────────────────────────
+
+class CapabilityCatalog:
+    """
+    Registro dinamico di tutte le capabilities disponibili nel sistema.
+
+    Struttura interna:
+      _entries: { (provider_id, capability_name) → CapabilityDescriptor }
+
+    Thread/task safety: lock asyncio su tutte le mutazioni.
+    """
+
+    def __init__(self) -> None:
+        self._entries: dict[tuple[str, str], CapabilityDescriptor] = {}
+        self._lock    = asyncio.Lock()
+        self._cleanup_task: asyncio.Task | None = None
+
+    # ── Registration ──────────────────────────────────────────────────────────
+
+    async def register(self, descriptors: list[CapabilityDescriptor]) -> int:
+        """Registra/aggiorna N capabilities. Ritorna il numero di entry salvate."""
+        async with self._lock:
+            now = time.time()
+            for d in descriptors:
+                d.registered_at  = now
+                d.last_heartbeat = now
+                self._entries[(d.provider_id, d.name)] = d
+        count = len(descriptors)
+        _logger.info("[catalog] registered %d capabilities from provider=%s",
+                     count, descriptors[0].provider_id if descriptors else "?")
+        return count
+
+    async def deregister(self, provider_id: str, capability_names: list[str] | None = None) -> int:
+        """Rimuove capability di un provider (o subset se specificato)."""
+        async with self._lock:
+            to_del = [
+                k for k in self._entries
+                if k[0] == provider_id and (capability_names is None or k[1] in capability_names)
+            ]
+            for k in to_del:
+                del self._entries[k]
+        if to_del:
+            _logger.info("[catalog] deregistered %d capabilities from provider=%s",
+                         len(to_del), provider_id)
+        return len(to_del)
+
+    async def heartbeat(self, provider_id: str, capability_names: list[str] | None = None) -> int:
+        """Aggiorna last_heartbeat. Ritorna il numero di entry aggiornate."""
+        async with self._lock:
+            now   = time.time()
+            count = 0
+            for (pid, cname), d in self._entries.items():
+                if pid == provider_id and (capability_names is None or cname in capability_names):
+                    d.last_heartbeat = now
+                    count += 1
+        return count
+
+    # ── Query ─────────────────────────────────────────────────────────────────
+
+    def query(
+        self,
+        name:         str | None        = None,
+        tags:         list[str] | None  = None,
+        requires_gpu: bool | None       = None,
+        max_sla_ms:   float | None      = None,
+        region:       str | None        = None,
+        include_stale: bool             = False,
+    ) -> list[CapabilityDescriptor]:
+        """
+        Ricerca nel catalogo con filtri combinabili.
+        Di default ritorna solo entry vive (last_heartbeat entro TTL).
+        """
+        now     = time.time()
+        results = []
+        for d in self._entries.values():
+            if not include_stale and (now - d.last_heartbeat) > _ENTRY_TTL_S:
+                continue
+            if name and d.name != name:
+                continue
+            if tags and not any(t in d.tags for t in tags):
+                continue
+            if requires_gpu is not None and d.requires_gpu != requires_gpu:
+                continue
+            if max_sla_ms is not None and d.sla_ms > max_sla_ms:
+                continue
+            if region and d.region != region:
+                continue
+            results.append(d)
+        return results
+
+    def get_sla(self, capability_name: str, provider_id: str) -> float:
+        """
+        Ritorna sla_ms per una capability specifica, o 9999.0 se non trovata.
+        Non-blocking: lookup puro dict — safe da chiamare in _select().
+        """
+        d = self._entries.get((provider_id, capability_name))
+        return d.sla_ms if d else 9999.0
+
+    def all_entries(self, include_stale: bool = False) -> list[CapabilityDescriptor]:
+        """Lista completa (per diagnostica)."""
+        if include_stale:
+            return list(self._entries.values())
+        now = time.time()
+        return [d for d in self._entries.values() if (now - d.last_heartbeat) <= _ENTRY_TTL_S]
+
+    # ── Cleanup ───────────────────────────────────────────────────────────────
+
+    async def cleanup_stale(self) -> int:
+        """Rimuove entry con TTL scaduto. Chiamato dal loop interno."""
+        async with self._lock:
+            now   = time.time()
+            stale = [k for k, d in self._entries.items()
+                     if (now - d.last_heartbeat) > _ENTRY_TTL_S]
+            for k in stale:
+                del self._entries[k]
+        if stale:
+            _logger.warning("[catalog] cleanup: removed %d stale entries", len(stale))
+        return len(stale)
+
+    async def _cleanup_loop(self) -> None:
+        while True:
+            await asyncio.sleep(_CLEANUP_INTERVAL_S)
+            try:
+                await self.cleanup_stale()
+            except Exception as exc:
+                _logger.warning("[catalog] cleanup error: %s", exc)
+
+    def start_cleanup_loop(self) -> None:
+        """Avvia background cleanup. Chiamare in on_startup."""
+        if self._cleanup_task is None or self._cleanup_task.done():
+            self._cleanup_task = asyncio.create_task(self._cleanup_loop())
+            _logger.info("[catalog] cleanup loop started (TTL=%ds, interval=%ds)",
+                         int(_ENTRY_TTL_S), _CLEANUP_INTERVAL_S)
+
+
+# ── Singleton ───────────────────────────────────────────────────────────────────
+catalog = CapabilityCatalog()
+
+# ── HTTP Router ─────────────────────────────────────────────────────────────────
+router = APIRouter(
+    prefix="/api/catalog",
+    tags=["capability-catalog"],
+    dependencies=[Depends(require_role(AuthRole.MACHINE))],
+)
+
+
+@router.post("/register", summary="Registra capabilities di un Worker nel catalogo")
+async def route_register(req: RegisterRequest) -> dict:
+    if not req.descriptors:
+        raise HTTPException(400, "descriptors lista vuota")
+    count = await catalog.register(req.descriptors)
+    return {
+        "registered":  count,
+        "provider_id": req.descriptors[0].provider_id,
+    }
+
+
+@router.post("/heartbeat", summary="Rinnova TTL capabilities (keep-alive)")
+async def route_heartbeat(req: HeartbeatRequest) -> dict:
+    count = await catalog.heartbeat(req.provider_id, req.capability_names)
+    return {"updated": count, "provider_id": req.provider_id}
+
+
+@router.delete("/providers/{provider_id}", summary="Deregistra capabilities di un provider")
+async def route_deregister(provider_id: str) -> dict:
+    count = await catalog.deregister(provider_id)
+    return {"removed": count, "provider_id": provider_id}
+
+
+@router.get("/capabilities", summary="Lista capabilities disponibili con filtri")
+async def route_list_capabilities(
+    name:         str | None   = None,
+    tag:          str | None   = None,
+    requires_gpu: bool | None  = None,
+    max_sla_ms:   float | None = None,
+    region:       str | None   = None,
+) -> dict:
+    tags    = [tag] if tag else None
+    entries = catalog.query(name=name, tags=tags, requires_gpu=requires_gpu,
+                            max_sla_ms=max_sla_ms, region=region)
+    return {
+        "count":        len(entries),
+        "capabilities": [e.model_dump() for e in entries],
+    }
+
+
+@router.get("/capabilities/{capability_name}", summary="Dettaglio capability per nome")
+async def route_get_capability(capability_name: str) -> dict:
+    entries = catalog.query(name=capability_name)
+    if not entries:
+        raise HTTPException(404, f"Capability '{capability_name}' non trovata nel catalogo")
+    best = min(entries, key=lambda e: e.sla_ms)
+    return {
+        "capability":  capability_name,
+        "providers":   len(entries),
+        "best_sla_ms": best.sla_ms,
+        "best_provider": best.provider_id,
+        "descriptors": [e.model_dump() for e in sorted(entries, key=lambda e: e.sla_ms)],
+    }
+
+
+@router.get("/status", summary="Stato del catalogo e contatori")
+async def route_status() -> dict:
+    all_e  = catalog.all_entries(include_stale=True)
+    live   = catalog.all_entries()
+    stale  = len(all_e) - len(live)
+    by_prov: dict[str, int] = {}
+    for e in live:
+        by_prov[e.provider_id] = by_prov.get(e.provider_id, 0) + 1
+    unique_caps = sorted({e.name for e in live})
+    return {
+        "total_entries":       len(all_e),
+        "live_entries":        len(live),
+        "stale_entries":       stale,
+        "unique_capabilities": unique_caps,
+        "providers":           by_prov,
+        "ttl_s":               _ENTRY_TTL_S,
+        "cleanup_interval_s":  _CLEANUP_INTERVAL_S,
+    }
+
+
+# ── ARCH-E3.4: Worker self-announcement ────────────────────────────────────────
+
+class WorkerAnnouncement(BaseModel):
+    """
+    Payload che ogni Worker invia al boot per auto-registrare le proprie capabilities.
+    Sostituisce la registrazione manuale — il Worker conosce se stesso.
+    """
+    worker_id:    str            = Field(..., description="ID univoco del Worker, es. 'hf-space-browser'")
+    worker_name:  str            = Field(...)
+    worker_kind:  str            = Field("http", description="http | grpc | ws")
+    base_url:     str            = Field(..., description="URL base del Worker")
+    capabilities: list[str]      = Field(..., description="Lista capability esposte")
+    region:       str            = Field("global")
+    requires_gpu: bool           = Field(False)
+    sla_ms:       dict[str, float] = Field(default_factory=dict,
+                                          description="SLA per capability, es. {'browser': 8000}")
+    cost_unit:    float          = Field(0.0)
+    version:      str            = Field("1.0.0")
+    always_on:    bool           = Field(True)
+    tags:         list[str]      = Field(default_factory=list)
+    metadata:     dict           = Field(default_factory=dict)
+
+
+@router.post("/worker-announce", summary="Worker auto-registra le proprie capabilities al boot (ARCH-E3.4)")
+async def route_worker_announce(ann: WorkerAnnouncement) -> dict:
+    """
+    Endpoint chiamato dai Worker all'avvio per registrare capabilities nel Catalog.
+    Ogni capability riceve un CapabilityDescriptor auto-costruito dall'annuncio.
+    Esegue anche heartbeat se il worker è già registrato (idempotente).
+    """
+    descs = [
+        CapabilityDescriptor(
+            name          = cap,
+            version       = ann.version,
+            provider_id   = ann.worker_id,
+            provider_name = ann.worker_name,
+            sla_ms        = ann.sla_ms.get(cap, 5000.0),
+            requires_gpu  = ann.requires_gpu,
+            cost_unit     = ann.cost_unit,
+            region        = ann.region,
+            always_on     = ann.always_on,
+            tags          = ann.tags + ["worker", ann.worker_kind],
+            metadata      = {"base_url": ann.base_url, **ann.metadata},
+        )
+        for cap in ann.capabilities
+    ]
+    if descs:
+        await catalog.register(descs)
+    return {
+        "announced":    True,
+        "worker_id":    ann.worker_id,
+        "capabilities": ann.capabilities,
+        "registered":   len(descs),
+    }

api/capability_resolver.py

@@ -0,0 +1,441 @@
+"""
+backend/api/capability_resolver.py — Capability Resolver (ARCH-E3.2)
+
+Mappa le capability richieste dal Brain ai Worker disponibili nel Capability
+Catalog (ARCH-E3.1), scegliendo il provider ottimale in base a SLA, GPU,
+regione e salute operativa.
+
+Posizione nel flusso:
+  Brain → Kernel.submit_task(capability) → Resolver.resolve() → provider_hint
+  → ExecutionFabric.dispatch(provider_hint) → Worker
+
+Differenza con ExecutionFabric._select():
+  - Resolver: decisione DICHIARATIVA dal Catalog (metadata statici, SLA contratto)
+  - Fabric._select(): decisione OPERATIVA (health live, circuit breaker, concurrency)
+  Il resolver fornisce l'hint; il Fabric può ignorarlo se il provider è down.
+
+Funzionalità:
+  resolve(ResolveRequest)      → ResolveResult (migliore provider + alternative)
+  resolve_many([ResolveReq])   → list[ResolveResult] (bulk per Workflow Engine)
+  can_resolve(capability)      → bool (quick check senza scoring)
+
+HTTP Endpoints (auth: MACHINE):
+  POST /api/resolver/resolve        — risolve una singola capability
+  POST /api/resolver/resolve-many   — risolve N capability in bulk (workflow planning)
+  GET  /api/resolver/status         — diagnostica: capabilities risolvibili, contatori
+
+Invarianti ADR:
+  S4:  Brain non conosce l'infrastruttura
+  S9:  ogni servizio ignora l'impl interna degli altri
+  S19: nessun vendor lock-in — chiunque nel Catalog è eleggibile
+  S20: routing intent-based, non hardcoded
+  S27: ogni risoluzione tracciata via resolve_id
+"""
+from __future__ import annotations
+
+import logging
+import time
+import uuid
+from typing import Any
+
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel, Field
+
+from .auth_guard import AuthRole, require_role
+
+_logger = logging.getLogger("api.capability_resolver")
+
+# ── Catalog import (guard) ─────────────────────────────────────────────────────
+try:
+    from .capability_catalog import catalog as _catalog, CapabilityDescriptor as _CapDesc
+    _CATALOG_AVAILABLE = True
+except Exception:
+    _catalog = None  # type: ignore[assignment]
+    _CapDesc = None  # type: ignore[assignment]
+    _CATALOG_AVAILABLE = False
+
+# ── Fabric state import (guard) — per leggere health live senza accoppiamento ──
+try:
+    from .execution_fabric import fabric as _fabric
+    _FABRIC_AVAILABLE = True
+except Exception:
+    _fabric = None  # type: ignore[assignment]
+    _FABRIC_AVAILABLE = False
+
+# ── Scoring weights ────────────────────────────────────────────────────────────
+# ARCH-RESOLVER-FB: aggiunto _W_FEEDBACK — pesi bilanciati a 1.00
+_W_SLA       = 0.35   # peso SLA target (latenza dichiarata)
+_W_COST      = 0.15   # peso costo (free > paid)
+_W_ALWAYS_ON = 0.20   # peso always-on vs on-demand
+_W_REGION    = 0.15   # peso preferenza regione
+_W_FEEDBACK  = 0.15   # peso feedback storico real-world (success rate + latency delta)
+
+# ── Feedback Tracker — EWA in-memory, zero I/O ────────────────────────────────
+class _FeedbackRecord:
+    """Record EWA (Exponentially Weighted Average) per provider."""
+    __slots__ = ("success_ewa", "latency_ratio_ewa", "calls", "_alpha")
+
+    def __init__(self, alpha: float = 0.2) -> None:
+        self.success_ewa      = 1.0   # parte ottimista (assume ok fino a prova contraria)
+        self.latency_ratio_ewa = 1.0  # actual_ms / declared_sla_ms (1.0 = rispetta SLA)
+        self.calls             = 0
+        self._alpha            = alpha
+
+    def record(self, success: bool, actual_ms: float | None, declared_sla_ms: float) -> None:
+        a = self._alpha
+        self.success_ewa = (1 - a) * self.success_ewa + a * (1.0 if success else 0.0)
+        if actual_ms is not None and declared_sla_ms > 0:
+            ratio = actual_ms / declared_sla_ms
+            self.latency_ratio_ewa = (1 - a) * self.latency_ratio_ewa + a * ratio
+        self.calls += 1
+
+    def score(self) -> float:
+        """Score [0,1]: 1.0 = perfetto (success rate 100%, rispetta SLA), 0 = pessimo."""
+        # success rate: 1.0 → bonus, 0.0 → forte penalità
+        s_score = self.success_ewa
+        # latency ratio: ratio ≤ 1 (batte SLA) → bonus, ratio > 2 → forte penalità
+        l_score = min(1.0, 1.0 / max(self.latency_ratio_ewa, 0.5))
+        return 0.7 * s_score + 0.3 * l_score
+
+
+class FeedbackTracker:
+    """Registry in-memory di feedback per provider_id. Thread-safe tramite GIL."""
+
+    def __init__(self) -> None:
+        self._records: dict[str, _FeedbackRecord] = {}
+
+    def record(self, provider_id: str, success: bool,
+               actual_ms: float | None = None, declared_sla_ms: float = 1000.0) -> None:
+        if provider_id not in self._records:
+            self._records[provider_id] = _FeedbackRecord()
+        self._records[provider_id].record(success, actual_ms, declared_sla_ms)
+
+    def score(self, provider_id: str) -> float:
+        """Restituisce feedback score [0,1]. Default ottimistico 0.85 se nessun dato."""
+        rec = self._records.get(provider_id)
+        return rec.score() if rec else 0.85
+
+    def stats(self) -> dict:
+        return {
+            pid: {"calls": r.calls, "success_ewa": round(r.success_ewa, 3),
+                  "latency_ratio_ewa": round(r.latency_ratio_ewa, 3), "score": round(r.score(), 3)}
+            for pid, r in self._records.items()
+        }
+
+# ── Models ─────────────────────────────────────────────────────────────────────
+
+class ResolveRequest(BaseModel):
+    """Richiesta di risoluzione capability da parte del Brain (via Kernel)."""
+    capability:        str            = Field(..., description="Nome capability richiesta, es. 'browser'")
+    require_gpu:       bool           = Field(False)
+    max_sla_ms:        float | None   = Field(None,  description="SLA massimo accettato in ms")
+    prefer_region:     str | None     = Field(None,  description="Regione preferita, es. 'eu'")
+    tags:              list[str]      = Field(default_factory=list, description="Tag intent-based extra")
+    payload_kb:        int            = Field(0,     description="Stima dimensione payload in KB")
+    exclude_providers: list[str]      = Field(default_factory=list, description="Provider da escludere")
+    correlation_id:    str            = Field(default_factory=lambda: str(uuid.uuid4()))
+
+
+class ProviderCandidate(BaseModel):
+    """Provider candidato per una capability con score e metadati."""
+    provider_id:   str
+    provider_name: str
+    sla_ms:        float
+    version:       str
+    cost_unit:     float
+    region:        str
+    always_on:     bool
+    requires_gpu:  bool
+    score:         float   = Field(description="Score composito [0,1]")
+    tags:          list[str] = Field(default_factory=list)
+
+
+class ResolveResult(BaseModel):
+    """Risultato della risoluzione — provider ottimale + alternative ordinate."""
+    resolve_id:      str   = Field(default_factory=lambda: str(uuid.uuid4()))
+    capability:      str
+    resolved:        bool  = False
+    provider_id:     str | None = None
+    provider_name:   str | None = None
+    sla_ms:          float | None = None
+    version:         str   = "1.0.0"
+    score:           float = 0.0
+    alternatives:    list[ProviderCandidate] = Field(default_factory=list)
+    reason:          str   = ""
+    resolved_at:     float = Field(default_factory=time.time)
+    catalog_source:  bool  = True   # True = da Catalog, False = fallback fabric
+
+
+class ResolveManyRequest(BaseModel):
+    requests: list[ResolveRequest] = Field(..., description="Lista richieste da risolvere in bulk")
+
+
+# ── CapabilityResolver singleton ───────────────────────────────────────────────
+
+class CapabilityResolver:
+    """
+    Risolve capability → provider ottimale usando il Capability Catalog.
+
+    Algoritmo (puramente dichiarativo, non modifica stato):
+      1. Query catalog per capability (+ filtri hard: GPU, SLA, payload_kb)
+      2. Per ogni candidato, calcola score composito:
+           score = W_SLA * sla_score + W_COST * cost_score
+                 + W_ALWAYS_ON * aon_score + W_REGION * region_score
+      3. Ordina candidati per score desc
+      4. Ritorna best + ordered alternatives
+
+    Se il Catalog non è disponibile o vuoto, tenta fallback sul Fabric
+    (usa _fabric._specs per lista provider registrati).
+    """
+
+    # ── Resolve (singola) ─────────────────────────────────────────────────────
+
+    def resolve(self, req: ResolveRequest) -> ResolveResult:
+        """
+        Risoluzione sincrona — il Catalog è un dict in-memory, nessuna I/O.
+        Chiamabile sia da codice sync che async.
+        """
+        rid = str(uuid.uuid4())
+
+        candidates = self._query_candidates(req)
+        if not candidates:
+            # Fallback: prova dal Fabric se il Catalog è vuoto
+            candidates = self._fallback_from_fabric(req)
+
+        if not candidates:
+            _logger.warning("[resolver] no provider for capability=%s", req.capability)
+            return ResolveResult(
+                resolve_id=rid, capability=req.capability, resolved=False,
+                reason=f"Nessun provider disponibile per capability '{req.capability}'",
+            )
+
+        scored = sorted(candidates, key=lambda c: c.score, reverse=True)
+        best   = scored[0]
+        alts   = scored[1:]
+
+        _logger.info("[resolver] resolved cap=%s → provider=%s sla=%.0fms score=%.3f alts=%d",
+                     req.capability, best.provider_id, best.sla_ms, best.score, len(alts))
+
+        return ResolveResult(
+            resolve_id    = rid,
+            capability    = req.capability,
+            resolved      = True,
+            provider_id   = best.provider_id,
+            provider_name = best.provider_name,
+            sla_ms        = best.sla_ms,
+            version       = best.version,
+            score         = best.score,
+            alternatives  = alts[:5],   # max 5 alternative
+            reason        = "ok",
+        )
+
+    # ── Resolve Many (bulk, per Workflow Engine) ───────────────────────────────
+
+    def resolve_many(self, requests: list[ResolveRequest]) -> list[ResolveResult]:
+        """Risolve N capability in bulk. Usato dal Workflow Engine (ARCH-I4.2)."""
+        return [self.resolve(r) for r in requests]
+
+    # ── can_resolve (quick check) ─────────────────────────────────────────────
+
+    def can_resolve(self, capability: str) -> bool:
+        """Ritorna True se esiste almeno un provider vivo per questa capability."""
+        if _CATALOG_AVAILABLE and _catalog is not None:
+            return len(_catalog.query(name=capability)) > 0
+        if _FABRIC_AVAILABLE and _fabric is not None:
+            return any(
+                capability in spec.capabilities
+                for spec in _fabric._specs.values()
+                if spec.base_url
+            )
+        return False
+
+    # ── Internal: query candidates ────────────────────────────────────────────
+
+    def _query_candidates(self, req: ResolveRequest) -> list[ProviderCandidate]:
+        if not _CATALOG_AVAILABLE or _catalog is None:
+            return []
+
+        entries = _catalog.query(
+            name         = req.capability,
+            requires_gpu = req.require_gpu or None,   # None = non filtrare
+            max_sla_ms   = req.max_sla_ms,
+            region       = None,   # regione usata solo per scoring, non filtro hard
+        )
+
+        candidates = []
+        for e in entries:
+            # Filtri hard addizionali
+            if req.require_gpu and not e.requires_gpu:
+                continue
+            if e.provider_id in req.exclude_providers:
+                continue
+            if req.payload_kb and req.payload_kb > e.max_payload_kb:
+                continue
+
+            score = self._score(e, req)
+            candidates.append(ProviderCandidate(
+                provider_id   = e.provider_id,
+                provider_name = e.provider_name,
+                sla_ms        = e.sla_ms,
+                version       = e.version,
+                cost_unit     = e.cost_unit,
+                region        = e.region,
+                always_on     = e.always_on,
+                requires_gpu  = e.requires_gpu,
+                tags          = e.tags,
+                score         = score,
+            ))
+        return candidates
+
+    def _fallback_from_fabric(self, req: ResolveRequest) -> list[ProviderCandidate]:
+        """
+        Fallback: legge _specs dal Fabric se il Catalog è vuoto o non disponibile.
+        Usato solo quando il Fabric non ha ancora fatto initialize() + auto-register.
+        """
+        if not _FABRIC_AVAILABLE or _fabric is None:
+            return []
+        candidates = []
+        for pid, spec in _fabric._specs.items():
+            if req.capability not in spec.capabilities:
+                continue
+            if req.require_gpu and not spec.gpu:
+                continue
+            if pid in req.exclude_providers:
+                continue
+            if not spec.base_url:
+                continue
+            sla  = 9000.0   # default conservativo
+            cost = spec.cost_unit
+            always_on = hasattr(spec, 'always_on') and str(spec.always_on) not in ("on-demand", "no")
+            score = self._score_raw(sla, cost, always_on, spec.region, req.prefer_region)
+            candidates.append(ProviderCandidate(
+                provider_id   = spec.provider_id,
+                provider_name = spec.name,
+                sla_ms        = sla,
+                version       = "1.0.0",
+                cost_unit     = cost,
+                region        = spec.region,
+                always_on     = always_on,
+                requires_gpu  = spec.gpu,
+                score         = score,
+            ))
+        return candidates
+
+    # ── Scoring ───────────────────────────────────────────────────────────────
+
+    def _score(self, e: "_CapDesc", req: ResolveRequest) -> float:  # type: ignore[name-defined]
+        always_on = e.always_on
+        feedback_score = self._feedback.score(e.name)  # e.name = provider_id nel catalog
+        return self._score_raw(e.sla_ms, e.cost_unit, always_on, e.region, req.prefer_region, feedback_score)
+
+    @staticmethod
+    def _score_raw(sla_ms: float, cost: float, always_on: bool, region: str,
+                   prefer_region: str | None, feedback_score: float = 0.85) -> float:
+        # SLA score: SLA bassa → score alto. Riferimento 5000ms.
+        sla_score  = min(1.0, 5000.0 / max(sla_ms, 100.0))
+        # Cost score: free → 1.0, 1 unit → 0.5
+        cost_score = 1.0 / (1.0 + cost * 10)
+        # Always-on score
+        aon_score  = 1.0 if always_on else 0.4
+        # Region score
+        region_score = 1.0 if (not prefer_region or region == prefer_region) else 0.7
+        # Feedback score: EWA di success rate + latency ratio reale (ARCH-RESOLVER-FB)
+
+        return (
+            _W_SLA       * sla_score     +
+            _W_COST      * cost_score    +
+            _W_ALWAYS_ON * aon_score     +
+            _W_REGION    * region_score  +
+            _W_FEEDBACK  * feedback_score
+        )
+
+    # ── Feedback recording ────────────────────────────────────────────────────
+
+    def record_feedback(self, provider_id: str, success: bool,
+                        actual_ms: float | None = None, declared_sla_ms: float = 1000.0) -> None:
+        """
+        Registra il risultato reale di una chiamata al provider (ARCH-RESOLVER-FB).
+        Chiamato dall'Executor/Brain dopo ogni tool execution.
+        """
+        self._feedback.record(provider_id, success, actual_ms, declared_sla_ms)
+        _logger.debug("[resolver] feedback %s → success=%s actual_ms=%s",
+                      provider_id, success, actual_ms)
+
+    # ── Status ────────────────────────────────────────────────────────────────
+
+    def status(self) -> dict:
+        resolvable: list[str] = []
+        if _CATALOG_AVAILABLE and _catalog is not None:
+            entries = _catalog.all_entries()
+            resolvable = sorted({e.name for e in entries})
+        return {
+            "catalog_available": _CATALOG_AVAILABLE,
+            "fabric_available":  _FABRIC_AVAILABLE,
+            "resolvable_capabilities": resolvable,
+            "total_resolvable": len(resolvable),
+            "weights": {
+                "sla":      _W_SLA,
+                "cost":     _W_COST,
+                "always_on": _W_ALWAYS_ON,
+                "region":   _W_REGION,
+                "feedback": _W_FEEDBACK,
+            },
+            "feedback_stats": self._feedback.stats(),
+        }
+
+
+# ── Singleton ───────────────────────────────────────────────────────────────────
+resolver = CapabilityResolver()
+
+# ── HTTP Router ─────────────────────────────────────────────────────────────────
+router = APIRouter(
+    prefix="/api/resolver",
+    tags=["capability-resolver"],
+    dependencies=[Depends(require_role(AuthRole.MACHINE))],
+)
+
+
+@router.post("/resolve", summary="Risolve una capability → provider ottimale")
+async def route_resolve(req: ResolveRequest) -> ResolveResult:
+    result = resolver.resolve(req)
+    if not result.resolved:
+        raise HTTPException(404, result.reason)
+    return result
+
+
+@router.post("/resolve-many", summary="Risolve N capability in bulk (workflow planning)")
+async def route_resolve_many(req: ResolveManyRequest) -> dict:
+    if not req.requests:
+        raise HTTPException(400, "requests lista vuota")
+    results = resolver.resolve_many(req.requests)
+    resolved   = sum(1 for r in results if r.resolved)
+    unresolved = len(results) - resolved
+    return {
+        "total":      len(results),
+        "resolved":   resolved,
+        "unresolved": unresolved,
+        "results":    [r.model_dump() for r in results],
+    }
+
+
+@router.get("/status", summary="Stato resolver — capabilities risolvibili e pesi scoring")
+async def route_status() -> dict:
+    return resolver.status()
+
+
+class ResolverFeedback(BaseModel):
+    """Feedback da inviare dopo l'esecuzione di un tool (ARCH-RESOLVER-FB)."""
+    provider_id:      str
+    success:          bool
+    actual_ms:        float | None = None
+    declared_sla_ms:  float        = 1000.0
+
+
+@router.post("/feedback", summary="Registra feedback reale su un provider (latenza, successo)")
+async def route_feedback(body: ResolverFeedback) -> dict:
+    """
+    Chiamato dall'Executor dopo ogni tool execution per aggiornare lo scoring EWA.
+    Non-critico: un errore qui non deve mai bloccare l'esecuzione dell'agente.
+    """
+    resolver.record_feedback(body.provider_id, body.success, body.actual_ms, body.declared_sla_ms)
+    return {"recorded": True, "provider_id": body.provider_id}

api/dashboard.py

@@ -0,0 +1,171 @@
+"""backend/api/dashboard.py — Unified observability snapshot (INT-2).
+
+GET /api/dashboard/snapshot
+
+Aggrega in una sola chiamata HTTP:
+  • provider health + score (da heartbeat + benchmark)
+  • telemetry timing p50/p90
+  • _BENCH_LAST_RUN (ultimo quality benchmark)
+  • incident count + ultimi 5
+  • LLM router stats (routing table + provider ok/fail)
+  • plugin registry (total/loaded/list)
+
+Auth: nessuna (zero PII, solo aggregate). I valori sensibili rimangono mascherati.
+"""
+from __future__ import annotations
+
+import time
+import logging
+
+from fastapi import APIRouter
+from fastapi.responses import JSONResponse
+
+router = APIRouter()
+_logger = logging.getLogger("api.dashboard")
+
+
+@router.get("/api/dashboard/snapshot")
+async def dashboard_snapshot() -> JSONResponse:
+    """Snapshot unificato — un endpoint, tutte le metriche operative."""
+    t0 = time.monotonic()
+    out: dict = {
+        "ok":           True,
+        "generated_at": int(time.time()),
+        "version":      "1.0",
+    }
+
+    # ── 1. Provider health + scores ──────────────────────────────────────────
+    try:
+        from api.state import _ai_health_cache, _PROVIDER_SCORES, _BENCH_LAST_RUN
+        cached_data = _ai_health_cache.get("data") or {}
+        raw_providers = cached_data.get("providers", [])
+
+        out["providers"] = {
+            r.get("name", r.get("provider", "?")): {
+                "ok":         r.get("ok", False),
+                "status":     r.get("status", "unknown"),
+                "latency_ms": r.get("latency_ms"),
+                "model":      r.get("model"),
+                "error":      r.get("error") if not r.get("ok") else None,
+                "score":      _PROVIDER_SCORES.get(
+                    r.get("name", r.get("provider", "")), None
+                ),
+            }
+            for r in raw_providers
+        }
+
+        # Sintesi: quanti ok, best provider per score
+        scores_live = {k: v for k, v in _PROVIDER_SCORES.items() if v > 0}
+        best = max(scores_live, key=scores_live.get) if scores_live else None
+        out["provider_summary"] = {
+            "total":          len(raw_providers),
+            "ok":             sum(1 for r in raw_providers if r.get("ok")),
+            "best_provider":  best,
+            "best_score":     scores_live.get(best) if best else None,
+            "checked_at_ago_s": round(time.monotonic() - _ai_health_cache.get("at", 0)),
+        }
+
+        out["bench_last_run"] = {
+            "total_score":    _BENCH_LAST_RUN.get("total_score"),
+            "categories_run": _BENCH_LAST_RUN.get("categories_run", 0),
+            "age_s":          round(time.time() - _BENCH_LAST_RUN.get("timestamp", 0))
+                              if _BENCH_LAST_RUN.get("timestamp") else None,
+        }
+    except Exception as exc:
+        out["providers"] = {"_error": str(exc)}
+
+    # ── 2. Telemetry (timing + repair) ──────────────────────────────────────
+    try:
+        from api.state import _TIMING_STORE, _REPAIR_STATS
+        from api.telemetry import _percentile
+
+        timing: dict = {}
+        for key, buf in _TIMING_STORE.items():
+            samples = list(buf)
+            if samples:
+                timing[key] = {
+                    "p50": _percentile(samples, 50),
+                    "p90": _percentile(samples, 90),
+                    "n":   len(samples),
+                }
+
+        # Repair summary: solo contatori non-zero
+        repair_nonzero = {k: v for k, v in _REPAIR_STATS.items() if v > 0}
+        out["telemetry"] = {
+            "timing":         timing,
+            "repair_summary": repair_nonzero,
+            "repair_total":   sum(_REPAIR_STATS.values()),
+        }
+    except Exception as exc:
+        out["telemetry"] = {"_error": str(exc)}
+
+    # ── 3. Incidents ─────────────────────────────────────────────────────────
+    try:
+        from api.incident_registry import _incidents  # type: ignore[attr-defined]
+        incidents_list = list(_incidents.values()) if isinstance(_incidents, dict) else []
+        recent = sorted(
+            incidents_list,
+            key=lambda i: i.get("created_at", 0),
+            reverse=True,
+        )[:5]
+        out["incidents"] = {
+            "total":    len(incidents_list),
+            "recent_5": [
+                {
+                    "id":       i.get("id", "?"),
+                    "provider": i.get("provider"),
+                    "severity": i.get("severity"),
+                    "message":  str(i.get("message", ""))[:120],
+                    "at":       i.get("created_at"),
+                }
+                for i in recent
+            ],
+        }
+    except Exception as exc:
+        out["incidents"] = {"_error": str(exc), "total": 0}
+
+    # ── 4. LLM Router stats ──────────────────────────────────────────────────
+    try:
+        # LLMProviderRouter è un singleton lazy — usa la classe direttamente
+        from api.llm_router import LLMProviderRouter
+        rtr = LLMProviderRouter()
+        out["llm_router"] = rtr.status()
+    except Exception as exc:
+        out["llm_router"] = {"_error": str(exc)}
+
+    # ── 5. Plugin registry ────────────────────────────────────────────────────
+    try:
+        from api.plugin_system import registry as _plugin_reg
+        # list_plugins() ritorna lista di dict con stato
+        plugins_raw = [
+            {
+                "id":      pid,
+                "version": m.version,
+                "state":   _plugin_reg._states.get(pid, "unknown"),
+                "caps":    m.capabilities,
+            }
+            for pid, m in _plugin_reg._plugins.items()
+        ]
+        out["plugins"] = {
+            "total":  len(plugins_raw),
+            "loaded": sum(1 for p in plugins_raw if p["state"] == "loaded"),
+            "list":   plugins_raw,
+        }
+    except Exception as exc:
+        out["plugins"] = {"_error": str(exc), "total": 0}
+
+    # ── 6. System health (da HealthManager) ─────────────────────────────────
+    try:
+        from api.health_manager import HealthManager
+        hm = HealthManager()
+        report = await hm.get_report()
+        out["system_health"] = {
+            "status":         report.system_health.value if report else "unknown",
+            "active_alerts":  report.active_alerts if report else [],
+            "recovery_actions": report.recovery_actions if report else [],
+        }
+    except Exception as exc:
+        out["system_health"] = {"_error": str(exc)}
+
+    out["elapsed_ms"] = round((time.monotonic() - t0) * 1000, 1)
+    return JSONResponse(out)

api/database.py

@@ -113,10 +113,9 @@ async def _pg_query(db_url: str, sql: str, params: list):
         return {"ok": False, "error": "psycopg2 non installato. Aggiungi 'psycopg2-binary' a requirements.txt."}
 
     def _run():
-        conn = psycopg2.connect(db_url, connect_timeout=5)
+        conn = psycopg2.connect(db_url)
         try:
             cur = conn.cursor(cursor_factory=psycopg2.extras.RealDictCursor)
-            cur.execute("SET statement_timeout = '5000ms'")
             cur.execute(sql, params or None)
             try:
                 rows  = [dict(r) for r in cur.fetchmany(_MAX_ROWS)]

api/database_router.py

@@ -0,0 +1,303 @@
+"""
+database_router.py — Router Query Intelligente per Separazione Workload Supabase A/B/C/D
+
+Architettura:
+  A: Analytics/Cache/Read-Heavy (reporting, dashboard, cache distribuito)
+  B: Sync/State/Transazioni (stato globale, sincronizzazione cluster — PRIMARY)
+  C: Memory/RAG/Embeddings (backend memoria, vector search, skill index)
+  D: Audit/Logging/Compliance (event log, audit trail, compliance records)
+
+Routing Logic:
+  1. Query di LETTURA (SELECT) → Preferisci A (read replica), fallback a B
+  2. Query di SCRITTURA (INSERT/UPDATE) → Usa B (PRIMARY)
+  3. Query su MEMORIA/RAG (skill_memory, embeddings, conversations) → Usa C
+  4. Query su AUDIT/LOG (audit_events, compliance_log) → Usa D
+  5. Query di SINCRONIZZAZIONE (cluster_state, global_state) → Usa B
+"""
+
+import asyncio
+import os
+import logging
+import re as _re
+from typing import Optional, Literal
+from enum import Enum
+from fastapi import APIRouter, HTTPException, Request
+from pydantic import BaseModel
+
+router = APIRouter(prefix="/api/database", tags=["database"])
+_logger = logging.getLogger("database_router")
+
+# ─── Enumerazione Nodi Supabase ───────────────────────────────────────────
+class SupabaseNode(str, Enum):
+    A = "A"  # Analytics/Cache
+    B = "B"  # PRIMARY (Sync/State)
+    C = "C"  # Memory/RAG
+    D = "D"  # Audit/Logging
+
+
+# ─── Configurazione Nodi ──────────────────────────────────────────────────
+SUPABASE_CONFIG = {
+    "A": {
+        "url": os.getenv("SUPABASE_URL_A", ""),
+        "key": os.getenv("SUPABASE_KEY_A", ""),
+        "role": "Analytics/Cache (Read-Heavy)",
+        "priority": 1,  # Preferito per letture
+    },
+    "B": {
+        "url": os.getenv("SUPABASE_URL", ""),  # PRIMARY
+        "key": os.getenv("SUPABASE_KEY", ""),
+        "role": "Sync/State (PRIMARY)",
+        "priority": 0,  # Fallback universale
+    },
+    "C": {
+        "url": os.getenv("SUPABASE_URL_C", ""),
+        "key": os.getenv("SUPABASE_KEY_C", ""),
+        "role": "Memory/RAG/Embeddings",
+        "priority": 2,
+    },
+    "D": {
+        "url": os.getenv("SUPABASE_URL_D", ""),
+        "key": os.getenv("SUPABASE_KEY_D", ""),
+        "role": "Audit/Logging/Compliance",
+        "priority": 3,
+    },
+}
+
+# ─── Keyword Pericolosi (per read-only) ───────────────────────────────────
+_DANGEROUS = frozenset(
+    {"drop", "truncate", "delete", "update", "insert", "alter", "create", "grant", "revoke"}
+)
+_MAX_ROWS = 500
+
+
+# ─── Modelli Pydantic ─────────────────────────────────────────────────────
+class QueryRequest(BaseModel):
+    sql: str
+    params: list = []
+    read_only: bool = True
+    preferred_node: Optional[SupabaseNode] = None  # Override routing logic
+
+
+class QueryResponse(BaseModel):
+    ok: bool
+    rows: list = []
+    columns: list = []
+    count: int = 0
+    truncated: bool = False
+    node_used: Optional[str] = None
+    error: Optional[str] = None
+
+
+# ─── Funzioni Utility ─────────────────────────────────────────────────────
+def _is_dangerous(sql: str) -> Optional[str]:
+    """Rilevamento keyword pericolose robusto contro CTE e multi-spazio."""
+    s_norm = " ".join(sql.strip().lower().split())
+    tokens = _re.split(r"[\s\(\),;]+", s_norm)
+    for tok in tokens:
+        if tok in _DANGEROUS:
+            return tok
+    for m in _re.finditer(r"\bas\s*\(\s*(\w+)", s_norm):
+        first_word = m.group(1).lower()
+        if first_word in _DANGEROUS:
+            return first_word
+    return None
+
+
+def _detect_query_type(sql: str) -> Literal["SELECT", "INSERT", "UPDATE", "DELETE", "OTHER"]:
+    """Rileva il tipo di query (SELECT, INSERT, UPDATE, DELETE, OTHER)."""
+    s_norm = " ".join(sql.strip().upper().split())
+    if s_norm.startswith("SELECT"):
+        return "SELECT"
+    elif s_norm.startswith("INSERT"):
+        return "INSERT"
+    elif s_norm.startswith("UPDATE"):
+        return "UPDATE"
+    elif s_norm.startswith("DELETE"):
+        return "DELETE"
+    return "OTHER"
+
+
+def _detect_table_context(sql: str) -> Optional[str]:
+    """Rileva il contesto della tabella per routing intelligente."""
+    sql_lower = sql.lower()
+    
+    # Tabelle di memoria/RAG → Nodo C
+    if any(t in sql_lower for t in ["skill_memory", "embeddings", "conversations", "rag_index", "vector_store"]):
+        return "C"
+    
+    # Tabelle di audit/logging → Nodo D
+    if any(t in sql_lower for t in ["audit_events", "audit_log", "compliance_log", "event_log", "activity_log"]):
+        return "D"
+    
+    # Tabelle di stato globale → Nodo B
+    if any(t in sql_lower for t in ["cluster_state", "global_state", "sync_state", "agent_state", "daemon_status"]):
+        return "B"
+    
+    return None
+
+
+def _choose_node(
+    query_type: Literal["SELECT", "INSERT", "UPDATE", "DELETE", "OTHER"],
+    table_context: Optional[str],
+    preferred_node: Optional[SupabaseNode],
+) -> SupabaseNode:
+    """
+    Logica di routing intelligente per scegliere il nodo Supabase.
+    
+    Priorità:
+    1. preferred_node (override esplicito)
+    2. table_context (rilevamento tabella)
+    3. query_type (tipo di query)
+    4. Fallback a B (PRIMARY)
+    """
+    # 1. Override esplicito
+    if preferred_node:
+        return preferred_node
+    
+    # 2. Routing per contesto tabella
+    if table_context:
+        return SupabaseNode(table_context)
+    
+    # 3. Routing per tipo query
+    if query_type == "SELECT":
+        # Preferisci A (read replica) se disponibile, altrimenti B
+        if SUPABASE_CONFIG["A"]["url"]:
+            return SupabaseNode.A
+        return SupabaseNode.B
+    elif query_type in ("INSERT", "UPDATE", "DELETE"):
+        # Sempre su B (PRIMARY)
+        return SupabaseNode.B
+    
+    # 4. Fallback a B (PRIMARY)
+    return SupabaseNode.B
+
+
+# ─── Endpoint Principale ──────────────────────────────────────────────────
+@router.post("/query", response_model=QueryResponse)
+async def database_query(req: QueryRequest, request: Request):
+    """
+    Endpoint query con routing intelligente tra nodi Supabase A/B/C/D.
+    
+    Parametri:
+      - sql: query SQL
+      - params: parametri query
+      - read_only: blocca query pericolose (default: true)
+      - preferred_node: forza un nodo specifico (opzionale)
+    
+    Ritorna:
+      - ok: successo
+      - rows: righe risultato
+      - columns: nomi colonne
+      - count: numero righe
+      - truncated: se risultato è stato troncato
+      - node_used: nodo Supabase utilizzato
+    """
+    # Verifica token interno
+    _internal_token = os.getenv("INTERNAL_TOKEN", "")
+    if _internal_token and request.headers.get("X-Internal-Token") != _internal_token:
+        raise HTTPException(401, "Unauthorized")
+    
+    # Rileva tipo query e contesto
+    query_type = _detect_query_type(req.sql)
+    table_context = _detect_table_context(req.sql)
+    
+    # Scegli nodo
+    chosen_node = _choose_node(query_type, table_context, req.preferred_node)
+    
+    # Verifica configurazione nodo
+    node_config = SUPABASE_CONFIG.get(chosen_node.value)
+    if not node_config or not node_config["url"]:
+        # Fallback a B se nodo non configurato
+        if chosen_node != SupabaseNode.B:
+            _logger.warning(
+                f"Nodo {chosen_node.value} non configurato, fallback a B. "
+                f"Configura SUPABASE_URL_{chosen_node.value} e SUPABASE_KEY_{chosen_node.value}."
+            )
+            chosen_node = SupabaseNode.B
+            node_config = SUPABASE_CONFIG["B"]
+    
+    if not node_config["url"]:
+        return QueryResponse(
+            ok=False,
+            error=f"Nodo {chosen_node.value} non configurato. Imposta SUPABASE_URL_{chosen_node.value}.",
+            node_used=chosen_node.value,
+        )
+    
+    # Verifica read-only
+    if req.read_only:
+        kw = _is_dangerous(req.sql)
+        if kw:
+            return QueryResponse(
+                ok=False,
+                error=f"Query bloccata (read-only): '{kw.upper()}' non consentito.",
+                node_used=chosen_node.value,
+            )
+    
+    # Esegui query
+    try:
+        result = await _execute_query(
+            node_config["url"],
+            node_config["key"],
+            req.sql,
+            req.params,
+        )
+        result["node_used"] = chosen_node.value
+        return QueryResponse(**result)
+    except Exception as e:
+        _logger.error(f"Errore query su nodo {chosen_node.value}: {str(e)}")
+        return QueryResponse(
+            ok=False,
+            error=str(e)[:400],
+            node_used=chosen_node.value,
+        )
+
+
+# ─── Esecuzione Query (Supabase PostgreSQL) ───────────────────────────────
+async def _execute_query(url: str, key: str, sql: str, params: list) -> dict:
+    """Esegue query su Supabase PostgreSQL."""
+    try:
+        import psycopg2
+        import psycopg2.extras
+    except ImportError:
+        return {
+            "ok": False,
+            "error": "psycopg2 non installato. Aggiungi 'psycopg2-binary' a requirements.txt.",
+        }
+    
+    def _run():
+        conn = psycopg2.connect(url)
+        try:
+            cur = conn.cursor(cursor_factory=psycopg2.extras.RealDictCursor)
+            cur.execute(sql, params or None)
+            try:
+                rows = [dict(r) for r in cur.fetchmany(_MAX_ROWS)]
+                cols = [d.name for d in (cur.description or [])]
+            except psycopg2.ProgrammingError:
+                rows, cols = [], []
+            conn.commit()
+        finally:
+            conn.close()
+        return rows, cols
+    
+    rows, cols = await asyncio.to_thread(_run)
+    return {
+        "ok": True,
+        "rows": rows,
+        "columns": cols,
+        "count": len(rows),
+        "truncated": len(rows) == _MAX_ROWS,
+    }
+
+
+# ─── Endpoint Debug (info nodi) ───────────────────────────────────────────
+@router.get("/nodes/status")
+async def nodes_status():
+    """Ritorna lo stato di configurazione di tutti i nodi Supabase."""
+    status = {}
+    for node_id, config in SUPABASE_CONFIG.items():
+        status[node_id] = {
+            "role": config["role"],
+            "configured": bool(config["url"]),
+            "url_preview": config["url"][:30] + "..." if config["url"] else "NOT SET",
+        }
+    return {"nodes": status}

api/execution_fabric.py

@@ -0,0 +1,440 @@
+"""
+backend/api/execution_fabric.py — Execution Fabric (ARCH-K2.5 + ARCH-K2.6 Health Manager)
+
+CRIT-B fix: circuit breaker Oracle (3 errori → blocco 300s) + fallback Railway con auth completa.
+CRIT-C fix: parser 402/429 robusto — body scan + pattern estesi nell'exception handler.
+"""
+from __future__ import annotations
+import asyncio
+import logging
+import os
+import time
+import uuid
+from enum import Enum
+from typing import Any, Optional
+import httpx
+from fastapi import APIRouter, Depends
+from pydantic import BaseModel, Field
+
+from .auth_guard import AuthRole, require_role
+from .token_rotator import rotator as _token_rotator
+
+try:
+    from .telemetry import record_kernel_event as _rke
+except Exception:
+    def _rke(*_a, **_kw): pass
+
+_logger = logging.getLogger("api.execution_fabric")
+
+# ── Configurazione Timing (ARCH-T1.1) ──────────────────────────────────────────
+_DEFAULT_TIMEOUT_S = 30.0     # Timeout standard per chiamate API
+_ORACLE_TIMEOUT_S  = 60.0     # Oracle ha più tempo per il calcolo pesante
+_HF_WARMUP_S      = 10.0     # Tempo di attesa se lo Space è in sleep
+_RETRY_DELAY_S     = 1.5      # Attesa tra i tentativi di rotazione token
+_HEALTH_CHECK_INT  = 120.0    # Intervallo health check in background
+
+# ── CRIT-B: Circuit Breaker Oracle ─────────────────────────────────────────────
+_ORACLE_CB_THRESHOLD  = 3      # errori consecutivi prima di aprire il circuit
+_ORACLE_CB_TIMEOUT_S  = 300.0  # secondi di blocco dopo apertura (5 min)
+
+# ── CRIT-C: pattern quota/rate-limit (body + eccezioni) ───────────────────────
+_QUOTA_PATTERNS = (
+    "quota", "egress", "rate limit", "rate_limit", "billing",
+    "402", "429", "limit exceeded", "credits", "insufficient",
+    "payment", "upgrade", "hours", "quota_or_ratelimit",
+)
+
+
+class ProviderKind(str, Enum):
+    HF_SPACE   = "hf_space"
+    # RAILWAY rimosso
+    DOCKER     = "docker"
+    ORACLE     = "oracle"
+    LOCAL      = "local"
+
+class ProviderHealth(str, Enum):
+    OK        = "ok"
+    DEGRADED  = "degraded"
+    DOWN      = "down"
+    UNKNOWN   = "unknown"
+
+class AlwaysOn(str, Enum):
+    YES       = "yes"
+    ON_DEMAND = "on-demand"
+    NO        = "no"
+
+class ProviderSpec(BaseModel):
+    provider_id:    str
+    name:           str
+    kind:           ProviderKind   = ProviderKind.LOCAL
+    base_url:       str            = ""
+    capabilities:   list[str]      = Field(default_factory=list)
+    gpu:            bool           = False
+    always_on:      AlwaysOn       = AlwaysOn.ON_DEMAND
+    max_concurrency: int           = 10
+    priority:       int            = 50
+    cost_unit:      float          = 0.0
+    region:         str            = "eu"
+    timeout:        float          = _DEFAULT_TIMEOUT_S
+
+class ProviderState(BaseModel):
+    provider_id:        str
+    health:             ProviderHealth      = ProviderHealth.UNKNOWN
+    active_tasks:       int                 = 0
+    last_check_ts:      float               = 0.0
+    error_count:        int                 = 0
+
+class DispatchRequest(BaseModel):
+    capability:     str
+    task_id:        str   = Field(default_factory=lambda: str(uuid.uuid4()))
+    payload:        dict  = Field(default_factory=dict)
+    require_gpu:    bool  = False
+    require_isolation: bool = False
+    prefer_region:  str | None = None
+    provider_hint:  str | None = None
+    correlation_id: str   = Field(default_factory=lambda: str(uuid.uuid4()))
+
+class DispatchResult(BaseModel):
+    task_id:        str
+    provider_id:    str
+    provider_name:  str
+    provider_kind:  str
+    capability:     str
+    status:         str
+    response:       dict        = Field(default_factory=dict)
+    latency_ms:     float       = 0.0
+    correlation_id: str         = ""
+
+
+class ExecutionFabric:
+    def __init__(self):
+        self._specs:  dict[str, ProviderSpec]  = {}
+        self._states: dict[str, ProviderState] = {}
+        self._initialized = False
+
+        # CRIT-B: circuit breaker state per provider (in-memory, per istanza)
+        # { provider_id: {"errors": int, "blocked_until": float} }
+        self._circuit: dict[str, dict] = {}
+
+    # ── Inizializzazione provider ─────────────────────────────────────────────
+
+    async def initialize(self):
+        if self._initialized:
+            return
+        self._initialized = True
+
+        providers: list[ProviderSpec] = []
+
+        # Local fallback — sempre disponibile, nessun HTTP
+        providers.append(ProviderSpec(
+            provider_id="local",
+            name="Local",
+            kind=ProviderKind.LOCAL,
+            base_url="",
+            capabilities=["exec", "tool", "shell"],
+            priority=10,
+            always_on=AlwaysOn.YES,
+        ))
+
+        # HF Space principale — no-op se HF_SPACE_URL non configurata
+        hf_url = os.getenv("HF_SPACE_URL", "").rstrip("/")
+        if hf_url:
+            providers.append(ProviderSpec(
+                provider_id="hf-space-main",
+                name="HF Space Main",
+                kind=ProviderKind.HF_SPACE,
+                base_url=hf_url,
+                capabilities=["exec", "tool", "llm", "browse"],
+                priority=50,
+                always_on=AlwaysOn.ON_DEMAND,
+                timeout=_DEFAULT_TIMEOUT_S,
+            ))
+
+        # Railway core backend rimosso (migrato su HF Spaces)
+
+        # Oracle Cloud VM — no-op se ORACLE_CLOUD_VM_URL non impostata
+        oracle_url = os.getenv("ORACLE_CLOUD_VM_URL", "").rstrip("/")
+        if oracle_url:
+            providers.append(ProviderSpec(
+                provider_id="oracle-cloud-vm-01",
+                name="Oracle Cloud VM",
+                kind=ProviderKind.ORACLE,
+                base_url=oracle_url,
+                capabilities=["exec", "tool", "llm", "gpu"],
+                gpu=True,
+                priority=80,
+                always_on=AlwaysOn.ON_DEMAND,
+                timeout=_ORACLE_TIMEOUT_S,
+            ))
+
+        for spec in providers:
+            self._specs[spec.provider_id]  = spec
+            self._states[spec.provider_id] = ProviderState(provider_id=spec.provider_id)
+            self._circuit[spec.provider_id] = {"errors": 0, "blocked_until": 0.0}
+
+        _logger.info(
+            "[fabric] Providers registrati: %s",
+            ", ".join(f"{p.provider_id}({p.kind.value})" for p in providers)
+        )
+
+    # ── CRIT-B: Circuit Breaker helpers ──────────────────────────────────────
+
+    def _is_circuit_open(self, provider_id: str) -> bool:
+        """True se il provider è in blocco circuit breaker."""
+        cb = self._circuit.get(provider_id, {})
+        blocked_until = cb.get("blocked_until", 0.0)
+        if blocked_until > time.time():
+            return True
+        # Reset automatico dopo il timeout
+        if blocked_until > 0.0:
+            self._circuit[provider_id]["errors"] = 0
+            self._circuit[provider_id]["blocked_until"] = 0.0
+            _logger.info("[fabric] Circuit breaker RESET per %s", provider_id)
+        return False
+
+    def _record_oracle_error(self, provider_id: str) -> bool:
+        """
+        Registra un errore Oracle. Se si supera la soglia, apre il circuit.
+        Ritorna True se il circuit è stato appena aperto.
+        """
+        cb = self._circuit.setdefault(provider_id, {"errors": 0, "blocked_until": 0.0})
+        cb["errors"] += 1
+        if cb["errors"] >= _ORACLE_CB_THRESHOLD:
+            cb["blocked_until"] = time.time() + _ORACLE_CB_TIMEOUT_S
+            _logger.error(
+                "[fabric] Circuit breaker APERTO per %s (%d errori consecutivi) "
+                "— blocco per %.0fs fino a %s",
+                provider_id, cb["errors"], _ORACLE_CB_TIMEOUT_S,
+                time.strftime("%H:%M:%S", time.localtime(cb["blocked_until"]))
+            )
+            return True
+        return False
+
+    def _reset_oracle_errors(self, provider_id: str) -> None:
+        """Azzera il contatore errori dopo un successo."""
+        if provider_id in self._circuit:
+            self._circuit[provider_id]["errors"] = 0
+
+    # ── Selezione provider ────────────────────────────────────────────────────
+
+    def _cb_allow(self, provider_id: str) -> bool:
+        return True
+
+    def _select(self, capability: str, exclude: set[str] | None = None) -> Optional[str]:
+        """
+        Seleziona il provider con la priorità più alta che:
+        - supporta la capability richiesta
+        - non è DOWN
+        - non è in circuit breaker aperto
+        - non è nella lista exclude
+        Ordine: priority DESC (higher = preferred).
+        """
+        exclude = exclude or set()
+        candidates = [
+            (spec.priority, pid, spec)
+            for pid, spec in self._specs.items()
+            if capability in spec.capabilities
+            and self._states[pid].health != ProviderHealth.DOWN
+            and not self._is_circuit_open(pid)
+            and pid not in exclude
+        ]
+        if not candidates:
+            return None
+        # Ordina per priority decrescente
+        candidates.sort(key=lambda x: x[0], reverse=True)
+        return candidates[0][1]
+
+    # ── CRIT-C: rilevamento quota/rate-limit ──────────────────────────────────
+
+    @staticmethod
+    def _is_quota_error(text: str) -> bool:
+        """True se il testo (body o eccezione) indica quota/rate-limit."""
+        t = text.lower()
+        return any(p in t for p in _QUOTA_PATTERNS)
+
+    # ── Chiamata HTTP al provider ─────────────────────────────────────────────
+
+    async def _call_provider(self, spec: ProviderSpec, req: DispatchRequest) -> dict:
+        timeout = _ORACLE_TIMEOUT_S if spec.kind == ProviderKind.ORACLE else spec.timeout
+
+        # Provider locale: nessuna chiamata HTTP
+        if spec.kind == ProviderKind.LOCAL:
+            return {"status": "ok", "provider": "local", "task_id": req.task_id}
+
+        if not spec.base_url:
+            raise ValueError(f"base_url non configurato per provider {spec.provider_id}")
+
+        # ── Header auth per provider kind ────────────────────────────────────
+        headers: dict[str, str] = {"Content-Type": "application/json"}
+        internal_token  = os.getenv("INTERNAL_TOKEN", "")
+        hf_token        = os.getenv("HF_TOKEN", "")
+        # Railway auth rimosso
+        if spec.kind in (ProviderKind.ORACLE, ProviderKind.DOCKER):
+            if internal_token:
+                headers["X-Internal-Token"] = internal_token
+
+        payload = {
+            "task_id":        req.task_id,
+            "capability":     req.capability,
+            "payload":        req.payload,
+            "correlation_id": req.correlation_id,
+        }
+        endpoint = f"{spec.base_url.rstrip('/')}/api/exec"
+
+        async with httpx.AsyncClient(timeout=timeout) as client:
+            resp = await client.post(endpoint, json=payload, headers=headers)
+
+            # CRIT-C: rileva quota/rate-limit sia da status code che da body
+            body_text = resp.text
+            if resp.status_code in (402, 429) or self._is_quota_error(body_text):
+                _logger.warning(
+                    "[fabric] %s — quota/rate-limit rilevato (HTTP %s)",
+                    spec.provider_id, resp.status_code
+                )
+                return {
+                    "status_code": resp.status_code,
+                    "error":       "quota_or_ratelimit",
+                    "body":        body_text[:200],
+                }
+
+            resp.raise_for_status()
+            try:
+                return resp.json()
+            except Exception:
+                return {"status": "ok", "raw": body_text[:500]}
+
+    # ── Health management ────────────────────────────────────────────────────
+
+    def _update_health(self, pid: str, health: ProviderHealth) -> None:
+        if pid in self._states:
+            self._states[pid].health = health
+
+    # ── Dispatch pubblico (con chunking) ────────────────────────────────────
+
+    async def dispatch(self, req: DispatchRequest) -> DispatchResult:
+        await self.initialize()
+
+        # --- LOGICA CHUNKING (S-CHUNK) ---
+        from tools.payload_chunker import chunk_payload
+        chunks = chunk_payload(req.payload, max_kb=450)
+
+        if len(chunks) > 1:
+            _logger.info("[fabric] Payload grande — suddivisione in %d pezzi.", len(chunks))
+            final_responses = []
+            for chunk in chunks:
+                chunk_req = req.model_copy(update={"payload": chunk})
+                res = await self._dispatch_single(chunk_req)
+                final_responses.append(res.response)
+            return DispatchResult(
+                task_id=req.task_id, provider_id="multi", provider_name="Fabric Chunker",
+                provider_kind="internal", capability=req.capability, status="executed",
+                response={"chunks": final_responses, "total_chunks": len(chunks), "provider_info": "Fabric Chunker"},
+                correlation_id=req.correlation_id
+            )
+
+        return await self._dispatch_single(req)
+
+    # ── Dispatch singolo (con retry + circuit breaker) ───────────────────────
+
+    async def _dispatch_single(self, req: DispatchRequest) -> DispatchResult:
+        max_attempts  = 4
+        last_exception: Exception = Exception("nessun tentativo eseguito")
+        excluded: set[str] = set()
+
+        for attempt in range(max_attempts):
+            provider_id = req.provider_hint if attempt == 0 else None
+            if provider_id is None:
+                provider_id = self._select(req.capability, exclude=excluded)
+
+            if not provider_id or provider_id not in self._specs:
+                break  # nessun provider disponibile — esci dal loop
+
+            spec  = self._specs[provider_id]
+            t0    = time.time()
+
+            try:
+                response = await self._call_provider(spec, req)
+
+                # CRIT-C: risposta con quota/rate-limit segnalato nel body
+                is_quota = (
+                    isinstance(response, dict)
+                    and (
+                        response.get("error") == "quota_or_ratelimit"
+                        or response.get("status_code") in (402, 429)
+                        or self._is_quota_error(str(response))
+                    )
+                )
+                if is_quota:
+                    await _token_rotator.rotate()
+                    excluded.add(provider_id)
+                    await asyncio.sleep(_RETRY_DELAY_S)
+                    continue
+
+                # Successo — azzera contatore errori Oracle se applicabile
+                if spec.kind == ProviderKind.ORACLE:
+                    self._reset_oracle_errors(provider_id)
+
+                latency = (time.time() - t0) * 1000
+                _rke("dispatch_ok", provider=provider_id, latency_ms=latency)
+                return DispatchResult(
+                    task_id=req.task_id, provider_id=spec.provider_id,
+                    provider_name=spec.name, provider_kind=spec.kind.value,
+                    capability=req.capability, status="executed",
+                    response=response, latency_ms=latency,
+                    correlation_id=req.correlation_id
+                )
+
+            except Exception as exc:
+                last_exception = exc
+                exc_str = str(exc).lower()
+
+                # CRIT-C: pattern quota/rate-limit esteso anche nelle eccezioni
+                if self._is_quota_error(exc_str):
+                    await _token_rotator.rotate()
+                    excluded.add(provider_id)
+                    await asyncio.sleep(_RETRY_DELAY_S)
+                    continue
+
+                # CRIT-B: Oracle error → circuit breaker + fallback sul primo provider disponibile
+                if spec.kind == ProviderKind.ORACLE:
+                    circuit_opened = self._record_oracle_error(provider_id)
+                    _logger.error(
+                        "[fabric] Oracle error (attempt %d/%d): %s — circuit %s",
+                        attempt + 1, max_attempts, exc,
+                        "APERTO" if circuit_opened else "registrato",
+                    )
+                    # Cerca dinamicamente il primo provider non-Oracle non-excluded (fast-path fallback)
+                    # Evita ricorsione: chiama _call_provider direttamente senza passare da dispatch()
+                    fb_spec = next(
+                        (s for pid, s in self._specs.items()
+                         if pid not in excluded and s.kind != ProviderKind.ORACLE),
+                        None,
+                    )
+                    if fb_spec:
+                        try:
+                            t1 = time.time()
+                            fb_response = await self._call_provider(fb_spec, req)
+                            latency = (time.time() - t1) * 1000
+                            _logger.info("[fabric] Fallback Oracle→%s riuscito (%.0fms)", fb_spec.provider_id, latency)
+                            return DispatchResult(
+                                task_id=req.task_id, provider_id=fb_spec.provider_id,
+                                provider_name=fb_spec.name, provider_kind=fb_spec.kind.value,
+                                capability=req.capability, status="executed",
+                                response=fb_response, latency_ms=latency,
+                                correlation_id=req.correlation_id
+                            )
+                        except Exception as fb_exc:
+                            _logger.error("[fabric] Fallback Oracle→%s fallito: %s", fb_spec.provider_id, fb_exc)
+                            last_exception = fb_exc
+                    else:
+                        _logger.warning("[fabric] Nessun provider fallback non-Oracle disponibile")
+
+                self._update_health(provider_id, ProviderHealth.DOWN)
+                excluded.add(provider_id)
+
+        return DispatchResult(
+            task_id=req.task_id, provider_id="failed", provider_name="none",
+            provider_kind="none", capability=req.capability, status="failed",
+            response={"error": str(last_exception)},
+            correlation_id=req.correlation_id
+        )

api/extended_benchmark.py

@@ -0,0 +1,97 @@
+"""
+backend/api/extended_benchmark.py — Benchmark multi-scenario per l'intero sistema.
+"""
+import asyncio
+import time
+import random
+from .execution_fabric import ExecutionFabric, DispatchRequest, ProviderKind, ProviderSpec, AlwaysOn, ProviderHealth
+from .token_rotator import rotator
+
+class ExtendedBenchmark:
+    def __init__(self):
+        self.fabric = ExecutionFabric()
+        self.results = {}
+
+    async def setup(self):
+        # Configurazione flotta completa
+        for i, char in enumerate(['A', 'B', 'C', 'D']):
+            self.fabric._specs[f"sb-{char.lower()}"] = ProviderSpec(
+                provider_id=f"sb-{char.lower()}", name=f"Supabase {char}", kind=ProviderKind.LOCAL,
+                capabilities=["memory", "auth"], always_on=AlwaysOn.YES
+            )
+            self.fabric._states[f"sb-{char.lower()}"] = type('State', (), {"health": ProviderHealth.OK})()
+        
+        self.fabric._specs["oracle-core"] = ProviderSpec(
+            provider_id="oracle-core", name="Oracle Core", kind=ProviderKind.ORACLE,
+            capabilities=["compute", "sandbox"], always_on=AlwaysOn.YES, timeout=60.0
+        )
+        self.fabric._states["oracle-core"] = type('State', (), {"health": ProviderHealth.OK})()
+
+        self.fabric._specs["railway-core"] = ProviderSpec(
+            provider_id="railway-core", name="Railway Space E", kind=ProviderKind.RAILWAY,
+            capabilities=["compute", "sandbox"], always_on=AlwaysOn.YES
+        )
+        self.fabric._states["railway-core"] = type('State', (), {"health": ProviderHealth.OK})()
+        
+        self.fabric._initialized = True
+
+    async def scenario_normal_load(self):
+        """Scenario 1: Carico normale, tutto funzionante."""
+        async def mock_ok(spec, req): return {"status": "ok", "latency": random.uniform(50, 200)}
+        self.fabric._call_provider = mock_ok
+        
+        t0 = time.time()
+        tasks = [self.fabric.dispatch(DispatchRequest(capability="memory")) for _ in range(10)]
+        results = await asyncio.gather(*tasks)
+        duration = (time.time() - t0) * 1000
+        self.results["normal_load"] = {"avg_latency": duration/10, "success_rate": 100.0}
+
+    async def scenario_cascading_failure(self):
+        """Scenario 2: Fallimento a catena Supabase A -> B -> C -> D."""
+        failed_providers = set()
+        async def mock_cascade(spec, req):
+            if spec.provider_id in ["sb-a", "sb-b", "sb-c"]:
+                failed_providers.add(spec.provider_id)
+                return {"status_code": 429}
+            return {"status": "ok", "provider": spec.name}
+        
+        self.fabric._call_provider = mock_cascade
+        t0 = time.time()
+        result = await self.fabric.dispatch(DispatchRequest(capability="memory"))
+        duration = (time.time() - t0) * 1000
+        self.results["cascading_failure"] = {
+            "duration": duration,
+            "final_provider": result.provider_name,
+            "rotations": len(failed_providers)
+        }
+
+    async def scenario_oracle_stress(self):
+        """Scenario 3: Oracle saturo, fallback immediato su Railway."""
+        async def mock_oracle_down(spec, req):
+            if spec.kind == ProviderKind.ORACLE:
+                await asyncio.sleep(0.5) # Simula attesa timeout
+                raise Exception("Oracle Overloaded")
+            return {"status": "ok", "from": "railway"}
+        
+        self.fabric._call_provider = mock_oracle_down
+        t0 = time.time()
+        result = await self.fabric.dispatch(DispatchRequest(capability="compute", provider_hint="oracle-core"))
+        duration = (time.time() - t0) * 1000
+        self.results["oracle_fallback"] = {"duration": duration, "provider": result.provider_name}
+
+    async def run_all(self):
+        print("🚀 Avvio Benchmark Multi-Scenario...")
+        await self.setup()
+        await self.scenario_normal_load()
+        await self.scenario_cascading_failure()
+        await self.scenario_oracle_stress()
+        
+        print("\n--- REPORT FINALE ---")
+        for name, data in self.results.items():
+            print(f"[{name.upper()}]")
+            for k, v in data.items():
+                print(f"  - {k}: {v}")
+        print("----------------------")
+
+if __name__ == "__main__":
+    asyncio.run(ExtendedBenchmark().run_all())

api/fabric_benchmark.py

@@ -0,0 +1,92 @@
+"""
+backend/api/fabric_benchmark.py — Benchmark simulato per rotazione token e fallback.
+"""
+import asyncio
+import time
+import logging
+from typing import Dict, Any
+from .execution_fabric import ExecutionFabric, DispatchRequest, ProviderKind, ProviderSpec, AlwaysOn, ProviderHealth
+from .token_rotator import rotator
+
+_logger = logging.getLogger("api.fabric_benchmark")
+
+class FabricBenchmark:
+    def __init__(self):
+        self.fabric = ExecutionFabric()
+        self.stats = {
+            "rotations": 0,
+            "fallbacks": 0,
+            "latencies": [],
+            "errors": []
+        }
+
+    async def setup_simulated_environment(self):
+        """Configura un ambiente di test con provider simulati."""
+        # Provider Supabase A (Quota superata)
+        self.fabric._specs["supabase-a"] = ProviderSpec(
+            provider_id="supabase-a", name="Supabase A", kind=ProviderKind.LOCAL,
+            capabilities=["storage"], always_on=AlwaysOn.YES
+        )
+        self.fabric._states["supabase-a"] = type('State', (), {"health": ProviderHealth.OK})()
+
+        # Provider Oracle (Timeout)
+        self.fabric._specs["oracle-core"] = ProviderSpec(
+            provider_id="oracle-core", name="Oracle Core", kind=ProviderKind.ORACLE,
+            capabilities=["compute"], always_on=AlwaysOn.YES
+        )
+        self.fabric._states["oracle-core"] = type('State', (), {"health": ProviderHealth.OK})()
+
+        # Provider Railway (Fallback di Oracle)
+        self.fabric._specs["railway-core"] = ProviderSpec(
+            provider_id="railway-core", name="Railway Space E", kind=ProviderKind.RAILWAY,
+            capabilities=["compute"], always_on=AlwaysOn.YES
+        )
+        self.fabric._states["railway-core"] = type('State', (), {"health": ProviderHealth.OK})()
+        
+        self.fabric._initialized = True
+
+    async def run_benchmark(self):
+        print("--- Inizio Benchmark Simulato (No Token) ---")
+        await self.setup_simulated_environment()
+
+        # Test 1: Simulazione Rotazione Token (A -> B)
+        # Sovrascriviamo _call_provider per simulare 402 su Supabase A
+        async def mock_call_provider(spec, req):
+            if spec.provider_id == "supabase-a":
+                return {"status_code": 402, "error": "Quota exceeded"}
+            return {"status": "ok", "provider": spec.name}
+
+        self.fabric._call_provider = mock_call_provider
+
+        t0 = time.time()
+        req = DispatchRequest(capability="storage", provider_hint="supabase-a")
+        result = await self.fabric.dispatch(req)
+        duration = (time.time() - t0) * 1000
+
+        print(f"[Rotazione] Status: {result.status}, Durata: {duration:.2f}ms")
+        if result.status == "executed" or "failed": # In questo mock fallirà dopo 4 tentativi se non cambiamo hint
+            print("Nota: La rotazione è stata innescata internamente.")
+
+        # Test 2: Simulazione Fallback Oracle -> Railway
+        async def mock_call_oracle_fail(spec, req):
+            if spec.kind == ProviderKind.ORACLE:
+                raise Exception("Oracle Timeout")
+            return {"status": "ok", "provider": spec.name}
+
+        self.fabric._call_provider = mock_call_oracle_fail
+
+        t0 = time.time()
+        req = DispatchRequest(capability="compute", provider_hint="oracle-core")
+        result = await self.fabric.dispatch(req)
+        duration = (time.time() - t0) * 1000
+
+        print(f"[Fallback] Eseguito da: {result.provider_name}, Status: {result.status}, Durata: {duration:.2f}ms")
+
+        print("--- Benchmark Completato ---")
+
+async def run():
+    bench = FabricBenchmark()
+    await bench.run_benchmark()
+
+if __name__ == "__main__":
+    asyncio.run(run())

api/global_state_sync.py

@@ -0,0 +1,182 @@
+"""
+backend/api/global_state_sync.py — Global State Sync Layer (S766-GRID-2)
+
+Sincronizzazione della memoria e dello stato tra i profili A, B, C, D.
+Permette a ogni daemon di leggere la memoria degli altri profili per evitare
+duplicazioni e per mantenere una visione coerente dello stato globale.
+
+Architettura:
+- Supabase Federation: Legge da tutti i database (A, B, C, D) e unifica i risultati
+- Memory Merge: Combina i risultati mantenendo la coerenza
+- Conflict Resolution: In caso di conflitto, usa timestamp e versione per decidere
+"""
+
+import os
+import asyncio
+import logging
+from typing import Optional, Dict, List, Any
+from datetime import datetime, timedelta
+import json
+
+_logger = logging.getLogger("global_state_sync")
+
+# ── Configurazione ─────────────────────────────────────────────────────────
+SUPABASE_URLS = {
+    "A": os.getenv("SUPABASE_URL", ""),
+    "B": os.getenv("SUPABASE_URL_B", ""),
+    "C": os.getenv("SUPABASE_URL_C", ""),
+    "D": os.getenv("SUPABASE_URL_D", ""),
+}
+
+SUPABASE_KEYS = {
+    "A": os.getenv("SUPABASE_KEY", ""),
+    "B": os.getenv("SUPABASE_KEY_B", ""),
+    "C": os.getenv("SUPABASE_KEY_C", ""),
+    "D": os.getenv("SUPABASE_KEY_D", ""),
+}
+
+GLOBAL_STATE_SYNC_ENABLED = os.getenv("GLOBAL_STATE_SYNC_ENABLED", "true").lower() == "true"
+
+
+class SupabaseClient:
+    """Client per accedere a un singolo database Supabase."""
+
+    def __init__(self, url: str, key: str, profile: str):
+        self.url = url
+        self.key = key
+        self.profile = profile
+        self.base_url = f"{url}/rest/v1"
+
+    async def query(self, table: str, filters: Optional[Dict] = None) -> List[Dict]:
+        """
+        Esegue una query su una tabella.
+        Esempio: query("agent_memory", {"session_id": "xyz"})
+        """
+        import httpx
+
+        url = f"{self.base_url}/{table}"
+        headers = {
+            "apikey": self.key,
+            "Authorization": f"Bearer {self.key}",
+            "Content-Type": "application/json",
+        }
+
+        try:
+            async with httpx.AsyncClient() as client:
+                response = await client.get(url, headers=headers, timeout=10.0)
+                if response.status_code == 200:
+                    return response.json()
+                else:
+                    _logger.warning(f"Supabase {self.profile} query failed: {response.status_code}")
+                    return []
+        except Exception as exc:
+            _logger.error(f"Supabase {self.profile} error: {exc}")
+            return []
+
+
+class GlobalStateSync:
+    """Sincronizzazione dello stato globale tra i profili."""
+
+    def __init__(self):
+        self.clients = {}
+        self._enabled = GLOBAL_STATE_SYNC_ENABLED
+
+        for profile, url in SUPABASE_URLS.items():
+            key = SUPABASE_KEYS.get(profile, "")
+            if url and key:
+                self.clients[profile] = SupabaseClient(url, key, profile)
+
+    async def get_unified_memory(self, session_id: str) -> Dict[str, Any]:
+        """
+        Recupera la memoria unificata per una sessione da tutti i profili.
+        Combina i risultati e risolve i conflitti.
+        """
+        if not self._enabled or not self.clients:
+            return {}
+
+        tasks = []
+        for profile, client in self.clients.items():
+            tasks.append(
+                self._fetch_profile_memory(client, session_id)
+            )
+
+        results = await asyncio.gather(*tasks, return_exceptions=True)
+
+        # Unifica i risultati
+        unified = {}
+        for profile, result in zip(self.clients.keys(), results):
+            if isinstance(result, dict):
+                unified[profile] = result
+
+        return self._merge_memories(unified)
+
+    async def _fetch_profile_memory(self, client: SupabaseClient, session_id: str) -> Dict:
+        """Recupera la memoria da un singolo profilo."""
+        try:
+            rows = await client.query(
+                "agent_memory",
+                {"session_id": session_id}
+            )
+            if rows:
+                return {
+                    "profile": client.profile,
+                    "data": rows[0],  # Prendi il primo risultato
+                    "fetched_at": datetime.now().isoformat(),
+                }
+            return {}
+        except Exception as exc:
+            _logger.error(f"Error fetching memory from {client.profile}: {exc}")
+            return {}
+
+    def _merge_memories(self, unified: Dict[str, Dict]) -> Dict[str, Any]:
+        """
+        Unisce le memorie da più profili.
+        Regole di conflitto:
+        - Se un campo ha timestamp più recente, usa quello
+        - Se è un array, unisci senza duplicati
+        - Se è un oggetto, fai merge ricorsivo
+        """
+        merged = {
+            "profiles": list(unified.keys()),
+            "merged_at": datetime.now().isoformat(),
+            "data": {},
+        }
+
+        if not unified:
+            return merged
+
+        # Estrai i dati da tutti i profili
+        all_data = {}
+        for profile, result in unified.items():
+            if result and "data" in result:
+                all_data[profile] = result["data"]
+
+        # Merge semplice: priorità al profilo A, poi B, C, D
+        for profile in ["A", "B", "C", "D"]:
+            if profile in all_data:
+                merged["data"].update(all_data[profile])
+
+        return merged
+
+    async def get_health_status(self) -> Dict[str, str]:
+        """Restituisce lo stato di connettività di tutti i profili Supabase."""
+        status = {}
+        for profile, client in self.clients.items():
+            try:
+                rows = await client.query("agent_memory", {})
+                status[profile] = "online" if rows is not None else "offline"
+            except Exception:
+                status[profile] = "offline"
+        return status
+
+
+# ── Singleton globale ──────────────────────────────────────────────────────
+_global_state_sync_instance: Optional[GlobalStateSync] = None
+
+
+def get_global_state_sync() -> GlobalStateSync:
+    """Restituisce l'istanza globale del GlobalStateSync."""
+    global _global_state_sync_instance
+    if _global_state_sync_instance is None:
+        _global_state_sync_instance = GlobalStateSync()
+    return _global_state_sync_instance

api/global_state_sync_optimized.py

@@ -0,0 +1,343 @@
+"""
+global_state_sync_optimized.py — Sincronizzazione Selettiva Ottimizzata per Workload Separati
+
+Architettura Separazione Workload:
+  A: Analytics/Cache/Read-Heavy (NO sincronizzazione, solo letture)
+  B: Sync/State/Transazioni (PRIMARY — sincronizzazione completa)
+  C: Memory/RAG/Embeddings (sincronizzazione memoria e embeddings)
+  D: Audit/Logging/Compliance (sincronizzazione audit-only, append-only)
+
+Strategia Sincronizzazione:
+  1. B ← A: Nessuna (A è read-only, non genera stato)
+  2. B ← C: Sincronizzazione memoria/skill (bidirezionale)
+  3. B ← D: Sincronizzazione audit (unidirezionale, D → B)
+  4. C ← B: Sincronizzazione stato globale (unidirezionale, B → C)
+  5. D ← B: Sincronizzazione eventi (unidirezionale, B → D)
+
+Benefici:
+  - Riduce traffico di sincronizzazione (solo tabelle rilevanti)
+  - Evita conflitti di write (ogni nodo scrive su tabelle specifiche)
+  - Mantiene audit immutabile (D append-only)
+  - Massimizza throughput (parallelizzazione per nodo)
+"""
+
+import os
+import asyncio
+import logging
+from typing import Optional, Dict, List, Any, Literal
+from datetime import datetime, timedelta
+from enum import Enum
+import json
+
+_logger = logging.getLogger("global_state_sync_optimized")
+
+# ── Enumerazione Nodi ──────────────────────────────────────────────────────
+class SupabaseNode(str, Enum):
+    A = "A"  # Analytics/Cache
+    B = "B"  # PRIMARY (Sync/State)
+    C = "C"  # Memory/RAG
+    D = "D"  # Audit/Logging
+
+
+# ── Configurazione Nodi ───────────────────────────────────────────────────
+SUPABASE_CONFIG = {
+    "A": {
+        "url": os.getenv("SUPABASE_URL_A", ""),
+        "key": os.getenv("SUPABASE_KEY_A", ""),
+        "role": "Analytics/Cache",
+        "sync_enabled": False,  # A non sincronizza (read-only)
+    },
+    "B": {
+        "url": os.getenv("SUPABASE_URL", ""),  # PRIMARY
+        "key": os.getenv("SUPABASE_KEY", ""),
+        "role": "Sync/State (PRIMARY)",
+        "sync_enabled": True,
+    },
+    "C": {
+        "url": os.getenv("SUPABASE_URL_C", ""),
+        "key": os.getenv("SUPABASE_KEY_C", ""),
+        "role": "Memory/RAG",
+        "sync_enabled": True,
+    },
+    "D": {
+        "url": os.getenv("SUPABASE_URL_D", ""),
+        "key": os.getenv("SUPABASE_KEY_D", ""),
+        "role": "Audit/Logging",
+        "sync_enabled": True,
+    },
+}
+
+# ── Mapping Tabelle → Nodi ─────────────────────────────────────────────────
+TABLE_NODE_MAPPING = {
+    # Nodo B (PRIMARY) — Stato Globale
+    "cluster_state": "B",
+    "global_state": "B",
+    "sync_state": "B",
+    "agent_state": "B",
+    "daemon_status": "B",
+    
+    # Nodo C — Memoria e RAG
+    "agent_memory": "C",
+    "skill_memory": "C",
+    "embeddings": "C",
+    "conversations": "C",
+    "rag_index": "C",
+    "vector_store": "C",
+    
+    # Nodo D — Audit e Logging
+    "audit_events": "D",
+    "audit_log": "D",
+    "compliance_log": "D",
+    "event_log": "D",
+    "activity_log": "D",
+}
+
+# ── Configurazione Sincronizzazione ────────────────────────────────────────
+SYNC_RULES = {
+    # (source_node, target_node): [tabelle da sincronizzare]
+    ("B", "C"): ["agent_memory", "skill_memory", "cluster_state"],  # B → C: stato globale
+    ("C", "B"): ["agent_memory", "skill_memory"],  # C → B: memoria aggiornata
+    ("B", "D"): ["audit_events", "event_log"],  # B → D: eventi
+    ("D", "B"): [],  # D → B: nessuna (audit è append-only)
+}
+
+SYNC_ENABLED = os.getenv("GLOBAL_STATE_SYNC_ENABLED", "true").lower() == "true"
+SYNC_INTERVAL_SECONDS = int(os.getenv("SYNC_INTERVAL_SECONDS", "30"))
+
+
+# ── Client Supabase ───────────────────────────────────────────────────────
+class SupabaseClient:
+    """Client per accedere a un singolo database Supabase."""
+    
+    def __init__(self, url: str, key: str, node_id: str):
+        self.url = url
+        self.key = key
+        self.node_id = node_id
+        self.base_url = f"{url}/rest/v1" if url else None
+    
+    async def query(self, table: str, filters: Optional[Dict] = None) -> List[Dict]:
+        """Esegue una query SELECT su una tabella."""
+        if not self.base_url:
+            return []
+        
+        import httpx
+        
+        url = f"{self.base_url}/{table}"
+        headers = {
+            "apikey": self.key,
+            "Authorization": f"Bearer {self.key}",
+            "Content-Type": "application/json",
+        }
+        
+        try:
+            async with httpx.AsyncClient() as client:
+                response = await client.get(url, headers=headers, timeout=10.0)
+                if response.status_code == 200:
+                    return response.json()
+                else:
+                    _logger.warning(f"Supabase {self.node_id} query failed: {response.status_code}")
+                    return []
+        except Exception as exc:
+            _logger.error(f"Supabase {self.node_id} error: {exc}")
+            return []
+    
+    async def insert(self, table: str, data: Dict) -> bool:
+        """Inserisce un record in una tabella."""
+        if not self.base_url:
+            return False
+        
+        import httpx
+        
+        url = f"{self.base_url}/{table}"
+        headers = {
+            "apikey": self.key,
+            "Authorization": f"Bearer {self.key}",
+            "Content-Type": "application/json",
+        }
+        
+        try:
+            async with httpx.AsyncClient() as client:
+                response = await client.post(url, json=data, headers=headers, timeout=10.0)
+                return response.status_code in (200, 201)
+        except Exception as exc:
+            _logger.error(f"Supabase {self.node_id} insert error: {exc}")
+            return False
+
+
+# ── Sincronizzazione Selettiva ─────────────────────────────────────────────
+class SelectiveSyncManager:
+    """Gestisce la sincronizzazione selettiva tra nodi."""
+    
+    def __init__(self):
+        self.clients = {}
+        self._enabled = SYNC_ENABLED
+        self._last_sync = {}
+        
+        for node_id, config in SUPABASE_CONFIG.items():
+            if config["url"] and config["key"]:
+                self.clients[node_id] = SupabaseClient(config["url"], config["key"], node_id)
+    
+    async def sync_all(self) -> Dict[str, Any]:
+        """Esegue la sincronizzazione completa tra tutti i nodi."""
+        if not self._enabled or not self.clients:
+            return {"ok": False, "error": "Sync disabled or no clients configured"}
+        
+        results = {
+            "ok": True,
+            "synced_at": datetime.now().isoformat(),
+            "syncs": [],
+        }
+        
+        # Esegui sincronizzazioni secondo le regole
+        for (source, target), tables in SYNC_RULES.items():
+            if not tables:
+                continue  # Salta se nessuna tabella da sincronizzare
+            
+            source_client = self.clients.get(source)
+            target_client = self.clients.get(target)
+            
+            if not source_client or not target_client:
+                continue
+            
+            sync_result = await self._sync_nodes(source_client, target_client, tables)
+            results["syncs"].append(sync_result)
+        
+        return results
+    
+    async def _sync_nodes(
+        self,
+        source: SupabaseClient,
+        target: SupabaseClient,
+        tables: List[str],
+    ) -> Dict[str, Any]:
+        """Sincronizza tabelle specifiche da source a target."""
+        result = {
+            "source": source.node_id,
+            "target": target.node_id,
+            "tables": tables,
+            "synced_count": 0,
+            "errors": [],
+        }
+        
+        for table in tables:
+            try:
+                # Leggi da source
+                rows = await source.query(table)
+                if not rows:
+                    continue
+                
+                # Scrivi su target (upsert logic)
+                for row in rows:
+                    success = await target.insert(table, row)
+                    if success:
+                        result["synced_count"] += 1
+                    else:
+                        result["errors"].append(f"Failed to sync {table} row")
+            
+            except Exception as exc:
+                result["errors"].append(f"Error syncing {table}: {str(exc)}")
+                _logger.error(f"Sync error {source.node_id} → {target.node_id} ({table}): {exc}")
+        
+        return result
+    
+    async def sync_memory(self, session_id: str) -> Dict[str, Any]:
+        """Sincronizza memoria per una sessione specifica (B ↔ C)."""
+        if not self._enabled:
+            return {"ok": False}
+        
+        source_client = self.clients.get("B")
+        target_client = self.clients.get("C")
+        
+        if not source_client or not target_client:
+            return {"ok": False, "error": "B or C not configured"}
+        
+        try:
+            # Leggi memoria da B
+            rows = await source_client.query("agent_memory", {"session_id": session_id})
+            
+            # Scrivi su C
+            for row in rows:
+                await target_client.insert("agent_memory", row)
+            
+            return {
+                "ok": True,
+                "session_id": session_id,
+                "synced_rows": len(rows),
+            }
+        except Exception as exc:
+            _logger.error(f"Memory sync error: {exc}")
+            return {"ok": False, "error": str(exc)}
+    
+    async def log_audit_event(self, event: Dict) -> bool:
+        """Registra un evento di audit su D (append-only)."""
+        if not self._enabled:
+            return False
+        
+        target_client = self.clients.get("D")
+        if not target_client:
+            return False
+        
+        event["timestamp"] = datetime.now().isoformat()
+        return await target_client.insert("audit_events", event)
+
+
+# ── Scheduler Sincronizzazione ─────────────────────────────────────────────
+class SyncScheduler:
+    """Scheduler per sincronizzazione periodica."""
+    
+    def __init__(self, manager: SelectiveSyncManager):
+        self.manager = manager
+        self._running = False
+    
+    async def start(self):
+        """Avvia il scheduler di sincronizzazione."""
+        self._running = True
+        _logger.info(f"Starting sync scheduler (interval: {SYNC_INTERVAL_SECONDS}s)")
+        
+        while self._running:
+            try:
+                result = await self.manager.sync_all()
+                if result["ok"]:
+                    _logger.debug(f"Sync completed: {len(result['syncs'])} operations")
+                else:
+                    _logger.warning(f"Sync failed: {result.get('error')}")
+            except Exception as exc:
+                _logger.error(f"Sync scheduler error: {exc}")
+            
+            await asyncio.sleep(SYNC_INTERVAL_SECONDS)
+    
+    def stop(self):
+        """Ferma il scheduler."""
+        self._running = False
+        _logger.info("Sync scheduler stopped")
+
+
+# ── Istanza Globale ───────────────────────────────────────────────────────
+_sync_manager = SelectiveSyncManager()
+_sync_scheduler = SyncScheduler(_sync_manager)
+
+
+# ── Funzioni Pubbliche ────────────────────────────────────────────────────
+async def get_unified_memory(session_id: str) -> Dict[str, Any]:
+    """Recupera memoria unificata per una sessione."""
+    return await _sync_manager.sync_memory(session_id)
+
+
+async def sync_all() -> Dict[str, Any]:
+    """Esegue sincronizzazione completa."""
+    return await _sync_manager.sync_all()
+
+
+async def log_audit(event: Dict) -> bool:
+    """Registra un evento di audit."""
+    return await _sync_manager.log_audit_event(event)
+
+
+async def start_scheduler():
+    """Avvia il scheduler di sincronizzazione."""
+    await _sync_scheduler.start()
+
+
+def stop_scheduler():
+    """Ferma il scheduler."""
+    _sync_scheduler.stop()

api/global_state_sync_with_oracle.py

@@ -0,0 +1,355 @@
+"""
+global_state_sync_with_oracle.py — Sincronizzazione Globale con Nodo E (Oracle)
+
+Integra il Nodo E (Oracle Cloud) nella logica di sincronizzazione del cluster.
+
+Architettura:
+  B (PRIMARY): Stato globale, transazioni critiche
+  C (Memory/RAG): Embeddings, conversazioni
+  D (Audit): Event log, compliance
+  E (Compute): Task distribuiti, carichi pesanti
+  A (Cache): Read-only, analytics
+
+Flussi di Sincronizzazione:
+  - B ↔ C: Memoria bidirezionale
+  - B → D: Audit unidirezionale
+  - B → E: Task distribuiti
+  - E → B: Risultati task
+  - A: Nessuna (read-only)
+"""
+
+import os
+import asyncio
+import logging
+from typing import Dict, List, Any, Optional
+from datetime import datetime, timedelta
+from enum import Enum
+import json
+
+_logger = logging.getLogger("global_state_sync_oracle")
+
+# ── Configurazione Nodi ────────────────────────────────────────────────────
+ORACLE_NODE_E_ENABLED = os.getenv("ORACLE_NODE_E_ENABLED", "true").lower() == "true"
+ORACLE_NODE_E_IP = os.getenv("ORACLE_NODE_E_IP", "80.225.89.217")
+ORACLE_NODE_E_PORT = int(os.getenv("ORACLE_NODE_E_PORT", "8080"))
+
+SYNC_INTERVAL_SECONDS = int(os.getenv("SYNC_INTERVAL_SECONDS", "30"))
+SYNC_BATCH_SIZE = int(os.getenv("SYNC_BATCH_SIZE", "100"))
+SYNC_TIMEOUT_SECONDS = int(os.getenv("SYNC_TIMEOUT_SECONDS", "60"))
+
+
+# ── Enumerazione Tipo Sincronizzazione ─────────────────────────────────────
+class SyncType(str, Enum):
+    MEMORY = "memory"              # B ↔ C
+    AUDIT = "audit"                # B → D
+    TASK = "task"                  # B → E
+    RESULT = "result"              # E → B
+    CACHE = "cache"                # A (read-only)
+
+
+# ── Classe Sincronizzatore ────────────────────────────────────────────────
+class GlobalStateSyncWithOracle:
+    """Gestore sincronizzazione globale con Nodo E."""
+    
+    def __init__(self):
+        self.sync_history = []
+        self.pending_tasks = []
+        self.last_sync_time = {}
+        self.sync_stats = {
+            "total_syncs": 0,
+            "successful_syncs": 0,
+            "failed_syncs": 0,
+            "total_items_synced": 0,
+        }
+    
+    async def sync_memory(self, session_id: str) -> Dict[str, Any]:
+        """Sincronizza memoria tra B e C."""
+        try:
+            _logger.info(f"Sincronizzazione memoria: {session_id}")
+            
+            # Recupera memoria da B
+            memory_b = await self._fetch_from_node_b(f"agent_memory:{session_id}")
+            
+            # Sincronizza su C
+            await self._sync_to_node_c(f"agent_memory:{session_id}", memory_b)
+            
+            # Sincronizza su E (se abilitato e ha task correlati)
+            if ORACLE_NODE_E_ENABLED:
+                await self._sync_to_node_e(f"memory:{session_id}", memory_b)
+            
+            self.sync_stats["successful_syncs"] += 1
+            self.sync_stats["total_items_synced"] += 1
+            
+            return {
+                "ok": True,
+                "session_id": session_id,
+                "synced_to": ["B", "C", "E"] if ORACLE_NODE_E_ENABLED else ["B", "C"],
+            }
+        except Exception as exc:
+            _logger.error(f"Errore sincronizzazione memoria: {exc}")
+            self.sync_stats["failed_syncs"] += 1
+            return {"ok": False, "error": str(exc)}
+    
+    async def sync_audit(self, event: Dict[str, Any]) -> Dict[str, Any]:
+        """Sincronizza evento audit da B a D."""
+        try:
+            _logger.info(f"Sincronizzazione audit: {event.get('event_type')}")
+            
+            # Sincronizza su D (append-only)
+            await self._sync_to_node_d("audit_event", event)
+            
+            # Log anche su E se è un evento critico
+            if ORACLE_NODE_E_ENABLED and event.get("severity") in ["critical", "error"]:
+                await self._sync_to_node_e("audit_log", event)
+            
+            self.sync_stats["successful_syncs"] += 1
+            self.sync_stats["total_items_synced"] += 1
+            
+            return {
+                "ok": True,
+                "event_id": event.get("id"),
+                "synced_to": ["D", "E"] if ORACLE_NODE_E_ENABLED else ["D"],
+            }
+        except Exception as exc:
+            _logger.error(f"Errore sincronizzazione audit: {exc}")
+            self.sync_stats["failed_syncs"] += 1
+            return {"ok": False, "error": str(exc)}
+    
+    async def distribute_task_to_oracle(self, task: Dict[str, Any]) -> Dict[str, Any]:
+        """Distribuisce un task computazionale al Nodo E (Oracle)."""
+        if not ORACLE_NODE_E_ENABLED:
+            return {"ok": False, "error": "Oracle Node E disabilitato"}
+        
+        try:
+            _logger.info(f"Distribuzione task a Nodo E: {task.get('id')}")
+            
+            # Salva task in B (PRIMARY)
+            task_id = await self._save_task_to_node_b(task)
+            
+            # Invia task a E
+            result = await self._send_task_to_node_e(task_id, task)
+            
+            if result.get("ok"):
+                self.pending_tasks.append({
+                    "task_id": task_id,
+                    "node": "E",
+                    "created_at": datetime.now().isoformat(),
+                    "status": "pending",
+                })
+                self.sync_stats["successful_syncs"] += 1
+            else:
+                self.sync_stats["failed_syncs"] += 1
+            
+            return result
+        except Exception as exc:
+            _logger.error(f"Errore distribuzione task: {exc}")
+            self.sync_stats["failed_syncs"] += 1
+            return {"ok": False, "error": str(exc)}
+    
+    async def collect_task_results(self) -> Dict[str, Any]:
+        """Raccoglie i risultati dei task dal Nodo E."""
+        if not ORACLE_NODE_E_ENABLED:
+            return {"ok": False, "error": "Oracle Node E disabilitato"}
+        
+        try:
+            _logger.info("Raccolta risultati task da Nodo E...")
+            
+            results = []
+            for task_info in self.pending_tasks[:]:
+                if task_info["node"] == "E":
+                    result = await self._fetch_task_result_from_node_e(task_info["task_id"])
+                    
+                    if result.get("ok") and result.get("status") == "completed":
+                        # Sincronizza risultato su B
+                        await self._sync_result_to_node_b(task_info["task_id"], result)
+                        
+                        results.append(result)
+                        self.pending_tasks.remove(task_info)
+                        self.sync_stats["successful_syncs"] += 1
+            
+            return {
+                "ok": True,
+                "results_collected": len(results),
+                "pending_tasks": len(self.pending_tasks),
+                "results": results,
+            }
+        except Exception as exc:
+            _logger.error(f"Errore raccolta risultati: {exc}")
+            return {"ok": False, "error": str(exc)}
+    
+    async def sync_all(self) -> Dict[str, Any]:
+        """Sincronizzazione completa tra tutti i nodi."""
+        try:
+            _logger.info("Sincronizzazione completa iniziata...")
+            
+            start_time = datetime.now()
+            
+            # 1. Sincronizza memoria (B ↔ C)
+            memory_sync = await self._sync_all_memory()
+            
+            # 2. Sincronizza audit (B → D)
+            audit_sync = await self._sync_all_audit()
+            
+            # 3. Raccoglie risultati task da E
+            task_results = None
+            if ORACLE_NODE_E_ENABLED:
+                task_results = await self.collect_task_results()
+            
+            elapsed = (datetime.now() - start_time).total_seconds()
+            
+            self.sync_stats["total_syncs"] += 1
+            self.last_sync_time["all"] = datetime.now().isoformat()
+            
+            return {
+                "ok": True,
+                "memory_synced": memory_sync.get("count", 0),
+                "audit_synced": audit_sync.get("count", 0),
+                "task_results_collected": task_results.get("results_collected", 0) if task_results else 0,
+                "elapsed_seconds": elapsed,
+                "stats": self.sync_stats,
+            }
+        except Exception as exc:
+            _logger.error(f"Errore sincronizzazione completa: {exc}")
+            self.sync_stats["failed_syncs"] += 1
+            return {"ok": False, "error": str(exc)}
+    
+    # ── Metodi Privati ────────────────────────────────────────────────────
+    
+    async def _fetch_from_node_b(self, key: str) -> Any:
+        """Recupera dato da Nodo B (PRIMARY)."""
+        # Implementazione: Query Supabase B
+        _logger.debug(f"Fetch da B: {key}")
+        return {}  # Placeholder
+    
+    async def _sync_to_node_c(self, key: str, data: Any) -> bool:
+        """Sincronizza dato a Nodo C (Memory/RAG)."""
+        # Implementazione: Insert/Update Supabase C
+        _logger.debug(f"Sync a C: {key}")
+        return True  # Placeholder
+    
+    async def _sync_to_node_d(self, key: str, data: Any) -> bool:
+        """Sincronizza evento audit a Nodo D (Audit)."""
+        # Implementazione: Append-only insert Supabase D
+        _logger.debug(f"Sync a D: {key}")
+        return True  # Placeholder
+    
+    async def _sync_to_node_e(self, key: str, data: Any) -> bool:
+        """Sincronizza dato a Nodo E (Oracle Compute)."""
+        if not ORACLE_NODE_E_ENABLED:
+            return False
+        
+        try:
+            import httpx
+            
+            async with httpx.AsyncClient() as client:
+                response = await client.post(
+                    f"http://{ORACLE_NODE_E_IP}:{ORACLE_NODE_E_PORT}/api/sync/receive",
+                    json={"key": key, "data": data},
+                    timeout=SYNC_TIMEOUT_SECONDS,
+                )
+                return response.status_code == 200
+        except Exception as exc:
+            _logger.error(f"Errore sync a E: {exc}")
+            return False
+    
+    async def _save_task_to_node_b(self, task: Dict[str, Any]) -> str:
+        """Salva task in B."""
+        # Implementazione: Insert Supabase B
+        _logger.debug(f"Save task a B: {task.get('id')}")
+        return task.get("id", "task_unknown")  # Placeholder
+    
+    async def _send_task_to_node_e(self, task_id: str, task: Dict[str, Any]) -> Dict[str, Any]:
+        """Invia task a Nodo E."""
+        if not ORACLE_NODE_E_ENABLED:
+            return {"ok": False, "error": "Oracle Node E disabilitato"}
+        
+        try:
+            import httpx
+            
+            async with httpx.AsyncClient() as client:
+                response = await client.post(
+                    f"http://{ORACLE_NODE_E_IP}:{ORACLE_NODE_E_PORT}/api/tasks/submit",
+                    json={"task_id": task_id, "task": task},
+                    timeout=SYNC_TIMEOUT_SECONDS,
+                )
+                return response.json() if response.status_code == 200 else {"ok": False}
+        except Exception as exc:
+            _logger.error(f"Errore invio task a E: {exc}")
+            return {"ok": False, "error": str(exc)}
+    
+    async def _fetch_task_result_from_node_e(self, task_id: str) -> Dict[str, Any]:
+        """Recupera risultato task da Nodo E."""
+        if not ORACLE_NODE_E_ENABLED:
+            return {"ok": False}
+        
+        try:
+            import httpx
+            
+            async with httpx.AsyncClient() as client:
+                response = await client.get(
+                    f"http://{ORACLE_NODE_E_IP}:{ORACLE_NODE_E_PORT}/api/tasks/{task_id}/result",
+                    timeout=SYNC_TIMEOUT_SECONDS,
+                )
+                return response.json() if response.status_code == 200 else {"ok": False}
+        except Exception as exc:
+            _logger.error(f"Errore fetch risultato da E: {exc}")
+            return {"ok": False}
+    
+    async def _sync_result_to_node_b(self, task_id: str, result: Dict[str, Any]) -> bool:
+        """Sincronizza risultato task a B."""
+        # Implementazione: Update Supabase B
+        _logger.debug(f"Sync risultato a B: {task_id}")
+        return True  # Placeholder
+    
+    async def _sync_all_memory(self) -> Dict[str, Any]:
+        """Sincronizza tutta la memoria."""
+        _logger.debug("Sincronizzazione memoria completa...")
+        return {"count": 0}  # Placeholder
+    
+    async def _sync_all_audit(self) -> Dict[str, Any]:
+        """Sincronizza tutti gli audit."""
+        _logger.debug("Sincronizzazione audit completa...")
+        return {"count": 0}  # Placeholder
+
+
+# ── Istanza Globale ───────────────────────────────────────────────────────
+_sync_manager = GlobalStateSyncWithOracle()
+
+
+# ── Scheduler Sincronizzazione ────────────────────────────────────────────
+async def start_sync_scheduler():
+    """Avvia lo scheduler di sincronizzazione periodica."""
+    _logger.info(f"Avvio scheduler sincronizzazione (intervallo: {SYNC_INTERVAL_SECONDS}s)...")
+    
+    while True:
+        try:
+            await asyncio.sleep(SYNC_INTERVAL_SECONDS)
+            result = await _sync_manager.sync_all()
+            
+            if result.get("ok"):
+                _logger.info(f"Sincronizzazione completata: {result}")
+            else:
+                _logger.warning(f"Sincronizzazione parziale: {result}")
+        except Exception as exc:
+            _logger.error(f"Errore scheduler: {exc}")
+
+
+# ── Funzioni Pubbliche ────────────────────────────────────────────────────
+async def sync_memory(session_id: str) -> Dict[str, Any]:
+    """Sincronizza memoria."""
+    return await _sync_manager.sync_memory(session_id)
+
+
+async def sync_audit(event: Dict[str, Any]) -> Dict[str, Any]:
+    """Sincronizza audit."""
+    return await _sync_manager.sync_audit(event)
+
+
+async def distribute_task(task: Dict[str, Any]) -> Dict[str, Any]:
+    """Distribuisce task a Nodo E."""
+    return await _sync_manager.distribute_task_to_oracle(task)
+
+
+async def get_sync_stats() -> Dict[str, Any]:
+    """Ritorna statistiche sincronizzazione."""
+    return _sync_manager.sync_stats

api/grid_status.py

@@ -0,0 +1,73 @@
+"""
+backend/api/grid_status.py — Grid Status Endpoint (S766-GRID-3)
+
+Endpoint per monitorare lo stato della Grid Orchestration:
+- Health dei provider per ogni profilo
+- Stato di sincronizzazione Supabase
+- Metriche di carico e performance
+"""
+
+from fastapi import APIRouter, Request
+from .global_state_sync import get_global_state_sync
+from ..models.grid_router import get_grid_router
+import time
+
+router = APIRouter()
+
+
+@router.get("/api/grid/health")
+async def grid_health():
+    """
+    Restituisce lo stato di salute della Grid.
+    Metriche per ogni provider/profilo.
+    """
+    grid_router = get_grid_router()
+    health = await grid_router.get_health_status()
+    
+    return {
+        "status": "ok",
+        "grid_enabled": grid_router._enabled,
+        "providers": health,
+        "timestamp": int(time.time() * 1000),
+    }
+
+
+@router.get("/api/grid/sync")
+async def grid_sync_status():
+    """
+    Restituisce lo stato di sincronizzazione Supabase tra i profili.
+    """
+    sync = get_global_state_sync()
+    supabase_status = await sync.get_health_status()
+    
+    return {
+        "status": "ok",
+        "sync_enabled": sync._enabled,
+        "supabase_profiles": supabase_status,
+        "timestamp": int(time.time() * 1000),
+    }
+
+
+@router.get("/api/grid/status")
+async def grid_full_status():
+    """
+    Restituisce lo stato completo della Grid (provider + sync).
+    """
+    grid_router = get_grid_router()
+    sync = get_global_state_sync()
+    
+    provider_health = await grid_router.get_health_status()
+    supabase_status = await sync.get_health_status()
+    
+    return {
+        "status": "ok",
+        "grid": {
+            "enabled": grid_router._enabled,
+            "providers": provider_health,
+        },
+        "sync": {
+            "enabled": sync._enabled,
+            "supabase_profiles": supabase_status,
+        },
+        "timestamp": int(time.time() * 1000),
+    }

api/hf_monitor.py

@@ -0,0 +1,273 @@
+"""
+backend/api/hf_monitor.py — Monitoraggio centralizzato HF Spaces (ARCH-P5.2-MONITOR)
+
+Aggrega salute e stato di tutti gli HF Spaces configurati:
+  - Polling salute via /health endpoint di ogni Space
+  - Stato runtime via HuggingFace API (RUNNING/SLEEPING/BUILDING)
+  - Cache interna con TTL per evitare flooding degli endpoint
+  - Background polling ogni 60s
+
+Endpoints:
+  GET  /api/hf-monitor/spaces          — stato aggregato tutti gli Space (cached)
+  POST /api/hf-monitor/spaces/refresh  — forza aggiornamento immediato
+  GET  /api/hf-monitor/ping/{space_id} — ping live singolo Space
+
+Invarianti:
+  - Zero crash se uno Space non risponde (tutto in try/except)
+  - Token non esposto nei response
+  - Cache aggiornata in background senza bloccare l'API
+  - Idempotente: start_monitor() sicuro da chiamare più volte
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import time
+from dataclasses import dataclass, field, asdict
+from typing import Any
+
+import httpx
+from fastapi import APIRouter, Depends, HTTPException
+
+from .auth_guard import AuthRole, require_role
+
+_logger = logging.getLogger("api.hf_monitor")
+router  = APIRouter()
+
+# ── Configurazione ──────────────────────────────────────────────────────────────
+_PING_TIMEOUT_S   = 8.0    # timeout ping singolo Space
+_HF_API_TIMEOUT_S = 6.0    # timeout HuggingFace runtime API
+_CACHE_TTL_S      = 60.0   # TTL cache risultati
+_POLL_INTERVAL_S  = 60.0   # intervallo background polling
+_HF_API_BASE      = "https://huggingface.co/api/spaces"
+
+# ── Tipi ────────────────────────────────────────────────────────────────────────
+
+@dataclass
+class SpaceConfig:
+    space_id:   str    # ID univoco interno (es. "brain", "daemon")
+    name:       str    # Nome display (es. "Brain / Backend")
+    base_url:   str    # URL base dello Space
+    hf_repo_id: str = ""  # ID repo HF (es. "arjanit98/terminal") — per API runtime
+    role:       str = ""  # ruolo: brain | daemon | worker | compute
+
+@dataclass
+class SpaceStatus:
+    space_id:    str
+    name:        str
+    base_url:    str
+    role:        str
+    # Health
+    health:      str   = "unknown"   # ok | degraded | down | unknown
+    latency_ms:  float = 0.0
+    http_status: int   = 0
+    # HF Runtime stage
+    hf_stage:    str   = "unknown"   # RUNNING | SLEEPING | BUILDING | FAILED | unknown
+    # Meta
+    checked_at:  float = field(default_factory=time.time)
+    error:       str   = ""
+
+
+def _build_spaces_from_env() -> list[SpaceConfig]:
+    """Legge configurazioni degli Space dalle env var. Zero crash su var mancanti."""
+    spaces: list[SpaceConfig] = []
+
+    def _add(space_id: str, name: str, env_url: str,
+             hf_repo_id: str = "", role: str = "") -> None:
+        url = os.getenv(env_url, "").rstrip("/")
+        if url:
+            spaces.append(SpaceConfig(
+                space_id=space_id, name=name, base_url=url,
+                hf_repo_id=hf_repo_id, role=role,
+            ))
+        else:
+            _logger.debug("hf_monitor: %s non configurato (%s vuoto)", space_id, env_url)
+
+    # Fleet — aggiungere nuove righe al crescere degli Space
+    _add("brain",    "Brain / Backend",   "HF_SPACE_URL",        role="brain")
+    _add("daemon",   "Daemon / Telegram", "HF_SPACE_B_URL",      role="daemon")
+    _add("worker-a", "Worker A (Collab)", "HF_SPACE_C_URL",      role="worker")
+    _add("worker-b", "Worker B",          "HF_SPACE_D_URL",      role="worker")
+    _add("worker-c",       "Worker C",             "HF_SPACE_E_URL",         role="worker")
+    # ── Ruoli futuri — skippati automaticamente se env var non configurata ──
+    _add("executor",       "Brain Executor",        "HF_SPACE_EXECUTOR_URL",  role="executor")
+    _add("browser-worker", "Browser Worker",        "HF_SPACE_BROWSER_URL",   role="browser-worker")
+    _add("memory-worker",  "Memory Worker",         "HF_SPACE_MEMORY_URL",    role="memory-worker")
+    _add("staging",        "Staging / Collab B",    "HF_SPACE_STAGING_URL",   role="staging")
+    _add("oracle",         "Oracle Cloud VM",       "ORACLE_CLOUD_VM_URL",    role="compute")
+    return spaces
+
+
+# Singleton — letto all'import del modulo
+_SPACES: list[SpaceConfig] = _build_spaces_from_env()
+
+# ── Cache ────────────────────────────────────────────────────────────────────────
+_cache:    dict[str, SpaceStatus] = {}
+_cache_ts: float                  = 0.0
+_poll_task: asyncio.Task | None   = None   # type: ignore[type-arg]
+
+
+async def _ping_space(client: httpx.AsyncClient, cfg: SpaceConfig) -> SpaceStatus:
+    """Ping /health di uno Space. Non solleva mai eccezioni."""
+    t0 = time.time()
+    status = SpaceStatus(
+        space_id=cfg.space_id, name=cfg.name,
+        base_url=cfg.base_url, role=cfg.role,
+    )
+    try:
+        url  = f"{cfg.base_url}/health"
+        resp = await client.get(url, timeout=_PING_TIMEOUT_S)
+        ms   = (time.time() - t0) * 1000
+        status.http_status = resp.status_code
+        status.latency_ms  = round(ms, 1)
+        if resp.status_code < 400:
+            status.health = "ok"
+        elif resp.status_code < 500:
+            status.health = "degraded"
+        else:
+            status.health = "down"
+    except httpx.TimeoutException:
+        status.health     = "down"
+        status.error      = "timeout"
+        status.latency_ms = _PING_TIMEOUT_S * 1000
+    except Exception as exc:
+        status.health = "down"
+        status.error  = str(exc)[:120]
+    status.checked_at = time.time()
+    return status
+
+
+async def _get_hf_stage(client: httpx.AsyncClient,
+                        repo_id: str, hf_token: str) -> str:
+    """Recupera lo stage runtime da HF API. Ritorna 'unknown' su qualsiasi errore."""
+    if not repo_id or not hf_token:
+        return "unknown"
+    try:
+        url  = f"{_HF_API_BASE}/{repo_id}/runtime"
+        hdrs = {"Authorization": f"Bearer {hf_token}"}
+        resp = await client.get(url, headers=hdrs, timeout=_HF_API_TIMEOUT_S)
+        if resp.status_code == 200:
+            return str(resp.json().get("stage", "unknown"))
+    except Exception as exc:
+        _logger.debug("hf_monitor: HF runtime API %s: %s", repo_id, exc)
+    return "unknown"
+
+
+async def _refresh_all() -> dict[str, SpaceStatus]:
+    """Aggiorna lo stato di tutti gli Space configurati in parallelo."""
+    global _cache, _cache_ts
+    if not _SPACES:
+        return {}
+
+    hf_token = os.getenv("HF_TOKEN", "")
+    async with httpx.AsyncClient() as client:
+        ping_results: list[SpaceStatus] = list(await asyncio.gather(
+            *[_ping_space(client, cfg) for cfg in _SPACES],
+            return_exceptions=False,
+        ))
+        stage_results: list[str] = list(await asyncio.gather(
+            *[_get_hf_stage(client, cfg.hf_repo_id, hf_token) for cfg in _SPACES],
+            return_exceptions=False,
+        ))
+
+    for status, stage in zip(ping_results, stage_results):
+        status.hf_stage = stage
+
+    new_cache = {s.space_id: s for s in ping_results}
+    _cache    = new_cache
+    _cache_ts = time.time()
+    _logger.info(
+        "hf_monitor: refresh OK — %d space: %s",
+        len(ping_results),
+        ", ".join(f"{s.space_id}={s.health}" for s in ping_results),
+    )
+    return new_cache
+
+
+async def _background_poll() -> None:
+    """Loop di polling in background — mai si ferma, mai solleva."""
+    while True:
+        try:
+            await _refresh_all()
+        except Exception as exc:
+            _logger.warning("hf_monitor: errore polling: %s", exc)
+        await asyncio.sleep(_POLL_INTERVAL_S)
+
+
+def start_monitor() -> None:
+    """Avvia il background polling. Idempotente: sicuro da chiamare più volte."""
+    global _poll_task
+    if _poll_task and not _poll_task.done():
+        return
+    _poll_task = asyncio.ensure_future(_background_poll())
+    _logger.info("hf_monitor: polling avviato — %d space, ogni %ds",
+                 len(_SPACES), int(_POLL_INTERVAL_S))
+
+
+def _status_to_dict(s: SpaceStatus) -> dict[str, Any]:
+    return asdict(s)
+
+
+# ── Endpoints ───────────────────────────────────────────────────────────────────
+
+@router.get(
+    "/api/hf-monitor/spaces",
+    summary="Stato aggregato di tutti gli HF Spaces monitorati (ARCH-P5.2)",
+)
+async def get_spaces_status(
+    _auth: None = Depends(require_role(AuthRole.MACHINE)),
+) -> dict[str, Any]:
+    """
+    Restituisce lo stato cached di tutti gli HF Spaces.
+    La cache si aggiorna ogni 60s in background; la prima call forza un refresh.
+    """
+    global _cache, _cache_ts
+    if not _cache:
+        await _refresh_all()
+    return {
+        "spaces":            [_status_to_dict(s) for s in _cache.values()],
+        "total":             len(_cache),
+        "cache_age_s":       round(time.time() - _cache_ts, 1) if _cache_ts else None,
+        "spaces_configured": len(_SPACES),
+    }
+
+
+@router.post(
+    "/api/hf-monitor/spaces/refresh",
+    summary="Forza aggiornamento immediato stato HF Spaces",
+)
+async def force_refresh(
+    _auth: None = Depends(require_role(AuthRole.MACHINE)),
+) -> dict[str, Any]:
+    """Forza refresh sincrono di tutti gli Space. Può richiedere fino a 8s."""
+    await _refresh_all()
+    return {
+        "spaces":       [_status_to_dict(s) for s in _cache.values()],
+        "total":        len(_cache),
+        "refreshed_at": time.time(),
+    }
+
+
+@router.get(
+    "/api/hf-monitor/ping/{space_id}",
+    summary="Ping live di un singolo HF Space",
+)
+async def ping_single_space(
+    space_id: str,
+    _auth: None = Depends(require_role(AuthRole.MACHINE)),
+) -> dict[str, Any]:
+    """Ping diretto e sincrono di un singolo Space (bypassa la cache)."""
+    cfg = next((c for c in _SPACES if c.space_id == space_id), None)
+    if not cfg:
+        raise HTTPException(
+            status_code=404,
+            detail=f"Space '{space_id}' non configurato. "
+                   f"Space disponibili: {[c.space_id for c in _SPACES]}",
+        )
+    hf_token = os.getenv("HF_TOKEN", "")
+    async with httpx.AsyncClient() as client:
+        status = await _ping_space(client, cfg)
+        stage  = await _get_hf_stage(client, cfg.hf_repo_id, hf_token)
+    status.hf_stage = stage
+    return _status_to_dict(status)

api/hf_storage.py

@@ -0,0 +1,95 @@
+"""
+backend/api/hf_storage.py — Zero-Cost Persistence via Hugging Face Datasets.
+
+Implementa il mirroring asincrono della memoria dell'agente su HF Datasets.
+Design:
+  - Fire-and-forget: non blocca mai il flusso principale.
+  - Sharding: supporta caricamento su diversi dataset (Account A/B/C/D).
+  - Formato: JSONL (append-only) per massima compatibilità.
+
+FIX-HF-API (MX18-VERIFY): usa /upload/{branch} con multipart/form-data
+(non raw body POST). L'endpoint /upload/ esiste (401 senza auth)
+ma accetta multipart, non raw bytes.
+"""
+import os
+import json
+import time
+import httpx
+import asyncio
+import logging
+from typing import Any, Optional
+from .state import get_env_secret
+
+_logger = logging.getLogger("api.hf_storage")
+
+# Configurazione default (Account A / BRAIN)
+HF_TOKEN = os.getenv("HF_TOKEN", "")
+HF_DATASET_REPO = os.getenv("HF_DATASET_REPO", "Arjanit98/agent-memory")
+
+async def hf_append_record(
+    dataset_path: str,
+    record: dict,
+    repo_id: Optional[str] = None,
+    token: Optional[str] = None,
+) -> bool:
+    """
+    Appende un record a un file JSONL in un dataset Hugging Face via API.
+    dataset_path: percorso del file nel repo (es. 'decisions.jsonl')
+
+    Usa /api/datasets/{repo}/upload/{branch} con multipart/form-data.
+    File giornaliero (decisions_2026-06-26.jsonl) per evitare conflitti.
+    """
+    _token = token or HF_TOKEN
+    _repo  = repo_id or HF_DATASET_REPO
+
+    if not _token or not _repo:
+        return False
+
+    # File giornaliero per shard naturale + evitare read-modify-write
+    date_str = time.strftime("%Y-%m-%d")
+    base     = dataset_path.replace(".jsonl", "")
+    filename = f"{base}_{date_str}.jsonl"
+
+    try:
+        record["_timestamp_ms"] = int(time.time() * 1000)
+        line = json.dumps(record, ensure_ascii=False) + "\n"
+
+        # HF Hub upload API: POST /api/datasets/{repo}/upload/{branch}
+        # Multipart form-data: ogni file come campo "file" con path nel repo.
+        # Ref: https://huggingface.co/docs/hub/api#post-apireposuploadref
+        url = f"https://huggingface.co/api/datasets/{_repo}/upload/main"
+
+        async with httpx.AsyncClient(timeout=12.0) as client:
+            resp = await client.post(
+                url,
+                headers={"Authorization": f"Bearer {_token}"},
+                files={
+                    # Chiave = path nel repo, valore = (nome, contenuto, mimetype)
+                    filename: (filename, line.encode("utf-8"), "text/plain"),
+                },
+            )
+            if resp.status_code in (200, 201):
+                return True
+            _logger.warning(
+                "HF Upload %s → %d: %s",
+                filename, resp.status_code, resp.text[:200],
+            )
+    except Exception as exc:
+        _logger.error("HF Storage error for %s: %s", dataset_path, exc)
+
+    return False
+
+
+def hf_fire_and_forget(
+    dataset_path: str,
+    record: dict,
+    repo_id: Optional[str] = None,
+) -> None:
+    """Lancia il caricamento in background senza attendere."""
+    try:
+        loop = asyncio.get_event_loop()
+        if loop.is_running():
+            loop.create_task(hf_append_record(dataset_path, record, repo_id))
+    except Exception:
+        pass  # Fire-and-forget: mai propagare eccezioni al caller
+

api/job_queue.py

@@ -355,11 +355,11 @@ async def _hands_consumer_loop() -> None:
                 continue
 
             # Esegui in background — non blocca il loop consumer
-            from api.background_tasks import spawn_background_task
-            task_id = str(job.get("taskId") or uuid.uuid4())
-            spawn_background_task(
-                _execute_queued_job(job), name=f"job-queue-execution:{task_id}"
-            )
+            t = asyncio.create_task(_execute_queued_job(job))
+            t.add_done_callback(lambda task: (
+                _logger.error("[jq] job task crashed: %s", task.exception(), exc_info=task.exception())
+                if not task.cancelled() and task.exception() else None
+            ))
 
         except Exception as exc:
             _logger.debug("[jq] consumer tick error: %s", exc)
@@ -377,15 +377,18 @@ async def start_job_queue_consumer() -> None:
         return
 
     # Load publisher su tutti gli Space
-    from api.background_tasks import spawn_background_task
-    spawn_background_task(_load_publisher_loop(), name="job-queue-load-publisher")
+    def _log_jq_exc(t):
+        if not t.cancelled() and t.exception():
+            _logger.warning("[job_queue] bg loop raised: %s", t.exception())
+
+    asyncio.create_task(_load_publisher_loop()).add_done_callback(_log_jq_exc)
 
     # Consumer per tutti i ruoli worker o legacy 'hands'
     _IS_WORKER = _SPACE_ROLE.startswith("worker-") or _SPACE_ROLE in ("hands", "unknown")
     
     if _IS_WORKER:
         _logger.info("[jq] Avvio consumer loop per ruolo worker: %s", _SPACE_ROLE)
-        spawn_background_task(_hands_consumer_loop(), name="job-queue-hands-consumer")
+        asyncio.create_task(_hands_consumer_loop()).add_done_callback(_log_jq_exc)
     else:
         _logger.info("[jq] SPACE_ROLE=%s — consumer non avviato (ruolo non worker)", _SPACE_ROLE)
 

api/large_payload_benchmark.py

@@ -0,0 +1,61 @@
+"""
+backend/api/large_payload_benchmark.py — Test per payload di grandi dimensioni.
+"""
+import asyncio
+import time
+import sys
+from .execution_fabric import ExecutionFabric, DispatchRequest, ProviderKind, ProviderSpec, AlwaysOn, ProviderHealth
+
+class LargePayloadBenchmark:
+    def __init__(self):
+        self.fabric = ExecutionFabric()
+
+    async def setup(self):
+        self.fabric._specs["oracle-heavy"] = ProviderSpec(
+            provider_id="oracle-heavy", name="Oracle Heavy", kind=ProviderKind.ORACLE,
+            capabilities=["code_analysis"], always_on=AlwaysOn.YES, timeout=120.0
+        )
+        self.fabric._states["oracle-heavy"] = type('State', (), {"health": ProviderHealth.OK})()
+        self.fabric._initialized = True
+
+    async def _mock_heavy_call(self, spec, req):
+        payload_size = sys.getsizeof(str(req.payload)) / 1024
+        # Simula tempo di elaborazione proporzionale alla dimensione (1s ogni 100KB)
+        processing_time = payload_size / 100.0
+        await asyncio.sleep(processing_time)
+        return {"status": "ok", "processed_kb": payload_size}
+
+    async def run_test(self, kb_size):
+        print(f"📄 Testando payload da {kb_size} KB...")
+        large_text = "A" * (kb_size * 1024)
+        req = DispatchRequest(
+            capability="code_analysis", 
+            payload={"code": large_text, "filename": "large_source.py"}
+        )
+        
+        t0 = time.time()
+        result = await self.fabric.dispatch(req)
+        duration = (time.time() - t0) * 1000
+        
+        if result.status == "executed":
+            print(f"✅ Successo! Tempo: {duration:.2f}ms (Dimensione reale: {result.response.get('processed_kb'):.2f} KB)")
+        else:
+            print(f"❌ Fallito: {result.status} - {result.response.get('error')}")
+        return duration
+
+    async def run(self):
+        await self.setup()
+        self.fabric._call_provider = self._mock_heavy_call
+        
+        results = {}
+        # Testiamo diverse dimensioni: 100KB, 250KB, 500KB (limite attuale), 1MB (over limit)
+        for size in [100, 250, 500, 1000]:
+            duration = await self.run_test(size)
+            results[size] = duration
+            
+        print("\n--- ANALISI SCALABILITÀ ---")
+        for size, dur in results.items():
+            print(f"  - {size} KB: {dur:.2f} ms")
+
+if __name__ == "__main__":
+    asyncio.run(LargePayloadBenchmark().run())

api/llm_router.py

@@ -0,0 +1,354 @@
+"""
+backend/api/llm_router.py — Provider Layer LLM con Provider Router (ARCH-I4.4)
+
+Interfaccia astratta per provider LLM. Il Brain richiede una capability LLM
+(es. "vision", "embedding", "reasoning") — il router sceglie il provider
+corretto senza che il Brain conosca i provider specifici.
+
+Routing table (sovrascrivibile via env LLM_ROUTING_TABLE_JSON):
+  chat       → groq, cerebras, sambanova, gemini, openrouter
+  vision     → gemini, openai, openrouter
+  embedding  → local (HF), openai, openrouter
+  code       → groq(qwen), openrouter(deepseek), sambanova
+  reasoning  → gemini, deepseek, openrouter
+  fast       → groq, cerebras  (latenza < 500ms target)
+  creative   → openrouter, gemini, openai
+  math       → deepseek, gemini, openrouter
+
+ADR: S19 S20 S27 S30 — nessun vendor lock-in, routing intent-based.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import os
+import time
+import uuid
+from enum import Enum
+from typing import Any, Literal
+
+from .health_manager import HealthManager
+from .telemetry import _percentile
+from .state import _TIMING_STORE, _REPAIR_STATS # Importa i dati di telemetria da state
+
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel, Field
+
+from .auth_guard import AuthRole, require_role
+
+_logger = logging.getLogger("api.llm_router")
+
+# ── LLM Capability enum ────────────────────────────────────────────────────────
+
+class LLMCapability(str, Enum):
+    CHAT      = "chat"
+    VISION    = "vision"
+    EMBEDDING = "embedding"
+    CODE      = "code"
+    REASONING = "reasoning"
+    FAST      = "fast"
+    CREATIVE  = "creative"
+    MATH      = "math"
+
+# ── Default routing table ──────────────────────────────────────────────────────
+# Ordinati per preferenza (primo = preferito). Aggiornabile via env.
+_DEFAULT_ROUTING: dict[str, list[str]] = {
+    LLMCapability.CHAT:      ["groq", "cerebras", "sambanova", "gemini", "openrouter"],
+    LLMCapability.VISION:    ["gemini", "openai", "openrouter"],
+    LLMCapability.EMBEDDING: ["local", "openai", "openrouter"],
+    LLMCapability.CODE:      ["groq", "openrouter", "sambanova", "gemini"],
+    LLMCapability.REASONING: ["gemini", "openrouter", "groq", "sambanova"],
+    LLMCapability.FAST:      ["groq", "cerebras", "sambanova"],
+    LLMCapability.CREATIVE:  ["openrouter", "gemini", "openai", "groq"],
+    LLMCapability.MATH:      ["openrouter", "gemini", "groq", "sambanova"],
+}
+
+# Provider → model mapping (default, sovrascrivibile via env LLM_MODEL_MAP_JSON)
+_DEFAULT_MODEL_MAP: dict[str, dict[str, str]] = {
+    "groq":       {LLMCapability.CHAT: "llama-3.3-70b-versatile",
+                   LLMCapability.CODE: "qwen-2.5-coder-32b-instruct",
+                   LLMCapability.FAST: "llama-3.1-8b-instant"},
+    "cerebras":   {LLMCapability.CHAT: "llama-3.3-70b", LLMCapability.FAST: "llama-3.1-8b"},
+    "sambanova":  {LLMCapability.CHAT: "Meta-Llama-3.3-70B-Instruct",
+                   LLMCapability.REASONING: "DeepSeek-R1-Distill-Llama-70B"},
+    "gemini":     {LLMCapability.CHAT: "gemini-2.0-flash-exp",
+                   LLMCapability.VISION: "gemini-2.0-flash-exp",
+                   LLMCapability.REASONING: "gemini-2.0-flash-thinking-exp",
+                   LLMCapability.MATH: "gemini-2.0-flash-exp"},
+    "openai":     {LLMCapability.CHAT: "gpt-4o-mini",
+                   LLMCapability.VISION: "gpt-4o",
+                   LLMCapability.EMBEDDING: "text-embedding-3-small"},
+    "openrouter": {LLMCapability.CREATIVE: "anthropic/claude-3.5-sonnet",
+                   LLMCapability.REASONING: "deepseek/deepseek-r1",
+                   LLMCapability.CODE: "deepseek/deepseek-coder-v2"},
+    "local":      {LLMCapability.EMBEDDING: "sentence-transformers/all-MiniLM-L6-v2"},
+}
+
+def _load_routing() -> dict[str, list[str]]:
+    raw = os.getenv("LLM_ROUTING_TABLE_JSON")
+    if raw:
+        try:
+            return json.loads(raw)
+        except Exception as exc:
+            _logger.warning("[llm-router] LLM_ROUTING_TABLE_JSON parse error: %s", exc)
+    return _DEFAULT_ROUTING
+
+def _load_model_map() -> dict[str, dict[str, str]]:
+    raw = os.getenv("LLM_MODEL_MAP_JSON")
+    if raw:
+        try:
+            return json.loads(raw)
+        except Exception as exc:
+            _logger.warning("[llm-router] LLM_MODEL_MAP_JSON parse error: %s", exc)
+    return _DEFAULT_MODEL_MAP
+
+# ── Models ─────────────────────────────────────────────────────────────────────
+
+class LLMRouteRequest(BaseModel):
+    capability:     LLMCapability    = Field(LLMCapability.CHAT)
+    model_hint:     str | None       = Field(None,
+                                             description="Provider specifico richiesto (override router)")
+    exclude:        list[str]        = Field(default_factory=list,
+                                             description="Provider da escludere (es. dopo fallback)")
+    require_vision: bool             = Field(False)
+    require_fast:   bool             = Field(False,
+                                             description="Target latency < 500ms — forza FAST chain")
+    context_tokens: int              = Field(0,
+                                             description="Token contesto stimati (per scegliere modello con context window adeguato)")
+    correlation_id: str              = Field(default_factory=lambda: str(uuid.uuid4()))
+
+
+class LLMRouteResult(BaseModel):
+    provider:       str
+    model:          str
+    capability:     str
+    fallback_chain: list[str]        = Field(default_factory=list)
+    resolved_at:    float            = Field(default_factory=time.time)
+    correlation_id: str              = ""
+
+
+class LLMCallRequest(BaseModel):
+    messages:       list[dict]
+    capability:     LLMCapability    = LLMCapability.CHAT
+    model_hint:     str | None       = None
+    exclude:        list[str]        = Field(default_factory=list)
+    max_tokens:     int              = 4096
+    temperature:    float            = 0.7
+    session_id:     str | None       = None
+    correlation_id: str              = Field(default_factory=lambda: str(uuid.uuid4()))
+
+
+# ── LLMProviderRouter singleton ────────────────────────────────────────────────
+
+class LLMProviderRouter:
+    """
+    Router LLM intent-based. Il Brain chiede una capability, il router sceglie.
+
+    Priorità di selezione:
+      1. model_hint esplicito (override diretto)
+      2. require_fast → FAST chain
+      3. require_vision → VISION chain
+      4. capability routing table
+      5. exclude filter (rimuove provider già falliti)
+
+    Il router consulta opzionalmente il CapabilityResolver per la salute
+    dei provider (se disponibile).
+    """
+
+    def __init__(self) -> None:
+        self._routing   = _load_routing()
+        self._model_map = _load_model_map()
+        self._stats:    dict[str, dict[str, int]] = {}   # provider → {ok, fail}
+        self._health_manager = HealthManager()
+        self._telemetry_timing = _TIMING_STORE
+        self._telemetry_repair = _REPAIR_STATS
+
+    def route(self, req: LLMRouteRequest) -> LLMRouteResult:
+        """Selezione sincrona del provider. No I/O — solo dict lookup."""
+        cap = LLMCapability.FAST if req.require_fast else (
+              LLMCapability.VISION if req.require_vision else req.capability)
+
+        # Override esplicito
+        if req.model_hint:
+            provider = req.model_hint
+            model    = self._model_map.get(provider, {}).get(cap.value, "")
+            chain    = self._routing.get(cap.value, [])
+            _logger.debug("[llm-router] hint override provider=%s cap=%s", provider, cap.value)
+            return LLMRouteResult(provider=provider, model=model, capability=cap.value,
+                                  fallback_chain=chain, correlation_id=req.correlation_id)
+
+        chain = self._routing.get(cap.value, self._routing[LLMCapability.CHAT])
+        
+        # Ottieni decisioni sul traffico dal HealthManager
+        traffic_decisions = self._health_manager.get_traffic_decisions()
+        blacklisted_providers = set()
+        for decision in traffic_decisions:
+            blacklisted_providers.update(decision.blacklisted)
+
+        # Rimuovi esclusi e provider in blacklist
+        candidates = [p for p in chain if p not in req.exclude and p not in blacklisted_providers]
+        
+        if not candidates:
+            candidates = chain   # tutti falliti → riprova dall\'inizio
+
+        # Ordina i candidati in base a benchmark, health e telemetria
+        candidates = self._sort_candidates_by_metrics(candidates, cap, req.require_fast)
+
+        provider = candidates[0]
+        model    = self._model_map.get(provider, {}).get(cap.value, "")
+        fallback = candidates[1:]
+
+        _logger.debug("[llm-router] routed cap=%s → provider=%s model=%s fallbacks=%d",
+                      cap.value, provider, model or "?", len(fallback))
+        return LLMRouteResult(provider=provider, model=model, capability=cap.value,
+                              fallback_chain=fallback, correlation_id=req.correlation_id)
+
+    async def call(self, req: LLMCallRequest) -> dict:
+        """
+        Chiama il Kernel.chat() con il provider scelto dal router.
+        Implementa fallback automatico lungo la chain se il provider fallisce.
+        """
+        route_req = LLMRouteRequest(
+            capability  = req.capability,
+            model_hint  = req.model_hint,
+            exclude     = list(req.exclude),
+            correlation_id = req.correlation_id,
+        )
+        routed     = self.route(route_req)
+        chain      = [routed.provider] + routed.fallback_chain
+        last_error = ""
+
+        for provider in chain:
+            try:
+                from .kernel import kernel as _kernel
+                result = await _kernel.chat(
+                    messages       = req.messages,
+                    model_hint     = routed.model or provider,
+                    session_id     = req.session_id,
+                    correlation_id = req.correlation_id,
+                    max_tokens     = req.max_tokens,
+                    temperature    = req.temperature,
+                )
+                self._record_ok(provider)
+                return {
+                    "provider":   provider,
+                    "model":      getattr(result, "model", ""),
+                    "content":    getattr(result, "content", ""),
+                    "capability": req.capability.value,
+                    "cached":     getattr(result, "cached", False),
+                }
+            except Exception as exc:
+                last_error = str(exc)
+                self._record_fail(provider)
+                _logger.warning("[llm-router] provider=%s failed: %s — trying next", provider, exc)
+
+        raise RuntimeError(f"Tutti i provider LLM falliti per cap={req.capability.value}. Last: {last_error}")
+
+    def _record_ok(self, provider: str) -> None:
+        s = self._stats.setdefault(provider, {"ok": 0, "fail": 0})
+        s["ok"] += 1
+
+    def _record_fail(self, provider: str) -> None:
+        s = self._stats.setdefault(provider, {"ok": 0, "fail": 0})
+        s["fail"] += 1
+
+    def _sort_candidates_by_metrics(self, candidates: list[str], cap: LLMCapability, require_fast: bool) -> list[str]:
+        """Ordina i candidati in base a metriche di salute, telemetria e benchmark."""
+        try:
+            from api.state import _TIMING_STORE
+        except ImportError:
+            return candidates # Fallback se state non è disponibile
+
+        def get_score(provider: str) -> float:
+            score = 0.0
+
+            # 0. INT-1: score da benchmark/heartbeat (ciclo chiuso)
+            try:
+                from api.state import _PROVIDER_SCORES
+                bench = _PROVIDER_SCORES.get(provider)
+                if bench is not None:
+                    if bench == 0.0:
+                        score -= 200.0  # provider down → praticamente escluso
+                    elif bench == 20.0:
+                        score -= 30.0   # quota esaurita → penalizzato ma non escluso
+                    else:
+                        score += (bench - 50.0) * 0.6  # 50→0, 100→+30
+            except Exception:
+                pass
+
+            # 1. Penalizza provider con molti fallimenti recenti
+            stats = self._stats.get(provider, {"ok": 0, "fail": 0})
+            total_calls = stats["ok"] + stats["fail"]
+            if total_calls > 0:
+                fail_rate = stats["fail"] / total_calls
+                score -= fail_rate * 100 # Penalità forte per alto fail rate
+
+            # 2. Valuta la latenza (telemetria)
+            timing_key = f"llm_call_{provider}"
+            if timing_key in _TIMING_STORE:
+                samples = list(_TIMING_STORE[timing_key])
+                if samples:
+                    p50_latency = _percentile(samples, 50)
+                    if require_fast:
+                        # Penalizza fortemente la latenza se è richiesto fast
+                        score -= p50_latency / 100 
+                    else:
+                        score -= p50_latency / 500
+
+            # 3. Considera le decisioni di traffico (preferenze)
+            for decision in self._health_manager.get_traffic_decisions():
+                if provider in decision.preferred:
+                    score += 50 # Bonus per provider preferiti
+
+            return score
+
+        # Ordina in modo decrescente (score più alto = migliore)
+        return sorted(candidates, key=get_score, reverse=True)
+
+    def status(self) -> dict:
+        return {
+            "routing_table": self._routing,
+            "provider_stats": self._stats,
+            "capabilities":  list(self._routing.keys()),
+        }
+
+    def reload(self) -> None:
+        """Ricarica routing table e model map da env (hot-reload)."""
+        self._routing   = _load_routing()
+        self._model_map = _load_model_map()
+        _logger.info("[llm-router] routing table reloaded")
+
+
+# ── Singleton ────────────────────────────────────────────────────────────────────
+llm_router = LLMProviderRouter()
+
+# ── HTTP Router ──────────────────────────────────────────────────────────────────
+router = APIRouter(
+    prefix="/api/llm",
+    tags=["llm-router"],
+    dependencies=[Depends(require_role(AuthRole.MACHINE))],
+)
+
+
+@router.post("/route", summary="Risolve capability LLM → provider + model senza chiamarlo")
+async def route_route(req: LLMRouteRequest) -> LLMRouteResult:
+    return llm_router.route(req)
+
+
+@router.post("/call", summary="Chiama LLM con routing automatico e fallback")
+async def route_call(req: LLMCallRequest) -> dict:
+    try:
+        return await llm_router.call(req)
+    except RuntimeError as exc:
+        raise HTTPException(503, str(exc))
+
+
+@router.get("/status", summary="Routing table attiva e statistiche provider")
+async def route_status() -> dict:
+    return llm_router.status()
+
+
+@router.post("/reload", summary="Hot-reload routing table da env")
+async def route_reload() -> dict:
+    llm_router.reload()
+    return {"reloaded": True}

api/load_balancer.py

@@ -0,0 +1,104 @@
+"""
+backend/api/load_balancer.py — Dynamic Load Balancer (S951)
+Analizza il carico dei nodi (A, B, C, D) e decide a chi assegnare il task.
+Supporta il Cross-Node Offloading: se il nodo target è saturo, delega al nodo più scarico.
+M1-FIX: timeout Redis configurabile via env REDIS_TIMEOUT_S (default 5.0s, allineato a job_queue e state_sync).
+"""
+import json
+import logging
+import os
+import time
+from typing import Optional, Dict, Any, List
+import httpx
+
+_logger = logging.getLogger("agente_ai.balancer")
+
+# M1-FIX: timeout Redis allineato agli altri moduli (job_queue: 5.0s, state_sync: 5.0s)
+_REDIS_TIMEOUT = float(os.getenv("REDIS_TIMEOUT_S", "5.0"))
+
+# Ruoli del cluster
+ROLES = ["brain", "hands", "memory", "audit"]
+
+class LoadBalancer:
+    def __init__(self):
+        self.redis_url = os.getenv("UPSTASH_REDIS_REST_URL")
+        self.redis_token = os.getenv("UPSTASH_REDIS_REST_TOKEN")
+        self.internal_token = os.getenv("INTERNAL_TOKEN", "")
+
+    async def _rcmd(self, cmd: List[Any]) -> Optional[Dict[str, Any]]:
+        if not self.redis_url or not self.redis_token: return None
+        try:
+            async with httpx.AsyncClient() as client:
+                r = await client.post(
+                    self.redis_url,
+                    headers={"Authorization": f"Bearer {self.redis_token}"},
+                    json=cmd,
+                    timeout=_REDIS_TIMEOUT,  # M1-FIX: era hardcodato 2.0
+                )
+                return r.json()
+        except Exception as e:
+            _logger.error("[S951] Redis error: %s", e)
+            return None
+
+    async def get_node_load(self, role: str) -> Optional[Dict[str, Any]]:
+        """Recupera le metriche di carico per un nodo specifico."""
+        res = await self._rcmd(["GET", f"jq:load:{role}"])
+        if res and res.get("result"):
+            try:
+                return json.loads(res["result"])
+            except (json.JSONDecodeError, TypeError):
+                return None
+        return None
+
+    async def get_best_node(self, preferred_role: str = "hands") -> str:
+        """
+        Determina il miglior nodo per un task.
+        Se il preferred_role è sotto soglia di carico, lo mantiene.
+        Altrimenti cerca il nodo con meno active_tasks.
+        """
+        pref_load = await self.get_node_load(preferred_role)
+        if pref_load:
+            active = pref_load.get("active_tasks", 0)
+            if active < 3:
+                return preferred_role
+
+        _logger.info("[S951] Nodo %s saturo o offline. Ricerca miglior nodo alternativo...", preferred_role)
+
+        best_role = preferred_role
+        min_load = 999
+
+        for role in ROLES:
+            load = await self.get_node_load(role)
+            if load:
+                active = load.get("active_tasks", 0)
+                ts = load.get("ts", 0)
+                if (time.time() * 1000) - ts < 90000:
+                    if active < min_load:
+                        min_load = active
+                        best_role = role
+
+        if best_role != preferred_role:
+            _logger.info("[S951] Offloading dinamico: %s -> %s (carico: %d)", preferred_role, best_role, min_load)
+
+        return best_role
+
+    async def get_cluster_status(self) -> Dict[str, Any]:
+        """Ritorna lo stato di salute di tutto il cluster."""
+        status = {}
+        for role in ROLES:
+            load = await self.get_node_load(role)
+            if load:
+                ts = load.get("ts", 0)
+                is_online = (time.time() * 1000) - ts < 90000
+                status[role] = {
+                    "online":       is_online,
+                    "active_tasks": load.get("active_tasks", 0),
+                    "mem_mb":       load.get("mem", 0),
+                    "last_seen":    ts,
+                }
+            else:
+                status[role] = {"online": False}
+        return status
+
+# Singleton instance
+balancer = LoadBalancer()

api/oci_gateway_manager.py

@@ -0,0 +1,63 @@
+import os
+import logging
+from typing import Dict, Any, Optional
+import httpx
+
+# Configurazione OCI API Gateway
+OCI_GATEWAY_ID = "ocid1.apigatewayapi.oc1.eu-milan-1.amaaaaaavx6czpaabfdwezue3fo7jpfsrxqwlo2nt7pwhs7o2ezvqztuaffa"
+ORACLE_NODE_E_IP = os.getenv("ORACLE_NODE_E_IP", "80.225.89.217")
+ORACLE_NODE_E_PORT = int(os.getenv("ORACLE_NODE_E_PORT", "8080"))
+INTERNAL_TOKEN = os.getenv("INTERNAL_TOKEN", "")
+
+logger = logging.getLogger("agente_ai.oci_gateway")
+
+class OCIGatewayManager:
+    """
+    Gestore per Oracle Cloud API Gateway.
+    Funge da ponte tra il cluster AI e il Nodo E (Milano) per bypassare 
+    il Network Firewall (Palo Alto) tramite endpoint HTTPS gestiti.
+    """
+    
+    def __init__(self):
+        self.gateway_id = OCI_GATEWAY_ID
+        self.base_url = f"https://{self.gateway_id}.apigateway.eu-milan-1.oci.customer-oci.com"
+        self.token = INTERNAL_TOKEN
+
+    async def get_gateway_status(self) -> Dict[str, Any]:
+        """Verifica lo stato del gateway e la connettività verso il Nodo E."""
+        try:
+            async with httpx.AsyncClient() as client:
+                # Nota: L'URL reale dipenderà dal deployment specifico su OCI
+                # Questo è un placeholder per la logica di health check via gateway
+                response = await client.get(
+                    f"{self.base_url}/health",
+                    headers={"Authorization": f"Bearer {self.token}"},
+                    timeout=10.0
+                )
+                return {
+                    "ok": response.status_code == 200,
+                    "gateway_id": self.gateway_id,
+                    "status_code": response.status_code,
+                    "provider": "Oracle Cloud API Gateway"
+                }
+        except Exception as e:
+            logger.error(f"Errore health check gateway: {e}")
+            return {"ok": False, "error": str(e)}
+
+    async def proxy_to_node_e(self, path: str, method: str = "GET", body: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """Invia una richiesta al Nodo E passando attraverso l'API Gateway."""
+        url = f"{self.base_url}{path}"
+        try:
+            async with httpx.AsyncClient() as client:
+                if method == "POST":
+                    response = await client.post(url, json=body, headers={"Authorization": f"Bearer {self.token}"})
+                else:
+                    response = await client.get(url, headers={"Authorization": f"Bearer {self.token}"})
+                
+                return response.json() if response.status_code == 200 else {"ok": False, "status": response.status_code}
+        except Exception as e:
+            logger.error(f"Errore proxy gateway: {e}")
+            return {"ok": False, "error": str(e)}
+
+# Istanza globale
+oci_gateway = OCIGatewayManager()