feat: anti-502 LLM — heartbeat (litellm) + watchdog auto-réparation (llama_server) (#23)

* feat(litellm): heartbeat anti-502 + request_timeout 20s

Cause racine du 502 « 1ʳᵉ demande après une pause » : la connexion keep-alive
LiteLLM↔llama-server devient inactive → llama-server la ferme → LiteLLM garde le
socket mort → la requête suivante part dans le vide → timeout → 502.

- llm-heartbeat : service systemd qui appelle hermes-default toutes les 15s
  (max_tokens:1, /no_think → ~10ms GPU) → la connexion n'est jamais inactive,
  jamais périmée. Logge les échecs → sert aussi de sonde (vraie génération).
- request_timeout 60→20s : un socket périmé échoue vite, dans la fenêtre où
  num_retries:2 peut rejouer sur une connexion neuve (sinon le client abandonnait
  avant le retry → 502 sec).
- Doc : admin/incidents-llm-gpu.md (fix racine) + README rôle.

⚠️ heartbeat appelle hermes-default en continu → si bascule sur Claude (facturé),
mettre llm_heartbeat_enabled: false. request_timeout global → remonter si Claude.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* feat(llama_server): watchdog auto-réparation du wedge ROCm

Service systemd local sur gpu-01 qui sonde une vraie génération sur :1234
(pas juste /health, qui ment quand le slot d'inférence est figé). Sur N
échecs consécutifs → systemctl restart llama-server en local (root, sans
SSH/sudo distant). Gère le 503 "Loading model" post-restart sans le compter
comme échec.

Complète le llm-heartbeat (rôle litellm) : le heartbeat empêche la péremption
par inactivité de la connexion ; le watchdog répare le figeage du serveur lui-même.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

admin/incidents-llm-gpu.md

@@ -124,8 +124,47 @@ tentative) et renvoie 502.
    (⚠️ redémarre LiteLLM — service partagé Hermes/n8n/Open WebUI/Ghostfolio).
 3. **Purge immédiate** (sans attendre l'IaC) : `sudo systemctl restart litellm` vide le pool.
 
-### Reste à faire (cause racine)
+### Fix racine — heartbeat (déployé)
 
-Tant que `llama-server` se fige et nécessite des redémarrages, le pool LiteLLM se re-périme.
-La vraie prévention = **watchdog de génération réelle** qui détecte le freeze et, idéalement,
-bounce **à la fois** llama-server **et** litellm pour repartir sur des connexions saines.
+Le timeout/retry ne fait que **borner** la casse : la 1ʳᵉ demande après une pause restait lente
+(la connexion keep-alive devient inactive → llama-server la ferme → LiteLLM garde le socket mort).
+La **vraie** cause = la connexion qui devient *périmée pendant l'inactivité*.
+
+**Solution** : `llm-heartbeat` (rôle `litellm`) — un service systemd qui appelle `hermes-default`
+toutes les `llm_heartbeat_interval` s (défaut 15 s, `max_tokens:1`, `/no_think` → ~10 ms GPU).
+La connexion LiteLLM↔llama-server n'est **jamais** inactive → jamais périmée → la 1ʳᵉ vraie
+demande tombe toujours sur un tuyau vivant. Logge les échecs (`journalctl -u llm-heartbeat`),
+donc sert aussi de **sonde** (génération réelle, pas juste `/health`).
+
+```bash
+ansible-playbook -i inventory.yml playbooks/storage-01.yml --tags litellm   # déploie heartbeat + config
+systemctl status llm-heartbeat ; journalctl -u llm-heartbeat -f             # vérifier
+```
+
+⚠️ Le heartbeat appelle `hermes-default` en continu → si on bascule cet alias sur **Claude**
+(API facturée), mettre `llm_heartbeat_enabled: false`.
+
+### Fix racine #2 — watchdog gpu-01 (déployé)
+
+Le heartbeat empêche la *péremption par inactivité*, mais si `llama-server` **se fige**
+carrément (wedge ROCm), il le **détecte** sans le **réparer**. C'est désormais couvert par le
+`llama-watchdog` (rôle `llama_server`) : un service systemd **local sur gpu-01** qui sonde une
+**vraie génération** sur `:1234` toutes les `llama_watchdog_interval` s (défaut 20 s,
+`max_tokens:1`, `/no_think`). Sur `llama_watchdog_failures` échecs consécutifs (défaut 3) →
+`systemctl restart llama-server` **en local** (tourne en root, ni SSH ni sudo distant), puis
+cooldown jusqu'à ce que la génération remarche (gère le `503 "Loading model"` du rechargement
+VRAM sans le compter comme échec).
+
+```bash
+ansible-playbook -i inventory.yml playbooks/gpu-01.yml --tags llama_server   # déploie le watchdog
+systemctl status llama-watchdog ; journalctl -u llama-watchdog -f            # vérifier
+```
+
+Pourquoi sur gpu-01 (et pas piloté depuis storage-01 via le heartbeat) : le restart est
+**local** → pas de SSH/sudo inter-hôtes, répare même si LiteLLM ou le réseau cluster est en
+vrac, et sonde au plus près du serveur figé.
+
+**Défense en profondeur (3 couches)** :
+1. `llm-heartbeat` (storage-01, rôle `litellm`) — garde la connexion chaude (anti-péremption).
+2. `request_timeout: 20` + `num_retries: 2` (LiteLLM) + retry STT-server — bornent le blip.
+3. `llama-watchdog` (gpu-01, rôle `llama_server`) — répare le wedge ROCm à la source.