fix: sync registry+fallback fixes da A (registry.py line692, LLM_TIMEOUT, _ANALYTICAL_VERBS_RE)

.env.example

@@ -28,13 +28,36 @@ VAULT_ADMIN_TOKEN=
 INTERNAL_TOKEN=
 NOTIFY_TOKEN=
 
-# ── Supabase (obbligatorio) ───────────────────────────────────
-# supabase.com → Settings → API
-SUPABASE_URL=https://xxxx.supabase.co
-SUPABASE_KEY=
-SUPABASE_SERVICE_ROLE_KEY=
-SUPABASE_ANON_KEY=
-DATABASE_URL=postgresql://postgres:[password]@db.[ref].supabase.co:5432/postgres
+# ═══════════════════════════════════════════════════════════════════════════════════════
+# ── CLUSTER SUPABASE — Separazione Workload Ottimale ──────────────────────────────────
+# ═══════════════════════════════════════════════════════════════════════════════════════
+# 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)
+#
+# SUPABASE_URL (primario) → punta a B (Sync/State)
+# SUPABASE_KEY (primario) → punta a B
+# ═══════════════════════════════════════════════════════════════════════════════════════
+
+# ── Nodo B: PRIMARY — Stato Globale e Sincronizzazione ──────────────────────────────────
+# Workload: transazioni critiche, stato cluster, sincronizzazione, write-heavy
+SUPABASE_URL=https://sluvxtpbtxevrcooaqou.supabase.co
+SUPABASE_KEY=sb_secret_OHtVs6Vw4b5UTbm_QUnh4A_zqx9dadY
+SUPABASE_SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6InNsdXZ4dHBidHhldnJjb29hcW91Iiwicm9sZSI6InNlcnZpY2Vfcm9sZSIsImlhdCI6MTc4MjA3Mjk5MiwiZXhwIjoyMDk3NjQ4OTkyfQ.WS4cpsvtO-FGkXukCqpFF6qXfQb38VUs5rtiLwa0khk
+SUPABASE_ANON_KEY=sb_secret_OHtVs6Vw4b5UTbm_QUnh4A_zqx9dadY
+DATABASE_URL=postgresql://postgres:[password]@db.sluvxtpbtxevrcooaqou.supabase.co:5432/postgres
+
+# ── Nodo A: Analytics/Cache — Read Replica e Cache Distribuito ──────────────────────────
+# Workload: reporting, dashboard, cache, read-heavy queries (non-critical)
+# Nota: Configurare con URL reale se disponibile; altrimenti fallback a B
+SUPABASE_URL_A=https://xxxx.supabase.co
+SUPABASE_KEY_A=
+SUPABASE_SERVICE_ROLE_KEY_A=
+# Enable cache layer su A (riduce carico su B)
+SUPABASE_CACHE_ENABLED=true
+SUPABASE_CACHE_TTL=3600
 
 # ── HuggingFace ───────────────────────────────────────────────
 # huggingface.co → Settings → Access Tokens
@@ -134,6 +157,19 @@ NOTION_TOKEN=
 CHROMA_DB_DIR=/app/backend/.data/chroma
 SQLITE_DB_PATH=/app/backend/.data/agent.sqlite
 
+# ═══════════════════════════════════════════════════════════════════════════════════════
+# ── Nodo E: Oracle Cloud (OCI) — Compute/AI Workload ──────────────────────────────────
+# ═══════════════════════════════════════════════════════════════════════════════════════
+# Workload: Carichi di calcolo intensivi, esecuzione script Python complessi, task di background a lunga durata, hosting modelli AI locali.
+ORACLE_NODE_E_ENABLED=true
+ORACLE_NODE_E_IP=80.225.89.217
+ORACLE_NODE_E_USER=opc
+ORACLE_NODE_E_SSH_KEY_PATH=/app/secrets/oracle_private_key.pem  # Path alla chiave privata SSH (gestita come segreto)
+ORACLE_NODE_E_ROLE="Compute/AI Workload"
+ORACLE_NODE_E_REGION="Italy Northwest (Milan)"
+ORACLE_NODE_E_OCPUS=4
+ORACLE_NODE_E_RAM_GB=24
+
 # ── Opzionali ─────────────────────────────────────────────────
 # Qdrant (vector DB cloud)
 QDRANT_URL=
@@ -155,13 +191,36 @@ PEXELS_API_KEY=
 PIXABAY_API_KEY=
 
 # ═══════════════════════════════════════════════════
-# ── Collaboratore Account B (dual-infra) ───────────
+# ── HF Spaces e Railway — Configurazione Infra ─────
 # ═══════════════════════════════════════════════════
 VITE_BACKEND_URL_2=https://baida00-ai-backend-collab.hf.space  # HF Space B — backend collab B (chat/AI)
 VITE_EXEC_BACKEND_URL_2=  # Railway B URL (exec/PTY) — formato: https://xxx.up.railway.app — DA CONFIGURARE
-E2B_API_KEY_2=               # e2b.dev — account B (100h/mese)
-SUPABASE_URL_2=              # Supabase B URL
-SUPABASE_KEY_2=              # Supabase B anon key
-SUPABASE_SERVICE_ROLE_KEY_2= # Supabase B service role (opzionale)
-GROQ_API_KEY_3=              # Groq account B (14.400 req/giorno)
-VITE_GROQ_API_KEY_3=         # stessa chiave — frontend
+E2B_API_KEY_2=2f548a79-9210-4037-87fa-4490a6a6b8fe               # e2b.dev — account B (100h/mese)
+
+# Groq account B (14.400 req/giorno) — load balancing con A
+GROQ_API_KEY_3=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
+VITE_GROQ_API_KEY_3=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
+
+# ═══════════════════════════════════════════════════════════════════════════════════════
+# ── Nodo C: Memory/RAG/Embeddings — Backend Memoria e Vector Search ──────────────────────
+# ═══════════════════════════════════════════════════════════════════════════════════════
+# Workload: embeddings, vector search, RAG index, skill memory, conversazioni
+SUPABASE_URL_C=https://rsiphwzlokhsxnkcvzos.supabase.co
+SUPABASE_ANON_KEY_C=sb_secret_11jeLuJnZBA1IKCAm1ZjiA_QxIyU5u6
+SUPABASE_SERVICE_ROLE_KEY_C=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6InJzaXBod3psb2toc3hua2N2em9zIiwicm9sZSI6InNlcnZpY2Vfcm9sZSIsImlhdCI6MTc4MjI1OTEyOSwiZXhwIjoyMDk3ODM1MTI5fQ.LxO8ltt-t8SpHf-ZIi1ogcEtcQcPvW1Vyu2W14i1zzM
+E2B_API_KEY_C=2f548a79-9210-4037-87fa-4490a6a6b8fe
+# RAG/Vector DB — Qdrant per embeddings (opzionale, altrimenti usa Supabase C)
+QDRANT_URL_C=
+QDRANT_API_KEY_C=
+
+# ═══════════════════════════════════════════════════════════════════════════════════════
+# ── Nodo D: Audit/Logging/Compliance — Event Log e Compliance Records ──────────────────
+# ═══════════════════════════════════════════════════════════════════════════════════════
+# Workload: audit trail, event logging, compliance records, immutable logs
+SUPABASE_URL_D=https://cyotadpvgaxfdwaovstv.supabase.co
+SUPABASE_ANON_KEY_D=sb_secret_aZGjt7d8KWsvIm5-JP4qrg_XrNPBAZE
+SUPABASE_SERVICE_ROLE_KEY_D=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImN5b3RhZHB2Z2F4ZmR3YW92c3R2Iiwicm9sZSI6InNlcnZpY2Vfcm9sZSIsImlhdCI6MTc4MjY1NjQ1OSwiZXhwIjoyMDk4MjMyNDU5fQ.FuLweX2H6RKJmC7PbXdctmgzVIcqspq9FSxwFzFwB9o
+E2B_API_KEY_D=e2b_9d242366288d5e9e0bb267f31cccc5d49298348c
+# Audit log — immutable append-only (opzionale)
+AUDIT_LOG_ENABLED=true
+AUDIT_LOG_RETENTION_DAYS=90

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/unified_loop_fallback.py

@@ -33,10 +33,22 @@ from agents.unified_loop_types import (
     UnifiedLoopState,
     _maybe_await,
     _LANG_INSTRUCTIONS,
+    _ANALYTICAL_VERBS_RE,
+    _TASK_VERBS_RE,
+    _is_goal_ambiguous,
+    _is_borderline_ambiguous,
+    _BORDERLINE_FIX_RE,
+    _BORDERLINE_HELP_RE,
+    _BORDERLINE_MAKE_RE,
+    _detect_user_lang,
 )
 
 _logger = logging.getLogger("agente_ai")
 
+# QF-2: costanti timeout — replicate da unified_loop.py (evita circular import)
+LLM_TIMEOUT:  float = float(os.getenv('LLM_CALL_TIMEOUT',  '60'))
+TOOL_TIMEOUT: float = float(os.getenv('TOOL_CALL_TIMEOUT', '25'))
+
 
 class FallbackMixin:
     async def _run_fallback(self, state: UnifiedLoopState,
@@ -2425,6 +2437,75 @@ class FallbackMixin:
             except Exception as _gv_exc:
                 _logger.warning("S624 GoalVerifier failed (silent): %s", _gv_exc)  # S624
 
+
+        # S303: Audit Semantico L2 — verifica coerenza logica interna dell'output.
+        # Eseguito DOPO GoalVerifier L1, solo se L1 ≠ FAIL (risparmio token).
+        # Rileva: hallucination claims (deploy/push/send non verificati),
+        #         contraddizioni interne (errore + completato), sotto-obiettivi mancanti.
+        # Silent failure totale — non blocca mai la risposta al client.
+        _l2_should_run = (
+            answer
+            and not answer.startswith('[LLM')
+            and len(answer.split()) > 15
+        )
+        try:
+            _l1_was_fail = (
+                getattr(_gvr, 'verification_status', None) is not None  # type: ignore[name-defined]
+                and str(getattr(_gvr, 'verification_status', '')).endswith('FAIL')
+            )
+        except NameError:
+            _l1_was_fail = False  # _gvr non definito — L1 non era attivo (goal non-code)
+        if _l2_should_run and not _l1_was_fail:
+            try:
+                from agents.audit_semantic_l2 import get_auditor as _get_auditor_l2
+                _auditor_l2 = _get_auditor_l2(
+                    ai_client=self._get_verifier_llm(),  # cross-model (P25-B4)
+                    timeout_s=12.0,
+                )
+                _l2_result = await asyncio.wait_for(
+                    _auditor_l2.audit(state.goal, answer),
+                    timeout=13.0,
+                )
+                # Telemetria
+                try:
+                    from api.state import increment_stat as _inc_l2
+                    _inc_l2(f"audit_l2_{_l2_result.status.value.lower()}")
+                except Exception as _exc:
+                    _logger.debug("[S303] telemetry silenced: %s", type(_exc).__name__)
+                _logger.info(
+                    "[S303] AuditL2 %s (conf=%.2f engine=%s) issues=%d",
+                    _l2_result.status.value,
+                    _l2_result.confidence,
+                    _l2_result.engine,
+                    len(_l2_result.issues),
+                )
+                if _l2_result.status.value == "FAIL" and _l2_result.issues:
+                    # Notifica UI — step visibile nel pannello avanzamento
+                    if on_step:
+                        await _maybe_await(on_step({
+                            "action":      "audit_l2",
+                            "status":      "warning",
+                            "visibility":  "progress",
+                            "title":       "⚠️ Verifica coerenza risposta",
+                            "explanation": _l2_result.issues[0][:120],
+                        }))
+                    # Appende nota discreta — non modifica il codice, solo avvisa
+                    if answer:
+                        _l2_note_parts = ["\n\n> ⚠️ **Nota di coerenza**:"]
+                        for _iss in _l2_result.issues[:2]:
+                            _l2_note_parts.append(f" {_iss}")
+                        if _l2_result.repair_hint:
+                            _l2_note_parts.append(f"  \n> 💡 {_l2_result.repair_hint}")
+                        answer += "".join(_l2_note_parts)
+            except asyncio.TimeoutError:
+                try:
+                    from api.state import increment_stat as _inc_l2t
+                    _inc_l2t("audit_l2_timeout")
+                except Exception as _exc:
+                    _logger.debug("[S303] timeout counter silenced: %s", type(_exc).__name__)
+            except Exception as _l2_exc:
+                _logger.debug("[S303] AuditL2 silenced: %s", type(_l2_exc).__name__)  # S624
+
         # Sprint 3b ITEM 8: Browser Goal Verification — Playwright headless su app live
         # Attivato solo se l'answer contiene un URL di deploy (pages.dev / vercel.app / ecc.)
         # e il RequirementEngine ha trovato requisiti (già estratti sopra in _gv2_reqs).

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_task_routes.py

@@ -23,6 +23,7 @@ from .state import (
     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:
@@ -98,6 +99,8 @@ async def create_agent_task(body: AgentTaskIn):
     # 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'}
 
 
@@ -794,3 +797,4 @@ async def stream_agent_task(task_id: str, request: Request, resume: int = 0):
             'X-Accel-Buffering': 'no',
         }
     )
+

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/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/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/job_queue.py

@@ -4,21 +4,28 @@ import time
 import asyncio
 import logging
 import uuid
+try:
+    import resource as _resource
+    _HAS_RESOURCE = True
+except ImportError:
+    _HAS_RESOURCE = False
 from typing import Optional, List, Dict, Any
 from fastapi import APIRouter, HTTPException, Request
 from pydantic import BaseModel
+from .load_balancer import balancer  # S951
 import httpx
 
 _logger = logging.getLogger("agente_ai.jq")
 router = APIRouter(prefix="/jq", tags=["job_queue"])
 
 # ── Configurazione ────────────────────────────────────────────────────────────
-# S42: Grid Orchestrator — Cluster 4x4 (A, B, C, D)
-# SPACE_ROLE: brain | hands | memory | audit
-_SPACE_ROLE  = os.getenv("SPACE_ROLE", "unknown")
-_JQ_ENABLED  = os.getenv("JQ_ENABLED", "0") == "1"
+_SPACE_ROLE     = os.getenv("SPACE_ROLE", "unknown")
+_JQ_ENABLED     = os.getenv("JQ_ENABLED", "0") == "1"
 _INTERNAL_TOKEN = os.getenv("INTERNAL_TOKEN", "")
 
+# C2-FIX: contatore reale di job attivi — incrementato/decrementato intorno a loop_inst.run()
+_active_job_count: int = 0
+
 # Redis keys (Upstash)
 _K_PENDING  = "jq:pending"
 _K_WAKE     = "jq:wake"
@@ -65,14 +72,23 @@ async def _lrange(key: str, start: int, end: int = -1) -> List[str]:
 
 # ── Core Logic ────────────────────────────────────────────────────────────────
 async def publish_load_metrics():
-    """Pubblica il carico corrente su Redis per il bilanciamento."""
+    """Pubblica il carico corrente su Redis per il bilanciamento (S951).
+    C2-FIX: usa _active_job_count (contatore reale) invece di asyncio.all_tasks()-5.
+    """
     if not _redis_ok(): return
+    # Memoria processo in MB (Linux: ru_maxrss è in kB)
+    mem_mb = 0
+    if _HAS_RESOURCE:
+        try:
+            mem_mb = _resource.getrusage(_resource.RUSAGE_SELF).ru_maxrss // 1024
+        except Exception:
+            mem_mb = 0
     data = {
-        "role": _SPACE_ROLE,
-        "ts": int(time.time() * 1000),
-        "active_tasks": len(asyncio.all_tasks()) - 5,  # Stima approssimativa
-        "cpu": 0,  # Placeholder per metrics reali
-        "mem": 0
+        "role":         _SPACE_ROLE,
+        "ts":           int(time.time() * 1000),
+        "active_tasks": max(0, _active_job_count),  # mai negativo
+        "cpu":          0,                            # placeholder — psutil non installato
+        "mem":          mem_mb,
     }
     await _rcmd(["SET", _K_LOAD(_SPACE_ROLE), json.dumps(data), "EX", "60"])
 
@@ -87,6 +103,7 @@ async def _load_publisher_loop():
 
 async def _hands_consumer_loop():
     """Loop consumer reale per nodi distribuiti (S42)."""
+    global _active_job_count
     _logger.info("[jq] consumer loop avviato per ruolo: %s", _SPACE_ROLE)
     _consecutive_errors = 0
     _MAX_CONSECUTIVE_ERRORS = 3  # INV-R1: dopo 3 errori infra → pausa 30s
@@ -96,21 +113,25 @@ async def _hands_consumer_loop():
             # 1. Heartbeat consumer
             await _rcmd(["SET", _K_CONSUMER, "1", "EX", "15"])
 
-            # 2. Prelievo job (RPOP per coda FIFO)
+            # 2. Prelievo job
             res = await _rcmd(["RPOP", _K_PENDING])
             if res and res.get("result"):
                 job_raw = res["result"]
                 try:
                     job_data = json.loads(job_raw)
-                except json.JSONDecodeError as _jd_err:
-                    _logger.error("[jq] JSON malformato in coda: %s | raw: %.120s", _jd_err, job_raw)
-                    continue
+                    # S951: Check assignment
+                    assigned_to = job_data.get("assignedTo", "hands")
+                    if assigned_to != _SPACE_ROLE and _SPACE_ROLE != "brain":
+                        await _rcmd(["LPUSH", _K_PENDING, job_raw])
+                        await asyncio.sleep(1)
+                        continue
+                except Exception:
+                    pass
                 task_id = job_data.get("taskId", str(uuid.uuid4()))
                 goal = job_data.get("goal", "")
                 context_raw = job_data.get("context", {})
                 _logger.info("[jq] job ricevuto: %s | goal: %.80s", task_id, goal)
 
-                # Normalizza context → stringa
                 if isinstance(context_raw, dict):
                     context_str = "\n".join(f"{k}: {v}" for k, v in context_raw.items() if v)
                 elif isinstance(context_raw, str):
@@ -118,7 +139,6 @@ async def _hands_consumer_loop():
                 else:
                     context_str = ""
 
-                # S429 — Esecuzione REALE via UnifiedAgentLoop
                 result_payload: Dict[str, Any] = {}
                 try:
                     from agents.unified_loop import UnifiedAgentLoop
@@ -136,7 +156,6 @@ async def _hands_consumer_loop():
                         _critic   = None
                         _verifier = None
 
-                    # Accumula step per tracciabilità nel risultato Redis
                     _steps: list = []
 
                     async def _on_step(step: dict) -> None:
@@ -154,17 +173,21 @@ async def _hands_consumer_loop():
                         planner=_get_planner(),
                     )
 
-                    # max_steps: clampato 5–16, scalato per priorità job
                     _priority = int(job_data.get("priority", 1))
                     _max_steps = max(5, min(4 + _priority * 2, 16))
 
-                    raw_result = await loop_inst.run(
-                        goal=goal,
-                        context=context_str,
-                        max_steps=_max_steps,
-                        on_step=_on_step,
-                        session_id=task_id,
-                    )
+                    # C2-FIX: incrementa contatore PRIMA di run(), decrementa in finally
+                    _active_job_count += 1
+                    try:
+                        raw_result = await loop_inst.run(
+                            goal=goal,
+                            context=context_str,
+                            max_steps=_max_steps,
+                            on_step=_on_step,
+                            session_id=task_id,
+                        )
+                    finally:
+                        _active_job_count = max(0, _active_job_count - 1)
 
                     output  = raw_result.get("output", "") if isinstance(raw_result, dict) else str(raw_result)
                     success = bool(raw_result.get("success", False)) if isinstance(raw_result, dict) else bool(output)
@@ -184,7 +207,6 @@ async def _hands_consumer_loop():
                     _logger.info("[jq] job completato: %s | engine: %s | success: %s", task_id, engine, success)
 
                 except (ImportError, ModuleNotFoundError) as imp_err:
-                    # UnifiedAgentLoop non disponibile su questo nodo
                     _logger.warning("[jq] agents.unified_loop non disponibile su %s: %s", _SPACE_ROLE, imp_err)
                     result_payload = {
                         "taskId": task_id,
@@ -204,7 +226,6 @@ async def _hands_consumer_loop():
                         "error":  str(exec_err)[:500],
                         "ts":     int(time.time() * 1000),
                     }
-                    # INV-R1: 3 errori consecutivi infra → pausa 30s, log esplicito
                     if _consecutive_errors >= _MAX_CONSECUTIVE_ERRORS:
                         _logger.error(
                             "[jq] INV-R1: %d errori consecutivi — pausa 30s (nodo: %s)",
@@ -217,7 +238,6 @@ async def _hands_consumer_loop():
                 _logger.info("[jq] risultato Redis: %s → %s", task_id, result_payload.get("status"))
 
             else:
-                # Coda vuota → reset errori consecutivi, polling leggero via REST
                 _consecutive_errors = 0
                 await asyncio.sleep(2)
 
@@ -231,7 +251,6 @@ async def start_job_queue_consumer() -> None:
         _logger.warning("[jq] Redis non configurato — job queue disabilitato")
         return
     _bg_tasks.append(asyncio.create_task(_load_publisher_loop()))
-    # Grid Orchestrator: Consumer specializzati (HANDS, MEMORY, AUDIT)
     if _SPACE_ROLE in ("hands", "memory", "audit", "unknown"):
         _bg_tasks.append(asyncio.create_task(_hands_consumer_loop()))
     else:
@@ -240,13 +259,13 @@ async def start_job_queue_consumer() -> None:
 # ── FastAPI endpoints ──────────────────────────────────────────────────────────
 @router.get("/status")
 async def jq_status():
-    result = {
+    return {
         "space_role":       _SPACE_ROLE,
         "jq_enabled":       _JQ_ENABLED,
         "redis_configured": _redis_ok(),
+        "active_tasks":     max(0, _active_job_count),
         "ts":               int(time.time() * 1000),
     }
-    return result
 
 @router.get("/load/{role}")
 async def jq_load(role: str):
@@ -262,56 +281,46 @@ async def jq_load(role: str):
 
 @router.post("/submit")
 async def jq_submit(job: JobPayload, request: Request):
-    """
-    S42 — Grid Orchestrator: sottomissione job reale su Redis.
-    Inserisce il job in coda LPUSH (FIFO con RPOP dal consumer).
-    Restituisce taskId e lunghezza coda corrente.
-    """
+    """S42 — Grid Orchestrator: sottomissione job reale su Redis."""
     if _INTERNAL_TOKEN and request.headers.get("X-Internal-Token") != _INTERNAL_TOKEN:
         raise HTTPException(401, "Unauthorized")
-
     if not _redis_ok():
         raise HTTPException(503, "Job queue non disponibile: Redis non configurato")
 
-    # Normalizza taskId: usa quello fornito o genera uno nuovo
     task_id = job.taskId if job.taskId else str(uuid.uuid4())
 
+    # S951: Dynamic Load Balancing
+    target_role = job.context.get('preferred_role', 'hands') if job.context else 'hands'
+    assigned_role = await balancer.get_best_node(target_role)
+
     job_payload = {
-        "taskId": task_id,
-        "goal": job.goal,
-        "context": job.context or {},
-        "priority": job.priority,
-        "submittedAt": int(time.time() * 1000),
-        "submittedBy": _SPACE_ROLE,
+        'taskId':      task_id,
+        'goal':        job.goal,
+        'context':     job.context or {},
+        'priority':    job.priority,
+        'submittedAt': int(time.time() * 1000),
+        'submittedBy': _SPACE_ROLE,
+        'assignedTo':  assigned_role,
     }
-
-    # LPUSH → consumer usa RPOP (FIFO)
     res = await _rcmd(["LPUSH", _K_PENDING, json.dumps(job_payload)])
     if res is None:
         raise HTTPException(503, "Errore Redis durante la sottomissione del job")
 
     queue_len = int(res.get("result", 0)) if res else 0
-
-    # Segnale di wake per consumer (TTL breve)
     await _rcmd(["SET", _K_WAKE, "1", "EX", "10"])
-
     _logger.info("[jq] job sottomesso: %s (coda: %d)", task_id, queue_len)
     return {
-        "taskId": task_id,
-        "status": "queued",
+        "taskId":      task_id,
+        "status":      "queued",
         "queueLength": queue_len,
-        "ts": int(time.time() * 1000),
+        "ts":          int(time.time() * 1000),
     }
 
 @router.get("/result/{task_id}")
 async def jq_result(task_id: str, request: Request):
-    """
-    S429 — Tool Success Contract: recupero risultato job per taskId.
-    Restituisce il risultato se disponibile, altrimenti pending.
-    """
+    """S429 — Tool Success Contract: recupero risultato job per taskId."""
     if _INTERNAL_TOKEN and request.headers.get("X-Internal-Token") != _INTERNAL_TOKEN:
         raise HTTPException(401, "Unauthorized")
-
     if not _redis_ok():
         raise HTTPException(503, "Job queue non disponibile: Redis non configurato")
 
@@ -323,3 +332,6 @@ async def jq_result(task_id: str, request: Request):
     except json.JSONDecodeError as _je:
         _logger.error("[jq] risultato Redis corrotto task=%s: %s", task_id, _je)
         raise HTTPException(500, f"Risultato corrotto in Redis per {task_id}: {_je}")
+
+# Lista dei background tasks (popolata da start_job_queue_consumer)
+_bg_tasks: List[asyncio.Task] = []

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()

api/oracle_endpoints.py

@@ -0,0 +1,189 @@
+"""
+oracle_endpoints.py — Endpoint API per Gestione Nodo E (Oracle Cloud)
+
+Endpoint:
+  GET  /api/oracle/health          — Health check Nodo E
+  GET  /api/oracle/metrics         — Metriche Nodo E
+  POST /api/oracle/sync            — Sincronizzazione cluster
+  POST /api/oracle/restart         — Riavvio servizi
+  GET  /api/oracle/logs            — Log backend remoto
+"""
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+from typing import Optional
+import logging
+
+# Import oracle manager
+try:
+    from backend.api.oracle_node_manager import (
+        initialize_oracle_node,
+        get_oracle_health,
+        sync_oracle_cluster,
+        get_oracle_metrics,
+        restart_oracle_services,
+        ORACLE_NODE_E_ENABLED,
+        ORACLE_NODE_E_IP,
+    )
+except ImportError:
+    from oracle_node_manager import (
+        initialize_oracle_node,
+        get_oracle_health,
+        sync_oracle_cluster,
+        get_oracle_metrics,
+        restart_oracle_services,
+        ORACLE_NODE_E_ENABLED,
+        ORACLE_NODE_E_IP,
+    )
+
+_logger = logging.getLogger("oracle_endpoints")
+
+router = APIRouter(prefix="/api/oracle", tags=["oracle"])
+
+
+# ── Modelli Pydantic ──────────────────────────────────────────────────────
+class OracleHealthResponse(BaseModel):
+    ok: bool
+    status: str
+    metrics: Optional[dict] = None
+    error: Optional[str] = None
+
+
+class OracleSyncResponse(BaseModel):
+    ok: bool
+    message: Optional[str] = None
+    error: Optional[str] = None
+
+
+# ── Endpoint: Health Check ────────────────────────────────────────────────
+@router.get("/health", response_model=OracleHealthResponse)
+async def oracle_health():
+    """Ritorna lo stato di salute del Nodo E."""
+    if not ORACLE_NODE_E_ENABLED:
+        return OracleHealthResponse(
+            ok=False,
+            status="disabled",
+            error="Oracle Node E è disabilitato",
+        )
+    
+    try:
+        health = await get_oracle_health()
+        return OracleHealthResponse(**health)
+    except Exception as exc:
+        _logger.error(f"Error getting oracle health: {exc}")
+        raise HTTPException(500, "Error getting oracle health")
+
+
+# ── Endpoint: Metriche ────────────────────────────────────────────────────
+@router.get("/metrics")
+async def oracle_metrics():
+    """Ritorna le metriche del Nodo E."""
+    if not ORACLE_NODE_E_ENABLED:
+        return {
+            "ok": False,
+            "error": "Oracle Node E è disabilitato",
+        }
+    
+    try:
+        metrics = await get_oracle_metrics()
+        return {
+            "ok": True,
+            "data": metrics,
+        }
+    except Exception as exc:
+        _logger.error(f"Error getting oracle metrics: {exc}")
+        raise HTTPException(500, "Error getting oracle metrics")
+
+
+# ── Endpoint: Sincronizzazione ───────────────────────────────────────────
+@router.post("/sync", response_model=OracleSyncResponse)
+async def oracle_sync():
+    """Sincronizza il Nodo E con il cluster principale."""
+    if not ORACLE_NODE_E_ENABLED:
+        return OracleSyncResponse(
+            ok=False,
+            error="Oracle Node E è disabilitato",
+        )
+    
+    try:
+        result = await sync_oracle_cluster()
+        return OracleSyncResponse(
+            ok=result.get("ok", False),
+            message=result.get("message", result.get("output", "")),
+            error=result.get("error"),
+        )
+    except Exception as exc:
+        _logger.error(f"Error syncing oracle cluster: {exc}")
+        raise HTTPException(500, "Error syncing oracle cluster")
+
+
+# ── Endpoint: Riavvio Servizi ────────────────────────────────────────────
+@router.post("/restart")
+async def oracle_restart():
+    """Riavvia i servizi sul Nodo E."""
+    if not ORACLE_NODE_E_ENABLED:
+        return {
+            "ok": False,
+            "error": "Oracle Node E è disabilitato",
+        }
+    
+    try:
+        result = await restart_oracle_services()
+        return {
+            "ok": result.get("ok", False),
+            "message": result.get("message"),
+            "health": result.get("health"),
+            "error": result.get("error"),
+        }
+    except Exception as exc:
+        _logger.error(f"Error restarting oracle services: {exc}")
+        raise HTTPException(500, "Error restarting oracle services")
+
+
+# ── Endpoint: Log ────────────────────────────────────────────────────────
+@router.get("/logs")
+async def oracle_logs(lines: int = 100):
+    """Ritorna i log del backend remoto."""
+    if not ORACLE_NODE_E_ENABLED:
+        return {
+            "ok": False,
+            "error": "Oracle Node E è disabilitato",
+        }
+    
+    try:
+        from backend.api.oracle_node_manager import _oracle_manager
+        
+        logs = await _oracle_manager.get_logs(lines)
+        return {
+            "ok": True,
+            "logs": logs,
+            "lines": lines,
+        }
+    except Exception as exc:
+        _logger.error(f"Error getting oracle logs: {exc}")
+        raise HTTPException(500, "Error getting oracle logs")
+
+
+# ── Endpoint: Info ────────────────────────────────────────────────────────
+@router.get("/info")
+async def oracle_info():
+    """Ritorna informazioni sul Nodo E."""
+    try:
+        from backend.api.oracle_node_manager import (
+            ORACLE_NODE_E_ROLE,
+            ORACLE_NODE_E_REGION,
+            ORACLE_NODE_E_PORT,
+        )
+        
+        return {
+            "enabled": ORACLE_NODE_E_ENABLED,
+            "ip": ORACLE_NODE_E_IP,
+            "role": ORACLE_NODE_E_ROLE,
+            "region": ORACLE_NODE_E_REGION,
+            "port": ORACLE_NODE_E_PORT,
+            "node_id": "E",
+            "type": "Oracle Cloud (OCI)",
+        }
+    except Exception as exc:
+        _logger.error(f"Error getting oracle info: {exc}")
+        raise HTTPException(500, "Error getting oracle info")

api/oracle_node_manager.py

@@ -0,0 +1,301 @@
+"""
+oracle_node_manager.py — Gestore Nodo E (Oracle Cloud)
+
+Funzionalità:
+  - Monitoraggio stato del server Oracle
+  - Sincronizzazione automatica con cluster principale
+  - Gestione task distribuiti
+  - Health check e failover
+  - Logging e metriche
+
+Utilizzo:
+  from backend.api.oracle_node_manager import OracleNodeManager
+  manager = OracleNodeManager()
+  await manager.sync_with_cluster()
+"""
+
+import os
+import asyncio
+import logging
+from .oci_gateway_manager import oci_gateway
+import json
+from typing import Optional, Dict, List, Any
+from datetime import datetime, timedelta
+from enum import Enum
+import httpx
+import paramiko
+
+_logger = logging.getLogger("oracle_node_manager")
+
+# ── Configurazione Oracle Node E ───────────────────────────────────────────
+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_USER = os.getenv("ORACLE_NODE_E_USER", "opc")
+ORACLE_NODE_E_SSH_KEY_PATH = os.getenv("ORACLE_NODE_E_SSH_KEY_PATH", "/app/secrets/oracle_private_key.pem")
+ORACLE_NODE_E_PORT = int(os.getenv("ORACLE_NODE_E_PORT", "8080"))
+ORACLE_NODE_E_ROLE = os.getenv("ORACLE_NODE_E_ROLE", "Compute/AI Workload")
+ORACLE_NODE_E_REGION = os.getenv("ORACLE_NODE_E_REGION", "Italy Northwest (Milan)")
+
+# ── Enumerazione Stato Nodo ────────────────────────────────────────────────
+class NodeStatus(str, Enum):
+    HEALTHY = "healthy"
+    DEGRADED = "degraded"
+    UNHEALTHY = "unhealthy"
+    OFFLINE = "offline"
+
+
+# ── SSH Client per Oracle ──────────────────────────────────────────────────
+class OracleSSHClient:
+    """Client SSH per gestire il server Oracle."""
+    
+    def __init__(self, host: str, user: str, key_path: str):
+        self.host = host
+        self.user = user
+        self.key_path = key_path
+        self.client = None
+    
+    async def connect(self) -> bool:
+        """Connette al server Oracle via SSH."""
+        try:
+            self.client = paramiko.SSHClient()
+            self.client.set_missing_host_key_policy(paramiko.AutoAddPolicy())
+            
+            # Carica chiave privata
+            if not os.path.exists(self.key_path):
+                _logger.error(f"Chiave SSH non trovata: {self.key_path}")
+                return False
+            
+            pkey = paramiko.RSAKey.from_private_key_file(self.key_path)
+            self.client.connect(self.host, username=self.user, pkey=pkey, timeout=10)
+            
+            _logger.info(f"Connesso a Oracle Node E: {self.host}")
+            return True
+        except Exception as exc:
+            _logger.error(f"Errore connessione SSH: {exc}")
+            return False
+    
+    async def execute_command(self, cmd: str) -> tuple[bool, str]:
+        """Esegue un comando remoto."""
+        try:
+            if not self.client:
+                return False, "Non connesso"
+            
+            stdin, stdout, stderr = self.client.exec_command(cmd, timeout=30)
+            output = stdout.read().decode('utf-8')
+            error = stderr.read().decode('utf-8')
+            
+            return True, output if output else error
+        except Exception as exc:
+            _logger.error(f"Errore esecuzione comando: {exc}")
+            return False, str(exc)
+    
+    async def disconnect(self):
+        """Disconnette dal server."""
+        if self.client:
+            self.client.close()
+            _logger.info("Disconnesso da Oracle Node E")
+
+
+# ── Oracle Node Manager ────────────────────────────────────────────────────
+class OracleNodeManager:
+    """Gestore del Nodo E (Oracle Cloud)."""
+    
+    def __init__(self):
+        self.ssh_client = OracleSSHClient(ORACLE_NODE_E_IP, ORACLE_NODE_E_USER, ORACLE_NODE_E_SSH_KEY_PATH)
+        self.status = NodeStatus.OFFLINE
+        self._last_sync = None
+        self._metrics = {
+            "cpu_usage": 0.0,
+            "memory_usage": 0.0,
+            "disk_usage": 0.0,
+            "uptime_seconds": 0,
+            "sync_lag_seconds": 0,
+        }
+    
+    async def initialize(self) -> bool:
+        """Inizializza la connessione al Nodo E."""
+        if not ORACLE_NODE_E_ENABLED:
+            _logger.info("Oracle Node E disabilitato")
+            return False
+        
+        connected = await self.ssh_client.connect()
+        if connected:
+            self.status = NodeStatus.HEALTHY
+            return True
+        else:
+            self.status = NodeStatus.OFFLINE
+            return False
+    
+    async def health_check(self) -> Dict[str, Any]:
+        # Tentativo tramite Gateway se la connessione diretta fallisce
+        gateway_res = await oci_gateway.get_gateway_status()
+        if gateway_res.get("ok"):
+            _logger.info("Connessione via OCI API Gateway attiva")
+        """Esegue health check del Nodo E."""
+        if not self.ssh_client.client:
+            return {
+                "ok": False,
+                "status": NodeStatus.OFFLINE.value,
+                "error": "Non connesso",
+            }
+        
+        try:
+            # Verifica backend
+            backend_ok, _ = await self.ssh_client.execute_command(
+                f"curl -s http://localhost:{ORACLE_NODE_E_PORT}/api/health || echo 'FAIL'"
+            )
+            
+            # Verifica risorse
+            cpu_ok, cpu_output = await self.ssh_client.execute_command("top -bn1 | grep 'Cpu(s)' | awk '{print $2}'")
+            mem_ok, mem_output = await self.ssh_client.execute_command("free | grep Mem | awk '{printf \"%.1f\", ($3/$2)*100}'")
+            disk_ok, disk_output = await self.ssh_client.execute_command("df -h / | tail -1 | awk '{print $5}'")
+            
+            # Aggiorna metriche
+            self._metrics["cpu_usage"] = float(cpu_output.strip()) if cpu_ok else 0.0
+            self._metrics["memory_usage"] = float(mem_output.strip()) if mem_ok else 0.0
+            self._metrics["disk_usage"] = float(disk_output.strip().rstrip('%')) if disk_ok else 0.0
+            
+            # Determina stato
+            if backend_ok and self._metrics["cpu_usage"] < 80 and self._metrics["memory_usage"] < 85:
+                self.status = NodeStatus.HEALTHY
+            elif self._metrics["cpu_usage"] < 95 and self._metrics["memory_usage"] < 95:
+                self.status = NodeStatus.DEGRADED
+            else:
+                self.status = NodeStatus.UNHEALTHY
+            
+            return {
+                "ok": True,
+                "status": self.status.value,
+                "metrics": self._metrics,
+                "timestamp": datetime.now().isoformat(),
+            }
+        except Exception as exc:
+            _logger.error(f"Errore health check: {exc}")
+            self.status = NodeStatus.UNHEALTHY
+            return {
+                "ok": False,
+                "status": NodeStatus.UNHEALTHY.value,
+                "error": str(exc),
+            }
+    
+    async def sync_with_cluster(self) -> Dict[str, Any]:
+        """Sincronizza il Nodo E con il cluster principale."""
+        if not self.ssh_client.client:
+            return {"ok": False, "error": "Non connesso"}
+        
+        try:
+            # Esegui script di sincronizzazione remoto
+            sync_cmd = "cd /home/opc/ai-cluster/repo && node scripts/sync-cluster-state.mjs --node E"
+            success, output = await self.ssh_client.execute_command(sync_cmd)
+            
+            if success:
+                self._last_sync = datetime.now()
+                _logger.info(f"Sincronizzazione completata: {output}")
+                return {
+                    "ok": True,
+                    "message": "Sincronizzazione completata",
+                    "output": output,
+                    "timestamp": datetime.now().isoformat(),
+                }
+            else:
+                return {
+                    "ok": False,
+                    "error": output,
+                }
+        except Exception as exc:
+            _logger.error(f"Errore sincronizzazione: {exc}")
+            return {
+                "ok": False,
+                "error": str(exc),
+            }
+    
+    async def get_logs(self, lines: int = 100) -> str:
+        """Recupera i log del backend remoto."""
+        if not self.ssh_client.client:
+            return "Non connesso"
+        
+        try:
+            cmd = f"tail -n {lines} /home/opc/ai-cluster/backend.log"
+            success, output = await self.ssh_client.execute_command(cmd)
+            return output if success else "Errore lettura log"
+        except Exception as exc:
+            return f"Errore: {str(exc)}"
+    
+    async def restart_services(self) -> Dict[str, Any]:
+        """Riavvia i servizi sul Nodo E."""
+        if not self.ssh_client.client:
+            return {"ok": False, "error": "Non connesso"}
+        
+        try:
+            # Ferma servizi
+            await self.ssh_client.execute_command("pkill -f 'npm start' || true")
+            await asyncio.sleep(2)
+            
+            # Avvia servizi
+            start_cmd = "cd /home/opc/ai-cluster/repo/backend && nohup npm start > /home/opc/ai-cluster/backend.log 2>&1 &"
+            success, output = await self.ssh_client.execute_command(start_cmd)
+            
+            await asyncio.sleep(3)
+            
+            # Verifica health
+            health = await self.health_check()
+            
+            return {
+                "ok": True,
+                "message": "Servizi riavviati",
+                "health": health,
+                "timestamp": datetime.now().isoformat(),
+            }
+        except Exception as exc:
+            _logger.error(f"Errore riavvio servizi: {exc}")
+            return {
+                "ok": False,
+                "error": str(exc),
+            }
+    
+    async def get_metrics(self) -> Dict[str, Any]:
+        """Ritorna metriche del Nodo E."""
+        return {
+            "node": "E",
+            "ip": ORACLE_NODE_E_IP,
+            "role": ORACLE_NODE_E_ROLE,
+            "region": ORACLE_NODE_E_REGION,
+            "status": self.status.value,
+            "metrics": self._metrics,
+            "last_sync": self._last_sync.isoformat() if self._last_sync else None,
+            "timestamp": datetime.now().isoformat(),
+        }
+    
+    async def cleanup(self):
+        """Pulizia risorse."""
+        await self.ssh_client.disconnect()
+
+
+# ── Istanza Globale ───────────────────────────────────────────────────────
+_oracle_manager = OracleNodeManager()
+
+
+# ── Funzioni Pubbliche ────────────────────────────────────────────────────
+async def initialize_oracle_node() -> bool:
+    """Inizializza il Nodo E."""
+    return await _oracle_manager.initialize()
+
+
+async def get_oracle_health() -> Dict[str, Any]:
+    """Ritorna health check del Nodo E."""
+    return await _oracle_manager.health_check()
+
+
+async def sync_oracle_cluster() -> Dict[str, Any]:
+    """Sincronizza il Nodo E con il cluster."""
+    return await _oracle_manager.sync_with_cluster()
+
+
+async def get_oracle_metrics() -> Dict[str, Any]:
+    """Ritorna metriche del Nodo E."""
+    return await _oracle_manager.get_metrics()
+
+
+async def restart_oracle_services() -> Dict[str, Any]:
+    """Riavvia servizi sul Nodo E."""
+    return await _oracle_manager.restart_services()

api/prewarm.py

@@ -0,0 +1,49 @@
+"""
+backend/api/prewarm.py — Predictive Pre-warming (S950)
+Rileva se un task richiederà i nodi HANDS (B) o MEMORY (C) e invia segnali di risveglio preventivi.
+Integrato con fire_speculative_tools per latenza zero.
+"""
+import asyncio
+import logging
+import os
+import re
+import httpx
+
+_logger = logging.getLogger("agente_ai.prewarm")
+
+# Configurazione nodi (Sync con daemon-health-autofix.mjs)
+WAKE_CONFIG = {
+    "B": {"owner": "Baida07", "name": "ai-backend-collab", "token": "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", "url": "https://baida07-ai-backend-collab.hf.space"},
+    "C": {"owner": "Baida07", "name": "ai-memory-backend", "token": "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", "url": "https://baida07-ai-memory-backend.hf.space"}
+}
+
+# Regex per rilevare necessità di nodi specifici
+RE_HANDS = re.compile(r"\b(crea|fai|scrivi|build|deploy|git|push|commit|shell|terminal|esegui|run|installa|npm|pip|pnpm|setup)\b", re.I)
+RE_MEMORY = re.compile(r"\b(ricorda|memoria|storia|passato|semantica|rag|conoscenza|database|vecchi|precedenti|documenti)\b", re.I)
+
+async def _wake_hf_space(node_id: str):
+    cfg = WAKE_CONFIG.get(node_id)
+    if not cfg: return
+    
+    _logger.info(f"[S950] Pre-warming Nodo {node_id} ({cfg['owner']}/{cfg['name']})...")
+    try:
+        async with httpx.AsyncClient() as client:
+            # 1. Soft Ping
+            try: await client.get(f"{cfg['url']}/health", timeout=2.0)
+            except: pass
+            # 2. Hard Wake (API Restart)
+            url = f"https://huggingface.co/api/spaces/{cfg['owner']}/{cfg['name']}/restart"
+            headers = {"Authorization": f"Bearer {cfg['token']}"}
+            await client.post(url, headers=headers, timeout=5.0)
+    except Exception as e:
+        _logger.error(f"[S950] Errore pre-warming {node_id}: {e}")
+
+async def predictive_prewarm(goal: str):
+    tasks = []
+    if RE_HANDS.search(goal): tasks.append(_wake_hf_space("B"))
+    if RE_MEMORY.search(goal): tasks.append(_wake_hf_space("C"))
+    if tasks: await asyncio.gather(*tasks)
+
+def fire_predictive_prewarm(goal: str):
+    try: asyncio.create_task(predictive_prewarm(goal))
+    except Exception as e: _logger.error(f"[S950] Impossibile avviare task prewarm: {e}")

api/telegram_callbacks.py

@@ -0,0 +1,358 @@
+"""backend/api/telegram_callbacks.py — Gestione callback_query e inline_query Telegram.
+
+Handler:
+  _handle_inline  — inline query (@bot testo in chat)
+  _handle_callback — callback_data dei bottoni inline
+"""
+from __future__ import annotations
+import asyncio, html, logging, os, time
+
+from .telegram_tg_client import (
+    _get_bot_token, _tg_reply, _tg_send, _tg_edit,
+    _tg_typing, _tg_answer_callback, _fmt_elapsed,
+    _log_tg_exc, _BACK_KB,
+)
+from .telegram_keyboards import (
+    _MAIN_KB, _QUICK_PICK_KB, _after_task_kb, _BENCH_CACHE, _LAST_GOAL,
+)
+from .telegram_cmd_ai import (
+    _cmd_do, _cmd_autofix, _cmd_score, _cmd_bench, _cmd_improve,
+    _cmd_scan_now, _cmd_telemetry, _cmd_coord, _cmd_git,
+)
+from .telegram_cmd_monitoring import (
+    _cmd_help, _cmd_status, _cmd_tasks, _cmd_check,
+    _cmd_logs,
+)
+
+_logger = logging.getLogger("api.telegram_webhook")
+
+# ── callback_query handler — inline buttons da notify_task_done ───────────────
+
+async def _handle_inline(iq: dict, token: str) -> None:
+    """Gestisce inline query: @ARJagent_ap_bot <testo> in qualsiasi chat.
+    Abilita tramite @BotFather → /setinline → ARJagent_ap_bot.
+    """
+    bot_token = token or _get_bot_token()
+    if not bot_token: return
+    iq_id = iq.get("id","")
+    query = (iq.get("query") or "").strip()
+    q60   = query[:60]
+    if not query:
+        results = [
+            {"type":"article","id":"help","title":"🤖 Comandi Agente AI",
+             "description":"Lista tutti i comandi",
+             "input_message_content":{"message_text":
+               "🤖 <b>Agente AI</b>\n/do &lt;goal&gt; — task streaming\n/ask &lt;q&gt; — risposta veloce\n"
+               "/autofix — fix errori auto\n/status — stato\n\nagente-ai.pages.dev","parse_mode":"HTML"}},
+            {"type":"article","id":"do","title":"🚀 Nuovo Task AI",
+             "description":"/do <goal> — lancia task complesso",
+             "input_message_content":{"message_text":"/do "}},
+            {"type":"article","id":"ask","title":"🧠 Domanda AI",
+             "description":"/ask <domanda>",
+             "input_message_content":{"message_text":"/ask "}},
+        ]
+    else:
+        results = [
+            {"type":"article","id":"ask","title":f"🧠 Chiedi: {q60}",
+             "description":f"/ask {q60}",
+             "input_message_content":{"message_text":f"/ask {query}"}},
+            {"type":"article","id":"do","title":f"🚀 Task: {q60}",
+             "description":f"/do {q60}",
+             "input_message_content":{"message_text":f"/do {query}"}},
+            {"type":"article","id":"fix","title":f"🔧 AutoFix: {q60}",
+             "description":f"/autofix {q60}",
+             "input_message_content":{"message_text":f"/autofix {query}"}},
+        ]
+    try:
+        import httpx as _hx
+        async with _hx.AsyncClient(timeout=5.0) as c:
+            await c.post(f"https://api.telegram.org/bot{bot_token}/answerInlineQuery",
+                         json={"inline_query_id":iq_id,"results":results,"cache_time":30,"is_personal":True})
+    except Exception as exc:
+        _logger.debug("inline answer error: %s", exc)
+
+
+async def _handle_callback(callback_query: dict, token: str) -> None:
+    """Gestisce i callback_data dei bottoni inline (notify_task_done, menu)."""
+    cq_id   = callback_query.get("id", "")
+    chat_id = callback_query.get("message", {}).get("chat", {}).get("id", 0)
+    data    = (callback_query.get("data") or "").strip()
+
+    # Risponde subito per chiudere il loading Telegram
+    await _tg_answer_callback(cq_id, token=token)
+
+    if not chat_id or not data:
+        return
+
+    # ── task_sum:<tid> — riepilogo task da Supabase ──────────────────────────
+    if data.startswith("task_sum:"):
+        tid = data[9:].strip()
+        try:
+            from api.state import _sb
+            if _sb:
+                res = await asyncio.to_thread(
+                    lambda: _sb.table("agent_tasks")
+                    .select("task_id,goal,status,created_at")
+                    .eq("task_id", tid)
+                    .limit(1)
+                    .execute()
+                )
+                rows = res.data or []
+                if rows:
+                    r = rows[0]
+                    st  = r.get("status", "?")
+                    gol = html.escape((r.get("goal") or "")[:200])
+                    em  = {"SUCCESS":"✅","ERROR":"❌","RUNNING":"⚙️","QUEUED":"⏳"}.get(st,"•")
+                    ca  = r.get("created_at", 0)
+                    age = _fmt_elapsed(ca) if isinstance(ca, int) and ca > 1_000_000 else "?"
+                    await _tg_reply(
+                        chat_id,
+                        "📋 <b>Riepilogo task</b>\n\n"
+                        "<b>ID:</b> <code>" + html.escape(tid) + "</code>\n"
+                        "<b>Stato:</b> " + em + " " + st + "\n"
+                        "<b>Goal:</b> " + gol + "\n"
+                        "<b>Avviato:</b> " + age,
+                        token=token,
+                    )
+                    return
+            await _tg_reply(chat_id, "⚠️ Task <code>" + html.escape(tid) + "</code> non trovato in Supabase.", token=token)
+        except Exception as exc:
+            await _tg_reply(chat_id, "❌ Errore: " + html.escape(str(exc)[:200]), token=token)
+
+    # ── task_wins:<tid> — quick wins (non persisti — riepilogo generico) ─────
+    elif data.startswith("task_wins:"):
+        tid = data[10:].strip()
+        await _tg_reply(
+            chat_id,
+            "💡 <b>Quick Wins</b> — <code>" + html.escape(tid) + "</code>\n\n"
+            "I quick wins vengono inclusi nella notifica del task.\n"
+            "Avvia <b>/tasks</b> per vedere i task recenti o usa il pannello web per dettagli completi.\n\n"
+            "<a href='https://agente-ai.pages.dev'>Apri Dashboard →</a>",
+            token=token,
+        )
+
+    # ── agent — nuovo task (quick-pick) ──────────────────────────────────────
+    elif data == "agent":
+        await _tg_reply(
+            chat_id,
+            "🚀 <b>Avvia Task</b> — scegli un template o scrivi il tuo obiettivo:",
+            token=token, keyboard=_QUICK_PICK_KB,
+        )
+
+    # ── tgw_status / tgw_tasks / tgw_health / tgw_help — menu comandi ────────
+    elif data == "tgw_chart":
+        await _tg_reply(chat_id,
+            "📈 <b>Grafici</b>\n\nHeatmap commit, burndown sprint e molto altro nella Dashboard:",
+            token=token, keyboard=_WEBAPP_KB)
+    elif data == "tgw_ask":
+        await _tg_reply(chat_id,
+            "🧠 <b>Chiedi all'AI</b>\n\n"
+            "Scrivi la domanda direttamente o usa:\n"
+            "<code>/ask &lt;domanda&gt;</code>\n\n"
+            "<i>Esempio: /ask come ottimizzare una query PostgreSQL?</i>",
+            token=token, keyboard=_BACK_KB)
+    elif data == "tgw_bench":
+        asyncio.create_task(_cmd_bench(chat_id)).add_done_callback(_log_tg_exc)
+    elif data == "tgw_autofix":
+        asyncio.create_task(_cmd_autofix(chat_id,"")).add_done_callback(_log_tg_exc)
+    elif data == "tgw_logs":
+        asyncio.create_task(_cmd_logs(chat_id,"WARNING")).add_done_callback(_log_tg_exc)
+    elif data == "tgw_bench_fix":
+        # Legge gap dall'ultimo run (cache) e chiede all'agente un fix mirato
+        cached = _BENCH_CACHE.get(chat_id, {})
+        goal = (
+            "Analizza i gap del benchmark-extended (bench.yml) più recente. "
+            "Identifica le categorie con score più basso e genera patch mirate "
+            "(prompt rules, retry logic, tool selection) per migliorare ogni area debole. "
+            "Priorità: agentic → coding → reasoning. Fai push delle modifiche su GitHub."
+        )
+        asyncio.create_task(_cmd_do(chat_id, goal)).add_done_callback(_log_tg_exc)
+    elif data == "tgw_bench_run":
+        # Rilancia bench
+        asyncio.create_task(_cmd_bench(chat_id)).add_done_callback(_log_tg_exc)
+    elif data == "tgw_score":
+        asyncio.create_task(_cmd_score(chat_id)).add_done_callback(_log_tg_exc)
+    elif data == "tgw_telemetry":
+        asyncio.create_task(_cmd_telemetry(chat_id)).add_done_callback(_log_tg_exc)
+    elif data == "tgw_improve":
+        asyncio.create_task(_cmd_improve(chat_id)).add_done_callback(_log_tg_exc)
+    elif data == "tgw_status":
+        await _cmd_status(chat_id)
+    elif data == "tgw_tasks":
+        await _cmd_tasks(chat_id)
+    elif data == "tgw_health":
+        await _cmd_scan_now(chat_id)
+    elif data == "tgw_check":
+        asyncio.create_task(_cmd_check(chat_id)).add_done_callback(_log_tg_exc)
+    elif data == "tgw_help":
+        await _cmd_help(chat_id)
+    elif data == "tgw_coord":
+        asyncio.create_task(_cmd_coord(chat_id)).add_done_callback(_log_tg_exc)
+    elif data == "tgw_git":
+        asyncio.create_task(_cmd_git(chat_id)).add_done_callback(_log_tg_exc)
+
+    # ── Sub-menu dispatchers (Reply Keyboard → inline sub-menu) ─────────────────
+    elif data in ("menu_task",):
+        await _tg_reply(chat_id, "🚀 <b>Task AI</b> — scegli un'azione:", token=token, keyboard=_TASK_MENU_KB)
+    elif data == "menu_status":
+        await _cmd_status(chat_id)
+        await _tg_reply(chat_id, "📊 <b>Stato Sistema</b> — altre opzioni:", token=token, keyboard=_STATUS_MENU_KB)
+    elif data == "menu_perf":
+        await _tg_reply(chat_id, "📈 <b>Performance</b> — scegli:", token=token, keyboard=_PERF_MENU_KB)
+    elif data == "menu_health":
+        asyncio.create_task(_cmd_scan_now(chat_id)).add_done_callback(_log_tg_exc)
+    elif data == "menu_dev":
+        await _tg_reply(chat_id, "🛠 <b>Dev Tools</b> — scegli:", token=token, keyboard=_DEV_MENU_KB)
+    elif data == "tgw_home":
+        asyncio.create_task(_cmd_help(chat_id)).add_done_callback(_log_tg_exc)
+
+    # ── Nuovi callback task/utility ────────────────────────────────────────────
+    elif data == "tgw_do":
+        await _tg_reply(chat_id,
+            "🚀 <b>Nuovo Task AI</b>\n\n"
+            "Scrivi il tuo obiettivo nella chat — elaboro tutto come task AI.\n\n"
+            "<i>Esempi:</i>\n"
+            "  <code>analizza bug in backend/api/state.py</code>\n"
+            "  <code>genera test per providers.py</code>\n"
+            "  <code>ottimizza le query Supabase più lente</code>\n\n"
+            "Oppure: <code>/do &lt;goal&gt;</code>",
+            token=token, keyboard=_BACK_KB)
+    elif data == "tgw_briefing":
+        asyncio.create_task(_cmd_riepilogo(chat_id)).add_done_callback(_log_tg_exc)
+    elif data == "tgw_nota":
+        await _tg_reply(chat_id,
+            "📝 <b>Salva Nota</b>\n\n"
+            "Usa: <code>/nota &lt;testo da ricordare&gt;</code>\n\n"
+            "<i>Esempio: /nota domani rivedere il deploy HF Space</i>",
+            token=token, keyboard=_BACK_KB)
+    elif data == "tgw_cerca":
+        await _tg_reply(chat_id,
+            "🔍 <b>Cerca sul web</b>\n\n"
+            "Usa: <code>/cerca &lt;query&gt;</code>\n\n"
+            "<i>Esempio: /cerca best practices FastAPI async Python</i>",
+            token=token, keyboard=_BACK_KB)
+    elif data == "tgw_meteo":
+        await _tg_reply(chat_id,
+            "🌤 <b>Meteo</b>\n\n"
+            "Usa: <code>/meteo &lt;città&gt;</code>\n\n"
+            "<i>Esempio: /meteo Milano</i>",
+            token=token, keyboard=_BACK_KB)
+    elif data == "tgw_providers":
+        try:
+            from api.providers import _heartbeat_state as _hs_pv
+            providers = (_hs_pv or {}).get("providers") or []
+            if providers:
+                lines = ["🔌 <b>Provider AI</b>\n"]
+                best = next((p for p in providers if p.get("ok")), None)
+                for p in providers:
+                    ok = p.get("ok", False)
+                    icon = "✅" if ok else ("🔑" if "401" in str(p.get("error","")) else ("💳" if "429" in str(p.get("error","")) else "❌"))
+                    ms = p.get("latency_ms")
+                    ms_str = f"{ms}ms" if ms else "–"
+                    name = p.get("name","?")
+                    star = " ⭐" if (best and p.get("name") == best.get("name")) else ""
+                    lines.append(f"{icon} <b>{html.escape(name)}</b>{star} — {ms_str}")
+                    if not ok and p.get("error"):
+                        lines.append(f"   <i>{html.escape(str(p['error'])[:80])}</i>")
+                import time as _tpv
+                last = (_hs_pv or {}).get("last_run_at",0)
+                age = f"{int(_tpv.time()-last)}s fa" if last else "?"
+                lines.append(f"\n<i>⏱ Heartbeat {age}</i>")
+                await _tg_reply(chat_id, "\n".join(lines), token=token, keyboard=_HEALTH_MENU_KB)
+            else:
+                await _tg_reply(chat_id,
+                    "⚠️ Dati provider non ancora disponibili (~90s al primo heartbeat).",
+                    token=token, keyboard=_BACK_KB)
+        except Exception as exc:
+            await _tg_reply(chat_id,
+                "❌ Errore: <code>" + html.escape(str(exc)[:200]) + "</code>",
+                token=token, keyboard=_BACK_KB)
+    elif data == "tgw_snap":
+        try:
+            from .integrity_manager import handle_snap_cmd as _hi_snap
+            asyncio.create_task(_hi_snap(chat_id, _tg_reply, None)).add_done_callback(_log_tg_exc)
+        except Exception:
+            await _tg_reply(chat_id, "⚠️ Integrity manager non disponibile.", token=token, keyboard=_BACK_KB)
+    elif data == "tgw_verify":
+        try:
+            from .integrity_manager import handle_verify_cmd as _hi_verify
+            asyncio.create_task(_hi_verify(chat_id, _tg_reply, None)).add_done_callback(_log_tg_exc)
+        except Exception:
+            await _tg_reply(chat_id, "⚠️ Integrity manager non disponibile.", token=token, keyboard=_BACK_KB)
+    elif data == "tgw_heal":
+        try:
+            from .integrity_manager import handle_heal_cmd as _hi_heal
+            asyncio.create_task(_hi_heal(chat_id, _tg_reply, None)).add_done_callback(_log_tg_exc)
+        except Exception:
+            await _tg_reply(chat_id, "⚠️ Integrity manager non disponibile.", token=token, keyboard=_BACK_KB)
+    elif data == "tgw_ping":
+        ry = os.getenv("RAILWAY_URL","https://ai-production-4c06.up.railway.app")
+        try:
+            async with httpx.AsyncClient(timeout=8.0) as _hxc:
+                r = await _hxc.get(f"{ry}/health")
+                j = r.json()
+                ok = "✅" if j.get("status")=="ok" else "⚠️"
+                await _tg_reply(chat_id,
+                    f"🏓 <b>Pong!</b> {ok}\nv{j.get('version','?')} — Railway live",
+                    token=token, keyboard=_DEV_MENU_KB)
+        except Exception as exc:
+            await _tg_reply(chat_id,
+                "❌ Railway non raggiungibile\n<code>"+html.escape(str(exc)[:150])+"</code>",
+                token=token, keyboard=_BACK_KB)
+
+    # ── Quick-pick task templates (MX-QUICKPICK) ─────────────────────────────
+    elif data == "qp_bug":
+        asyncio.create_task(_cmd_do(chat_id,
+            "Leggi i log di Railway/HF degli ultimi 30 minuti. Identifica gli errori principali, "
+            "trova la root cause reale e suggerisci un fix concreto con codice.")).add_done_callback(_log_tg_exc)
+    elif data == "qp_db":
+        asyncio.create_task(_cmd_do(chat_id,
+            "Analizza le query Supabase più lente del progetto (agent_tasks, agent_logs, semantic_memory). "
+            "Identifica query N+1, indici mancanti, e proponi le ottimizzazioni con SQL concreto.")).add_done_callback(_log_tg_exc)
+    elif data == "qp_autofix":
+        asyncio.create_task(_cmd_autofix(chat_id, "")).add_done_callback(_log_tg_exc)
+    elif data == "qp_commits":
+        asyncio.create_task(_cmd_do(chat_id,
+            "Leggi gli ultimi 10 commit su Baida98/AI via GitHub API e produci un riepilogo in italiano: "
+            "cosa è stato fatto, da chi, e qual è lo stato attuale del progetto.")).add_done_callback(_log_tg_exc)
+    elif data == "qp_docs":
+        asyncio.create_task(_cmd_do(chat_id,
+            "Genera la documentazione degli endpoint API principali del backend Railway: "
+            "/api/telegram, /api/agent, /health. Per ognuno: metodo HTTP, parametri, risposta attesa, esempi.")).add_done_callback(_log_tg_exc)
+    elif data == "qp_tests":
+        asyncio.create_task(_cmd_do(chat_id,
+            "Genera test pytest per i moduli critici del backend: "
+            "api/telegram_webhook.py, agents/unified_loop.py, providers. "
+            "Priorità: test di integrazione per i path più usati e i casi di errore.")).add_done_callback(_log_tg_exc)
+    elif data == "qp_custom":
+        await _tg_reply(chat_id,
+            "✍️ <b>Scrivi il tuo obiettivo</b>\n"
+            "Scrivi liberamente nella chat — lo eseguo come task AI.\n"
+            "<i>Esempi:</i>\n"
+            "  <code>ottimizza le query Supabase lente</code>\n"
+            "  <code>analizza providers.py e suggerisci fix</code>",
+            token=token, keyboard=_BACK_KB)
+    # ── tgw_retry — rilancia l'ultimo task ───────────────────────────────────
+    elif data == "tgw_retry":
+        last = _LAST_GOAL.get(chat_id)
+        if last:
+            asyncio.create_task(_cmd_do(chat_id, last)).add_done_callback(_log_tg_exc)
+        else:
+            await _tg_reply(chat_id,
+                "⚠️ Nessun task precedente da ripetere. Avvia un nuovo task:",
+                token=token, keyboard=_QUICK_PICK_KB)
+
+    # ── m — menu principale ───────────────────────────────────────────────────
+    elif data == "m":
+        await _tg_reply(
+            chat_id,
+            "🤖 <b>Menu principale</b>\n\nScegli un'azione:",
+            token=token,
+            keyboard=_MAIN_KB,
+        )
+
+    # ── fallback — command non gestito ───────────────────────────────────────
+    else:
+        _logger.debug("callback_query unhandled: %s", data)
+
+

api/telegram_cmd_ai.py

@@ -0,0 +1,1154 @@
+"""backend/api/telegram_cmd_ai.py — Comandi Telegram AI e operativi.
+
+Comandi:
+  _cmd_do, _cmd_autofix, _cmd_nota, _cmd_cerca, _cmd_meteo,
+  _cmd_riepilogo, _cmd_score, _cmd_bench, _cmd_improve
+"""
+from __future__ import annotations
+import asyncio, html, logging, os, re, time
+
+from .telegram_tg_client import (
+    _get_bot_token, _tg_reply, _tg_send, _tg_edit,
+    _tg_typing, _tg_react, _tg_photo, _fmt_elapsed,
+    _log_tg_exc, _BACK_KB,
+)
+from .telegram_keyboards import (
+    _MAIN_KB, _QUICK_PICK_KB, _after_task_kb, _BENCH_CACHE, _LAST_GOAL,
+    _BENCH_ACTION_KB,
+)
+
+_logger = logging.getLogger("api.telegram_webhook")
+
+async def _cmd_do(chat_id: int, goal: str) -> None:
+    """Lancia task AI con streaming progressivo via editMessageText.
+
+    Flusso: invia msg iniziale → salva message_id → on_step accumula token
+    → edit throttled ogni 1.5s → flush finale con output + keyboard.
+    Rate-limit sicuro: max ~40 edit/min totali, Telegram consente 20 edit/min/chat.
+    """
+    if not goal.strip():
+        await _tg_reply(chat_id, "⚠️ Usa il menu per scegliere un task:", keyboard=_QUICK_PICK_KB)
+        return
+
+    _LAST_GOAL[chat_id] = goal  # salva per retry
+    await _tg_typing(chat_id)
+    msg_id = await _tg_send(
+        chat_id,
+        "🚀 <b>Avvio task…</b>\n\n"
+        "🎯 <i>" + html.escape(goal[:200]) + "</i>\n\n"
+        "⏳ <i>Sto elaborando, un momento…</i>",
+    )
+
+    _buf: list[str] = []
+    _last_edit: list[float] = [0.0]  # list per mutabilità in closure
+    _EDIT_INTERVAL = 1.5
+    _MAX_LEN = 3600
+
+    async def _flush(final: bool = False) -> None:
+        if not msg_id:
+            return
+        content = "".join(_buf).strip()
+        if not content:
+            return
+        now = time.monotonic()
+        if not final and (now - _last_edit[0]) < _EDIT_INTERVAL:
+            return
+        prefix = "🧠 <b>Risposta AI</b>\n<b>Goal:</b> " + html.escape(goal[:80]) + "\n\n"
+        suffix = "" if final else "\n⏳"
+        body = html.escape(content[: _MAX_LEN - len(prefix) - len(suffix)])
+        await _tg_edit(chat_id, msg_id, prefix + body + suffix)
+        _last_edit[0] = time.monotonic()
+
+    async def _on_step(event: dict) -> None:
+        if event.get("action") == "text_chunk":
+            tok = event.get("token", "")
+            if tok:
+                _buf.append(tok)
+                await _flush(final=False)
+
+    try:
+        from agents.unified_loop import UnifiedAgentLoop
+        from api.state import _get_ai_client, _get_mem_manager_async, _get_executor, _get_planner
+        client   = _get_ai_client()
+        memory   = await _get_mem_manager_async()
+        executor = _get_executor()
+        planner  = _get_planner()
+        try:
+            from agents.critic            import Critic
+            from agents.response_verifier import ResponseVerifier
+            critic   = Critic(llm_client=client)
+            verifier = ResponseVerifier()
+        except Exception:
+            critic = verifier = None
+        loop = UnifiedAgentLoop(
+            llm_client=client, critic=critic, verifier=verifier,
+            memory=memory, executor=executor, planner=planner,
+        )
+        result = await asyncio.wait_for(
+            loop.run(goal=goal, context="", max_steps=8, on_step=_on_step),
+            timeout=120.0,
+        )
+        output = result.get("output", "") if isinstance(result, dict) else str(result)
+        await _flush(final=True)
+        if msg_id and output:
+            _out_str  = str(output)
+            _out_esc  = html.escape(_out_str[:3000])
+            # Usa blockquote espandibile per output lunghi (Bot API 7.4+, Jul 2024)
+            _out_body = (
+                f"<blockquote expandable>{_out_esc}</blockquote>"
+                if len(_out_str) > 400 else _out_esc
+            )
+            await _tg_edit(
+                chat_id, msg_id,
+                "✅ <b>Fatto!</b>\n\n"
+                "🎯 <i>" + html.escape(goal[:100]) + "</i>\n\n"
+                + _out_body,
+                keyboard=_after_task_kb(chat_id),
+            )
+            await _tg_react(chat_id, msg_id, "🎉")
+        try:
+            from .telegram_notify import notify_task_done
+            task_id = result.get("task_id", "tgw-do") if isinstance(result, dict) else "tgw-do"
+            await notify_task_done(str(task_id), goal, str(output))
+        except Exception:
+            if not msg_id:
+                _fb_esc  = html.escape(str(output)[:800])
+                _fb_body = (
+                    f"<blockquote expandable>{_fb_esc}</blockquote>"
+                    if len(str(output)) > 400 else _fb_esc
+                )
+                await _tg_reply(
+                    chat_id,
+                    "✅ <b>Fatto!</b>\n\n"
+                    "🎯 <i>" + html.escape(goal[:80]) + "</i>\n\n"
+                    + _fb_body,
+                )
+    except asyncio.TimeoutError:
+        await _flush(final=True)
+        err = ("⏱ <b>Timeout</b> — task &gt;120s.\n<b>Goal:</b> "
+               + html.escape(goal[:120]) + "\n\n<i>Usa il pannello web.</i>")
+        if msg_id: await _tg_edit(chat_id, msg_id, err, keyboard=_MAIN_KB)
+        else: await _tg_reply(chat_id, err)
+    except Exception as exc:
+        await _flush(final=True)
+        err = "❌ <b>Errore</b>\n<code>" + html.escape(str(exc)[:300]) + "</code>"
+        if msg_id: await _tg_edit(chat_id, msg_id, err, keyboard=_MAIN_KB)
+        else: await _tg_reply(chat_id, err)
+
+
+async def _cmd_autofix(chat_id: int, hint: str = "") -> None:
+    """Comando /autofix — legge errori dai log backend, genera patch via AI, pusha su GitHub.
+
+    Flusso:
+      1. GET /api/telegram/logs?level=ERROR  — raccoglie ultimi errori
+      2. AI loop con streaming (on_step) — analizza e genera patch
+      3. Parsa blocco ```autofix\nFILE: path\n---\ncontent``` dall'output AI
+      4. Git Data API blob->tree->commit->PATCH ref — push automatico
+      5. Riporta commit SHA al chat + link GitHub
+
+    Env vars Railway: GITHUB_TOKEN (gia' presente), GITHUB_REPO, GITHUB_BRANCH.
+    """
+    import httpx, base64 as _b64, json as _json
+    await _tg_typing(chat_id, "upload_document")
+
+    msg_id = await _tg_send(
+        chat_id,
+        "🔧 <b>AutoFix avviato</b>\n\n"
+        + (f"<i>Hint: {html.escape(hint[:100])}</i>\n\n" if hint else "")
+        + "⏳ <i>Step 1/4 — Lettura log errori…</i>",
+    )
+
+    async def _edit(text: str, final: bool = False) -> None:
+        if msg_id:
+            await _tg_edit(chat_id, msg_id, text, keyboard=_MAIN_KB if final else None)
+
+    # ── Step 1: leggi errori dal log endpoint ─────────────────────────────────────────
+    railway_url = os.getenv("RAILWAY_URL","https://ai-production-4c06.up.railway.app").rstrip("/")
+    try:
+        async with httpx.AsyncClient(timeout=10.0) as c:
+            resp = await c.get(f"{railway_url}/api/telegram/logs",
+                               params={"level": "ERROR", "n": 30})
+            log_data = resp.json() if resp.status_code == 200 else {}
+    except Exception as e:
+        log_data = {}
+        _logger.warning("autofix: log fetch: %s", e)
+
+    records = log_data.get("records", [])
+
+    if not records and not hint:
+        await _edit(
+            "✅ <b>AutoFix</b>\n\n"
+            "🟢 Nessun errore nei log recenti!\n\n"
+            "<i>Sistema stabile. Usa <code>/autofix &lt;descrizione bug&gt;</code> "
+            "per fix su un errore specifico.</i>",
+            final=True,
+        )
+        return
+
+    log_lines = "\n".join(
+        f"[{r.get('level','?')}] {r.get('logger','?')}: {r.get('msg','')}"
+        for r in records[:15]
+    ) if records else f"(nessun errore nei log — hint: {hint})"
+
+    log_preview = "\n".join(
+        f"• [{r.get('level','?')}] {r.get('logger','?')}: {r.get('msg','')[:80]}"
+        for r in records[:5]
+    ) or f"<i>hint: {html.escape(hint[:100])}</i>"
+
+    await _edit(
+        "🔧 <b>AutoFix</b>\n\n"
+        "📋 <b>Errori trovati:</b>\n" + log_preview
+        + "\n\n⏳ <i>Step 2/4 — Analisi AI in corso…</i>",
+    )
+
+    # ── Step 2: AI loop genera patch ─────────────────────────────────────────────────────
+    BT3 = "```"  # triple backtick — non usare literal per evitare syntax issues
+    goal = (
+        "Sei un senior engineer. Analizza questi errori dal log backend Python "
+        "e genera un patch preciso per risolvere il problema principale.\n\n"
+        "LOG ERRORI:\n" + log_lines[:2000]
+        + (f"\n\nHINT UTENTE: {hint}" if hint else "")
+        + "\n\n"
+        "FORMATO RISPOSTA RICHIESTO (tassativo):\n"
+        + BT3 + "autofix\n"
+        + "FILE: backend/api/<filename>.py\n"
+        + "---\n"
+        + "<contenuto completo del file modificato>\n"
+        + BT3 + "\n\n"
+        "Regole:\n"
+        "1. Scrivi SOLO il blocco con FILE: e contenuto completo (non un diff)\n"
+        "2. Per piu' file includi un blocco per file\n"
+        "3. Se non riesci a determinare il file, scrivi FILE: UNKNOWN e spiega"
+    )
+    context = f"Backend: {railway_url}  Repo: {os.getenv('GITHUB_REPO','Baida98/AI')}"
+
+    _buf: list[str] = []
+    _last: list[float] = [0.0]
+
+    async def _on_step(event: dict) -> None:
+        if event.get("action") == "text_chunk":
+            tok = event.get("token", "")
+            if tok:
+                _buf.append(tok)
+                now = time.monotonic()
+                if now - _last[0] > 2.0:
+                    preview = "".join(_buf).strip()[-300:]
+                    await _edit(
+                        "🔧 <b>AutoFix</b> — Step 2/4 AI analizza…\n\n"
+                        "<code>" + html.escape(preview) + "</code>\n\n⏳"
+                    )
+                    _last[0] = now
+
+    try:
+        from agents.unified_loop import UnifiedAgentLoop
+        from api.state import _get_ai_client, _get_mem_manager_async, _get_executor, _get_planner
+        client   = _get_ai_client()
+        memory   = await _get_mem_manager_async()
+        executor = _get_executor()
+        planner  = _get_planner()
+        try:
+            from agents.critic            import Critic
+            from agents.response_verifier import ResponseVerifier
+            critic   = Critic(llm_client=client)
+            verifier = ResponseVerifier()
+        except Exception:
+            critic = verifier = None
+        loop = UnifiedAgentLoop(
+            llm_client=client, critic=critic, verifier=verifier,
+            memory=memory, executor=executor, planner=planner,
+        )
+        result = await asyncio.wait_for(
+            loop.run(goal=goal, context=context, max_steps=5, on_step=_on_step),
+            timeout=150.0,
+        )
+        ai_output = result.get("output", "") if isinstance(result, dict) else str(result)
+    except asyncio.TimeoutError:
+        await _edit("⏱ <b>AutoFix timeout</b> — AI non ha risposto in 150s.\n\n"
+                    "<i>Riprova con un hint più specifico.</i>", final=True)
+        return
+    except Exception as exc:
+        await _edit("❌ <b>AutoFix — errore AI</b>\n<code>"
+                    + html.escape(str(exc)[:300]) + "</code>", final=True)
+        return
+
+    # ── Step 3: parsa blocco autofix dall'output AI ───────────────────────────────────
+    await _edit(
+        "🔧 <b>AutoFix</b>\n\n⏳ <i>Step 3/4 — Parsing patch…</i>\n\n"
+        "<code>" + html.escape(ai_output.strip()[-300:]) + "</code>"
+    )
+
+    import re as _re
+    BLOCK_RE = _re.compile(
+        r"```autofix\s*\nFILE:\s*(\S+)\s*\n---\s*\n([\s\S]*?)```",
+        _re.MULTILINE,
+    )
+    patches: list[tuple[str, str]] = [
+        (m.group(1).strip(), m.group(2))
+        for m in BLOCK_RE.finditer(ai_output)
+        if m.group(1).strip() not in ("", "UNKNOWN") and m.group(2).strip()
+    ]
+
+    if not patches:
+        await _edit(
+            "⚠️ <b>AutoFix</b> — nessuna patch parsata\n\n"
+            "<b>Output AI:</b>\n<code>" + html.escape(ai_output.strip()[:600]) + "</code>\n\n"
+            "<i>L'AI non ha prodotto un blocco autofix valido.\n"
+            "Prova: <code>/autofix descrizione precisa del bug</code></i>",
+            final=True,
+        )
+        return
+
+    # ── Step 4: push su GitHub via Git Data API ─────────────────────────────────────────
+    gh_token  = os.getenv("GITHUB_TOKEN", "")
+    gh_repo   = os.getenv("GITHUB_REPO",   "Baida98/AI")
+    gh_branch = os.getenv("GITHUB_BRANCH", "main")
+
+    if not gh_token:
+        await _edit(
+            "❌ <b>AutoFix</b> — GITHUB_TOKEN non configurato\n\n"
+            "<i>Aggiungi GITHUB_TOKEN nelle Railway env vars.</i>",
+            final=True,
+        )
+        return
+
+    await _edit(
+        "🔧 <b>AutoFix</b>\n\n"
+        f"⏳ <i>Step 4/4 — Push {len(patches)} file su GitHub…</i>\n\n"
+        + "\n".join(f"• <code>{p[0]}</code>" for p in patches[:6])
+    )
+
+    gh_hdr = {
+        "Authorization": f"token {gh_token}",
+        "Accept": "application/vnd.github.v3+json",
+        "Content-Type": "application/json",
+        "User-Agent": "agente-ai-autofix",
+    }
+    gh_base = f"https://api.github.com/repos/{gh_repo}"
+
+    try:
+        async with httpx.AsyncClient(timeout=20.0) as c:
+            r = await c.get(f"{gh_base}/git/refs/heads/{gh_branch}", headers=gh_hdr)
+            r.raise_for_status()
+            h_sha = r.json()["object"]["sha"]
+
+            r = await c.get(f"{gh_base}/git/commits/{h_sha}", headers=gh_hdr)
+            r.raise_for_status()
+            t_sha = r.json()["tree"]["sha"]
+
+            tree_items = []
+            for fpath, content in patches:
+                b64 = _b64.b64encode(content.encode()).decode()
+                r = await c.post(f"{gh_base}/git/blobs", headers=gh_hdr,
+                                 json={"content": b64, "encoding": "base64"})
+                r.raise_for_status()
+                tree_items.append({"path": fpath, "mode": "100644",
+                                   "type": "blob", "sha": r.json()["sha"]})
+
+            r = await c.post(f"{gh_base}/git/trees", headers=gh_hdr,
+                             json={"base_tree": t_sha, "tree": tree_items})
+            r.raise_for_status()
+            new_t = r.json()["sha"]
+
+            err_summary = ("; ".join(rc.get("msg","")[:60] for rc in records[:2])
+                           or hint[:60] or "autofix via /autofix command")
+            commit_msg = (
+                f"fix(autofix): {err_summary}\n\n"
+                f"Generato da /autofix — {len(patches)} file patchati\n"
+                + "Patch: " + ", ".join(p[0] for p in patches)
+            )
+            r = await c.post(f"{gh_base}/git/commits", headers=gh_hdr,
+                             json={"message": commit_msg, "tree": new_t, "parents": [h_sha]})
+            r.raise_for_status()
+            c_sha = r.json()["sha"]
+
+            r = await c.patch(f"{gh_base}/git/refs/heads/{gh_branch}", headers=gh_hdr,
+                              json={"sha": c_sha, "force": False})
+            r.raise_for_status()
+
+        files_list = "\n".join(f"• <code>{p[0]}</code>" for p in patches[:6])
+        await _edit(
+            "✅ <b>AutoFix completato!</b>\n\n"
+            f"<b>Commit:</b> <code>{c_sha[:10]}</code>\n"
+            f"<b>Branch:</b> <code>{gh_branch}</code>\n"
+            f"<b>File patchati:</b>\n{files_list}\n\n"
+            "U0001f680 <b>Railway deploy:</b> avviato automaticamente\n"
+            f"U0001f517 <a href=\"https://github.com/{gh_repo}/commit/{c_sha}\">Vedi commit</a>",
+            final=True,
+        )
+        _logger.info("autofix: pushed %s — %d files", c_sha[:10], len(patches))
+
+    except Exception as exc:
+        await _edit(
+            "❌ <b>AutoFix — push GitHub fallito</b>\n<code>"
+            + html.escape(str(exc)[:400]) + "</code>\n\n"
+            "<i>Verifica GITHUB_TOKEN nelle Railway env vars.</i>",
+            final=True,
+        )
+        _logger.error("autofix: push failed: %s", exc)
+
+
+async def _cmd_nota(chat_id: int, text: str) -> None:
+    """Salva nota rapida nella memoria persistente dell'agente."""
+    goal = (
+        f"Salva questa nota nella tua memoria persistente usando il tool remember: "
+        f"«{text}». Poi confermami con '✅ Nota salvata' e ripeti il testo della nota."
+    )
+    await _cmd_do(chat_id, goal)
+
+
+async def _cmd_cerca(chat_id: int, query: str) -> None:
+    """Ricerca web + sintesi AI in italiano."""
+    goal = (
+        f"Cerca su web: {query}. "
+        "Usa web_search e sintetizza i risultati più rilevanti in 4-5 bullet points concisi "
+        "in italiano. Per ogni punto includi la fonte (dominio) tra parentesi."
+    )
+    await _cmd_do(chat_id, goal)
+
+
+async def _cmd_meteo(chat_id: int, city: str) -> None:
+    """Meteo per città specifica via tool get_weather."""
+    goal = (
+        f"Usa il tool get_weather per {city} e dimmi: temperatura attuale, "
+        "condizioni meteo, umidità, previsioni per le prossime ore. Risposta concisa in italiano."
+    )
+    await _cmd_do(chat_id, goal)
+
+
+async def _cmd_riepilogo(chat_id: int) -> None:
+    """Briefing completo: task recenti + deploy + score + prossimi passi.
+    
+    GAP-TGB: usa benchmark_handler.get_smart_summary per briefing strutturato
+    con analisi gap da ultimo report. Fallback: agent-loop se import fallisce.
+    """
+    try:
+        from .benchmark_handler import get_smart_summary as _gsummary
+        text = await _gsummary(chat_id)
+        await _tg_reply(chat_id, text, keyboard=_BENCH_ACTION_KB)
+    except Exception as _exc:
+        _logger.debug("benchmark_handler fallback: %s", _exc)
+        goal = (
+            "Dammi un briefing completo dello stato attuale come assistente personale. "
+            "Struttura ESATTA con questi header ## obbligatori:\n"
+            "## 📋 Task recenti (usa recall per recuperare gli ultimi 5)\n"
+            "## 🚀 Deploy status (CF Pages + Railway + HF Space — dati reali via tool)\n"
+            "## 📊 Score AI (ultimo benchmark disponibile)\n"
+            "## ⚠️ Problemi aperti (errori, timeout, regressioni)\n"
+            "## ✅ Prossimi passi (3 priorità concrete)\n"
+            "Usa i tool per dati reali — mai inventare status."
+        )
+        await _cmd_do(chat_id, goal)
+
+
+async def _cmd_scan_now(chat_id: int) -> None:
+    """Health-check via health_full() — AI + Supabase + Telegram."""
+    await _tg_reply(chat_id, "🔍 <b>Scan in corso…</b>")
+    try:
+        from .providers import health_full
+        h  = await health_full()
+        ai = h.get("ai",       {})
+        sb = h.get("supabase", {})
+        tg = h.get("telegram", {})
+        bk = h.get("backend",  {})
+        ai_ok  = "✅" if ai.get("ok") else "❌"
+        sb_ok  = "✅" if sb.get("ok") else "❌"
+        tg_ok  = "✅" if tg.get("ok") else "❌"
+        over   = "✅" if h.get("ok")  else "⚠️"
+        sb_msg = "ok" if sb.get("ok") else str(sb.get("error", "?"))[:40]
+        tg_msg = ("@" + str(tg.get("username", ""))) if tg.get("username") else str(tg.get("error", "?"))[:40]
+        avail  = str(ai.get("available", 0)) + "/" + str(ai.get("total", 0))
+        best   = str(ai.get("best", "?"))
+        ntasks = str(bk.get("active_tasks", 0))
+        ms_str = str(h.get("elapsed_ms", "?"))
+        st_str = str(h.get("status", "?"))
+        parts  = [
+            over + " <b>Health Check</b> — " + st_str,
+            "",
+            ai_ok + " <b>AI</b> — " + avail + " provider | best: " + best,
+            sb_ok + " <b>Supabase</b> — " + sb_msg,
+            tg_ok + " <b>Telegram</b> — " + tg_msg,
+            "📦 Task attivi: " + ntasks + "  🕒 " + ms_str + "ms",
+        ]
+        await _tg_reply(chat_id, "\n".join(parts), keyboard=_MAIN_KB)
+    except Exception as exc:
+        await _tg_reply(
+            chat_id,
+            "❌ <b>Scan errore</b>\n<code>" + html.escape(str(exc)[:300]) + "</code>",
+        )
+
+
+async def _cmd_coord(chat_id: int) -> None:
+    """🔗 /coord — sessioni agent-coord attive e file claimati (sola lettura).
+
+    Legge la tabella Supabase 'agent_tasks' dove le sessioni agent-coord.mjs
+    persistono con goal='__session__<uuid>'. TTL = 5 minuti senza heartbeat.
+    Non modifica nulla — pura lettura. Non interferisce con il lavoro agente.
+    """
+    import httpx as _hx_c, time as _tc, json as _jc
+    SB_URL = os.getenv("SUPABASE_URL", "").rstrip("/")
+    SB_KEY = os.getenv("SUPABASE_KEY", "")
+    if not SB_KEY:
+        await _tg_reply(chat_id, "⚠️ <b>SUPABASE_KEY</b> non configurata su Railway.")
+        return
+    await _tg_reply(chat_id, "🔗 <b>Agent Coord</b> — lettura sessioni…")
+    try:
+        async with _hx_c.AsyncClient(timeout=8.0) as _c:
+            r = await _c.get(
+                f"{SB_URL}/rest/v1/agent_tasks",
+                params={"goal": "ilike.*__session__*", "select": "goal,context,updated_at"},
+                headers={
+                    "apikey": SB_KEY,
+                    "Authorization": f"Bearer {SB_KEY}",
+                    "Content-Type": "application/json",
+                },
+            )
+        if not r.is_success:
+            await _tg_reply(chat_id, f"❌ Supabase {r.status_code}: {r.text[:200]}")
+            return
+        rows = r.json() or []
+    except Exception as exc:
+        await _tg_reply(chat_id,
+            "❌ <code>" + html.escape(str(exc)[:200]) + "</code>")
+        return
+
+    SESSION_TTL_MS = 5 * 60 * 1000  # 5 minuti senza heartbeat = morta
+    now_ms = int(_tc.time() * 1000)
+    active, stale = [], []
+    for row in rows:
+        try:
+            ctx = _jc.loads(row.get("context") or "{}")
+        except Exception:
+            continue
+        hb    = int(ctx.get("lastHeartbeat", 0))
+        age_ms = now_ms - hb
+        entry  = {
+            "name":   ctx.get("sessionName", "?"),
+            "sprint": ctx.get("sprint", "—"),
+            "files":  ctx.get("claimedFiles", []),
+            "age_ms": age_ms,
+        }
+        (active if age_ms < SESSION_TTL_MS else stale).append(entry)
+
+    if not rows:
+        await _tg_reply(chat_id,
+            "🔗 <b>Agent Coord</b>\n\n"
+            "ℹ️ Nessuna sessione registrata.\n<i>Tutti i file sono liberi.</i>",
+            keyboard=_BACK_KB)
+        return
+
+    def _age_str(ms: int) -> str:
+        s = ms // 1000
+        return f"{s // 60}m{s % 60:02d}s" if s >= 60 else f"{s}s"
+
+    out = ["🔗 <b>Agent Coord</b>", ""]
+    if active:
+        out.append(f"✅ <b>Attive ({len(active)})</b>")
+        for s in active:
+            fnames = ", ".join(
+                "<code>" + html.escape(f.split("/")[-1]) + "</code>"
+                for f in s["files"]
+            ) or "<i>nessun file</i>"
+            out.append(
+                f"  <b>{html.escape(s['name'])}</b> "
+                f"[{html.escape(s['sprint'])}] · {_age_str(s['age_ms'])} fa"
+            )
+            out.append(f"  📎 {fnames}")
+    else:
+        out.append("✅ Nessuna sessione attiva — file liberi")
+    if stale:
+        out.append("")
+        out.append(f"⚫ <b>Inattive &gt;5min ({len(stale)})</b>")
+        for s in stale:
+            out.append(f"  {html.escape(s['name'])} · {_age_str(s['age_ms'])} fa")
+
+    await _tg_reply(chat_id, "\n".join(out), keyboard=_BACK_KB)
+
+
+async def _cmd_git(chat_id: int, n: int = 5) -> None:
+    """🔀 /git [n] — ultimi N commit su main con SHA, messaggio, autore, eta e link diff.
+
+    Chiama GitHub API (GITHUB_TOKEN Railway). Default: ultimi 5 commit.
+    Max: 10. Timeout 6s. Silent fail se GITHUB_TOKEN assente.
+    """
+    import httpx as _hx_git2, datetime as _dt2
+    _gh_token = os.getenv("GITHUB_TOKEN", "").strip()
+    _gh_repo  = os.getenv("GITHUB_REPO", "Baida98/AI").strip()
+    if not _gh_token:
+        await _tg_reply(chat_id,
+            "⚠️ <b>GITHUB_TOKEN</b> non configurato su Railway — /git non disponibile.")
+        return
+    n = max(1, min(n, 10))
+    await _tg_reply(chat_id, f"🔀 <b>Git log</b> — ultimi {n} commit…")
+    try:
+        async with _hx_git2.AsyncClient(timeout=6.0) as _gc:
+            _gr = await _gc.get(
+                f"https://api.github.com/repos/{_gh_repo}/commits",
+                headers={"Authorization": f"Bearer {_gh_token}", "User-Agent": "agente-ai"},
+                params={"sha": "main", "per_page": str(n)},
+            )
+        if _gr.status_code != 200:
+            await _tg_reply(chat_id,
+                f"❌ GitHub API {_gr.status_code}: {html.escape(_gr.text[:200])}")
+            return
+        commits = _gr.json() or []
+    except Exception as exc:
+        await _tg_reply(chat_id,
+            "❌ <code>" + html.escape(str(exc)[:200]) + "</code>")
+        return
+
+    if not commits:
+        await _tg_reply(chat_id, "ℹ️ Nessun commit trovato.", keyboard=_BACK_KB)
+        return
+
+    _now_utc = _dt2.datetime.now(_dt2.timezone.utc)
+
+    def _age(iso: str) -> str:
+        try:
+            _ts   = _dt2.datetime.fromisoformat(iso.replace("Z", "+00:00"))
+            _secs = int((_now_utc - _ts).total_seconds())
+            if _secs < 3600:   return f"{_secs // 60}m fa"
+            if _secs < 86400:  return f"{_secs // 3600}h fa"
+            if _secs < 604800: return f"{_secs // 86400}g fa"
+            return _ts.strftime("%d/%m")
+        except Exception:
+            return "?"
+
+    lines = [f"🔀 <b>Git log — main</b> ({_gh_repo})\n"]
+    for c in commits:
+        _sha     = (c.get("sha") or "")[:7]
+        _commit  = c.get("commit") or {}
+        _msg_raw = (_commit.get("message") or "").split("\n")[0][:52]
+        _msg     = html.escape(_msg_raw)
+        _author  = html.escape((_commit.get("author") or {}).get("name", "?")[:18])
+        _date    = (_commit.get("committer") or {}).get("date", "")
+        _when    = _age(_date)
+        _url     = f"https://github.com/{_gh_repo}/commit/{c.get('sha','')}"
+        lines.append(
+            f"<code>{html.escape(_sha)}</code> {_msg}\n"
+            f"  <i>{_author} · {_when}</i>  "
+            f'<a href="{_url}">diff →</a>'
+        )
+
+    await _tg_reply(chat_id, "\n".join(lines), keyboard=_BACK_KB)
+
+async def _cmd_telemetry(chat_id: int) -> None:
+    """📡 Metriche runtime live: /api/telemetry + /debug/timing da Railway."""
+    import httpx as _hx_t
+    rw_url = os.getenv("RAILWAY_URL", "https://ai-production-4c06.up.railway.app").rstrip("/")
+    await _tg_reply(chat_id, "⏳ <b>Telemetria</b> — interrogo Railway…")
+    try:
+        async with _hx_t.AsyncClient(timeout=8.0) as _c:
+            tel_r, tim_r = await asyncio.gather(
+                _c.get(f"{rw_url}/api/telemetry"),
+                _c.get(f"{rw_url}/debug/timing"),
+                return_exceptions=True,
+            )
+    except Exception as e:
+        await _tg_reply(chat_id, f"❌ Railway non raggiungibile\n<code>{html.escape(str(e)[:120])}</code>", keyboard=_BACK_KB)
+        return
+
+    tel_d = tel_r.json() if not isinstance(tel_r, Exception) and tel_r.status_code == 200 else {}
+    tim_d = tim_r.json() if not isinstance(tim_r, Exception) and tim_r.status_code == 200 else {}
+
+    msg = "📡 <b>Telemetria Runtime</b>\n\n"
+    timing = tel_d.get("timing", {})
+    if timing:
+        msg += "<b>⏱ Latenze per fase (avg / p90 / n):</b>\n<code>"
+        for phase, v in list(timing.items())[:10]:
+            avg_v = v.get("avg", 0); p90_v = v.get("p90", 0); n_v = v.get("n", 0)
+            icon  = "🟢" if avg_v < 3000 else "🟡" if avg_v < 10000 else "🔴"
+            msg  += f"{icon} {phase[:18]:<18} {avg_v:>7}ms  p90:{p90_v:>7}ms  ×{n_v}\n"
+        msg += "</code>\n"
+    else:
+        msg += "<i>⚠️ Nessun dato timing — backend idle o prima run.</i>\n"
+    repair = tel_d.get("repair", tim_d.get("repair_stats", {}))
+    if repair:
+        msg += "\n<b>🔧 Quality & Repair:</b>\n<code>"
+        for k, v in list(repair.items())[:10]:
+            msg += f"  {k[:22]:<22} {v:>6}\n"
+        msg += "</code>\n"
+    ts_d = tim_d.get("timing_stats", {})
+    if ts_d:
+        msg += "\n<b>📊 Breakdown /debug/timing:</b>\n<code>"
+        for label, v in list(ts_d.items())[:8]:
+            avg_v = v.get("avg") or 0; icon = "🟢" if avg_v < 3000 else "🟡" if avg_v < 10000 else "🔴"
+            msg  += f"{icon} {label[:18]:<18} {avg_v:>8}ms  ×{v.get('count',0)}\n"
+        msg += "</code>"
+    if len(msg) > 4000:
+        msg = msg[:4000] + "…"
+    await _tg_reply(chat_id, msg, keyboard=_BACK_KB)
+
+async def _cmd_score(chat_id: int) -> None:
+    """🏆 Score card dettagliata — chart + ranking 4 competitor + nodes + gaps + runtime telemetry."""
+    import httpx as _hx_sc, base64 as _b64_sc, json as _j_sc, urllib.parse as _ul_sc
+    gh_token = os.getenv("GITHUB_TOKEN", "").strip()
+    rw_url   = os.getenv("RAILWAY_URL", "https://ai-production-4c06.up.railway.app").rstrip("/")
+    await _tg_reply(chat_id, "⏳ <b>Score</b> — carico report + metriche runtime…")
+
+    report: dict | None = None
+    if gh_token:
+        try:
+            async with _hx_sc.AsyncClient(timeout=8.0) as _c:
+                _r = await _c.get(
+                    "https://api.github.com/repos/Baida98/AI/contents/benchmark-report.json?ref=main",
+                    headers={"Authorization": f"Bearer {gh_token}",
+                             "Accept": "application/vnd.github.v3+json",
+                             "User-Agent": "AgenteAI-Bot"},
+                )
+                if _r.status_code == 200:
+                    report = _j_sc.loads(_b64_sc.b64decode(_r.json()["content"]).decode())
+        except Exception as _e:
+            _logger.warning("cmd_score fetch: %s", _e)
+
+    if not report:
+        await _tg_reply(chat_id,
+            "❌ <b>Score</b> — benchmark-report.json non trovato.\n"
+            "Avvia prima <code>/bench</code> per generare i dati.", keyboard=_BENCH_ACTION_KB)
+        return
+
+    s      = report.get("summary", {})
+    tasks  = report.get("tasks", [])
+    gaps   = report.get("gapCards", [])
+    nodes  = report.get("orchestrationNodeMap", {})
+    ts     = (report.get("timestamp") or "")[:16].replace("T", " ")
+    seed   = report.get("seed", "?")
+    ver    = report.get("version", "?")
+    replay = report.get("replayCli", f"node benchmark-extended.mjs --seed {seed}")
+    mft    = s.get("mft")
+    gap_cnt = s.get("gapCount", len(gaps))
+    verdict = s.get("verdict", "").replace("_", " ")
+    avg_ai  = s.get("avgScore",  0)
+    avg_rpl = s.get("avgReplit", 57.9)
+    avg_cur = s.get("avgCursor", 64.1)
+    avg_dev = s.get("avgDevin",  70.1)
+    avg_mns = s.get("avgManus",  71.2)
+    w_rpl   = s.get("wins_replit", "?")
+    w_dev   = s.get("wins_devin",  "?")
+    w_mns   = s.get("wins_manus",  "?")
+
+    # Runtime telemetria da Railway (best-effort)
+    rt_timing: dict = {}
+    rt_repair: dict = {}
+    try:
+        async with _hx_sc.AsyncClient(timeout=5.0) as _c:
+            _tr = await _c.get(f"{rw_url}/api/telemetry")
+            if _tr.status_code == 200:
+                _td = _tr.json()
+                rt_timing = _td.get("timing", {})
+                rt_repair = _td.get("repair", {})
+    except Exception:
+        pass
+
+    # ── Chart per categoria ───────────────────────────────────────
+    cat_map: dict = {}
+    for t in tasks:
+        cat = (t.get("cat") or "other").replace("_", " ")[:14]
+        cat_map.setdefault(cat, []).append(float(t.get("score", 0)))
+    labels_ = list(cat_map.keys())
+    scores_ = [round(sum(v)/len(v)) for v in cat_map.values()]
+    colors_ = ["#4CAF50" if sc >= avg_rpl else "#FF9800" if sc >= 50 else "#F44336" for sc in scores_]
+    chart_cfg = {
+        "type": "horizontalBar",
+        "data": {"labels": labels_, "datasets": [
+            {"label": "Agente AI", "data": scores_, "backgroundColor": colors_, "borderWidth": 1},
+            {"label": f"Replit {avg_rpl}",
+             "data": [avg_rpl]*len(labels_), "type": "line",
+             "borderColor": "#2196F3", "borderDash": [5,3], "pointRadius": 0, "fill": False, "borderWidth": 2},
+            {"label": f"Devin {avg_dev}",
+             "data": [avg_dev]*len(labels_), "type": "line",
+             "borderColor": "#FF9800", "borderDash": [5,3], "pointRadius": 0, "fill": False, "borderWidth": 2},
+            {"label": f"Manus {avg_mns}",
+             "data": [avg_mns]*len(labels_), "type": "line",
+             "borderColor": "#9C27B0", "borderDash": [5,3], "pointRadius": 0, "fill": False, "borderWidth": 2},
+        ]},
+        "options": {
+            "title": {"display": True, "text": f"Agente AI {avg_ai}% | Replit {avg_rpl}% | Devin {avg_dev}% | Manus {avg_mns}%"},
+            "scales": {"xAxes": [{"ticks": {"min": 0, "max": 100, "stepSize": 20}}]},
+            "legend": {"display": True, "position": "bottom"},
+            "plugins": {"datalabels": {"display": False}},
+        },
+    }
+    chart_url = ("https://quickchart.io/chart?c=" +
+                 _ul_sc.quote(_j_sc.dumps(chart_cfg, separators=(",",":"))) +
+                 "&width=760&height=440&backgroundColor=white")
+
+    # ── Caption messaggio 1 (foto, max 1024) ─────────────────────
+    bar_g   = "█" * round(avg_ai/10) + "░" * (10 - round(avg_ai/10))
+    d_rpl   = round(avg_ai - avg_rpl);  s_rpl = ("+" if d_rpl >= 0 else "") + str(d_rpl)
+    d_dev   = round(avg_ai - avg_dev);  s_dev = ("+" if d_dev >= 0 else "") + str(d_dev)
+    d_mns   = round(avg_ai - avg_mns);  s_mns = ("+" if d_mns >= 0 else "") + str(d_mns)
+    d_cur   = round(avg_ai - avg_cur);  s_cur = ("+" if d_cur >= 0 else "") + str(d_cur)
+    caption  = f"🏆 <b>Score</b> — {ts} UTC  <code>v{ver}</code>\n"
+    caption += f"<code>{bar_g}</code> <b>{avg_ai}%</b>  {verdict}\n\n"
+    caption += f"<code>{'Modello':<10} {'Score':>5}  {'Δ':>4}  Wins</code>\n"
+    caption += f"<code>{'Agente AI':<10} {str(avg_ai)+'%':>5}  {'─':>4}    ─</code>\n"
+    caption += f"<code>{'Replit':<10} {str(avg_rpl)+'%':>5}  {s_rpl:>4}  {w_rpl}/10</code>\n"
+    caption += f"<code>{'Cursor':<10} {str(avg_cur)+'%':>5}  {s_cur:>4}    ─</code>\n"
+    caption += f"<code>{'Devin':<10} {str(avg_dev)+'%':>5}  {s_dev:>4}  {w_dev}/10</code>\n"
+    caption += f"<code>{'Manus':<10} {str(avg_mns)+'%':>5}  {s_mns:>4}  {w_mns}/10</code>\n\n"
+    for cat, vals in sorted(cat_map.items(), key=lambda x: -sum(x[1])/len(x[1])):
+        sc   = round(sum(vals)/len(vals))
+        bar  = "█" * round(sc/10) + "░" * (10 - round(sc/10))
+        d    = round(sc - avg_rpl)
+        vs   = ("+" if d >= 0 else "") + str(d)
+        icon = "✅" if sc >= avg_rpl else "⚠️" if sc >= 50 else "❌"
+        line = f"<code>{cat[:12]:<12} {bar} {sc:>3}% {vs:>4}</code> {icon}\n"
+        if len(caption) + len(line) < 1010:
+            caption += line
+    caption += f"\n🎲 Seed <code>{seed}</code>  MFT <b>{mft}s</b>  Gaps: <b>{gap_cnt}</b>"
+    await _tg_photo(chat_id, chart_url, caption=caption[:1024], keyboard=_BENCH_ACTION_KB)
+
+    # ── Messaggio 2 — dettaglio completo ─────────────────────────
+    det = "📊 <b>Score — Dettaglio</b>\n\n"
+
+    # Orchestration nodes
+    NODE_ICONS = {"planner":"🧠","executor":"⚙️","reasoner":"🔬",
+                  "recovery_manager":"🛡","robustness_layer":"🔒","memory_module":"💾"}
+    if nodes:
+        det += "<b>⚡ Orchestration Nodes:</b>\n<code>"
+        for nk, nv in nodes.items():
+            sr  = str(nv.get("success_rate", "?"))
+            lat = nv.get("avg_latency_s")
+            ntsk = nv.get("tasks", "")
+            try:
+                icon = "✅" if float(sr.rstrip("%")) >= 60 else "⚠️" if float(sr.rstrip("%")) >= 30 else "❌"
+            except Exception:
+                icon = "❓"
+            lat_s  = f"  {lat}s" if lat is not None else ""
+            tsk_s  = f"  ×{ntsk}" if ntsk else ""
+            det   += f"{NODE_ICONS.get(nk,'•')} {nk[:20]:<20} {icon} {sr:>5}{lat_s}{tsk_s}\n"
+        det += "</code>\n"
+
+    # Runtime telemetria (live da Railway)
+    if rt_timing:
+        det += "\n<b>⏱ Runtime Latenze (live):</b>\n<code>"
+        for phase, v in list(rt_timing.items())[:8]:
+            avg_v = v.get("avg", 0); p90_v = v.get("p90", 0); n_v = v.get("n", 0)
+            icon  = "🟢" if avg_v < 3000 else "🟡" if avg_v < 10000 else "🔴"
+            det  += f"{icon} {phase[:16]:<16} avg:{avg_v:>7}ms  p90:{p90_v:>7}ms  ×{n_v}\n"
+        det += "</code>\n"
+        if rt_repair:
+            det += "<b>🔧 Quality counters:</b>\n<code>"
+            for k, v in list(rt_repair.items())[:6]:
+                det += f"  {k[:20]:<20} {v}\n"
+            det += "</code>\n"
+    else:
+        det += "<i>ℹ️ Telemetria runtime non disponibile (Railway idle)</i>\n"
+
+    # Top 3 best + Top 3 worst
+    sorted_tasks = sorted([t for t in tasks if t.get("score") is not None], key=lambda t: -t["score"])
+    if sorted_tasks:
+        det += "\n<b>🥇 Migliori task:</b>\n"
+        for t in sorted_tasks[:3]:
+            ref_r = (t.get("ref") or {}).get("replit", avg_rpl)
+            d_    = round(t["score"] - ref_r)
+            ds_   = ("+" if d_ >= 0 else "") + str(d_)
+            ms_   = f"  {round(t['agentMs']/1000)}s" if t.get("agentMs") else ""
+            det  += f"  <code>{(t.get('id') or '?'):>3}</code> <b>{t['score']}%</b> ({ds_} vsRpl){ms_}\n"
+            det  += f"    <i>{(t.get('label') or '')[:60]}</i>\n"
+        det += "\n<b>⚠️ Task critici:</b>\n"
+        for t in sorted_tasks[-3:]:
+            ref_r = (t.get("ref") or {}).get("replit", avg_rpl)
+            ref_m = (t.get("ref") or {}).get("manus", avg_mns)
+            d_    = round(t["score"] - ref_r)
+            dm_   = round(t["score"] - ref_m)
+            ds_   = ("+" if d_ >= 0 else "") + str(d_)
+            dms_  = ("+" if dm_ >= 0 else "") + str(dm_)
+            det  += f"  <code>{(t.get('id') or '?'):>3}</code> <b>{t['score']}%</b>  vsRpl {ds_}  vsManus {dms_}\n"
+            det  += f"    <i>{(t.get('label') or '')[:60]}</i>\n"
+
+    # Gap cards top 3
+    if gaps:
+        det += "\n<b>🔥 Gap da correggere:</b>\n"
+        for g in gaps[:3]:
+            gicon = "🔴" if g.get("gravita") == "critical" else "🟡"
+            det  += f"{gicon} <b>{(g.get('modulo_coinvolto') or '').replace('_',' ')}</b> — {(g.get('causa_radice') or '')[:55]}\n"
+            det  += f"   Fix: <i>{(g.get('fix_immediato') or '')[:65]}</i>\n"
+            det  += f"   Atteso: <b>{(g.get('beneficio_atteso') or '')[:40]}</b>\n"
+
+    det += f"\n<code>{replay}</code>"
+    det += f"\n🌐 <a href=\"https://agente-ai.pages.dev\">Dashboard →</a>"
+
+    _TG_MAX = 4000
+    if len(det) <= _TG_MAX:
+        await _tg_reply(chat_id, det, keyboard=_BENCH_ACTION_KB)
+    else:
+        await _tg_reply(chat_id, det[:_TG_MAX])
+        await _tg_reply(chat_id, det[_TG_MAX:_TG_MAX*2][:_TG_MAX], keyboard=_BENCH_ACTION_KB)
+
+
+async def _cmd_bench(chat_id: int, mode: str = "default") -> None:
+    """📊 Benchmark via bench.yml (benchmark-extended.mjs) + quickchart.io.
+
+    GAP-TGB: workflow_dispatch su bench.yml — usa benchmark-extended.mjs
+    (20 categorie, seed canonico 1337, tutte le fix v5).
+    Risultati inviati via Telegram da ab-bench.mjs --notify al completamento.
+    """
+    gh_token = os.getenv("GITHUB_TOKEN", "").strip()
+
+    # ── Tenta fetch ultimo run completato da GitHub Actions artifact ─────────
+    last_report: dict | None = None
+    if gh_token:
+        try:
+            import httpx as _hx
+            async with _hx.AsyncClient(timeout=8.0) as _c:
+                _r = await _c.get(
+                    "https://api.github.com/repos/Baida98/AI/actions/workflows/bench.yml/runs"
+                    "?status=completed&per_page=1",
+                    headers={"Authorization": f"Bearer {gh_token}",
+                             "Accept": "application/vnd.github.v3+json",
+                             "User-Agent": "AgenteAI-Bot"},
+                )
+                if _r.status_code == 200:
+                    _runs = _r.json().get("workflow_runs", [])
+                    if _runs:
+                        last_report = {
+                            "run_id":    _runs[0]["id"],
+                            "run_url":   _runs[0]["html_url"],
+                            "conclusion":_runs[0].get("conclusion","?"),
+                            "updated":   _runs[0].get("updated_at",""),
+                        }
+        except Exception as _exc:
+            _logger.debug("bench fetch last run: %s", _exc)
+
+    # ── Trigger nuovo run via workflow_dispatch ───────────────────────────────
+    run_url = "https://github.com/Baida98/AI/actions/workflows/bench.yml"
+    if gh_token:
+        try:
+            import httpx as _hx
+            async with _hx.AsyncClient(timeout=10.0) as _c:
+                _r = await _c.post(
+                    "https://api.github.com/repos/Baida98/AI/actions/workflows/bench.yml/dispatches",
+                    json={"ref": "main", "inputs": {
+                        "mode": mode,
+                        "run_improve": "false",
+                        "force_update_baseline": "false",
+                    }},
+                    headers={"Authorization": f"Bearer {gh_token}",
+                             "Accept": "application/vnd.github.v3+json",
+                             "User-Agent": "AgenteAI-Bot"},
+                )
+                if _r.status_code == 204:
+                    _logger.info("[bench] workflow_dispatch OK (mode=%s)", mode)
+                    # Attendi 2s e leggi il run ID appena creato
+                    await asyncio.sleep(2.0)
+                    async with _hx.AsyncClient(timeout=8.0) as _c2:
+                        _r2 = await _c2.get(
+                            "https://api.github.com/repos/Baida98/AI/actions/workflows/"
+                            "bench.yml/runs?per_page=1",
+                            headers={"Authorization": f"Bearer {gh_token}",
+                                     "Accept": "application/vnd.github.v3+json",
+                                     "User-Agent": "AgenteAI-Bot"},
+                        )
+                        if _r2.status_code == 200:
+                            _rr = _r2.json().get("workflow_runs", [])
+                            if _rr:
+                                run_url = _rr[0]["html_url"]
+                else:
+                    _logger.warning("[bench] workflow_dispatch status=%d", _r.status_code)
+        except Exception as _exc:
+            _logger.warning("[bench] workflow_dispatch error: %s", _exc)
+
+    # ── Costruisci messaggio con quickchart dell'ultimo run (se disponibile) ──
+    _BENCH_CACHE[chat_id] = {"mode": mode, "run_url": run_url}
+
+    # ── Fetch benchmark-report.json dal repo per quickchart reale ──────────────
+    bench_report: dict | None = None
+    if gh_token:
+        try:
+            import httpx as _hx, base64 as _b64, json as _json
+            async with _hx.AsyncClient(timeout=8.0) as _c:
+                _br = await _c.get(
+                    "https://api.github.com/repos/Baida98/AI/contents/benchmark-report.json?ref=main",
+                    headers={"Authorization": f"Bearer {gh_token}",
+                             "Accept": "application/vnd.github.v3+json",
+                             "User-Agent": "AgenteAI-Bot"},
+                )
+                if _br.status_code == 200:
+                    _content = _b64.b64decode(_br.json()["content"]).decode()
+                    bench_report = _json.loads(_content)
+        except Exception as _exc:
+            _logger.debug("bench fetch benchmark-report.json: %s", _exc)
+
+    chart_url: str | None = None
+
+    def _build_quickchart(report: dict) -> str:
+        """Costruisce URL quickchart.io da benchmark-report.json."""
+        import json as _j, urllib.parse as _ul
+        tasks    = report.get("tasks", [])
+        summary  = report.get("summary", {})
+        avg_ai   = summary.get("avgScore", 0)
+        avg_rpl  = summary.get("avgReplit", 57.9)
+        avg_mns  = summary.get("avgManus",  71.2)
+        cat_map: dict[str, list[float]] = {}
+        for t in tasks:
+            cat = (t.get("cat") or "other").replace("_", " ")[:14]
+            cat_map.setdefault(cat, []).append(t.get("score", 0))
+        if not cat_map:
+            return ""
+        labels = list(cat_map.keys())
+        scores = [round(sum(v)/len(v)) for v in cat_map.values()]
+        colors = ["#4CAF50" if s >= avg_rpl else "#FF9800" if s >= 50 else "#F44336" for s in scores]
+        cfg = {
+            "type": "horizontalBar",
+            "data": {
+                "labels": labels,
+                "datasets": [
+                    {"label": "Agente AI", "data": scores,
+                     "backgroundColor": colors, "borderColor": colors, "borderWidth": 1},
+                    {"label": f"Replit {avg_rpl}",
+                     "data": [avg_rpl]*len(labels),
+                     "type": "line", "borderColor": "#2196F3", "borderDash": [5,3],
+                     "pointRadius": 0, "fill": False, "borderWidth": 2},
+                    {"label": f"Manus {avg_mns}",
+                     "data": [avg_mns]*len(labels),
+                     "type": "line", "borderColor": "#9C27B0", "borderDash": [5,3],
+                     "pointRadius": 0, "fill": False, "borderWidth": 2},
+                ],
+            },
+            "options": {
+                "title": {"display": True,
+                          "text": f"Agente AI {avg_ai}% | Replit {avg_rpl}% | Manus {avg_mns}%"},
+                "scales": {"xAxes": [{"ticks": {"min": 0, "max": 100, "stepSize": 20}}]},
+                "legend": {"display": True, "position": "bottom"},
+                "plugins": {"datalabels": {"display": False}},
+            },
+        }
+        return ("https://quickchart.io/chart?c=" +
+                _ul.quote(_j.dumps(cfg, separators=(",",":"))) +
+                "&width=720&height=420&backgroundColor=white")
+
+    if bench_report:
+        chart_url = _build_quickchart(bench_report)
+
+    summary    = (bench_report or {}).get("summary", {})
+    avg_ai     = summary.get("avgScore")
+    avg_rpl    = summary.get("avgReplit")
+    avg_mns    = summary.get("avgManus")
+    # ── Tabella ASCII con barre per caption Telegram ──────────────────────────
+    def _text_table_bench(report: dict, rpl: float) -> str:
+        tasks = report.get("tasks", [])
+        cat_map: dict[str, list[float]] = {}
+        for t in tasks:
+            cat = (t.get("cat") or "other").replace("_", " ")[:12]
+            cat_map.setdefault(cat, []).append(float(t.get("score", 0)))
+        if not cat_map:
+            return ""
+        rows = []
+        for cat, vals in sorted(cat_map.items(), key=lambda x: -sum(x[1]) / len(x[1])):
+            sc = round(sum(vals) / len(vals))
+            bar = "█" * round(sc / 10) + "░" * (10 - round(sc / 10))
+            delta_rpl = sc - rpl
+            vs = ("+" if delta_rpl >= 0 else "") + str(round(delta_rpl)) + "vsRpl"
+            rows.append(f"{cat:<12} {bar} {sc:>3}% {vs}")
+        return "\n".join(rows)
+
+    text_table = ""
+    if bench_report and avg_rpl is not None:
+        text_table = _text_table_bench(bench_report, float(avg_rpl))
+
+    score_line = ""
+    if avg_ai is not None:
+        score_line = (
+            f"\n📈 <b>Score:</b> AI <b>{avg_ai}%</b>"
+            + (f" | Replit {avg_rpl}%" if avg_rpl else "")
+            + (f" | Manus {avg_mns}%" if avg_mns else "")
+            + "\n"
+        )
+
+    def _build_bench_caption(header: str) -> str:
+        tbl = ("\n<code>" + text_table + "</code>") if text_table else ""
+        link = f'\n🔗 <a href="{html.escape(run_url)}">GitHub Actions</a>'
+        full = header + score_line + tbl + link
+        if len(full) > 1020 and text_table:
+            avail = max(0, 1020 - len(header) - len(score_line) - len(link) - 14)
+            tbl = "\n<code>" + text_table[:avail] + "…</code>"
+            full = header + score_line + tbl + link
+        return full[:1024]
+
+    if last_report:
+        _conclusion = last_report.get("conclusion", "?")
+        _em = "✅" if _conclusion == "success" else ("❌" if _conclusion == "failure" else "⚠️")
+        _upd = last_report.get("updated", "")[:16].replace("T", " ")
+        header = f"📊 <b>Benchmark avviato</b> — {_em} {_conclusion}\n🕐 {_upd} UTC"
+    else:
+        header = "📊 <b>Benchmark avviato</b> (benchmark-extended.mjs)"
+
+    caption = _build_bench_caption(header)
+
+    if chart_url:
+        await _tg_photo(chat_id, chart_url, caption=caption, keyboard=_BENCH_ACTION_KB)
+    else:
+        await _tg_reply(chat_id, caption, keyboard=_BENCH_ACTION_KB)
+
+
+
+# ── _cmd_improve — ciclo miglioramento: bench → gap → patch ─────────────────
+
+async def _cmd_improve(chat_id: int) -> None:
+    """⚙️ Ciclo di miglioramento: bench.yml con --improve → gap → patch automatica.
+
+    Triggera bench.yml con run_improve=true (benchmark-extended.mjs --improve).
+    Il ciclo: few-shot retry sui task falliti → identifica pattern di miglioramento
+    → genera regole → propone patch via notify Telegram.
+    """
+    gh_token = os.getenv("GITHUB_TOKEN", "").strip()
+
+    await _tg_reply(chat_id,
+        "⚙️ <b>Ciclo miglioramento avviato</b>\n\n"
+        "• Avvio <code>benchmark-extended.mjs --improve</code>\n"
+        "• Identifica gap · genera regole migliorate · propone patch\n"
+        "<i>Riceverai notifica Telegram al completamento (~10-25 min).</i>",
+        keyboard=_BACK_KB)
+
+    run_url = "https://github.com/Baida98/AI/actions/workflows/bench.yml"
+    if not gh_token:
+        await _tg_reply(chat_id,
+            "⚠️ GITHUB_TOKEN non configurato — impossibile avviare workflow.",
+            keyboard=_BACK_KB)
+        return
+
+    try:
+        import httpx as _hx
+        async with _hx.AsyncClient(timeout=10.0) as _c:
+            _r = await _c.post(
+                "https://api.github.com/repos/Baida98/AI/actions/workflows/bench.yml/dispatches",
+                json={"ref": "main", "inputs": {
+                    "mode": "default",
+                    "run_improve": "true",
+                    "force_update_baseline": "false",
+                }},
+                headers={"Authorization": f"Bearer {gh_token}",
+                         "Accept": "application/vnd.github.v3+json",
+                         "User-Agent": "AgenteAI-Bot"},
+            )
+            if _r.status_code == 204:
+                _logger.info("[improve] workflow_dispatch OK")
+                await asyncio.sleep(2.0)
+                async with _hx.AsyncClient(timeout=8.0) as _c2:
+                    _r2 = await _c2.get(
+                        "https://api.github.com/repos/Baida98/AI/actions/workflows/"
+                        "bench.yml/runs?per_page=1",
+                        headers={"Authorization": f"Bearer {gh_token}",
+                                 "Accept": "application/vnd.github.v3+json",
+                                 "User-Agent": "AgenteAI-Bot"},
+                    )
+                    if _r2.status_code == 200:
+                        _rr = _r2.json().get("workflow_runs", [])
+                        if _rr:
+                            run_url = _rr[0]["html_url"]
+                await _tg_reply(chat_id,
+                    f"✅ Ciclo miglioramento avviato\n"
+                    f'🔗 <a href="{html.escape(run_url)}">Segui su GitHub Actions</a>',
+                    keyboard=_BENCH_ACTION_KB)
+            else:
+                await _tg_reply(chat_id,
+                    f"⚠️ GitHub API status {_r.status_code} — riprova tra poco.",
+                    keyboard=_BACK_KB)
+    except Exception as _exc:
+        _logger.warning("[improve] error: %s", _exc)
+        await _tg_reply(chat_id,
+            f"❌ Errore: <code>{html.escape(str(_exc)[:150])}</code>",
+            keyboard=_BACK_KB)
+
+

api/telegram_cmd_monitoring.py

@@ -0,0 +1,457 @@
+"""backend/api/telegram_cmd_monitoring.py — Comandi Telegram di monitoraggio e stato.
+
+Comandi:
+  _cmd_help, _cmd_logs, _cmd_status, _cmd_commit_summary,
+  _cmd_check, _cmd_tasks, _cmd_git, _cmd_coord,
+  _cmd_scan_now, _cmd_telemetry
+"""
+from __future__ import annotations
+import asyncio, html, logging, os, re, time
+
+from .telegram_tg_client import (
+    _get_bot_token, _tg_reply, _tg_send, _tg_edit,
+    _tg_typing, _tg_react, _tg_photo, _fmt_elapsed,
+    _BACK_KB,
+)
+from .telegram_keyboards import (
+    _MAIN_KB, _QUICK_PICK_KB, _after_task_kb, _BENCH_CACHE, _LAST_GOAL,
+)
+
+_logger = logging.getLogger("api.telegram_webhook")
+
+# ── Command handlers ──────────────────────────────────────────────────────────
+
+async def _cmd_help(chat_id: int) -> None:
+    """Menu principale: un messaggio pulito + inline keyboard essenziale."""
+    await _tg_typing(chat_id)
+    welcome = (
+        "🤖 <b>Agente AI</b>\n"
+        "<i>Assistente autonomo per lo sviluppo software</i>\n\n"
+        "📝 <b>Come usarmi:</b>\n"
+        "Scrivi qualsiasi obiettivo — lo eseguo autonomamente:\n"
+        "  • <code>analizza i bug in providers.py</code>\n"
+        "  • <code>ottimizza le query Supabase più lente</code>\n"
+        "  • <code>fai autofix degli errori nel log</code>\n\n"
+        "📌 <b>Comandi rapidi:</b>\n"
+        "  /avvia — lancia un task AI\n"
+        "  /stato — vedi cosa sta facendo\n"
+        "  /salute — controllo sistema\n"
+        "  /chiedi — domanda veloce all\'AI\n\n"
+        "⬇️ <b>O scegli dal menu:</b>"
+    )
+    await _tg_reply(chat_id, welcome, keyboard=_MAIN_KB)
+
+
+async def _cmd_logs(chat_id: int, level: str = "WARNING") -> None:
+    """Mostra ultimi log dal backend Railway filtrando per livello."""
+    import httpx as _hx
+    railway_url = os.getenv("RAILWAY_URL", "https://ai-production-4c06.up.railway.app").rstrip("/")
+    await _tg_reply(chat_id,
+        f"📋 <b>Log Railway</b> — <code>{level.upper()}</code>\n⏳ <i>Fetching…</i>")
+    try:
+        async with _hx.AsyncClient(timeout=10.0) as c:
+            r = await c.get(f"{railway_url}/api/telegram/logs",
+                            params={"level": level.upper(), "n": 20})
+            data = r.json() if r.status_code == 200 else {}
+    except Exception as exc:
+        await _tg_reply(chat_id,
+            "❌ <b>Log non disponibili</b>\n<code>" + html.escape(str(exc)[:200]) + "</code>\n"
+            "<i>Controlla Railway dashboard.</i>", keyboard=_BACK_KB)
+        return
+    records = data.get("records", [])
+    if not records:
+        msg = ("✅ <b>Nessun " + level.upper() + " nei log!</b>\n<i>Sistema stabile.</i>"
+               if level.upper() in ("WARNING","ERROR")
+               else "📋 <b>Log vuoti</b> — nessun record disponibile")
+        await _tg_reply(chat_id, msg, keyboard=_BACK_KB)
+        return
+    import datetime as _dt
+    lines = [f"📋 <b>Log</b> ({data.get('count',0)} rec — {level.upper()})\n"]
+    for rec in records[:15]:
+        ts = _dt.datetime.fromtimestamp(rec.get("ts",0), tz=_dt.timezone.utc).strftime("%H:%M:%S")
+        lvl = rec.get("level","?")
+        lgr = rec.get("logger","").split(".")[-1][:18]
+        msg = html.escape(str(rec.get("msg",""))[:100])
+        icon = "🔴" if lvl=="ERROR" else "🟡" if lvl=="WARNING" else "⚪"
+        lines.append(f"{icon} <code>{ts}</code> [{lgr}] {msg}")
+    await _tg_reply(chat_id, "\n".join(lines), keyboard=_BACK_KB)
+
+
+async def _cmd_status(chat_id: int) -> None:
+    await _tg_typing(chat_id)
+    try:
+        from api.state import _agent_tasks, _loop_registry  # noqa: F401
+        total   = len(_agent_tasks)
+        running = sum(1 for t in _agent_tasks.values() if t.get("status") == "RUNNING")
+        success = sum(1 for t in _agent_tasks.values() if t.get("status") == "SUCCESS")
+        error   = sum(1 for t in _agent_tasks.values() if t.get("status") == "ERROR")
+        queued  = sum(1 for t in _agent_tasks.values() if t.get("status") == "QUEUED")
+
+        # Supabase fallback: se in-memory è vuoto (restart backend) legge dal DB
+        sb_line = ""
+        if total == 0:
+            try:
+                from api.state import _sb
+                if _sb:
+                    res = await asyncio.to_thread(
+                        lambda: _sb.table("agent_tasks")
+                        .select("status")
+                        .order("created_at", desc=True)
+                        .limit(50)
+                        .execute()
+                    )
+                    rows = res.data or []
+                    if rows:
+                        db_run  = sum(1 for r in rows if r.get("status") == "RUNNING")
+                        db_done = sum(1 for r in rows if r.get("status") == "SUCCESS")
+                        db_err  = sum(1 for r in rows if r.get("status") == "ERROR")
+                        sb_line = (
+                            "\n📦 <b>Supabase (ultimi 50):</b> "
+                            + str(db_run) + " in corso / "
+                            + str(db_done) + " ok / "
+                            + str(db_err) + " err"
+                            + " <i>(backend riavviato)</i>"
+                        )
+            except Exception as _exc:
+                _logger.debug("[telegram_webhook] silenced %s", type(_exc).__name__)  # noqa: BLE001
+
+        from api.scheduler import _tasks as sched_tasks, _loop_task
+        sched_ok = _loop_task is not None and not _loop_task.done()
+        sched_pending = sum(1 for t in sched_tasks.values() if t.get("status") == "pending")
+        sched_label = "✅ attivo" if sched_ok else "❌ fermo"
+
+        ts_now = time.strftime("%Y-%m-%d %H:%M:%S")
+        railway_url = os.getenv("RAILWAY_URL","https://ai-production-4c06.up.railway.app")
+        ry_line = ""
+        try:
+            import httpx as _hx
+            async with _hx.AsyncClient(timeout=4.0) as c:
+                rv = await c.get(f"{railway_url}/api/info")
+                if rv.status_code == 200:
+                    rj = rv.json()
+                    ry_line = ("\n🚂 <b>Railway:</b> v" + rj.get("version","?")
+                               + " — " + rj.get("sprint",""))
+        except Exception:
+            pass
+
+        # ── NEW-1: HEAD git + ultimo commit ──────────────────────────────────
+        # Chiama GitHub API con GITHUB_TOKEN (Railway env) — timeout 4s, silent fail.
+        # Mostra: sha corto + prima riga commit message + età ("3h fa").
+        git_line = ""
+        try:
+            import httpx as _hx_g, datetime as _dt
+            _gh_token = os.getenv("GITHUB_TOKEN", "").strip()
+            _gh_repo  = os.getenv("GITHUB_REPO", "Baida98/AI").strip()
+            if _gh_token and _gh_repo:
+                async with _hx_g.AsyncClient(timeout=4.0) as _gc:
+                    _gr = await _gc.get(
+                        f"https://api.github.com/repos/{_gh_repo}/commits/main",
+                        headers={"Authorization": f"Bearer {_gh_token}", "User-Agent": "agente-ai"},
+                        params={"per_page": 1},
+                    )
+                if _gr.status_code == 200:
+                    _cj   = _gr.json()
+                    _sha  = (_cj.get("sha") or "")[:7]
+                    _cmsg = ((_cj.get("commit") or {}).get("message") or "").split("\n")[0][:45]
+                    _date = ((_cj.get("commit") or {}).get("committer") or {}).get("date", "")
+                    _age  = ""
+                    if _date:
+                        _ts   = _dt.datetime.fromisoformat(_date.replace("Z", "+00:00"))
+                        _secs = int((_dt.datetime.now(_dt.timezone.utc) - _ts).total_seconds())
+                        if _secs < 3600:   _age = f"{_secs // 60}m fa"
+                        elif _secs < 86400: _age = f"{_secs // 3600}h fa"
+                        else:               _age = f"{_secs // 86400}g fa"
+                    git_line = (
+                        f"\n🔀 <b>HEAD:</b> <code>{html.escape(_sha)}</code>"
+                        f" {html.escape(_cmsg)} <i>({_age})</i>"
+                    )
+        except Exception:
+            pass
+
+        # ── NEW-2: task live — goal + step corrente dal loop_registry ────────
+        # Per il primo task RUNNING: mostra goal + azione corrente (dal buffer SSE)
+        # + tempo trascorso. Zero overhead se non c'è task in corso.
+        live_line = ""
+        try:
+            _running_list = [t for t in _agent_tasks.values() if t.get("status") == "RUNNING"]
+            if _running_list:
+                import json as _lj
+                _rt   = _running_list[0]
+                _tid  = _rt.get("id") or _rt.get("task_id") or ""
+                _goal_s = html.escape((_rt.get("goal") or "")[:38])
+                _elapsed = ""
+                _ca = _rt.get("created_at", 0)
+                if isinstance(_ca, int) and _ca > 0:
+                    _es = int(time.time() * 1000 - _ca) // 1000
+                    _elapsed = f" · {_es // 60}m{_es % 60:02d}s" if _es >= 60 else f" · {_es}s"
+                # Legge ultimo evento SSE dal buffer (action/type corrente)
+                _act = ""
+                _ebuf = (_loop_registry.get(_tid) or {}).get("event_buffer", [])
+                for _ev in reversed(_ebuf[-30:]):
+                    try:
+                        _raw = _ev[6:] if _ev.startswith("data: ") else _ev
+                        _ed  = _lj.loads(_raw)
+                        _a   = _ed.get("action") or _ed.get("type") or ""
+                        if _a and _a not in ("ping", "connected", "keepalive"):
+                            _act = f" → <code>{html.escape(str(_a)[:20])}</code>"
+                            break
+                    except Exception:
+                        pass
+                live_line = f"\n⚙️ <b>Live:</b> {_goal_s}{_act}{_elapsed}"
+        except Exception:
+            pass
+
+        # ── NEW-3: coord mini — sessioni agent-coord attive ──────────────────
+        # 1 riga: chi sta lavorando, su quale sprint, su quali file.
+        # Timeout aggressivo 3s — /status deve essere veloce.
+        coord_line = ""
+        try:
+            import httpx as _hx_c2, json as _jc2, time as _tc2
+            _SB_URL2 = os.getenv("SUPABASE_URL", "").rstrip("/")
+            _SB_KEY2 = os.getenv("SUPABASE_KEY", "")
+            if _SB_KEY2:
+                async with _hx_c2.AsyncClient(timeout=3.0) as _cc:
+                    _cr = await _cc.get(
+                        f"{_SB_URL2}/rest/v1/agent_tasks",
+                        params={"goal": "ilike.*__session__*", "select": "context"},
+                        headers={"apikey": _SB_KEY2, "Authorization": f"Bearer {_SB_KEY2}"},
+                    )
+                if _cr.is_success:
+                    _now_ms = int(_tc2.time() * 1000)
+                    _active = []
+                    for _row in (_cr.json() or []):
+                        try:
+                            _ctx = _jc2.loads(_row.get("context") or "{}")
+                            if _now_ms - int(_ctx.get("lastHeartbeat", 0)) < 300_000:
+                                _active.append(_ctx)
+                        except Exception:
+                            pass
+                    if _active:
+                        _s     = _active[0]
+                        _files = [f.split("/")[-1] for f in _s.get("claimedFiles", [])]
+                        _fstr  = ", ".join(_files[:3]) or "—"
+                        _extra = f" (+{len(_active)-1})" if len(_active) > 1 else ""
+                        coord_line = (
+                            f"\n🔗 <b>Coord:</b> {html.escape(_s.get('sessionName','?'))}"
+                            f" [{html.escape(_s.get('sprint','—'))}]"
+                            f" · <code>{html.escape(_fstr)}</code>{_extra}"
+                        )
+                    else:
+                        coord_line = "\n🔗 <b>Coord:</b> <i>nessuna sessione attiva</i>"
+        except Exception:
+            pass
+
+        # ── Icona salute sistema ──────────────────────────────────────────────
+        if running > 0:
+            _sys_icon, _sys_label = "⚙️", f"{running} task in esecuzione"
+        elif error > 0 and success == 0 and total > 0:
+            _sys_icon, _sys_label = "🔴", "ultimi task terminati con errore"
+        elif total == 0:
+            _sys_icon, _sys_label = "💤", "nessun task recente"
+        else:
+            _sys_icon, _sys_label = "✅", "tutto operativo"
+
+        parts = [f"📊 <b>Sistema</b> {_sys_icon} — <i>{_sys_label}</i>", ""]
+        if running or queued:
+            parts.append(f"⚙️ <b>In esecuzione:</b> {running}  ·  <b>In coda:</b> {queued}")
+        if success or error or total:
+            parts.append(f"✅ Completati: {success}  ·  ❌ Errori: {error}  ·  Totale: {total}")
+        for _extra_line in [sb_line, ry_line, git_line, live_line, coord_line]:
+            if _extra_line:
+                parts.append(_extra_line)
+        parts += [
+            "",
+            f"🗓 <b>Scheduler:</b> {sched_label}" + (f" · {sched_pending} in coda" if sched_pending else ""),
+            "",
+            f"<i>🕐 {ts_now} UTC</i>",
+        ]
+        await _tg_reply(chat_id, "\n".join(p for p in parts if p is not None),
+                        keyboard=_MAIN_KB)
+    except Exception as exc:
+        await _tg_reply(chat_id, "⚠️ Errore lettura stato: " + html.escape(str(exc)[:200]))
+
+
+async def _cmd_commit_summary(chat_id: int) -> None:
+    """Riepilogo humanizzato degli ultimi commit via GitHub + AI leggera."""
+    import json as _json
+    GH_API = "https://api.github.com/repos/Baida98/AI/commits?per_page=8"
+    SKIP_RE = re.compile(r"^(🔒|🔓|acquire push lock|release push lock)", re.I)
+    try:
+        import httpx
+        async with httpx.AsyncClient(timeout=10) as cli:
+            r = await cli.get(GH_API, headers={"Authorization": f"Bearer {_gh_token}",
+                                                "Accept": "application/vnd.github+json"})
+        commits = r.json() if r.status_code == 200 else []
+    except Exception:
+        commits = []
+
+    # Filtra commit di lock/chore puro
+    commits = [c for c in commits
+                if not SKIP_RE.match((c.get("commit", {}).get("message") or "").split("\n")[0])][:6]
+
+    if not commits:
+        await _tg_reply(chat_id, "📭 Nessun commit recente trovato.", keyboard=_BACK_KB)
+        return
+
+    # Costruisci breve sintesi statica (no AI) con traduzione tipo
+    _TYPE_IT = {
+        "feat": "Nuova funzione", "fix": "Correzione bug", "docs": "Documentazione",
+        "refactor": "Refactor", "chore": "Manutenzione", "test": "Test",
+        "perf": "Performance", "ux": "Esperienza utente", "style": "Stile",
+        "ci": "CI/CD", "build": "Build",
+    }
+    _TYPE_ICON = {
+        "feat": "✨", "fix": "🔧", "docs": "📄", "refactor": "♻️",
+        "chore": "🔩", "test": "🧪", "perf": "⚡", "ux": "🎨",
+        "ci": "⚙️", "build": "📦",
+    }
+    lines = ["🔀 <b>Ultimi commit</b>\n"]
+    for c in commits:
+        raw_msg = (c.get("commit", {}).get("message") or "").split("\n")[0]
+        sha     = (c.get("sha") or "")[:7]
+        date    = (c.get("commit", {}).get("author", {}).get("date") or "")
+        time_s  = date[11:16] if len(date) >= 16 else "??:??"
+        # Estrai tipo e corpo
+        m = re.match(r"^(feat|fix|docs|refactor|chore|test|perf|ux|style|ci|build)(?:\([^)]+\))?:\s*(.+)$", raw_msg)
+        if m:
+            tipo, corpo = m.group(1), m.group(2)
+            icon = _TYPE_ICON.get(tipo, "📌")
+            tipo_it = _TYPE_IT.get(tipo, tipo)
+            # Humanizza la descrizione: rimuovi jargon tecnico comune
+            corpo_h = corpo.replace("_", " ").replace("-", " ")
+            corpo_h = re.sub(r"(impl|add|implement|update|refactor|fix|use|remove|clean)", "", corpo_h, flags=re.I).strip()
+            corpo_h = corpo_h[:60] or corpo[:60]
+            lines.append(f"{icon} <b>{tipo_it}</b> — {html.escape(corpo_h)}\n   <i>{time_s} · <code>{sha}</code></i>")
+        else:
+            lines.append(f"📌 {html.escape(raw_msg[:65])}\n   <i>{time_s} · <code>{sha}</code></i>")
+
+    await _tg_reply(
+        chat_id,
+        "\n\n".join(lines),
+        keyboard={
+            "inline_keyboard": [
+                [{"text": "🔄 Aggiorna", "callback_data": "qp_commits"},
+                 {"text": "🚀 Nuovo Task", "callback_data": "agent"}],
+                [{"text": "🏠 Menu", "callback_data": "tgw_help"}],
+            ]
+        }
+    )
+
+
+async def _cmd_check(chat_id: int) -> None:
+    """🔍 Health check live: Railway, HF Space A+B, versione vs GH HEAD."""
+    import time as _time
+    await _tg_typing(chat_id)
+    await _tg_reply(chat_id, "🔍 <b>Check infrastruttura...</b>", keyboard=None)
+
+    async def _probe(label: str, url: str, timeout: int = 7) -> str:
+        t0 = _time.monotonic()
+        try:
+            async with httpx.AsyncClient(timeout=timeout) as cli:
+                r = await cli.get(url)
+            ms = round((_time.monotonic() - t0) * 1000)
+            icon = "✅" if r.status_code == 200 else "⚠️"
+            return f"{icon} <b>{label}</b> — <code>{r.status_code}</code> <i>{ms}ms</i>"
+        except Exception as exc:
+            ms = round((_time.monotonic() - t0) * 1000)
+            return f"❌ <b>{label}</b> — <code>{str(exc)[:55]}</code> <i>{ms}ms</i>"
+
+    probes = await asyncio.gather(
+        _probe("Railway backend", "https://ai-production-4c06.up.railway.app/health"),
+        _probe("HF Space A",      "https://arjanit98-terminal.hf.space/api/version"),
+        _probe("HF Space B",      "https://baida00-ai-backend-collab.hf.space/api/version"),
+    )
+
+    # GH HEAD vs HF Space version
+    gh_sha, hf_build = "?", "?"
+    try:
+        async with httpx.AsyncClient(timeout=5) as cli:
+            ref_r = await cli.get(
+                "https://api.github.com/repos/Baida98/AI/git/refs/heads/main",
+                headers={"Authorization": f"Bearer {_gh_token}", "Accept": "application/vnd.github+json"},
+            )
+            if ref_r.status_code == 200:
+                gh_sha = (ref_r.json().get("object", {}).get("sha") or "?")[:10]
+    except Exception:
+        pass
+    try:
+        async with httpx.AsyncClient(timeout=5) as cli:
+            ver_r = await cli.get("https://arjanit98-terminal.hf.space/api/version")
+            if ver_r.status_code == 200:
+                d = ver_r.json()
+                hf_build = f"{d.get('version','?')} ({d.get('build_date','?')})"
+    except Exception:
+        pass
+
+    sync_icon = "✅" if gh_sha != "?" and gh_sha[:8] in hf_build else "⚠️"
+    lines_out = ["🔍 <b>Infrastructure Check</b>"]
+    lines_out.extend(probes)
+    lines_out.append(f"<code>GH HEAD:    {gh_sha}</code>")
+    lines_out.append(f"<code>HF build:   {hf_build}</code>")
+    lines_out.append(f"{sync_icon} <i>GH↔HF {'in sync' if sync_icon=='✅' else 'OUT OF SYNC — usa 🔄 Sync HF'}</i>")
+    await _tg_reply(chat_id, "\n".join(lines_out), keyboard=_BACK_KB)
+
+
+async def _cmd_tasks(chat_id: int) -> None:
+    await _tg_typing(chat_id)
+    STATUS_EMOJI = {
+        "SUCCESS": "✅", "ERROR": "❌", "RUNNING": "⚙️",
+        "QUEUED": "⏳", "CANCELLED": "🚫",
+    }
+    try:
+        from api.state import _agent_tasks
+        mem_tasks = sorted(
+            _agent_tasks.values(),
+            key=lambda t: t.get("created_at", 0),
+            reverse=True,
+        )[:8]
+
+        # Supabase fallback se memoria vuota
+        if not mem_tasks:
+            try:
+                from api.state import _sb
+                if _sb:
+                    res = await asyncio.to_thread(
+                        lambda: _sb.table("agent_tasks")
+                        .select("task_id,goal,status,created_at")
+                        .order("created_at", desc=True)
+                        .limit(8)
+                        .execute()
+                    )
+                    rows = res.data or []
+                    if rows:
+                        lines = ["📋 <b>Ultimi task (Supabase)</b>  <i>⚠️ backend riavviato</i>\n"]
+                        for r in rows:
+                            em  = STATUS_EMOJI.get(r.get("status", ""), "•")
+                            gol = html.escape((r.get("goal") or "")[:55])
+                            tid = html.escape(str(r.get("task_id") or "")[:8])
+                            ts  = r.get("created_at", 0)
+                            age = _fmt_elapsed(ts) if isinstance(ts, int) and ts > 1_000_000 else "?"
+                            lines.append(em + " <code>" + tid + "</code> " + gol + " <i>" + age + "</i>")
+                        return await _tg_reply(chat_id, "\n".join(lines))
+            except Exception as _exc:
+                _logger.debug("[telegram_webhook] silenced %s", type(_exc).__name__)  # noqa: BLE001
+            return await _tg_reply(chat_id, "📋 Nessun task recente in memoria.")
+
+        _ST_LABEL = {
+            "SUCCESS": "Fatto",    "ERROR": "Fallito ⚠️", "RUNNING": "In corso…",
+            "QUEUED": "In coda",   "CANCELLED": "Annullato",
+        }
+        _ST_FLAIR = {
+            "SUCCESS": "✅", "ERROR": "❌", "RUNNING": "⚙️",
+            "QUEUED": "⏳",  "CANCELLED": "🚫",
+        }
+        lines = ["<b>Cosa ha fatto l'agente:</b>\n"]
+        for t in mem_tasks:
+            st   = t.get("status", "?")
+            em   = _ST_FLAIR.get(st, "•")
+            gol  = html.escape((t.get("goal") or "—")[:70])
+            ca   = t.get("created_at", 0)
+            age  = _fmt_elapsed(ca) if isinstance(ca, int) and ca > 1_000_000 else "poco fa"
+            lbl  = _ST_LABEL.get(st, st)
+            lines.append(f"{em} {gol}\n   <i>{lbl} · {age}</i>")
+        await _tg_reply(chat_id, "\n\n".join(lines), keyboard=_BACK_KB)
+    except Exception as exc:
+        await _tg_reply(chat_id, "⚠️ " + html.escape(str(exc)[:200]))
+
+

api/telegram_keyboards.py

@@ -0,0 +1,122 @@
+"""backend/api/telegram_keyboards.py — Inline keyboards, menu e costanti UI Telegram.
+
+Costanti:
+  _QUICK_PICK_KB  — quick-pick task templates
+  _MAIN_KB        — tastiera principale (reply keyboard)
+  _LAST_GOAL      — dict chat_id → ultimo goal (per retry)
+  _BENCH_CACHE    — cache benchmark
+
+Funzioni:
+  _after_task_kb(chat_id) — keyboard post-task con retry
+"""
+from __future__ import annotations
+# ── Quick-pick task templates (MX-QUICKPICK) ──────────────────────────────────
+_QUICK_PICK_KB = {
+    "inline_keyboard": [
+        [{"text": "🔍 Analizza bug",    "callback_data": "qp_bug"},
+         {"text": "⚡ Ottimizza DB",    "callback_data": "qp_db"}],
+        [{"text": "🔧 AutoFix log",     "callback_data": "qp_autofix"},
+         {"text": "🔀 Riassumi commit", "callback_data": "qp_commits"}],
+        [{"text": "📝 Genera docs",     "callback_data": "qp_docs"},
+         {"text": "🧪 Genera test",     "callback_data": "qp_tests"}],
+        [{"text": "✍️ Scrivi obiettivo...", "callback_data": "qp_custom"}],
+        [{"text": "🏠 Menu",            "callback_data": "tgw_help"}],
+    ]
+}
+
+# ── After-task keyboard (retry + navigazione) ─────────────────────────────────
+# Ultimo goal per chat_id — usato da 🔁 Rifai
+_LAST_GOAL: dict[int, str] = {}
+
+def _after_task_kb(chat_id: int) -> dict:
+    """Keyboard mostrata dopo ogni task completato."""
+    return {
+        "inline_keyboard": [
+            [{"text": "🔁 Rifai",       "callback_data": "tgw_retry"},
+             {"text": "📋 Attività",    "callback_data": "tgw_tasks"}],
+            [{"text": "🚀 Nuovo Task",  "callback_data": "agent"},
+             {"text": "🏠 Menu",        "callback_data": "tgw_help"}],
+        ]
+    }
+
+
+
+# ── Main reply keyboard ─────────────────────────────────────────────────────
+_MAIN_KB = {
+    "inline_keyboard": [
+        [{"text": "🚀 Nuovo Task",   "callback_data": "agent"},
+         {"text": "📋 Attività",     "callback_data": "tgw_tasks"}],
+        [{"text": "🩺 Salute",       "callback_data": "tgw_health"},
+         {"text": "🔧 AutoFix",      "callback_data": "tgw_autofix"}],
+        [{"text": "💬 Chiedi all'AI","callback_data": "tgw_ask"},
+         {"text": "📈 Stato",        "callback_data": "tgw_status"}],
+        [{"text": "🌐 Dashboard →",  "url": "https://agente-ai.pages.dev"}],
+    ]
+}
+
+# ── Bench cache + keyboard (GAP-TGB) ─────────────────────────────────────────
+# Salva l'ultimo run bench per chat_id → usato dai callback tgw_bench_fix/run
+_BENCH_CACHE: dict[int, dict] = {}
+
+_BENCH_ACTION_KB = {
+    "inline_keyboard": [
+        [{"text": "🔧 Applica Fix",  "callback_data": "tgw_bench_fix"},
+         {"text": "🔄 Riesegui",     "callback_data": "tgw_bench_run"}],
+        [{"text": "⚙️ Migliora",     "callback_data": "tgw_improve"}],
+        [{"text": "🏠 Menu",         "callback_data": "tgw_help"}],
+    ]
+}
+
+# ── ReplyKeyboardRemove — rimuove tastiera persistente da versioni precedenti ──
+_REPLY_KB_REMOVE = {"remove_keyboard": True}
+
+# ── Sub-menu inline keyboards ─────────────────────────────────────────────────
+_TASK_MENU_KB = {
+    "inline_keyboard": [
+        [{"text": "🤖 Nuovo Task",   "callback_data": "tgw_do"},
+         {"text": "🔧 AutoFix",      "callback_data": "tgw_autofix"}],
+        [{"text": "⚙️ Migliora AI",  "callback_data": "tgw_improve"},
+         {"text": "📋 Task recenti", "callback_data": "tgw_tasks"}],
+        [{"text": "🧠 Briefing",     "callback_data": "tgw_briefing"},
+         {"text": "📝 Salva Nota",   "callback_data": "tgw_nota"}],
+        [{"text": "🔍 Cerca web",    "callback_data": "tgw_cerca"},
+         {"text": "🌤 Meteo",        "callback_data": "tgw_meteo"}],
+    ]
+}
+_STATUS_MENU_KB = {
+    "inline_keyboard": [
+        [{"text": "📊 Daemon+Task",    "callback_data": "tgw_status"},
+         {"text": "🔌 Provider AI",    "callback_data": "tgw_providers"}],
+        [{"text": "🔗 Coord sessioni", "callback_data": "tgw_coord"},
+         {"text": "🔀 Git log",        "callback_data": "tgw_git"}],
+        [{"text": "🌐 Dashboard",      "url": "https://agente-ai.pages.dev"}],
+    ]
+}
+_PERF_MENU_KB = {
+    "inline_keyboard": [
+        [{"text": "📊 Benchmark",      "callback_data": "tgw_bench"},
+         {"text": "🏆 Score",          "callback_data": "tgw_score"}],
+        [{"text": "📡 Telemetria",     "callback_data": "tgw_telemetry"},
+         {"text": "⚙️ Migliora",      "callback_data": "tgw_improve"}],
+        [{"text": "🔧 Fix gap bench",  "callback_data": "tgw_bench_fix"}],
+    ]
+}
+_HEALTH_MENU_KB = {
+    "inline_keyboard": [
+        [{"text": "🔍 Scan completo",  "callback_data": "tgw_health"},
+         {"text": "📝 Log errori",     "callback_data": "tgw_logs"}],
+        [{"text": "📊 Status",         "callback_data": "tgw_status"},
+         {"text": "🔌 Provider AI",    "callback_data": "tgw_providers"}],
+    ]
+}
+_DEV_MENU_KB = {
+    "inline_keyboard": [
+        [{"text": "📸 Snapshot",       "callback_data": "tgw_snap"},
+         {"text": "✅ Verify",         "callback_data": "tgw_verify"}],
+        [{"text": "💊 Heal",           "callback_data": "tgw_heal"},
+         {"text": "📝 Log",            "callback_data": "tgw_logs"}],
+        [{"text": "🔀 Git commits",    "callback_data": "tgw_git"},
+         {"text": "🏓 Ping",          "callback_data": "tgw_ping"}],
+    ]
+}
+

api/telegram_tg_client.py

@@ -0,0 +1,264 @@
+"""backend/api/telegram_tg_client.py — Telegram Bot API helpers.
+
+Livello più basso dell'integrazione Telegram: funzioni pure per inviare
+messaggi, modificarli, reazioni, typing indicator, foto.
+Non ha dipendenze da altri moduli interni — importabile ovunque.
+
+Esportati:
+  _get_bot_token, _log_tg_exc, _fmt_elapsed
+  _tg_reply, _tg_send, _tg_edit, _tg_photo, _tg_typing, _tg_react, _tg_answer_callback
+"""
+from __future__ import annotations
+import asyncio, html, logging, os, time
+import httpx  # top-level — era lazy in 20+ funzioni
+
+_logger = logging.getLogger("api.telegram_webhook")  # unico logger (duplicato rimosso)
+
+
+def _log_tg_exc(task: "asyncio.Task[None]") -> None:
+    """Gap-2.6: log exceptions from fire-and-forget tasks."""
+    try:
+        exc = task.exception()
+        if exc:
+            _logger.warning("tg_webhook bg task error: %s: %s", type(exc).__name__, exc)
+    except (asyncio.CancelledError, asyncio.InvalidStateError):
+        pass
+
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+def _get_bot_token() -> str:
+    return os.getenv("TELEGRAM_BOT_TOKEN", "").strip()
+
+
+async def _tg_reply(chat_id: str | int, text: str, token: str | None = None,
+                    keyboard: dict | None = None) -> None:
+    """Invia risposta al chat_id con HTML + opzionale inline keyboard."""
+    bot_token = token or _get_bot_token()
+    if not bot_token:
+        return
+    payload: dict = {
+        "chat_id": chat_id,
+        "text": text,
+        "parse_mode": "HTML",
+        "link_preview_options": {"is_disabled": True},
+    }
+    if keyboard:
+        payload["reply_markup"] = keyboard
+    try:
+        import httpx
+        async with httpx.AsyncClient(timeout=8.0) as c:
+            await c.post(
+                f"https://api.telegram.org/bot{bot_token}/sendMessage",
+                json=payload,
+            )
+    except Exception as exc:
+        _logger.warning("tg_reply error: %s", exc)
+
+
+async def _tg_answer_callback(callback_query_id: str, text: str = "", token: str | None = None) -> None:
+    """Risponde a un callback_query (obbligatorio per chiudere il loading sui buttons)."""
+    bot_token = token or _get_bot_token()
+    if not bot_token:
+        return
+    try:
+        import httpx
+        async with httpx.AsyncClient(timeout=5.0) as c:
+            await c.post(
+                f"https://api.telegram.org/bot{bot_token}/answerCallbackQuery",
+                json={"callback_query_id": callback_query_id, "text": text, "show_alert": False},
+            )
+    except Exception as exc:
+        _logger.debug("answer_callback error: %s", exc)
+
+
+async def _tg_send(chat_id: str | int, text: str, token: str | None = None,
+                   keyboard: dict | None = None) -> str | None:
+    """Invia messaggio e ritorna il message_id (per editMessageText streaming)."""
+    bot_token = token or _get_bot_token()
+    if not bot_token:
+        return None
+    payload: dict = {
+        "chat_id": chat_id,
+        "text": text,
+        "parse_mode": "HTML",
+        "link_preview_options": {"is_disabled": True},
+    }
+    if keyboard:
+        payload["reply_markup"] = keyboard
+    try:
+        import httpx
+        async with httpx.AsyncClient(timeout=8.0) as c:
+            r = await c.post(
+                f"https://api.telegram.org/bot{bot_token}/sendMessage",
+                json=payload,
+            )
+            j = r.json()
+            return str(j.get("result", {}).get("message_id", "")) if j.get("ok") else None
+    except Exception as exc:
+        _logger.warning("tg_send error: %s", exc)
+        return None
+
+
+async def _tg_edit(chat_id: str | int, message_id: str, text: str,
+                   token: str | None = None, keyboard: dict | None = None) -> bool:
+    """Aggiorna messaggio esistente — streaming live via editMessageText.
+    Ritorna True se successo. Rate-limit: max 20 edit/min per chat Telegram."""
+    bot_token = token or _get_bot_token()
+    if not bot_token or not message_id:
+        return False
+    payload: dict = {
+        "chat_id": chat_id,
+        "message_id": int(message_id),
+        "text": text[:4000],
+        "parse_mode": "HTML",
+        "link_preview_options": {"is_disabled": True},
+    }
+    if keyboard:
+        payload["reply_markup"] = keyboard
+    try:
+        import httpx
+        async with httpx.AsyncClient(timeout=8.0) as c:
+            r = await c.post(
+                f"https://api.telegram.org/bot{bot_token}/editMessageText",
+                json=payload,
+            )
+            return r.json().get("ok", False)
+    except Exception as exc:
+        _logger.debug("tg_edit error: %s", exc)
+        return False
+
+
+async def _tg_photo(
+    chat_id: str | int,
+    photo_url: str,
+    caption: str = "",
+    token: str | None = None,
+    keyboard: dict | None = None,
+) -> None:
+    """Invia foto/chart via sendPhoto Telegram.
+
+    Strategia anti URL-lungo:
+    1. POST a quickchart.io → scarica PNG bytes → multipart sendPhoto (no limite URL).
+    2. Fallback: invia URL direttamente (funziona se URL < ~2000 chars).
+    """
+    bot_token = token or _get_bot_token()
+    if not bot_token:
+        return
+    caption_safe = (caption or "")[:1024]
+
+    import httpx as _hx_p, json as _j_p, urllib.parse as _ul_p, re as _re_p
+
+    png_bytes: bytes | None = None
+    if "quickchart.io/chart" in photo_url:
+        try:
+            m = _re_p.search(r"[?&]c=([^&]+)", photo_url)
+            if m:
+                cfg_dict = _j_p.loads(_ul_p.unquote(m.group(1)))
+                async with _hx_p.AsyncClient(timeout=20.0) as c:
+                    qr = await c.post(
+                        "https://quickchart.io/chart",
+                        json={"chart": cfg_dict, "width": 720, "height": 420,
+                              "backgroundColor": "white", "format": "png"},
+                    )
+                    if qr.status_code == 200 and qr.headers.get("content-type", "").startswith("image/"):
+                        png_bytes = qr.content
+                        _logger.debug("tg_photo: quickchart POST ok, %d bytes", len(png_bytes))
+        except Exception as exc:
+            _logger.debug("tg_photo: quickchart POST fallback: %s", exc)
+
+    try:
+        import httpx as _hx_s
+        async with _hx_s.AsyncClient(timeout=15.0) as c:
+            if png_bytes:
+                import json as _j_s
+                data: dict = {"chat_id": str(chat_id), "parse_mode": "HTML"}
+                if caption_safe:
+                    data["caption"] = caption_safe
+                if keyboard:
+                    data["reply_markup"] = _j_s.dumps(keyboard)
+                files = {"photo": ("chart.png", png_bytes, "image/png")}
+                await c.post(f"https://api.telegram.org/bot{bot_token}/sendPhoto",
+                             data=data, files=files)
+            else:
+                payload: dict = {"chat_id": chat_id, "photo": photo_url, "parse_mode": "HTML"}
+                if caption_safe:
+                    payload["caption"] = caption_safe
+                if keyboard:
+                    payload["reply_markup"] = keyboard
+                await c.post(f"https://api.telegram.org/bot{bot_token}/sendPhoto", json=payload)
+    except Exception as exc:
+        _logger.warning("tg_photo error: %s", exc)
+
+
+async def _tg_typing(chat_id: str | int, action: str = "typing", token: str | None = None) -> None:
+    """Invia sendChatAction — mostra '⌨️ digitando…' prima di operazioni pesanti.
+
+    Dura 5 secondi o fino al prossimo messaggio del bot.
+    Azioni: typing, upload_photo, upload_document, find_location, record_video_note.
+    """
+    bot_token = token or _get_bot_token()
+    if not bot_token:
+        return
+    try:
+        async with httpx.AsyncClient(timeout=3.0) as c:
+            await c.post(
+                f"https://api.telegram.org/bot{bot_token}/sendChatAction",
+                json={"chat_id": chat_id, "action": action},
+            )
+    except Exception:
+        pass
+
+
+async def _tg_react(
+    chat_id: str | int,
+    message_id: int | str,
+    emoji: str = "👍",
+    token: str | None = None,
+) -> None:
+    """Aggiunge reazione emoji a un messaggio (Bot API 7.1+, Feb 2024).
+
+    Emoji supportate: 👍 👎 ❤ 🔥 🥰 👏 😁 🤔 🤯 😱 🎉 🤩 🏆 ✅ 💯 ⚡ 🚀 🎯
+    """
+    bot_token = token or _get_bot_token()
+    if not bot_token or not message_id:
+        return
+    try:
+        async with httpx.AsyncClient(timeout=3.0) as c:
+            await c.post(
+                f"https://api.telegram.org/bot{bot_token}/setMessageReaction",
+                json={
+                    "chat_id": chat_id,
+                    "message_id": int(message_id),
+                    "reaction": [{"type": "emoji", "emoji": emoji}],
+                    "is_big": False,
+                },
+            )
+    except Exception:
+        pass
+
+
+def _fmt_elapsed(created_at_ms: int) -> str:
+    """Formatta elapsed time da un timestamp ms → stringa leggibile."""
+    diff = int(time.time() * 1000) - created_at_ms
+    s = diff // 1000
+    if s < 60:
+        return f"{s}s fa"
+    if s < 3600:
+        return f"{s // 60}m{s % 60:02d}s fa"
+    return f"{s // 3600}h{(s % 3600) // 60:02d}m fa"
+
+_WEBAPP_KB = {
+    "inline_keyboard": [
+        [{"text": "🚀 Apri Dashboard", "web_app": {"url": "https://agente-ai.pages.dev"}}],
+        [{"text": "🏠 Menu", "callback_data": "tgw_help"}],
+    ]
+}
+_BACK_KB = {
+    "inline_keyboard": [
+        [{"text": "🏠 Menu",    "callback_data": "tgw_help"},
+         {"text": "📊 Stato",  "callback_data": "tgw_status"}],
+    ]
+}
+

memory/distiller.py

@@ -1,68 +1,123 @@
 """
-distiller.py — S-SESTO-SENSO-V2: Memory Cognitive Compressive.
+distiller.py — S-SESTO-SENSO-V2: Memory Cognitive Compressive.
 Sintetizza i log grezzi delle sessioni in lezioni apprese e concetti chiave.
-Riduce il rumore e ottimizza l'uso dei token per la memoria a lungo termine.
+
+C1-FIX (2026-07-01): chiamata LLM reale implementata — il distillatore produceva
+solo placeholder vuoto (lessons: [], patterns: [], facts: []) invece di estrarre
+conoscenza reale. Ora chiama ai_client quando disponibile; fallback euristico
+se il client è None o se la chiamata fallisce.
 """
 import logging
 import json
-from typing import List, Dict, Any
+import re
+from typing import List, Dict, Any, Optional
 from datetime import datetime, timezone
 
 _logger = logging.getLogger("agente_ai.memory.distiller")
 
+_DISTILL_SYSTEM = (
+    "Sei un Memory Distiller per un agente AI avanzato. "
+    "Analizza la sessione e restituisci SOLO un oggetto JSON valido, "
+    "senza markdown, senza spiegazioni. Formato esatto:\n"
+    '{"lessons":["..."],"patterns":["..."],"facts":["..."],'
+    '"completed":true|false,"completion_note":"..."}'
+)
+
+def _build_distill_prompt(goal: str, cleaned_msgs: List[Dict]) -> str:
+    transcript = "\n".join(
+        f"[{m['role'].upper()}] {m['content'][:300]}" for m in cleaned_msgs[-20:]
+    )
+    return (
+        f"OBIETTIVO: {goal}\n\n"
+        f"TRASCRIZIONE (ultimi {len(cleaned_msgs[-20:])} messaggi):\n{transcript}\n\n"
+        "Estrai lessons (errori + soluzioni), patterns (architetture fragili o ricorrenti), "
+        "facts (info tecniche stabili). Rispondi SOLO con il JSON."
+    )
+
+def _heuristic_distill(messages: List[Dict], goal: str) -> Dict[str, Any]:
+    """Fallback euristico — estrae pattern semplici dal testo."""
+    errors_found = []
+    facts_found  = []
+    combined = " ".join(m.get("content", "") for m in messages).lower()
+    if "errore" in combined or "error" in combined or "exception" in combined:
+        errors_found.append("Errori rilevati nella sessione — dettagli nel transcript.")
+    if "completato" in combined or "done" in combined or "success" in combined:
+        facts_found.append("Task marcato come completato nel transcript.")
+    return {
+        "timestamp":       datetime.now(timezone.utc).isoformat(),
+        "goal":            goal,
+        "message_count":   len(messages),
+        "lessons":         errors_found,
+        "patterns":        [],
+        "facts":           facts_found,
+        "completed":       "completato" in combined or "done" in combined,
+        "completion_note": "Distillazione euristica (LLM non disponibile).",
+        "source":          "heuristic",
+    }
+
 class MemoryDistiller:
     def __init__(self, ai_client=None):
         self.ai_client = ai_client
 
     async def distill_session(self, messages: List[Dict[str, Any]], goal: str) -> Dict[str, Any]:
         """
-        Analizza una sequenza di messaggi e ne estrae il succo cognitivo.
+        C1-FIX: chiama l'LLM reale per estrarre lezioni/pattern/fatti.
+        Fallback euristico se ai_client è None o la chiamata fallisce.
         """
         if not messages:
             return {}
 
-        # 1. Pre-processing: Rimuove i contenuti troppo pesanti (es. dump di file)
+        # 1. Pre-processing: tronca contenuti pesanti
         cleaned_msgs = []
         for msg in messages:
             content = msg.get("content", "")
             if len(content) > 2000:
-                content = content[:1000] + "... [TRUNCATED FOR DISTILLATION] ..." + content[-500:]
-            cleaned_msgs.append({"role": msg.get("role"), "content": content})
+                content = content[:1000] + "... [TRUNCATED] ..." + content[-400:]
+            cleaned_msgs.append({"role": msg.get("role", "user"), "content": content})
 
-        # 2. Prompt per la distillazione (da usare con l'AI client)
-        distill_prompt = f"""
-        Sei un Memory Distiller per un agente AI avanzato.
-        Analizza la seguente sessione di lavoro e sintetizzala in modo ultra-compresso.
-        
-        OBIETTIVO ORIGINALE: {goal}
-        
-        ESTRAI:
-        1. **Lezioni Imparate**: Errori fatti e come sono stati risolti.
-        2. **Pattern Rilevati**: Comportamenti ricorrenti o architetture fragili identificate.
-        3. **Fatti Chiave**: Informazioni tecniche stabili scoperte (es. percorsi file, API keys, limiti).
-        4. **Stato Finale**: Il task è stato completato? Se no, perché?
-        
-        FORMATO: JSON compresso.
-        """
+        # 2. Tentativo LLM reale
+        if self.ai_client is not None:
+            try:
+                result = await self._distill_with_llm(cleaned_msgs, goal)
+                if result:
+                    return result
+            except Exception as e:
+                _logger.warning("[Distiller] LLM call failed (%s) — fallback euristico", e)
+
+        # 3. Fallback euristico
+        return _heuristic_distill(cleaned_msgs, goal)
 
-        # Nota: Qui si chiamerebbe l'LLM per la distillazione reale.
-        # Per ora implementiamo una logica di fallback euristica.
-        
-        summary = {
-            "timestamp": datetime.now(timezone.utc).isoformat(),
-            "goal": goal,
-            "message_count": len(messages),
-            "summary": f"Sessione con {len(messages)} messaggi distillata automaticamente.",
-            "lessons": [],
-            "patterns": [],
-            "facts": []
-        }
-        
-        _logger.info(f"[Distiller] Sessione distillata con successo: {goal[:50]}...")
-        return summary
+    async def _distill_with_llm(
+        self, cleaned_msgs: List[Dict], goal: str
+    ) -> Optional[Dict[str, Any]]:
+        """Chiamata LLM reale via ai_client (qualsiasi provider con interfaccia openai-compat)."""
+        prompt = _build_distill_prompt(goal, cleaned_msgs)
+        response = await self.ai_client.chat.completions.create(
+            model=getattr(self.ai_client, "_distill_model", "llama-3.1-8b-instant"),
+            messages=[
+                {"role": "system", "content": _DISTILL_SYSTEM},
+                {"role": "user",   "content": prompt},
+            ],
+            max_tokens=600,
+            temperature=0.1,
+        )
+        raw = response.choices[0].message.content or ""
+        # Estrai JSON dalla risposta (può avere testo attorno)
+        match = re.search(r"\{[\s\S]*\}", raw)
+        if not match:
+            _logger.warning("[Distiller] risposta LLM non contiene JSON valido: %.100s", raw)
+            return None
+        parsed = json.loads(match.group(0))
+        parsed.setdefault("timestamp",    datetime.now(timezone.utc).isoformat())
+        parsed.setdefault("goal",         goal)
+        parsed.setdefault("message_count", len(cleaned_msgs))
+        parsed["source"] = "llm"
+        _logger.info(
+            "[Distiller] distillazione LLM completata: %d lessons, %d facts | goal: %.50s",
+            len(parsed.get("lessons", [])), len(parsed.get("facts", [])), goal,
+        )
+        return parsed
 
     def compress_for_long_term(self, distilled_data: Dict[str, Any]) -> str:
-        """
-        Converte i dati distillati in una stringa ottimizzata per pgvector/semantic memory.
-        """
-        return json.dumps(distilled_data)
+        """Converte i dati distillati in stringa ottimizzata per pgvector/semantic memory."""
+        return json.dumps(distilled_data, ensure_ascii=False)

memory/evolutionary.py

@@ -0,0 +1,93 @@
+"""
+backend/memory/evolutionary.py — Evolutionary Memory (S960)
+Distilla preferenze utente, stili di codice e regole operative dalle sessioni.
+Alimenta il layer 'Reflection' con conoscenze di alto livello (Long-term Evolution).
+"""
+import json
+import logging
+import os
+from pathlib import Path
+from datetime import datetime
+from typing import List, Dict, Any
+
+_logger = logging.getLogger("memory.evolutionary")
+
+# Directory per i dati evolutivi (Sync con reflection.py)
+_DATA_DIR = os.getenv('CHROMA_DATA_DIR') or ('/data' if Path('/data').exists() else '.')
+EVO_PATH  = Path(_DATA_DIR) / 'evolutionary_rules.json'
+
+class EvolutionaryMemory:
+    def __init__(self, ai_client=None):
+        self.ai_client = ai_client
+        self.rules: Dict[str, Any] = {
+            "user_preferences": {},  # es. "language": "python", "style": "functional"
+            "operational_rules": [], # es. "Usa sempre pnpm invece di npm"
+            "domain_knowledge": {},  # es. "path/to/project": "description"
+            "last_updated": None
+        }
+        self._load()
+
+    def _load(self):
+        if EVO_PATH.exists():
+            try:
+                self.rules = json.loads(EVO_PATH.read_text())
+            except Exception as e:
+                _logger.error(f"[S960] Load error: {e}")
+
+    def _save(self):
+        try:
+            EVO_PATH.write_text(json.dumps(self.rules, indent=2, ensure_ascii=False))
+        except Exception as e:
+            _logger.error(f"[S960] Save error: {e}")
+
+    async def distill_and_evolve(self, session_summary: Dict[str, Any]):
+        """
+        Prende un sommario distillato (dal MemoryDistiller) e aggiorna le regole evolutive.
+        """
+        # 1. Estrazione euristica (in attesa di LLM integration)
+        # Se il sommario contiene fatti chiave, li integriamo
+        facts = session_summary.get("facts", [])
+        for fact in facts:
+            if ":" in fact:
+                k, v = fact.split(":", 1)
+                self.rules["domain_knowledge"][k.strip()] = v.strip()
+
+        # 2. Rilevamento preferenze (es. linguaggi usati con successo)
+        lessons = session_summary.get("lessons", [])
+        for lesson in lessons:
+            if lesson.get("type") == "success":
+                # Esempio: "Usato FastAPI con successo" -> preferenza per FastAPI
+                pass
+
+        self.rules["last_updated"] = datetime.now().isoformat()
+        self._save()
+        _logger.info("[S960] Memoria evolutiva aggiornata.")
+
+    def get_evolutionary_context(self) -> str:
+        """
+        Ritorna una stringa formattata da iniettare nel System Prompt.
+        """
+        if not self.rules["user_preferences"] and not self.rules["operational_rules"] and not self.rules["domain_knowledge"]:
+            return ""
+
+        context = "\n[MEMORIA EVOLUTIVA - REGOLE APPRESE]\n"
+        
+        if self.rules["user_preferences"]:
+            context += "Preferenze Utente:\n"
+            for k, v in self.rules["user_preferences"].items():
+                context += f"- {k}: {v}\n"
+                
+        if self.rules["operational_rules"]:
+            context += "Regole Operative:\n"
+            for rule in self.rules["operational_rules"]:
+                context += f"- {rule}\n"
+                
+        if self.rules["domain_knowledge"]:
+            context += "Conoscenza Dominio:\n"
+            for k, v in self.rules["domain_knowledge"].items():
+                context += f"- {k}: {v}\n"
+                
+        return context
+
+# Singleton
+evo_memory = EvolutionaryMemory()

memory/manager.py

@@ -8,6 +8,7 @@ from .working import WorkingMemory
 from .episodic import EpisodicMemory
 from .semantic import SemanticMemory
 from .reflection import ReflectionMemory
+from .evolutionary import evo_memory  # S960
 
 import logging
 _logger = logging.getLogger("memory.manager")
@@ -89,6 +90,9 @@ class MemoryManager:
     # ── get_context — algoritmo Waterfall TAM ──────────────────────────────────
 
     async def get_context(self, query: str, code_length: int = 0) -> str:
+        # S960: Recupero regole evolutive apprese
+        evo_context = evo_memory.get_evolutionary_context()
+
         """Assembla il contesto dai 4 layer con Waterfall Token Budget.
 
         TAM — Token-Aware Memory:
@@ -284,3 +288,4 @@ class MemoryManager:
             if self.episodic._db:
                 self.episodic._db.execute("DELETE FROM episodes")
                 self.episodic._db.commit()
+

sql/cache_schema.sql

@@ -0,0 +1,158 @@
+-- ============================================================================
+-- cache_schema.sql — Schema Tabella Cache per Supabase A
+-- 
+-- Eseguire su Supabase A (nodo analytics/cache) per creare la tabella cache
+-- ============================================================================
+
+-- Tabella Cache Entries
+CREATE TABLE IF NOT EXISTS cache_entries (
+    id BIGSERIAL PRIMARY KEY,
+    cache_key VARCHAR(32) NOT NULL UNIQUE,
+    strategy VARCHAR(50) NOT NULL,
+    identifier TEXT NOT NULL,
+    value TEXT NOT NULL,
+    ttl_seconds INTEGER DEFAULT 3600,
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    expires_at TIMESTAMP WITH TIME ZONE NOT NULL,
+    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    
+    -- Indici per performance
+    CONSTRAINT cache_key_idx UNIQUE (cache_key),
+    CONSTRAINT strategy_idx ON strategy,
+    CONSTRAINT expires_at_idx ON expires_at
+);
+
+-- Indice su expires_at per pulizia automatica
+CREATE INDEX IF NOT EXISTS idx_cache_expires_at ON cache_entries(expires_at);
+
+-- Indice su strategy per query veloci per strategia
+CREATE INDEX IF NOT EXISTS idx_cache_strategy ON cache_entries(strategy);
+
+-- Indice composito per query veloci (strategy + identifier)
+CREATE INDEX IF NOT EXISTS idx_cache_strategy_identifier ON cache_entries(strategy, identifier);
+
+-- Tabella Statistiche Cache
+CREATE TABLE IF NOT EXISTS cache_stats (
+    id BIGSERIAL PRIMARY KEY,
+    hits BIGINT DEFAULT 0,
+    misses BIGINT DEFAULT 0,
+    sets BIGINT DEFAULT 0,
+    deletes BIGINT DEFAULT 0,
+    evictions BIGINT DEFAULT 0,
+    recorded_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    
+    CONSTRAINT cache_stats_pkey PRIMARY KEY (id)
+);
+
+-- Tabella Audit Cache (opzionale)
+CREATE TABLE IF NOT EXISTS cache_audit (
+    id BIGSERIAL PRIMARY KEY,
+    action VARCHAR(50) NOT NULL,  -- 'GET', 'SET', 'DELETE', 'EVICT'
+    strategy VARCHAR(50) NOT NULL,
+    identifier TEXT NOT NULL,
+    cache_key VARCHAR(32),
+    status VARCHAR(20) NOT NULL,  -- 'HIT', 'MISS', 'SUCCESS', 'FAILURE'
+    duration_ms INTEGER,
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
+);
+
+-- Indice su created_at per query audit veloci
+CREATE INDEX IF NOT EXISTS idx_cache_audit_created_at ON cache_audit(created_at DESC);
+
+-- Indice su action per filtrare per tipo operazione
+CREATE INDEX IF NOT EXISTS idx_cache_audit_action ON cache_audit(action);
+
+-- ============================================================================
+-- Funzione: Pulizia automatica entry scaduti
+-- ============================================================================
+CREATE OR REPLACE FUNCTION cleanup_expired_cache()
+RETURNS TABLE(deleted_count INTEGER) AS $$
+BEGIN
+    DELETE FROM cache_entries WHERE expires_at < NOW();
+    RETURN QUERY SELECT COUNT(*)::INTEGER FROM cache_entries WHERE expires_at < NOW();
+END;
+$$ LANGUAGE plpgsql;
+
+-- ============================================================================
+-- Trigger: Aggiorna updated_at su UPDATE
+-- ============================================================================
+CREATE OR REPLACE FUNCTION update_cache_updated_at()
+RETURNS TRIGGER AS $$
+BEGIN
+    NEW.updated_at = NOW();
+    RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+CREATE TRIGGER cache_entries_updated_at_trigger
+BEFORE UPDATE ON cache_entries
+FOR EACH ROW
+EXECUTE FUNCTION update_cache_updated_at();
+
+-- ============================================================================
+-- View: Statistiche Cache Attuali
+-- ============================================================================
+CREATE OR REPLACE VIEW cache_stats_view AS
+SELECT
+    COUNT(*) as total_entries,
+    COUNT(CASE WHEN expires_at > NOW() THEN 1 END) as valid_entries,
+    COUNT(CASE WHEN expires_at <= NOW() THEN 1 END) as expired_entries,
+    COUNT(DISTINCT strategy) as unique_strategies,
+    MIN(created_at) as oldest_entry,
+    MAX(created_at) as newest_entry,
+    AVG(ttl_seconds) as avg_ttl_seconds
+FROM cache_entries;
+
+-- ============================================================================
+-- View: Hit Rate (ultimi 24 ore)
+-- ============================================================================
+CREATE OR REPLACE VIEW cache_hit_rate_24h AS
+SELECT
+    COUNT(CASE WHEN status = 'HIT' THEN 1 END) as hits,
+    COUNT(CASE WHEN status = 'MISS' THEN 1 END) as misses,
+    COUNT(*) as total_requests,
+    ROUND(
+        COUNT(CASE WHEN status = 'HIT' THEN 1 END)::NUMERIC / 
+        NULLIF(COUNT(*), 0) * 100,
+        2
+    ) as hit_rate_percent
+FROM cache_audit
+WHERE created_at > NOW() - INTERVAL '24 hours';
+
+-- ============================================================================
+-- Policy RLS (Row Level Security) — Opzionale
+-- ============================================================================
+-- Abilita RLS sulla tabella cache_entries
+ALTER TABLE cache_entries ENABLE ROW LEVEL SECURITY;
+
+-- Policy: Tutti possono leggere cache (read-only per A)
+CREATE POLICY "Allow read access to cache" ON cache_entries
+    FOR SELECT USING (true);
+
+-- Policy: Solo service role può scrivere/modificare cache
+CREATE POLICY "Allow write access to cache (service role only)" ON cache_entries
+    FOR INSERT WITH CHECK (current_user = 'postgres');
+
+CREATE POLICY "Allow update access to cache (service role only)" ON cache_entries
+    FOR UPDATE USING (current_user = 'postgres');
+
+CREATE POLICY "Allow delete access to cache (service role only)" ON cache_entries
+    FOR DELETE USING (current_user = 'postgres');
+
+-- ============================================================================
+-- Commenti Documentazione
+-- ============================================================================
+COMMENT ON TABLE cache_entries IS 'Archivio cache distribuito su Supabase A (read-heavy, non-critical)';
+COMMENT ON COLUMN cache_entries.cache_key IS 'Chiave cache univoca (SHA256 hash di strategy:identifier)';
+COMMENT ON COLUMN cache_entries.strategy IS 'Strategia cache: query, memory, embedding, conversation, analytics';
+COMMENT ON COLUMN cache_entries.identifier IS 'Identificatore univoco per il valore (es. session_id, query_hash)';
+COMMENT ON COLUMN cache_entries.value IS 'Valore memorizzato in cache (JSON serializzato)';
+COMMENT ON COLUMN cache_entries.ttl_seconds IS 'Time-to-live in secondi (tempo di scadenza)';
+COMMENT ON COLUMN cache_entries.expires_at IS 'Timestamp di scadenza (created_at + ttl_seconds)';
+
+COMMENT ON TABLE cache_stats IS 'Statistiche aggregate del cache layer';
+COMMENT ON TABLE cache_audit IS 'Audit log di tutte le operazioni cache (GET, SET, DELETE, EVICT)';
+
+COMMENT ON FUNCTION cleanup_expired_cache() IS 'Rimuove entry scaduti dalla cache';
+COMMENT ON VIEW cache_stats_view IS 'Statistiche attuali della cache (totale, valide, scadute, ecc.)';
+COMMENT ON VIEW cache_hit_rate_24h IS 'Hit rate del cache nelle ultime 24 ore';

tests/test_telegram_commands.py

@@ -0,0 +1,367 @@
+#!/usr/bin/env python3
+"""tests/test_telegram_commands.py — Test funzionale dei command handler Telegram.
+
+Cosa testa
+----------
+Ogni command handler (19 comandi + 2 callback dispatcher) viene eseguito
+davvero, ma tutte le chiamate HTTP verso api.telegram.org sono intercettate.
+
+Nessun messaggio viene inviato su Telegram.
+Nessuna env var richiesta.
+Nessuna connessione di rete necessaria.
+
+Come funziona
+-------------
+1. Le dipendenze esterne (fastapi, pydantic, httpx, api.*) vengono stubbate.
+2. Le funzioni _tg_reply / _tg_send / _tg_edit / _tg_typing / _tg_react
+   vengono rimpiazzate da AsyncMock PRIMA di ogni test, nel namespace del
+   modulo importato (import_module caching garantisce coerenza).
+3. Il test verifica che ogni handler abbia chiamato almeno una funzione TG.
+
+Uso
+---
+  cd backend && python -m pytest tests/test_telegram_commands.py -v
+  cd backend && python tests/test_telegram_commands.py         # standalone
+"""
+from __future__ import annotations
+import asyncio, importlib, sys, types, unittest
+from unittest.mock import AsyncMock, MagicMock, patch
+
+# ─────────────────────────────────────────────────────────────────────────────
+# 0. Stub dipendenze esterne (identico a test_telegram_imports.py)
+# ─────────────────────────────────────────────────────────────────────────────
+def _stub(name: str, **attrs) -> types.ModuleType:
+    m = types.ModuleType(name)
+    for k, v in attrs.items():
+        setattr(m, k, v)
+    sys.modules[name] = m
+    return m
+
+_fa = _stub("fastapi")
+_fa.APIRouter     = type("APIRouter",     (), {
+    "__init__": lambda self, **kw: None,
+    "post":     lambda self, *a, **kw: (lambda f: f),
+    "get":      lambda self, *a, **kw: (lambda f: f),
+})
+_fa.Request       = type("Request",       (), {})
+_fa.HTTPException = type("HTTPException", (Exception,), {})
+_fa.BackgroundTasks = type("BackgroundTasks", (), {})
+_stub("fastapi.responses", JSONResponse=type("JSONResponse", (), {}))
+_stub("fastapi.routing")
+_stub("starlette.requests", Request=_fa.Request)
+_stub("pydantic",           BaseModel=type("BaseModel", (), {}))
+
+# httpx — il client viene moccato per intercettare tutte le chiamate TG
+class _FakeResponse:
+    status_code = 200
+    def json(self): return {"ok": True, "result": {"message_id": 999}}
+    async def aread(self): return b'{"ok":true,"result":{"message_id":999}}'
+
+class _FakeAsyncClient:
+    def __init__(self, *a, **kw): pass
+    async def __aenter__(self): return self
+    async def __aexit__(self, *a): pass
+    async def post(self, url, **kw): return _FakeResponse()
+    async def get(self,  url, **kw): return _FakeResponse()
+
+_httpx = _stub("httpx", AsyncClient=_FakeAsyncClient, Response=_FakeResponse)
+_stub("httpcore")
+_stub("anyio")
+
+# Backend interno — stub per evitare import circolari
+for _m in [
+    "api.agent", "api.providers", "api.state", "api.unified_api",
+    "api.structured_log", "api.supabase_client", "api.exec",
+    "agents.unified_loop_fallback", "agents.goal_verifier",
+    "agents.memory_manager", "agents.audit_semantic_l2",
+]:
+    _stub(_m)
+
+# ─────────────────────────────────────────────────────────────────────────────
+# 1. Import moduli (dopo aver stubbato le dipendenze)
+# ─────────────────────────────────────────────────────────────────────────────
+def _imp(name: str):
+    full = f"api.{name}"
+    return sys.modules.get(full) or importlib.import_module(full)
+
+# Import nell'ordine delle dipendenze
+_tg_client = _imp("telegram_tg_client")
+_keyboards  = _imp("telegram_keyboards")
+_mon        = _imp("telegram_cmd_monitoring")
+_ai         = _imp("telegram_cmd_ai")
+_cb         = _imp("telegram_callbacks")
+
+CHAT_ID = 123456789   # chat_id fittizio — non viene mai usato realmente
+
+# ─────────────────────────────────────────────────────────────────────────────
+# 2. Helper — patch di tutte le _tg_* nel modulo target
+# ─────────────────────────────────────────────────────────────────────────────
+TG_FUNS = ["_tg_reply", "_tg_send", "_tg_edit", "_tg_typing",
+           "_tg_react", "_tg_photo", "_tg_answer_callback"]
+
+class TGCapture:
+    """Context manager: patcha le funzioni TG in 'mod', registra le chiamate."""
+    def __init__(self, *mods):
+        self.mods   = mods
+        self.mocks  = {}   # "mod.fun" → AsyncMock
+        self._patches = []
+
+    def __enter__(self):
+        for mod in self.mods:
+            for fun in TG_FUNS:
+                if hasattr(mod, fun):
+                    m = AsyncMock(return_value=999)
+                    p = patch.object(mod, fun, m)
+                    p.start()
+                    self._patches.append(p)
+                    self.mocks[f"{mod.__name__}.{fun}"] = m
+        return self
+
+    def __exit__(self, *a):
+        for p in self._patches:
+            p.stop()
+
+    def called_any(self) -> bool:
+        return any(m.called for m in self.mocks.values())
+
+    def calls(self) -> list[str]:
+        return [k.split(".")[-1] for k,m in self.mocks.items() if m.called]
+
+def run(coro):
+    return asyncio.get_event_loop().run_until_complete(coro)
+
+# ─────────────────────────────────────────────────────────────────────────────
+# 3. Test suite
+# ─────────────────────────────────────────────────────────────────────────────
+class TestTelegramCommands(unittest.TestCase):
+
+    # ── Monitoring ─────────────────────────────────────────────────────────
+    def test_cmd_help(self):
+        with TGCapture(_mon) as cap:
+            run(_mon._cmd_help(CHAT_ID))
+        self.assertTrue(cap.called_any(), f"_cmd_help non ha chiamato nulla. Mocks: {cap.calls()}")
+
+    def test_cmd_logs(self):
+        with TGCapture(_mon) as cap:
+            run(_mon._cmd_logs(CHAT_ID))
+        self.assertTrue(cap.called_any(), f"_cmd_logs: {cap.calls()}")
+
+    def test_cmd_logs_level(self):
+        """_cmd_logs accetta livello custom."""
+        with TGCapture(_mon) as cap:
+            run(_mon._cmd_logs(CHAT_ID, level="ERROR"))
+        self.assertTrue(cap.called_any())
+
+    def test_cmd_status(self):
+        with TGCapture(_mon) as cap:
+            run(_mon._cmd_status(CHAT_ID))
+        self.assertTrue(cap.called_any(), f"_cmd_status: {cap.calls()}")
+
+    def test_cmd_commit_summary(self):
+        with TGCapture(_mon) as cap:
+            run(_mon._cmd_commit_summary(CHAT_ID))
+        self.assertTrue(cap.called_any(), f"_cmd_commit_summary: {cap.calls()}")
+
+    def test_cmd_check(self):
+        with TGCapture(_mon) as cap:
+            run(_mon._cmd_check(CHAT_ID))
+        self.assertTrue(cap.called_any(), f"_cmd_check: {cap.calls()}")
+
+    def test_cmd_tasks(self):
+        with TGCapture(_mon) as cap:
+            run(_mon._cmd_tasks(CHAT_ID))
+        self.assertTrue(cap.called_any(), f"_cmd_tasks: {cap.calls()}")
+
+    # ── AI commands ────────────────────────────────────────────────────────
+    def test_cmd_do_empty_goal(self):
+        """_cmd_do con goal vuoto deve rispondere con la keyboard quick-pick."""
+        with TGCapture(_ai) as cap:
+            run(_ai._cmd_do(CHAT_ID, goal=""))
+        self.assertTrue(cap.called_any(), f"_cmd_do(goal=''): {cap.calls()}")
+
+    def test_cmd_do_with_goal(self):
+        """_cmd_do con goal reale avvia lo streaming — la prima chiamata TG è _tg_send."""
+        with TGCapture(_ai) as cap:
+            run(_ai._cmd_do(CHAT_ID, goal="analizza i log"))
+        self.assertTrue(cap.called_any(), f"_cmd_do(goal): {cap.calls()}")
+
+    def test_cmd_do_saves_last_goal(self):
+        """_cmd_do salva il goal in _LAST_GOAL per il tasto Rifai."""
+        with TGCapture(_ai):
+            run(_ai._cmd_do(CHAT_ID, goal="test retry goal"))
+        from api.telegram_keyboards import _LAST_GOAL
+        self.assertEqual(_LAST_GOAL.get(CHAT_ID), "test retry goal")
+
+    def test_cmd_autofix(self):
+        with TGCapture(_ai) as cap:
+            run(_ai._cmd_autofix(CHAT_ID))
+        self.assertTrue(cap.called_any(), f"_cmd_autofix: {cap.calls()}")
+
+    def test_cmd_autofix_with_hint(self):
+        with TGCapture(_ai) as cap:
+            run(_ai._cmd_autofix(CHAT_ID, hint="TypeError in providers.py"))
+        self.assertTrue(cap.called_any())
+
+    def test_cmd_nota(self):
+        with TGCapture(_ai) as cap:
+            run(_ai._cmd_nota(CHAT_ID, text="ricordati di aggiornare il token"))
+        self.assertTrue(cap.called_any(), f"_cmd_nota: {cap.calls()}")
+
+    def test_cmd_cerca(self):
+        with TGCapture(_ai) as cap:
+            run(_ai._cmd_cerca(CHAT_ID, query="FastAPI async streaming"))
+        self.assertTrue(cap.called_any(), f"_cmd_cerca: {cap.calls()}")
+
+    def test_cmd_meteo(self):
+        with TGCapture(_ai) as cap:
+            run(_ai._cmd_meteo(CHAT_ID, city="Milano"))
+        self.assertTrue(cap.called_any(), f"_cmd_meteo: {cap.calls()}")
+
+    def test_cmd_riepilogo(self):
+        with TGCapture(_ai) as cap:
+            run(_ai._cmd_riepilogo(CHAT_ID))
+        self.assertTrue(cap.called_any(), f"_cmd_riepilogo: {cap.calls()}")
+
+    def test_cmd_scan_now(self):
+        with TGCapture(_ai) as cap:
+            run(_ai._cmd_scan_now(CHAT_ID))
+        self.assertTrue(cap.called_any(), f"_cmd_scan_now: {cap.calls()}")
+
+    def test_cmd_coord(self):
+        with TGCapture(_ai) as cap:
+            run(_ai._cmd_coord(CHAT_ID))
+        self.assertTrue(cap.called_any(), f"_cmd_coord: {cap.calls()}")
+
+    def test_cmd_git(self):
+        with TGCapture(_ai) as cap:
+            run(_ai._cmd_git(CHAT_ID))
+        self.assertTrue(cap.called_any(), f"_cmd_git: {cap.calls()}")
+
+    def test_cmd_git_custom_n(self):
+        with TGCapture(_ai) as cap:
+            run(_ai._cmd_git(CHAT_ID, n=10))
+        self.assertTrue(cap.called_any())
+
+    def test_cmd_telemetry(self):
+        with TGCapture(_ai) as cap:
+            run(_ai._cmd_telemetry(CHAT_ID))
+        self.assertTrue(cap.called_any(), f"_cmd_telemetry: {cap.calls()}")
+
+    def test_cmd_score(self):
+        with TGCapture(_ai) as cap:
+            run(_ai._cmd_score(CHAT_ID))
+        self.assertTrue(cap.called_any(), f"_cmd_score: {cap.calls()}")
+
+    def test_cmd_bench(self):
+        with TGCapture(_ai) as cap:
+            run(_ai._cmd_bench(CHAT_ID))
+        self.assertTrue(cap.called_any(), f"_cmd_bench: {cap.calls()}")
+
+    def test_cmd_improve(self):
+        with TGCapture(_ai) as cap:
+            run(_ai._cmd_improve(CHAT_ID))
+        self.assertTrue(cap.called_any(), f"_cmd_improve: {cap.calls()}")
+
+    # ── Callback dispatcher ────────────────────────────────────────────────
+    def _make_cb(self, data: str) -> dict:
+        return {
+            "id": "cb_001",
+            "from": {"id": CHAT_ID, "first_name": "Test"},
+            "message": {"message_id": 42, "chat": {"id": CHAT_ID}},
+            "chat_instance": "ci",
+            "data": data,
+        }
+
+    def test_handle_callback_help(self):
+        with TGCapture(_mon, _ai, _cb) as cap:
+            run(_cb._handle_callback(self._make_cb("tgw_help"), token="fake"))
+        self.assertTrue(cap.called_any(), "callback tgw_help: nessuna chiamata TG")
+
+    def test_handle_callback_status(self):
+        with TGCapture(_mon, _ai, _cb) as cap:
+            run(_cb._handle_callback(self._make_cb("tgw_status"), token="fake"))
+        self.assertTrue(cap.called_any(), "callback tgw_status")
+
+    def test_handle_callback_tasks(self):
+        with TGCapture(_mon, _ai, _cb) as cap:
+            run(_cb._handle_callback(self._make_cb("tgw_tasks"), token="fake"))
+        self.assertTrue(cap.called_any(), "callback tgw_tasks")
+
+    def test_handle_callback_do(self):
+        with TGCapture(_mon, _ai, _cb) as cap:
+            run(_cb._handle_callback(self._make_cb("agent"), token="fake"))
+        self.assertTrue(cap.called_any(), "callback agent (→ _cmd_do)")
+
+    def test_handle_callback_autofix(self):
+        with TGCapture(_mon, _ai, _cb) as cap:
+            run(_cb._handle_callback(self._make_cb("tgw_autofix"), token="fake"))
+        self.assertTrue(cap.called_any(), "callback tgw_autofix")
+
+    def test_handle_callback_bench(self):
+        with TGCapture(_mon, _ai, _cb) as cap:
+            run(_cb._handle_callback(self._make_cb("tgw_bench"), token="fake"))
+        self.assertTrue(cap.called_any(), "callback tgw_bench")
+
+    def test_handle_callback_score(self):
+        with TGCapture(_mon, _ai, _cb) as cap:
+            run(_cb._handle_callback(self._make_cb("tgw_score"), token="fake"))
+        self.assertTrue(cap.called_any(), "callback tgw_score")
+
+    def test_handle_callback_improve(self):
+        with TGCapture(_mon, _ai, _cb) as cap:
+            run(_cb._handle_callback(self._make_cb("tgw_improve"), token="fake"))
+        self.assertTrue(cap.called_any(), "callback tgw_improve")
+
+    def test_handle_callback_retry(self):
+        """tgw_retry rilegge _LAST_GOAL — deve funzionare anche se vuoto."""
+        with TGCapture(_mon, _ai, _cb) as cap:
+            run(_cb._handle_callback(self._make_cb("tgw_retry"), token="fake"))
+        self.assertTrue(cap.called_any(), "callback tgw_retry")
+
+    def test_handle_callback_qp_bug(self):
+        """quick-pick qp_bug lancia _cmd_do con goal preimpostato."""
+        with TGCapture(_mon, _ai, _cb) as cap:
+            run(_cb._handle_callback(self._make_cb("qp_bug"), token="fake"))
+        self.assertTrue(cap.called_any(), "callback qp_bug")
+
+    def test_handle_inline_empty(self):
+        """Inline query vuota → risponde con lista comandi."""
+        iq = {"id": "iq_001", "from": {"id": CHAT_ID}, "query": ""}
+        with TGCapture(_cb) as cap:
+            run(_cb._handle_inline(iq, token="fake"))
+        # La risposta va a answerInlineQuery — httpx è stubbato, non fallisce
+
+    def test_handle_inline_with_query(self):
+        iq = {"id": "iq_002", "from": {"id": CHAT_ID}, "query": "analizza bug login"}
+        with TGCapture(_cb):
+            run(_cb._handle_inline(iq, token="fake"))
+
+    # ── Guardrail: nessun messaggio reale inviato ──────────────────────────
+    def test_no_real_http_calls(self):
+        """Verifica che httpx.AsyncClient.post non chiami api.telegram.org reale."""
+        real_calls: list[str] = []
+        original_post = _FakeAsyncClient.post
+        async def spy_post(self, url, **kw):
+            real_calls.append(url)
+            return _FakeResponse()
+        _FakeAsyncClient.post = spy_post
+        try:
+            with TGCapture(_mon):
+                run(_mon._cmd_help(CHAT_ID))
+            # Se arriva qui senza errori di rete → ok (le _tg_* erano moccate,
+            # quindi httpx.post non è stato chiamato direttamente)
+            for url in real_calls:
+                self.assertNotIn("api.telegram.org", url,
+                    f"Chiamata reale a api.telegram.org intercettata: {url}")
+        finally:
+            _FakeAsyncClient.post = original_post
+
+
+if __name__ == "__main__":
+    import pathlib
+    backend = pathlib.Path(__file__).parent.parent
+    if str(backend) not in sys.path:
+        sys.path.insert(0, str(backend))
+    runner = unittest.TextTestRunner(verbosity=2)
+    result = runner.run(unittest.TestLoader().loadTestsFromTestCase(TestTelegramCommands))
+    sys.exit(0 if result.wasSuccessful() else 1)

tests/test_telegram_imports.py

@@ -0,0 +1,162 @@
+#!/usr/bin/env python3
+"""tests/test_telegram_imports.py — Smoke test import chain moduli M2 split.
+
+Verifica che tutti i 6 moduli Telegram si importino correttamente senza
+avviare FastAPI né connettersi a Telegram. Eseguibile in CI senza env vars.
+
+Uso:
+  cd backend && python -m pytest tests/test_telegram_imports.py -v
+  # oppure direttamente:
+  cd backend && python tests/test_telegram_imports.py
+"""
+from __future__ import annotations
+import importlib, sys, types, unittest
+
+# ── Stub dipendenze esterne non disponibili in CI ─────────────────────────────
+def _stub(name: str, **attrs) -> types.ModuleType:
+    m = types.ModuleType(name)
+    for k, v in attrs.items():
+        setattr(m, k, v)
+    sys.modules[name] = m
+    return m
+
+# fastapi
+_fa = _stub("fastapi")
+_fa.APIRouter   = type("APIRouter",   (), {"__init__": lambda self, **kw: None,
+                                           "post":     lambda self, *a, **kw: (lambda f: f),
+                                           "get":      lambda self, *a, **kw: (lambda f: f)})
+_fa.Request     = type("Request",     (), {})
+_fa.HTTPException = type("HTTPException", (Exception,), {})
+_fa.BackgroundTasks = type("BackgroundTasks", (), {})
+_stub("fastapi.responses",   JSONResponse=type("JSONResponse", (), {}))
+_stub("fastapi.routing")
+_stub("starlette.requests",  Request=_fa.Request)
+
+# pydantic
+_stub("pydantic", BaseModel=type("BaseModel", (), {}))
+
+# httpx
+_httpx = _stub("httpx")
+_httpx.AsyncClient = type("AsyncClient", (), {
+    "__aenter__": lambda self: self, "__aexit__": lambda *a: None,
+    "post": lambda self, *a, **kw: None,
+})
+_stub("httpx._models")
+
+# httpcore, anyio (transitive deps di httpx)
+_stub("httpcore")
+_stub("anyio")
+
+# Altre dipendenze del backend usate dalle funzioni TG
+for _mod in [
+    "api.agent", "api.providers", "api.state", "api.unified_api",
+    "api.structured_log", "api.supabase_client", "api.exec",
+    "agents.unified_loop_fallback", "agents.goal_verifier",
+    "agents.memory_manager", "agents.audit_semantic_l2",
+]:
+    _stub(_mod)
+
+
+# ── Test ──────────────────────────────────────────────────────────────────────
+class TestTelegramImportChain(unittest.TestCase):
+
+    def _import(self, modname: str) -> types.ModuleType:
+        """Importa (o re-importa) un modulo dal package api."""
+        full = f"api.{modname}"
+        if full in sys.modules:
+            return sys.modules[full]
+        return importlib.import_module(full)
+
+    # ── Layer 0 ───────────────────────────────────────────────────────────────
+    def test_01_tg_client(self):
+        """telegram_tg_client — nessuna dipendenza interna."""
+        m = self._import("telegram_tg_client")
+        for sym in ("_get_bot_token", "_tg_reply", "_tg_send", "_tg_edit",
+                    "_tg_photo", "_tg_typing", "_tg_react",
+                    "_tg_answer_callback", "_fmt_elapsed", "_log_tg_exc"):
+            self.assertTrue(hasattr(m, sym), f"Manca {sym} in tg_client")
+
+    # ── Layer 1 ───────────────────────────────────────────────────────────────
+    def test_02_keyboards(self):
+        """telegram_keyboards — solo costanti/dict."""
+        m = self._import("telegram_keyboards")
+        for sym in ("_MAIN_KB", "_QUICK_PICK_KB", "_after_task_kb",
+                    "_LAST_GOAL", "_BENCH_CACHE"):
+            self.assertTrue(hasattr(m, sym), f"Manca {sym} in keyboards")
+
+    # ── Layer 2 ───────────────────────────────────────────────────────────────
+    def test_03_cmd_monitoring(self):
+        """telegram_cmd_monitoring — importa da tg_client + keyboards."""
+        m = self._import("telegram_cmd_monitoring")
+        for sym in ("_cmd_help", "_cmd_logs", "_cmd_status",
+                    "_cmd_commit_summary", "_cmd_check", "_cmd_tasks"):
+            self.assertTrue(hasattr(m, sym), f"Manca {sym} in cmd_monitoring")
+
+    def test_04_cmd_ai(self):
+        """telegram_cmd_ai — importa da tg_client + keyboards."""
+        m = self._import("telegram_cmd_ai")
+        for sym in ("_cmd_do", "_cmd_autofix", "_cmd_nota", "_cmd_cerca",
+                    "_cmd_meteo", "_cmd_riepilogo", "_cmd_score", "_cmd_bench",
+                    "_cmd_improve", "_cmd_git", "_cmd_coord",
+                    "_cmd_scan_now", "_cmd_telemetry"):
+            self.assertTrue(hasattr(m, sym), f"Manca {sym} in cmd_ai")
+
+    # ── Layer 3 ──────────────────────��────────────────────────────────────────
+    def test_05_callbacks(self):
+        """telegram_callbacks — importa da tg_client + keyboards + cmd_ai + cmd_monitoring."""
+        m = self._import("telegram_callbacks")
+        for sym in ("_handle_inline", "_handle_callback"):
+            self.assertTrue(hasattr(m, sym), f"Manca {sym} in callbacks")
+
+    # ── Layer 4 (router) ──────────────────────────────────────────────────────
+    def test_06_webhook(self):
+        """telegram_webhook — router puro, importa da tutti i moduli."""
+        m = self._import("telegram_webhook")
+        self.assertTrue(hasattr(m, "router"),
+                        "Manca 'router' in telegram_webhook")
+
+    # ── Import chain completo ─────────────────────────────────────────────────
+    def test_07_no_circular_imports(self):
+        """Nessun import circolare: webhook importa callbacks che NON importa webhook."""
+        cb = sys.modules.get("api.telegram_callbacks")
+        wh = sys.modules.get("api.telegram_webhook")
+        if cb and wh:
+            # callbacks non deve avere 'telegram_webhook' come dipendenza diretta
+            cb_src = getattr(cb, "__file__", "")
+            import ast, pathlib
+            if cb_src and pathlib.Path(cb_src).exists():
+                tree = ast.parse(pathlib.Path(cb_src).read_text())
+                for node in ast.walk(tree):
+                    if isinstance(node, ast.ImportFrom):
+                        self.assertNotIn("telegram_webhook", (node.module or ""),
+                            "Import circolare: callbacks → webhook")
+
+    def test_08_main_kb_in_keyboards_not_tg_client(self):
+        """_MAIN_KB deve stare in keyboards, NON in tg_client."""
+        tc = self._import("telegram_tg_client")
+        kb = self._import("telegram_keyboards")
+        self.assertFalse(hasattr(tc, "_MAIN_KB"),
+            "_MAIN_KB non deve essere in tg_client")
+        self.assertTrue(hasattr(kb, "_MAIN_KB"),
+            "_MAIN_KB deve essere in keyboards")
+
+    def test_09_scan_now_in_cmd_ai(self):
+        """_cmd_scan_now/_cmd_git/_cmd_coord/_cmd_telemetry devono stare in cmd_ai."""
+        ai  = self._import("telegram_cmd_ai")
+        mon = self._import("telegram_cmd_monitoring")
+        for sym in ("_cmd_scan_now", "_cmd_git", "_cmd_coord", "_cmd_telemetry"):
+            self.assertTrue(hasattr(ai, sym),
+                f"{sym} deve essere in cmd_ai")
+            self.assertFalse(hasattr(mon, sym),
+                f"{sym} NON deve essere in cmd_monitoring")
+
+
+if __name__ == "__main__":
+    # Aggiungi backend/ al path se eseguito da root
+    import os, pathlib
+    backend = pathlib.Path(__file__).parent.parent
+    if str(backend) not in sys.path:
+        sys.path.insert(0, str(backend))
+    runner = unittest.TextTestRunner(verbosity=2)
+    result = runner.run(unittest.TestLoader().loadTestsFromTestCase(TestTelegramImportChain))
+    sys.exit(0 if result.wasSuccessful() else 1)

tools/registry.py

@@ -1,3 +1,4 @@
+# sync: 2026-07-02T21:03
 """
 registry.py — Tool Registry
 Ogni tool ha: goal, required_inputs, risk_level, fallbacks, _fn.
@@ -63,6 +64,7 @@ from tools.registry_web import (
 from tools.registry_fs import (
     _read_file, _write_file, _ts_syntax_check, _apply_patch, _execute_shell,
     _web_research, _send_email, _database_query, _call_api, _execute_sql, _create_pdf,
+    _read_file_range, _grep_file, _file_metadata,
 )
 from tools.registry_dev import (
     _directory_tree, _file_search, _git_status, _git_clone, _git_diff,
@@ -689,7 +691,17 @@ TOOL_REGISTRY: dict[str, dict] = {
             "P30-B1: Analisi statica Python in-process — zero exec_engine, <5ms. "
             "code: stringa Python (obbligatorio). filename: nome file per errori (default '<string>'). "
             "Ritorna: syntax_ok (bool), errors[] (type/message/line/col), "
-            "complexity{total_lines/functions/classes/imports/max_nesting},
+            "complexity{total_lines/functions/classes/imports/max_nesting}, "
+            "suggestions[] (max 5 actionable), summary (stringa leggibile). "
+            "Usare per: verificare sintassi prima di exec, analizzare qualità codice, "
+            "ottenere metriche strutturali, suggerire refactoring."
+        ),
+        "required_inputs": ["code"],
+        "optional_inputs": {"filename": "<string>", "content": ""},  # GAP-1: alias per 'code' (frontend compat)
+        "risk_level": "low",
+        "fallbacks": [],
+        "_fn": _python_analyze,
+    },
     "read_file_range": {
         "name": "read_file_range",
         "goal": "Legge un range specifico di righe da un file (ottimizzato per file grandi)",
@@ -731,15 +743,4 @@ TOOL_REGISTRY: dict[str, dict] = {
         "fallbacks": [],
         "_fn": _file_metadata,
     },
-, "
-            "suggestions[] (max 5 actionable), summary (stringa leggibile). "
-            "Usare per: verificare sintassi prima di exec, analizzare qualità codice, "
-            "ottenere metriche strutturali, suggerire refactoring."
-        ),
-        "required_inputs": ["code"],
-        "optional_inputs": {"filename": "<string>", "content": ""},  # GAP-1: alias per 'code' (frontend compat)
-        "risk_level": "low",
-        "fallbacks": [],
-        "_fn": _python_analyze,
-    },
 }

tools/registry_fs.py

@@ -30,7 +30,7 @@ import pathlib
 import itertools
 
 async def _read_file_range(path: str, start_line: int = 1, end_line: int = 100, encoding: str = "utf-8") -> dict:
-    \"\"\"P42: Legge un range specifico di righe da un file (ottimizzato per file grandi).\"\"\"
+    """P42: Legge un range specifico di righe da un file (ottimizzato per file grandi)."""
     try:
         _p = pathlib.Path(path)
         if not _p.exists():
@@ -53,7 +53,7 @@ async def _read_file_range(path: str, start_line: int = 1, end_line: int = 100,
         return {"ok": False, "error": str(exc)}
 
 async def _grep_file(path: str, pattern: str, max_results: int = 20, encoding: str = "utf-8") -> dict:
-    \"\"\"P42: Cerca un pattern in un file senza caricarlo interamente in RAM.\"\"\"
+    """P42: Cerca un pattern in un file senza caricarlo interamente in RAM."""
     try:
         _p = pathlib.Path(path)
         if not _p.exists():
@@ -79,7 +79,7 @@ async def _grep_file(path: str, pattern: str, max_results: int = 20, encoding: s
         return {"ok": False, "error": str(exc)}
 
 async def _file_metadata(path: str) -> dict:
-    \"\"\"P42: Ottiene metadati del file (dimensione, numero righe) senza leggere il contenuto.\"\"\"
+    """P42: Ottiene metadati del file (dimensione, numero righe) senza leggere il contenuto."""
     try:
         _p = pathlib.Path(path)
         if not _p.exists():