Phase 20: Föderierte Bot-Architektur

Arc OS — von "einem Büro" zu "Kommandozentrale für alle Projekte" Autor: Rick (Lead Architect) | Datum: 2026-04-02 Status: 20.1–20.5 ABGESCHLOSSEN Genehmigt von: CEO

Das Problem

Der CEO verwaltet mehrere Projekte (Arc OS, Msolution, RTS_001) vom Telefon aus. Aktuelle Architektur: ein Telegram Bot → eine Claude-Sitzung → ein Kontextfenster. Das scheitert ab 3+ Projekten:

• Kontextfenster-Verschmutzung (200.000 Token zwischen nicht verwandten Projekten geteilt)
• Keine Projektisolierung (Msolution-Code dringt in Citadel-Prompts ein)
• Keine Multi-User-Fähigkeit (kann keinen Designer zu einem Projekt-Chat einladen)
• Reply-Kontext kaputt (auf Nachricht aus falschem Projekt antworten = Chaos)

Die Lösung: Föderierung

CEO ↔ @citadel_master_bot (Master)          ← nur globale Befehle
       │
       ├── /status          → fragt alle Children ab
       ├── /emergency-stop  → Kill-Signal an alle
       ├── /deploy all      → kaskadiertes Deployment
       │
       ├── @citadel_v2_bot (Child 1)         ← separater Chat, separater Kontext
       │    └── Claude-Sitzung #1, cwd=/opt/repos/citadel-v2
       │
       ├── @msolution_bot (Child 2)          ← kann Designer zum Chat hinzufügen
       │    └── Claude-Sitzung #2, cwd=/opt/repos/msol
       │
       └── @rts_bot (Child 3)               ← kann Morty-Agent hinzufügen
            └── Claude-Sitzung #3, cwd=/opt/repos/rts-001

Entscheidungsanalyse: Single Bot vs. Föderierung

Option A: Single Bot + Projekt-Switcher

Urteil: Funktioniert für Solo-CEO mit 1–2 Projekten. Scheitert ab 3+.

Option B: Föderierte Bots (Master + Children) — GEWÄHLT

Urteil: Richtige Lösung. Mehr Infra-Komplexität, löst aber ALLE Probleme.

Warum Föderierung gewinnt

1. Kontext-Isolation — entscheidender Faktor. Eine Claude-Sitzung für 3+ Projekte = Kontext-Überlauf in 30 Minuten aktiver Arbeit. Föderierung gibt jedem Projekt saubere 200.000 Token.
2. Multi-User-Bereitschaft — kein "zukünftiges Feature", es ist ein Fundament. Ohne es kann Arc OS kein Produkt werden.
3. Reply = natives RAG — Telegram hat das Kontext-Problem bereits gelöst. Wir bilden Reply → GSD-Prompt ab.

Emergency-Stop-Architektur

CEO tippt /emergency-stop im Master-Chat
        │
        ▼
Master Bot (Node.js/Bun, leichtgewichtig, KEINE Claude-Sitzung)
        │
        ├── 1. config/bot_registry.json lesen
        │      { "children": [
        │          { "name": "citadel-v2", "tmux": "citadel", ... },
        │          { "name": "msolution", "tmux": "msolution", ... }
        │      ]}
        │
        ├── 2. Für jedes Child (parallel):
        │      a) tmux send-keys -t $SESSION "C-c" Enter      ← graceful: Ctrl+C
        │      b) sleep 2
        │      c) tmux send-keys -t $SESSION "/exit" Enter     ← expliziter Exit
        │      d) sleep 2
        │      e) tmux kill-session -t $SESSION                 ← erzwungen falls noch aktiv
        │
        ├── 3. office-state.json aktualisieren: alle Agents → idle
        │
        └── 4. Im Master-Chat antworten:
               "EMERGENCY STOP ausgeführt.
                citadel-v2: GESTOPPT (arbeitete an: hooks)
                msolution: GESTOPPT (war: idle)
                Alle Agents auf idle zurückgesetzt."

Kill-Protokoll (3 Ebenen)

Failsafe

Cron-Job alle 5 Minuten prüft /tmp/emergency-stop.flag. Wenn die Datei existiert und frisch ist (<10 min), führt er die Kill-Sequenz aus. Deckt den Fall ab, in dem der Master Bot selbst abgestürzt ist.

Smart Context Recall

Problem

Der CEO antwortet auf eine 3 Tage alte Nachricht und sagt "mach das Gleiche, aber für ein anderes Modul". Claude hat keine Ahnung von der referenzierten Nachricht.

Lösung: Reply → GSD-Prompt-Transformation

Die Telegram Bot API stellt das reply_to_message-Objekt mit vollem Originaltext bereit.

CEO antwortet auf: "Ich habe Hooks auf VPS deployed, alles funktioniert"
CEO schreibt: "mach das Gleiche für msolution"
        │
        ▼
Child Bot empfängt:
{
  "message": {
    "text": "mach das Gleiche für msolution",
    "reply_to_message": {
      "text": "Ich habe Hooks auf VPS deployed, alles funktioniert",
      "date": 1743580800,
      "message_id": 847
    }
  }
}
        │
        ▼
Bot baut GSD-Prompt für Claude:
┌─────────────────────────────────────┐
│ KONTEXT (aus Reply):                │
│ > [2026-04-02] "Ich habe Hooks auf  │
│ > VPS deployed, alles funktioniert" │
│                                     │
│ AUFGABE (neue Nachricht):           │
│ "mach das Gleiche für msolution"    │
│                                     │
│ PROJEKT: msolution (aus Bot-Scope)  │
└─────────────────────────────────────┘

Deep Recall (ältere Nachrichten)

Ebene 1: Thread-Historie (schnell)
  Bot speichert letzte 50 Nachrichten in state/thread_history.json pro Chat.
  Reply → Bot findet Original → injiziert in CONTEXT-Block.

Ebene 2: Library Recall (Fallback)
  Wenn Nachricht nicht in Thread-Historie (>50 Nachrichten zurück) →
  Bot führt /citadel-recall mit Reply-Text aus →
  zieht Kontext aus library-export/ → injiziert in Prompt.

Ablauf: reply_to_message → thread_history → library-export/ → GSD-Prompt

Schlüsselprinzip

Claude weiß NIEMALS direkt über Telegram-Replies. Die Bot-Middleware transformiert Reply IMMER in einen sauberen CONTEXT + TASK-Block, bevor er an die Claude-Sitzung gesendet wird.

Master-Bot-Spezifikation

Was der Master Bot IST

• Leichtgewichtiger Bun/Node.js-Service (~300 Zeilen)
• Telegram Bot API (Long-Polling)
• Liest config/bot_registry.json für Child-Registry
• HTTP-Health-Endpunkt: /api/master/health
• Docker-Container in gemeinsamer Compose

Was der Master Bot NICHT IST

• KEINE Claude-Sitzung (kein KI, keine LLM-Aufrufe)
• KEIN Nachrichten-Proxy (leitet Nachrichten nicht an Children weiter)
• KEIN State-Store (liest State aus Children-Dateien)

Child-Bot-Protokoll

Jeder Child Bot muss:

1. Sich in config/bot_registry.json beim Start registrieren
2. Heartbeat senden (alle 60s) an Master via Datei: state/heartbeat_<name>.json
3. reply_to_message → GSD-CONTEXT-Injektion verarbeiten
4. Letzte 50 Nachrichten in state/thread_history.json speichern
5. Auf Emergency-Stop-Signal reagieren (graceful Ctrl+C → /exit → kill)
6. Strukturierten Logger verwenden (shared/logger.ts) — Logs nach /var/log/citadel/<name>/
7. BOT_NAME-Umgebungsvariable für dynamische Benennung akzeptieren
8. /api/child/health für Watchdog-Health-Checks exponieren

Ressourcenschätzung

Phase-20-Unterphasen

20.1 — Master-Bot-Fundament

• Bun + TypeScript Telegram Bot (Long-Polling)
• config/bot_registry.json — Child-Registry
• Befehle: /status, /emergency-stop, /list, /health
• Docker-Container in docker/docker-compose.yml
• Health-Endpunkt: /api/master/health
• Kein KI, keine Claude-Sitzung — reiner Orchestrator

20.2 — Child-Bot-Protokoll (Erster Child)

• Child-Bot-Registrierungsprotokoll definieren
• Nachrichten-Middleware: reply_to_message → GSD-CONTEXT-Injektion
• Thread-Historie: letzte 50 Nachrichten in state/thread_history.json
• Graceful-Shutdown-Protokoll (auf Emergency-Stop reagieren)
• Pilot: @citadel_v2_bot von Claude Channel auf Custom Bot migrieren
• Heartbeat an Master (alle 60s via Datei)

20.3 — Onboarding-Engine (FERTIG)

• /new_project <name> — 4-schrittiges interaktives Interview
• Skill-Matching (Registry + Library), Blueprint-Erkennung
• Auto-Provisioning: Verzeichnisse, CLAUDE.md, MANIFEST.md, .env, Registry, tmux

20.4 — Skill-Library & Projekt-Entfernung (FERTIG)

• /remove_project <name> — dreifache Bestätigung + geschützte Namen
• Library-Skills werden beim Onboarding automatisch abgeglichen und kopiert
• Registry-Reload-Hook für In-Memory-Updates

20.5 — Phantom-Ready-Infrastruktur (FERTIG)

• shared/logger.ts — JSONL strukturiertes Logging, tägliche Dateiaufteilung
• shared/vault.ts — AES-256-GCM verschlüsselte Secrets (Token im Vault, nicht in .env)
• master-bot/watchdog.ts — Self-Healing-Monitor mit exponentiellem Backoff
• /watchdog-Befehl für Echtzeit-Child-Status
• Logrotate-Konfig + VPS-Setup-Skript
• Alle console.log → strukturierter Logger

Master-Bot-Befehle (Final)

Nicht im Umfang (Phase 21+)

• SaaS Multi-Tenancy (JWT, Stripe-Abrechnung)
• Webbasiertes Dashboard als Alternative zu Telegram
• Sprachbefehle via Telegram
• Agent-Sprite-Editor und Büro-Anpassung
• Vault-Key-Rotationsmechanismus
• Multi-VPS Peer Health-Monitoring

Phase-20-Architektur von Rick (Lead Architect). Phasen 20.1–20.5 abgeschlossen. Genehmigt von CEO 2026-04-02.