# Portabilität: UNIVERSAL
# Version: 1.0.0
# Zuletzt validiert: 2026-05-17
# Nächste Prüfung: 2026-11-17

BRIDGE LOCK & FACKEL - Koordination bei Mehrfachinstanzen
==========================================================

Stand: 2026-02-23 v1.0.0 (ENT-45)

ÜBERBLICK
==========
Die BACH Bridge (claude_bridge) nutzt zwei Lock-Ebenen um sicherzustellen,
dass zu einem Zeitpunkt immer nur EINE Bridge-Instanz aktiv ist:

  Ebene 1 — LOCK-DATEI (lokal):     verhindert zwei Instanzen auf demselben PC
  Ebene 2 — FACKEL-SYSTEM (global): verhindert parallelen Betrieb über OneDrive

Beide Ebenen sind unabhängig und ergänzen sich.


EBENE 1: LOCK-DATEI
===================
Datei: %TEMP%\bach_bridge.lock  (lokaler Temp-Ordner)

Mechanismus:
  - Beim Start: msvcrt File-Lock auf bach_bridge.lock
  - Zweite Instanz auf demselben PC: erkennt Lock → beendet sich
  - Beim sauberen Beenden: Lock wird freigegeben und Datei gelöscht
  - Beim Absturz: Lock bleibt (OS gibt ihn frei sobald Prozess tot)

Wann nötig: IMMER — auch auf Einzelsystemen ohne OneDrive.


EBENE 2: FACKEL-SYSTEM
=======================
Tabelle: bridge_session_lock in bach.db (über OneDrive synchronisiert)

  Wann nötig:
    Nur wenn dieselbe bach.db über OneDrive (oder anderen Sync-Dienst)
    auf mehreren PCs geteilt wird. Zwei Bridges würden sonst gleichzeitig
    in dieselbe DB schreiben → Konflikte, doppelte Nachrichten, Race Conditions.

    Bei rein lokalem BACH (kein Sync) genügt der Lock-File. Das Fackel-System
    schadet aber auch nicht — es gewinnt einfach immer wenn kein anderer PC
    konkurriert.

  Heartbeat:
    - Aktiver Daemon sendet alle 60s einen Heartbeat (Zeitstempel in DB)
    - Kein Heartbeat > 5 Min → Fackel gilt als abgelaufen (Crash-Schutz)

  Force-Takeover (ENT-45, ab 2026-02-23):
    - Wer zuletzt die Fackel anfragt, bekommt sie — immer
    - Kein "blockiert"-Fehler mehr
    - Alter Halter erhält automatisch Signal via Heartbeat-Ausfall


FACKEL-VERLUST: ABLAUF
=======================
Wenn PC-B die Fackel von PC-A übernimmt:

  1. PC-B schreibt pc_name='PC-B' in bridge_session_lock
  2. PC-A: nächster Heartbeat schlaegt fehl (0 rows updated)
  3. PC-A prüft: check_fackel_mine() → False
  4. PC-A loggt: "FACKEL VERLOREN: PC-B hat die Fackel übernommen"
  5. PC-A sendet Telegram-Nachricht: "Fackel an PC-B abgegeben"
  6. PC-A: geordneter Shutdown, Exit-Code 2 (FACKEL_LOST)
  7. Tray auf PC-A: erkennt Exit-Code 2 → kein Neustart → Tray beendet sich


TRAY-LOCK
=========
Datei: %TEMP%\bach_bridge_tray.lock

  - Verhindert zwei Tray-Instanzen auf demselben PC
  - Wird vom Daemon genutzt um zu prüfen ob Tray noch läuft
    (Tray-Kopplung: Daemon beendet sich wenn Tray stirbt)
  - Wird im finally-Block des Trays gelöscht (bei sauberem Beenden)
  - Bei Absturz des Trays: Lock bleibt → Daemon erkennt toten Tray
    nach nächstem Check (alle 30s) und beendet sich


EXIT-CODES DES DAEMONS
=======================
  0   Normales Beenden (Benutzer hat "Beenden" gewählt)
  1   Fehler beim Start (Lock belegt o.ä.)
  2   FACKEL_LOST — Fackel durch anderen PC übernommen
      → Tray startet Daemon NICHT neu bei Exit-Code 2


ARCHITEKTUR: CONNECTORS VS. BRIDGE
====================================
Die Bridge (claude_bridge) ist der einzige Dienst der einen eigenen
Daemon-Prozess hat und Koordination benötigt.

Die Connectors (telegram_connector.py, discord_connector.py, etc.) sind
reine Adapter-Module ohne eigenen Daemon — sie werden vom Bridge-Daemon
aufgerufen und brauchen kein eigenes Lock/Fackel-System.

  Bridge-Daemon     → hat Lock-Datei + Fackel
  telegram_connector.py  → Adapter, kein Lock
  discord_connector.py   → Adapter, kein Lock
  signal_connector.py    → Adapter, kein Lock
  homeassistant_connector.py → Adapter, kein Lock


DIAGNOSE
========
  Fackel-Status prüfen:
    python -c "
    import sqlite3, json
    from pathlib import Path
    db = Path('data/bach.db')
    conn = sqlite3.connect(str(db))
    rows = conn.execute('SELECT * FROM bridge_session_lock').fetchall()
    for r in rows: print(r)
    "

  Bridge-Log:
    data/logs/claude_bridge.log

  Relevante Log-Meldungen:
    "Fackel erworben: Fackel übernommen (Force-Takeover von X)" — normaler Takeover
    "FACKEL VERLOREN: X hat die Fackel übernommen"             — dieser PC verliert
    "Heartbeat fehlgeschlagen (DB-Problem)"                     — kurzer DB-Fehler


VERWANDTE ENTSCHEIDUNGEN
=========================
  ENT-45  Fackel: Force-Takeover, Exit-Code 2, Tray-Selbstbeendung
  SQ013   Bridge-Implementierung
