# Portabilität: UNIVERSAL
# Version: 1.1.71
# Zuletzt validiert: 2026-02-08 (Help-Forensik)
# Nächste Prüfung: 2026-08-08

MULTI-LLM PROTOCOL - Koordination paralleler Agenten
=====================================================

Stand: 2026-01-28 v1.1.71

Protokoll V3 für sichere parallele Arbeit mehrerer LLMs
(Claude, Gemini, Copilot, Ollama, Perplexity) im selben
Dateisystem. Entwickelt durch Claude + Gemini Experiment
am 2026-01-28.

WICHTIG: RICHTIG STARTEN
========================
ALLE Partner muessen mit Stempelkarte starten!

  # Claude startet
  bach --startup --partner=claude --mode=silent

  # Gemini startet
  bach --startup --partner=gemini --mode=silent

  # Neuer Partner (mit eigenem Namen)
  bach --startup --partner=simonAI --mode=silent

  # Neuer Partner (ohne Namen)
  bach --startup --partner=new --mode=silent

WARUM?
- Automatisches Ein-/Ausstempeln in partner_presence DB
- Partner-Awareness: Erkennt wer noch online ist
- Protokoll V3 wird bei mehreren Partnern automatisch empfohlen
- Between-Task Check erinnert an Partner-Prüfung

CLI-BEFEHLE
-----------
bach llm presence [dir] [task]  Presence erstellen/aktualisieren
bach llm check [dir]            Andere Agenten erkennen
bach llm lock <datei>           Lock erwerben
bach llm unlock [datei]         Lock freigeben
bach llm handshake [dir]        Handshake-Protokoll starten
bach llm status [dir]           Status anzeigen

PROTOKOLL V3 KOMPONENTEN
========================

1. PRESENCE-SYSTEM
------------------
Jeder Agent erstellt eine Presence-Datei im Arbeitsverzeichnis:

Datei:   .<agent>_presence (z.B. .claude_presence)

Inhalt:
  agent: claude
  status: ACTIVE|FINISHED
  started: 2026-01-28T01:00:00
  heartbeat: 2026-01-28T01:05:00
  working_on: TASK_BESCHREIBUNG
  current_file: datei.txt
  lock_status: FREE|LOCKED|WAITING

Regeln:
- Heartbeat alle 30-60 Sekunden aktualisieren
- Heartbeat älter als 2 Minuten = Agent inaktiv
- Bei Session-Ende: status auf FINISHED setzen

2. LOCKING-SYSTEM
-----------------
Vor Schreibzugriff auf geteilte Dateien:

Lock-Datei: <datei>.lock.<agent>
Beispiel:   PROTOKOL.md.lock.claude

Workflow:
  1. list_directory - Prüfen ob fremder .lock.* existiert
  2. Falls ja -> WARTEN (5 Sek Backoff, dann erneut)
  3. Falls nein -> Lock erstellen
  4. Backup erstellen (<datei>.bak)
  5. Datei bearbeiten
  6. Lock SOFORT löschen

Lock-Inhalt:
  agent: claude
  locked_at: 2026-01-28T01:00:00
  file: PROTOKOL.md

Timeout: Lock älter als 5 Minuten gilt als "stale"
         und kann von anderem Agent gelöscht werden.

3. BACKUP-SYSTEM
----------------
VOR jeder Änderung an geteilten Dateien:
- Backup erstellen: <datei>.bak
- Erst danach schreiben
- Backup bleibt für Recovery

4. HANDSHAKE-PROTOKOLL
----------------------
Auto-Detection wenn sich Agenten begegnen:

Ablauf:
  1. Agent A erstellt Presence
  2. Agent A erkennt Agent B (via detect_other_agents)
  3. Agent A erstellt: .handshake_<agent_a>
  4. Agent B erkennt Handshake-Anfrage
  5. Agent B antwortet: .handshake_<agent_b> mit ACCEPTED
  6. Beide aktivieren Protokoll V3

Handshake-Datei:
  from: claude
  to: gemini
  time: 2026-01-28T01:00:00
  status: ACCEPTED
  protocol: V3

KOMMUNIKATION
=============

Meta-Ebene (asynchron):
  bach msg send <partner> "Nachricht"
  bach msg list
  bach msg read <id>

Echtzeit (im Arbeitsordner):
  Presence-Dateien für Status
  In-File-Kommunikation (Einträge mit Timestamp)

In-File-Format:
  [HH:MM] [Agent] Nachricht oder Aktion

WORKFLOW: GEMEINSAME DATEI BEARBEITEN
=====================================

1. Presence prüfen:
   bach llm check

2. Lock erwerben:
   bach llm lock DATEI.md

3. Backup erstellen:
   (automatisch bei safe_write)

4. Datei bearbeiten

5. Lock freigeben:
   bach llm unlock DATEI.md

6. Presence aktualisieren:
   bach llm presence . "Fertig"

BEISPIEL SESSION
================

# Agent A startet
bach llm presence . "Task_123"
bach llm check              # -> "Keine anderen Agenten"

# Agent B startet
bach llm presence . "Task_456"
bach llm check              # -> "claude: AKTIV"

# Agent A will SHARED.txt bearbeiten
bach llm lock SHARED.txt    # -> "Lock erworben"
# ... bearbeitet ...
bach llm unlock SHARED.txt

# Agent B wartet automatisch wenn Lock existiert
bach llm lock SHARED.txt    # -> Wartet bis A fertig

BEKANNTE AGENTEN
================

- claude      Claude (Anthropic)
- gemini      Gemini (Google)
- copilot     GitHub Copilot
- ollama      Lokale LLMs
- perplexity  Perplexity AI

DATEIEN IM ARBEITSORDNER
========================

.claude_presence       Presence Claude
.gemini_presence       Presence Gemini
DATEI.lock.claude      Lock von Claude
DATEI.lock.gemini      Lock von Gemini
DATEI.bak              Backup vor Änderung
.handshake_claude      Handshake-Signal
.handshake_gemini      Handshake-Antwort

TROUBLESHOOTING
===============

Problem: Lock bleibt haengen
Lösung: Lock älter als 5 Min wird als stale betrachtet
         und automatisch ignoriert. Manuell löschen OK.

Problem: Agent erkennt anderen nicht
Lösung: Presence-Datei prüfen. Heartbeat aktuell?

Problem: Race Condition trotz Lock
Lösung: Prüfen ob list_directory VOR Lock-Erstellung
         ausgeführt wird. Timing-Problem?

HANDLER
-------
hub/multi_llm_protocol.py   Protokoll-Implementation

LESSONS
-------
Lesson #62: Multi-LLM Parallelarbeit Grundlagen
Lesson #63: Multi-LLM Protokoll V3

SIEHE AUCH
----------
bach --help partner   Partner-System
bach --help messages       Nachrichten


STEMPELKARTEN-SYSTEM (v1.1.71)
==============================
DB-basierte Partner-Praesenz für automatische Awareness.

TABELLE: partner_presence
  id               INTEGER PRIMARY KEY
  partner_name     TEXT     Partner-ID (claude, gemini, user, ...)
  status           TEXT     online|offline|crashed
  clocked_in       TEXT     Einstempel-Zeitpunkt
  clocked_out      TEXT     Ausstempel-Zeitpunkt
  last_heartbeat   TEXT     Letzte Aktivitaet
  current_task     TEXT     Aktuelle Aufgabe
  session_id       TEXT     Zugehörige Session

AUTOMATISCH:
- Bei --startup: Clock-In (alte crashed Sessions markiert)
- Bei --shutdown: Clock-Out
- Partner-Awareness im Startup-Output

MANUELL (optional):
- Heartbeat: bach llm presence . "Task_XYZ"
- Status: bach llm status

TIMEOUT:
- Heartbeat älter als 5 Minuten = Partner inaktiv
- Crashed Sessions werden bei nächstem Startup bereinigt
