# KA Guardian — ka2 · ka4 · ka6

Les trois agents gardiens autonomes du Groupe KA. 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).

## 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.*

<table>
  <tr>
    <td align="center"><img src="docs/screenshots/desktop/ka2.webp" width="300" alt="ka2.bot"><br><sub><b><a href="https://www.ka2.bot">ka2.bot</a> — gardien immobilier & local (lou-ka, immo-ka, resto-ka)</b></sub></td>
    <td align="center"><img src="docs/screenshots/desktop/ka4.webp" width="300" alt="ka4.bot"><br><sub><b><a href="https://www.ka4.bot">ka4.bot</a></b></sub></td>
    <td align="center"><img src="docs/screenshots/desktop/ka6.webp" width="300" alt="ka6.bot"><br><sub><b><a href="https://www.ka6.bot">ka6.bot</a></b></sub></td>
  </tr>
  <tr>
    <td align="center"><img src="docs/screenshots/mobile/ka2.webp" width="200" alt="ka2 mobile"><br><sub>mobile</sub></td>
    <td align="center"><img src="docs/screenshots/mobile/ka4.webp" width="200" alt="ka4 mobile"><br><sub>mobile</sub></td>
    <td align="center"><img src="docs/screenshots/mobile/ka6.webp" width="200" alt="ka6 mobile"><br><sub>mobile</sub></td>
  </tr>
</table>

## Ce qu'ils font

1. **Détection** — toutes les 5 min, chaque agent lit la supervision centralisée
   d'api-ka (`/api/v1/monitoring/connectors`, ~2 600 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, lancé dans le repo de l'app, avec un prompt de
   mission strict (diagnostiquer, reproduire, corriger minimalement, re-tester,
   `pm2 restart` du process de sync, commit `[kaX] fix connecteur …`, jamais de push).
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, puis `abandoned`
   (intervention humaine).
5. **Vitrine live** — chaque site (www.ka2.bot / www.ka4.bot / www.ka6.bot) 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,
   historique des missions avec transcript et coût.

## Répartition

| Agent | Domaine | Services surveillés |
|---|---|---|
| ka2 | www.ka2.bot :8799 | louka, immoka, restoka |
| ka4 | www.ka4.bot :8899 | autoka, foodka, sortika |
| ka6 | www.ka6.bot :8999 | fabrika, jobka, creaka + tout nouveau service (défaut) |

## Architecture

- `orchestrator/` — un process FastAPI par agent (M4M36, launchd
  `com.kaX.guardian`), SQLite `data/kaX.db`, dashboard servi sur le même port,
  tunnels ngrok existants conservés.
- `runner/` — un service par nœud d'app (M3U96a/b, M4M64a/b, port 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` et relaie chaque événement à l'orchestrateur (`/api/ingest`).
- `topology.json` — source de vérité : agents, services (nœud/dir/pm2/port),
  IP LAN, politique (fenêtres, cooldowns, modèle).
- Auth interne : token partagé `~/.ka-guardian.env` (orchestrateurs + runners),
  header `X-KA-Token`. Clé Anthropic + clés anti-bot : `~/.claude/.env` des nœuds.
- Communication **par le LAN 192.168.2.x** (SSH/Tailscale inter-nœuds bloqué).

## Déploiement

```bash
deploy/deploy.sh all          # runners + orchestrateurs
deploy/deploy.sh runners      # seulement les 4 runners
deploy/deploy.sh orchestrators
```

## Admin (token requis)

```bash
# 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"}'
# pause / reprise d'un agent
curl -X POST http://M4M36.maclustr.io:8799/api/admin/pause -H "X-KA-Token: $TOKEN" -d '{"paused":true}'
```

## 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).