# KA Guardian — ka2 · ka4 · ka6

Les trois agents gardiens autonomes du Groupe KA. Un seul repo, trois instances, trois salles de contrôle publiques :

www.ka2.bot · www.ka4.bot · www.ka6.bot

Depuis le 2026-08-23, ka2/ka4/ka6 ne sont plus des bots de cartographie web : ce sont des agents de maintenance autonomes des connecteurs des plateformes ·Ka, bâtis sur Claude (CLI headless). Un connecteur tombe en panne quelque part dans l'écosystème ·Ka ? Le gardien concerné le détecte, ouvre le code, le répare, prouve que ça marche — et si ça empire, il revient au commit d'avant. Tout ce qu'il fait est public, en direct.

# Les trois agents

L'identité de chaque agent (numéro, domaine, tagline, accents, services surveillés, modèle Claude) vit dans topology.json. L'emplacement des apps (nœud, IP LAN, répertoire, port, process PM2) n'y est PAS codé en dur : il vient du registre de la passerelle mld (M1M32:~/dispatch/registry.json), appliqué par orchestrator/registry.py au démarrage et à chaque tick — quand mld move déplace une app, les gardiens suivent sans redéploiement (voir « Où sont les apps ? » plus bas). Les pages web (orchestrator/web/index.html, commander.html) sont des gabarits communs : les jetons __NUM__, __DOMAIN__, __TAGLINE__ sont rendus par agent au démarrage (_render_page dans main.py). Chaque agent a sa bannière de partage OG (orchestrator/web/og-ka{2,4,6}.png, servie à /og.png, régénérable via deploy/make_og_images.py), ses favicons et son apple-touch-icon aux couleurs de son accent.

# Aperçu des sites publics

Captures du 2026-08-25 (mobile 390×844 · desktop 1440×900) — chaque gardien rend des comptes en direct sur son site. Visites guidées détaillées (30 captures du 2026-08-28) plus bas.

ka2.bot — gardien immobilier & local	ka4.bot — gardien mobilité & quotidien	ka6.bot — gardien flagship
mobile	mobile	mobile

# Cycle de vie d'une mission

api-ka /monitoring/connectors          nœud de l'app (runner :7791)
        │  (scan aux 5 min)                      │
        ▼                                        ▼
   ① DÉTECTION ──► incident ──► ② MISSION claude -p headless
                                     │  (diagnostic, correctif minimal,
                                     │   test réel, commit [kaX] …)
                                     ▼
                               ③ SURVEILLANCE 8 h (watching)
                                     │
                     ┌───────────────┴───────────────┐
                     ▼                               ▼
              connecteur ok                 toujours cassé / app down
               → RÉSOLU                  ④ ROLLBACK git + pm2 restart
                                            (3 tentatives max → abandoned)

1. Détection — toutes les 5 min, chaque agent lit la supervision centralisée d'api-ka (/api/v1/monitoring/connectors, ~2 800 connecteurs classés ok/degraded/broken/stale toutes les 2 h). Un connecteur broken ou stale de son périmètre → incident.
2. Mission — l'agent dépêche une mission au runner du nœud qui héberge l'app : claude -p headless (Claude Code CLI, --output-format stream-json), lancé dans le repo de l'app, avec un prompt de mission strict : diagnostiquer, reproduire, corriger minimalement (mêmes patterns que les connecteurs voisins), re-tester en volume réel, pm2 restart du process de sync, commit [kaX] fix connecteur … — jamais de push par la mission elle-même (voir le pousseur plus bas). La pile d'escalade anti-bot du Groupe KA (curl → Scrapfly → Bright Data → proxys résidentiels Oxylabs → Serper/Tavily) est à sa disposition sur le nœud.
3. Surveillance — après réparation déclarée, l'incident passe en watching pendant 8 h. Connecteur de retour à ok → résolu.
4. Rollback automatique — si l'app tombe (healthcheck) ou si le connecteur est toujours cassé après la fenêtre : retour au commit d'avant mission (git reset --hard/revert) + pm2 restart. 3 tentatives max (cooldown 6 h entre tentatives), puis abandoned (intervention humaine, ré-examen après 7 jours).
5. Vitrine live — chaque site est une salle de contrôle : flux SSE en direct de chaque action de l'agent (outils, réflexions, verdicts), board d'incidents, couverture par service (« Territoire surveillé »), registre des missions avec transcript complet, nombre de tours, durée et coût API par mission.

# Garde-fous (politique topology.json)

• 1 mission à la fois par agent et par nœud (le runner refuse s'il est occupé).
• Plafonds de mission : 70 tours / 1 h (efforts commandés : 150 tours / 2 h).
• Seuil d'incident de masse (≥ 20 connecteurs d'un coup) : pas de missions en rafale — c'est presque toujours une panne d'infrastructure, pas 20 bugs.
• Push git jamais fait par la mission : commits [kaX] locaux seulement, poussés par le pousseur (chaîne launchd de confiance, voir Architecture).

# Veilleur de sites (2026-08-25)

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

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

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

# Efforts commandés — la page /commander

Chaque site expose un poste de commande (/commander, « Donne-lui du travail. ») : un opérateur muni du jeton d'opérateur (jamais publié — il vit dans ~/.ka-guardian.env des nœuds) peut commander un effort autonome à l'agent :

L'opérateur fixe la laisse : durée max et budget max (coût API estimé en direct). Plafond atteint → la session s'arrête proprement ; les réparations déjà committées et testées sont conservées si la plateforme est saine. Une consigne libre optionnelle oriente l'agent (« vise les microbrasseries de la Côte-Nord… »). Chaque effort est journalisé action par action dans le flux, listé dans « Efforts commandés récents », et annulable par rollback git. Contrairement aux incidents api-ka, un effort livré est validé par healthcheck de l'app (pas par la supervision) : app en échec post-effort → rollback préventif automatique.

API équivalente : POST /api/admin/effort (header X-KA-Token).

# Architecture

                        M4M36 (nœud orchestrateur)
   ┌────────────────────────────────────────────────────────────┐
   │  com.ka2.guardian :8799   com.ka4.guardian :8899           │
   │  com.ka6.guardian :8999   (FastAPI + SQLite data/kaX.db)   │
   │  ngrok com.kaX.ngrok → www.ka2.bot / ka4.bot / ka6.bot     │
   │  courrier zsh com.ka.guardian-courier (spool → ssh+curl)   │
   │  registry-sync zsh com.ka.registry-sync (registre + sondes) │
   └───────────────┬────────────────────────────────────────────┘
                   │  LAN 192.168.2.x uniquement (via le courrier)
      ┌────────────┼──────────────┬──────────────┐
      ▼            ▼              ▼              ▼      … tout nœud que le registre
   M3U96a        M2U64         M4M64a         M4M64b        mld désigne (liste vivante)
   runner :7791 (com.ka.guardian-runner) sur chaque nœud hébergeur
   + pousseur git com.ka.pousseur (nœuds à repos Ka)
        ▲
        │ registre poussé (abonné ka2) + tiré toutes les 2 min
   M1M32 (passerelle) ~/dispatch/registry.json — source de vérité des emplacements

# Où sont les apps ? — le registre mld fait foi (2026-09-04)

• orchestrator/registry.py lit ~/ka-guardian-spool/registry.json et applique, EN PLACE, nœud / IP / répertoire / port / PM2 à chaque service de topology.json (clé registry_app = nom de l'app dans le registre ; pm2_exclude retire un process des restarts ; les tunnels *-ngrok sont toujours exclus). Les déménagements détectés sont journalisés (flux SSE + /api/state → registry.changes).

• La copie locale arrive par deux chemins : poussée par mld à chaque sauvegarde du registre (abonné ka2, cf. mld subscribers sur M1M32) et tirée toutes les 2 min par deploy/registry-sync.sh (launchd com.ka.registry-sync, zsh pur — LNP). Le même service sonde :7791/health sur chaque nœud hébergeur → runners.json : un nœud sans runner est affiché « ⚠ sans runner » et l'orchestrateur n'y dépêche rien (erreur loggée 1×/h) jusqu'à deploy/deploy.sh runners — dont la liste de nœuds est elle aussi dérivée du registre (deploy/deploy.sh nodes pour la voir).

• Les champs node/dir/web_port/pm2 de topology.json ne servent que de repli si le registre n'a jamais été reçu ; ne pas les maintenir à la main.

• orchestrator/ — un process FastAPI par agent (M4M36, launchd com.kaX.guardian, env AGENT=ka2|ka4|ka6), SQLite data/kaX.db, dashboard servi sur le même port (flux SSE, board incidents, couverture, registre des missions + transcripts, /commander), tunnels ngrok existants conservés.

• runner/ — un service par nœud hébergeur (liste dérivée du registre mld ; :7791, launchd com.ka.guardian-runner), 1 mission à la fois par nœud, transcripts dans ~/ka-guardian-runner/transcripts/. Exécute claude -p --output-format stream-json dans le repo de l'app et relaie chaque événement à l'orchestrateur (/api/ingest). Expose aussi /restart (pm2) pour le veilleur de sites et /health (busy). ⚠️ Ne jamais redémarrer un runner occupé : ça tue la mission Claude en vol.

• topology.json — agents (port/domaine/accent/tagline/modèle/services), correspondance service → registry_app (+ pm2_exclude), politique (fenêtres, cooldowns, plafonds). Nœud/dir/port/PM2 des services = registre mld (repli seulement).

• orchestrator/registry.py + deploy/registry-sync.sh — topologie vivante : lecture/application du registre, journal des déménagements, sonde des runners.

• deploy/courier.sh — courrier inter-nœuds 100 % zsh (launchd com.ka.guardian-courier). macOS 26 « Local Network Privacy » refuse le trafic LAN dès que python (homebrew) est dans la chaîne de processus ; le courrier (binaire responsable : zsh) expédie donc les requêtes via spool : spool/outbox/<id>.job → ssh <nœud> curl http://127.0.0.1:<port><path> → spool/done/<id>.resp, avec 3 tentatives et multiplexage SSH. Ne pas le contourner.

• deploy/pousseur.sh — pousseur git (launchd com.ka.pousseur sur les nœuds qui hébergent des repos Ka). Chaîne 100 % binaires Apple (launchd → zsh → /usr/bin/git → /usr/bin/ssh) : contourne le blocage LNP des git push lancés par les missions (descendants du runner python homebrew). Toutes les 5 min, pousse vers spbgit les commits en attente des repos listés dans ~/.ka-pousseur-repos. Push simple uniquement (jamais de force) : un non-fast-forward est loggé, jamais résolu d'autorité.

• Auth interne — token partagé entre orchestrateurs et runners (fichier ~/.ka-guardian.env sur chaque nœud, header X-KA-Token). Clé Anthropic et clés anti-bot : ~/.claude/.env des nœuds. Aucun secret dans ce repo.

• Communication par le LAN 192.168.2.x (SSH/Tailscale inter-nœuds bloqué par ACL).

# Visite guidée — ka2 (www.ka2.bot)

Gardien immobilier & local — Lou·Ka, Immo·Ka, Resto·Ka, House·Ka, Rent·Ka. Captures du 2026-08-28 (desktop 1440×900, mobile 390×844).

Capture	Description
	Accueil — héro « Il veille. Il répare. Il rend des comptes. », définition gar·dien (détecte / répare / surveille / recule), tuiles « L'état du gardien » (1 378 connecteurs sous garde, incidents actifs, missions lancées, réparations confirmées, rollbacks assumés, temps moyen de guérison, coût API total) et amorce du flux temps réel + board d'incidents.
	Poste de commande /commander — « Donne-lui du travail. » : type d'effort (nouveau connecteur avec découverte Serper, enrichissement, inspection des dégradés), plateforme cible (avec son nœud), consigne libre, laisse durée max / coût max et champ jeton d'opérateur.
	Territoire surveillé — couverture live par service : Lou·Ka (M3U96b, 431 connecteurs), Immo·Ka (M4M64A, 140), Resto·Ka (14), House·Ka (M4M64B, 25), Rent·Ka (M4M36, 768), chacun avec sa barre ok/dégradé/cassé/endormi ; en dessous, l'entête du registre des missions.
	Registre des missions (récentes) — une ligne par mission : horodatage, connecteur, service, nœud, verdict (ici « RIEN À FAIRE »), commits, tours · durée, coût API. Cliquer une ligne ouvre le déroulé complet, commits inclus.
	Registre des missions (suite) — tout l'éventail des verdicts en conditions réelles : RÉPARÉ, ÉCHEC, RIEN À FAIRE, LIVRÉ (efforts commandés), INCONNU, avec tentatives, commits et coûts (de 0,10 $ à 3,64 $ la mission).
	Fin du registre + pied de page « Zéro boîte noire » — « Chaque diagnostic, chaque commit, chaque rollback de cet agent est journalisé et affiché ici. Les réparations sont committées dans les repos des plateformes, jamais poussées sans passage humain. » Liens vers les plateformes gardées et les agents frères.
	Accueil mobile — la salle de contrôle complète en 390×844 : héro, tuiles d'état, flux, incidents, territoire, registre.
	/commander — bas de page — plafonds (durée, coût max estimé en direct), jeton d'opérateur, bouton « Lancer l'effort → », liste « Efforts commandés récents » avec statuts (LIVRÉ / TERMINÉ) et rappel « La laisse est réelle ».
	Poste de commande mobile — le formulaire d'effort complet au téléphone.
	Flux en temps réel (SSE) — le terminal « KA2 — FLUX EN TEMPS RÉEL » : chaque outil, réflexion et verdict de l'agent y est diffusé en direct ; au repos, « en attente d'activité — le gardien scrute api-ka toutes les 5 minutes… ».

# Visite guidée — ka4 (www.ka4.bot)

Gardien mobilité & quotidien — Auto·Ka, Food·Ka, Sorti·Ka. Accent ambre.

Capture	Description
	Accueil — même gabarit que ses frères, aux couleurs de ka4 : héro, définition gar·dien, tuiles d'état de son périmètre mobilité & quotidien, flux temps réel et incidents.
	Poste de commande /commander — commander un effort à ka4 : nouveau connecteur (découverte Serper), enrichissement ou inspection des dégradés sur Auto·Ka, Food·Ka ou Sorti·Ka, avec laisse durée/coût et jeton d'opérateur.
	Flux + incidents + Territoire surveillé — couverture live des trois services (Auto·Ka sur M4M64b, Food·Ka sur M4M64b, Sorti·Ka sur M3U96a) avec barres ok/dégradé/cassé/endormi, puis le registre des missions.
	Accueil mobile — la salle de contrôle ka4 en 390×844.
	/commander — bas de page — plafonds, jeton d'opérateur et « Efforts commandés récents » de ka4.
	Poste de commande mobile.
	Flux en temps réel (1/4) — le terminal SSE de ka4.
	Flux en temps réel (2/4) — chaque action de mission (outil lancé, fichier lu, test exécuté) s'affiche ici à mesure.
	Flux en temps réel (3/4) — le même flux que consomme le board d'incidents et le registre.
	Flux en temps réel (4/4) — au repos : « en attente d'activité — le gardien scrute api-ka toutes les 5 minutes… ».

# Visite guidée — ka6 (www.ka6.bot)

Gardien flagship — gros volumes : Fabri·Ka, Job·Ka, Créa·Ka, Vrai·Prix (site seulement) + tout nouveau service par défaut. Accent violet.

Capture	Description
	Accueil — le plus gros périmètre du trio : 2 819 connecteurs sous garde, 251 missions lancées, 89 réparations confirmées, 14 rollbacks assumés, 3,3 h de temps moyen de guérison ; incidents en SURVEILLANCE (fabrika, jobka) visibles au chargement.
	Poste de commande /commander — commander un effort à ka6 sur Fabri·Ka, Job·Ka ou Créa·Ka (nouveau connecteur découvert via Serper, enrichissement, inspection des dégradés).
	Flux + incidents + Territoire surveillé — couverture live de Fabri·Ka (M4M64a), Job·Ka (M3U96a), Créa·Ka (M3U96b) et Vrai·Prix (M3U96a, surveillance du site seulement).
	Registre des missions (1/5) — le registre le plus long du trio : gros volumes = plus d'incidents, plus de missions, plus de verdicts.
	Registre des missions (2/5) — missions récentes avec verdicts, tours, durées et coûts par connecteur.
	Registre des missions (3/5) — l'historique se déroule : réparations confirmées, échecs assumés, missions « rien à faire ».
	Registre des missions (4/5) — chaque ligne reste cliquable : déroulé complet de la mission, commits inclus.
	Registre des missions (5/5) + pied de page « Zéro boîte noire » — fin de l'historique et engagement de transparence.
	Accueil mobile — la salle de contrôle ka6 en 390×844.
	/commander — bas de page — plafonds, jeton d'opérateur et « Efforts commandés récents » de ka6.

# Transparence publique

Le principe fondateur des gardiens : zéro boîte noire.

• Chaque diagnostic, chaque commit, chaque rollback est journalisé et affiché en direct sur le site de l'agent (flux SSE, board d'incidents, registre des missions avec transcript, tours, durée et coût API au cent près).
• Les réparations sont committées [kaX] … dans les repos des plateformes et poussées par le pousseur vers le git du Groupe — jamais de force-push, jamais de résolution d'autorité.
• Les trois agents sont présentés publiquement sur groupe-ka.com/bots, et chaque site gardien lie ses frères et les plateformes qu'il garde.
• Les actions sensibles (/commander, API admin) exigent le jeton d'opérateur — la consultation, elle, est ouverte à tous.

# Déploiement

• Nœud de production : 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).

deploy/deploy.sh all            # runners + orchestrateurs (+ courrier)
deploy/deploy.sh runners        # seulement les 5 runners (refuse un runner occupé)
deploy/deploy.sh orchestrators  # ka2/ka4/ka6 sur M4M36 (tar-over-ssh + md5 + relance launchd)

Après toute modification sur M4M36 :

launchctl kickstart -k gui/$(id -u)/com.ka2.guardian   # idem ka4/ka6
curl -sf localhost:8799/health                          # puis 8899, 8999 + site public
git add … && git commit && git push origin main         # origin = gitsrv/spbgit, PAS GitHub

# Admin (token requis)

# mission manuelle sur un connecteur
curl -X POST http://M4M36.maclustr.io:8799/api/admin/mission \
  -H "X-KA-Token: $TOKEN" -d '{"service":"louka","source":"kijiji"}'
# effort commandé (équivalent API de /commander)
curl -X POST http://M4M36.maclustr.io:8799/api/admin/effort \
  -H "X-KA-Token: $TOKEN" -d '{"kind":"effort_new","service":"restoka"}'
# pause / reprise d'un agent
curl -X POST http://M4M36.maclustr.io:8799/api/admin/pause \
  -H "X-KA-Token: $TOKEN" -d '{"paused":true}'

# Repo & contact

• Repo : ka-guardian.git sur spbgit (le git personnel du Groupe — git.spboucher.ai, bare repos sur M3U96a). Origin des nœuds : gitsrv:srv/git/ka-guardian.git.
• Structure : orchestrator/ (main.py + web/), runner/runner.py, deploy/ (deploy.sh, courier.sh, pousseur.sh, make_og_images.py), topology.json, docs/screenshots/.
• Contact : groupe-ka.com — Groupe KA, agrégation automatisée, Québec.

# Historique

Les anciens bots (cartographie du web québécois / influenceurs) sont archivés : ~/ka-bots-backup-20260823.tar.gz sur M4M36 (code + bases SQLite complètes).