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>

ansible/roles/llama_server/templates/llama-watchdog.service.j2

@@ -0,0 +1,15 @@
+[Unit]
+Description=llama-watchdog (auto-réparation du llama-server figé — ROCm gfx1031)
+After=llama-server.service
+Wants=llama-server.service
+
+[Service]
+Type=simple
+User=root
+ExecStart=/usr/local/bin/llama-watchdog
+Restart=always
+RestartSec=10
+SyslogIdentifier=llama-watchdog
+
+[Install]
+WantedBy=multi-user.target

ansible/roles/llama_server/templates/llama-watchdog.sh.j2

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# llama-watchdog — auto-réparation du llama-server figé (instabilité ROCm gfx1031).
+#
+# Le piège (cf. admin/incidents-llm-gpu.md) : un llama-server wedgé répond encore à
+# /health et /v1/models, mais la GÉNÉRATION est morte. On sonde donc par une VRAIE
+# génération (max_tokens:1, /no_think). Sur N échecs consécutifs → restart local.
+#
+# Tourne en root (service systemd) → peut `systemctl restart` en local, sans SSH ni sudo
+# distant. Déployé/géré par le rôle Ansible `llama_server`.
+set -u
+
+URL="http://127.0.0.1:{{ llama_watchdog_port }}/v1/chat/completions"
+MODEL="{{ llama_watchdog_model }}"
+SERVICE="{{ llama_watchdog_service }}"
+INTERVAL="{{ llama_watchdog_interval }}"
+TIMEOUT="{{ llama_watchdog_timeout }}"
+THRESHOLD="{{ llama_watchdog_failures }}"
+
+payload="{\"model\":\"${MODEL}\",\"messages\":[{\"role\":\"user\",\"content\":\"ping /no_think\"}],\"max_tokens\":1}"
+
+probe() {  # echo le code HTTP ; "000" si pas de réponse (timeout/refus)
+  curl -s -m "$TIMEOUT" -o /tmp/llama-watchdog.body -w '%{http_code}' \
+    "$URL" -H 'Content-Type: application/json' -d "$payload" 2>/dev/null || echo "000"
+}
+
+fails=0
+while true; do
+  code=$(probe)
+
+  if [ "$code" = "200" ]; then
+    fails=0
+  elif [ "$code" = "503" ] && grep -q "Loading model" /tmp/llama-watchdog.body 2>/dev/null; then
+    # Rechargement VRAM (juste après un restart) → ni échec ni succès : on patiente.
+    :
+  else
+    fails=$((fails + 1))
+    echo "watchdog: probe KO (HTTP ${code}) — ${fails}/${THRESHOLD}"
+    if [ "$fails" -ge "$THRESHOLD" ]; then
+      echo "watchdog: ${SERVICE} figé (${THRESHOLD} échecs consécutifs) → restart"
+      systemctl restart "$SERVICE"
+      echo "watchdog: restart émis ; attente du rechargement du modèle…"
+      # Cooldown : attendre que la génération remarche (couvre mort de l'instance + load VRAM).
+      for _ in $(seq 1 30); do
+        sleep 5
+        [ "$(probe)" = "200" ] && { echo "watchdog: ${SERVICE} de nouveau réactif"; break; }
+      done
+      fails=0
+    fi
+  fi
+
+  sleep "$INTERVAL"
+done