runbook: telegram duplication getUpdates offset + fix DNS agents

common/telegram-duplication-getupdates-offset.md

@@ -0,0 +1,30 @@
+# Telegram — réponses dupliquées 4-5× + tokens facturés 4-5× (relivraison getUpdates)
+
+**Date** : 09/07/2026 · **Instances** : les 3 (observé sur nyora, présent sur tt/perso)
+
+## Symptômes
+- La même réponse arrive 4-5 fois sur Telegram.
+- OpenCode/OpenRouter facture 4-5 complétions pour un seul message utilisateur.
+
+## Cause racine
+Le NAT Tunisie Telecom coupe les connexions longues (même comportement que le tunnel Contabo). Quand la connexion `getUpdates` tombe **avant la confirmation d'offset** à Telegram, python-telegram-bot logge :
+`When polling for updates is restarted, updates may be fetched again`
+→ Telegram relivre le même update après reconnexion → l'agent retraite le message de bout en bout (appel LLM facturé + envoi de la réponse), en boucle jusqu'à ce qu'un commit d'offset passe.
+
+**Facteur aggravant** : résolution DNS dans les containers agents à ~4 s (Docker embedded → Pi-hole), avec échecs francs intermittents (`Temporary failure in name resolution`) qui multipliaient les coupures.
+
+## Fix appliqué (09/07/2026)
+`dns: [1.1.1.1, 9.9.9.9]` ajouté aux 3 services hermes-agent-* dans `/volume1/docker/hermes-platform/docker-compose.yml` → contourne Pi-hole pour ces containers. Résolution mesurée : **4,04 s → 0,03 s**.
+Recreate des 3 agents, UID data/ vérifiés 1026:100, Telegram `connected` sur les 3.
+
+## Diagnostic rapide (si récidive)
+```
+docker logs --since 48h hermes-agent-nyora 2>&1 | grep -cE 'updates may be fetched again|scheduling reconnect|name resolution'
+docker exec hermes-agent-nyora python3 -c 'import socket,time; t=time.time(); print(socket.gethostbyname("api.telegram.org"), round(time.time()-t,2),"s")'
+```
+
+## Limites / suites possibles
+- Le NAT TT reste la cause première : le fix DNS réduit drastiquement les coupures mais ne les élimine pas.
+- Dédup applicative impossible sans image custom : code gateway cuit dans `nousresearch/hermes-agent:latest` (seul /opt/data monté). Vérifier si une image plus récente corrige la gestion d'offset (changement d'image = accord Nabil requis).
+- Timeout getUpdates non exposé dans config.yaml — à creuser doc Hermes si récidive.
+- Distinct : mimo-v2.5 renvoie des HTTP 400 « Param Incorrect » (Xiaomi) — problème séparé du pilote, non traité ici.