# KA Guardian — ka2 · ka4 · ka6 (agents gardiens des connecteurs ET des sites)

Un seul repo pour les 3 sites gardiens : www.ka2.bot, www.ka4.bot, www.ka6.bot. Chaque agent est une instance de orchestrator/main.py (env AGENT=ka2|ka4|ka6), identité (accent, tagline, services surveillés) dans topology.json.

# Où sont les apps ? → le registre mld, jamais en dur (2026-09-04)

L'emplacement de chaque service (nœud, IP LAN, répertoire, port web, process PM2) vient du registre de la passerelle M1M32:~/dispatch/registry.json, appliqué par orchestrator/registry.py au démarrage et à chaque tick (registry.refresh mute SERVICES/NODES en place ; les déménagements sont journalisés dans le flux et dans /api/state → registry.changes). topology.json ne porte que la correspondance service → registry_app (+ pm2_exclude optionnel) ; ses champs node/dir/web_port/pm2 sont un repli si le registre n'a jamais été reçu — ne pas les « corriger » à la main, c'est mld qui fait foi.

Copie locale : ~/ka-guardian-spool/registry.json — poussée par mld (abonné ka2, mld subscribers sur M1M32) et tirée toutes les 2 min par le service launchd com.ka.registry-sync (deploy/registry-sync.sh, zsh pur : LNP interdit le LAN à python).
Le même service sonde :7791/health de chaque nœud hébergeur → ~/ka-guardian-spool/runners.json. Un nœud sans runner (app déménagée sur un nœud jamais équipé) est affiché « ⚠ sans runner » dans le territoire surveillé et l'orchestrateur refuse d'y dépêcher (log d'erreur 1×/h) : lancer deploy/deploy.sh runners (la liste des nœuds est elle-même dérivée du registre).
Les process PM2 = processes du registre moins les tunnels *-ngrok moins pm2_exclude.
Rollback après un déménagement : vise le nœud actuel du service (le repo git suit l'app).

# Veilleur de sites (2026-08-25)

En plus des connecteurs (scan api-ka), chaque agent surveille le site public de chacun de ses services (site_engine dans main.py, source d'incident _site) :

GET du site de chaque service aux site_check_interval_seconds (120 s) ; down = ≥500/timeout, confirmé par un 2ᵉ essai puis site_check_fails (2) cycles consécutifs.
Down confirmé → pm2 restart automatique via l'endpoint /restart du runner du nœud (throttle site_restart_throttle_seconds), re-check du site.
Toujours down → incident site_down (priorité max au dispatch) → mission Claude d'investigation (build_site_down_prompt) sur le nœud : logs pm2, cause racine (crash, port, build, DB, disque, tunnel ngrok), correctif minimal, commit+push.
Cycle standard ensuite : watching (fenêtre courte site_watch_window_hours), rollback si faux « repare », cooldown site_cooldown_hours, max 3 tentatives puis abandon (re-examen après site_abandoned_retry_hours). Les restarts automatiques continuent pendant les cooldowns.

vraiprix (M3U96a, port 8090) est un service site seulement de ka6 : aucun connecteur sous api-ka, seule la surveillance du site s'applique.

# Production (nœud M4M36)

Répertoire : ~/cluster-projects/ka-guardian (ce repo, origin = gitsrv/spbgit ka-guardian.git).
Process : launchd (PAS pm2) — com.ka2.guardian (:8799), com.ka4.guardian (:8899), com.ka6.guardian (:8999). Tunnels ngrok com.kaX.ngrok (ne pas toucher).
Pas d'étape de build : Python servi en place (.venv local au nœud).

# Après toute modification (sur M4M36)

Redémarrer le ou les agents concernés : launchctl kickstart -k gui/$(id -u)/com.ka2.guardian (idem ka4/ka6 — les 3 partagent le code, redémarre les 3 si le changement est commun).
Vérifier : curl -sf localhost:8799/health (8899, 8999) puis le site public.
git add … && git commit && git push origin main (origin = gitsrv/spbgit, PAS GitHub).

⚠️ NE JAMAIS redémarrer les runners (com.ka.guardian-runner sur chaque nœud hébergeur — liste vivante : deploy/deploy.sh nodes, dérivée du registre mld) pendant qu'ils sont occupés : ça tue la mission Claude en vol. Pour redéployer runner/runner.py, vérifier d'abord curl localhost:7791/health (busy:false) sur chaque nœud, comme le fait deploy/deploy.sh runners. ⚠️ Le trafic LAN direct est bloqué par macOS 26 (Local Network Privacy) — le courrier zsh com.ka.guardian-courier s'en occupe ; ne pas le contourner.

# Pages & image de marque

orchestrator/web/index.html + commander.html : les jetons __NUM__, __DOMAIN__, __TAGLINE__ (balises OG) sont rendus par agent au démarrage dans main.py (_render_page).
Bannières de partage orchestrator/web/og-ka{2,4,6}.png (servies à /og.png) : régénérer sur le laptop avec python3 deploy/make_og_images.py (Playwright/Chromium) si l'identité visuelle change.

# Déploiement complet depuis le laptop

deploy/deploy.sh orchestrators (tar-over-ssh + vérif md5 + relance launchd). Source laptop : ~/Desktop/Groupe-KA/apps-web/ka-guardian.