# Portability: UNIVERSAL
# Last validated: 2026-05-17
# Next review: 2027-05-17

BRIDGE LOCK & FACKEL - 複数インスタンスの調整
==========================================================

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

概要
==========
BACH ブリッジ (claude_bridge) は 2 つのロック レベルを使用して、
一度にアクティブになるブリッジ インスタンスは 1 つだけです:

  レベル 1 — LOCK FILE (ローカル): 同じ PC 上で 2 つのインスタンスを禁止します。
  レベル 2 — トーチ システム (グローバル): OneDrive を介した並列操作を防止します

両方のレベルは独立しており、相互に補完します。


レベル 1: ロック ファイル
===================
ファイル: %TEMP%\bach_bridge.lock (ローカル一時フォルダー)

メカニズム:
  - 起動時: bach_bridge.lock での msvcrt ファイル ロック
  - 同じ PC 上の 2 番目のインスタンス: ロックを検出 → 終了
  - 正常に終了する場合: ロックが解除され、ファイルが削除されます
  - クラッシュの場合: ロックは残ります (プロセスが停止するとすぐに OS がロックを解放します)

必要な場合: 常に - OneDrive のない個々のシステムでも。


レベル 2: トーチ システム
=======================
テーブル: bach.db の Bridge_session_lock (OneDrive 経由で同期)

  必要な場合:
    同じ bach.db が OneDrive (または他の同期サービス) 経由である場合のみ
    複数のPCで共有できます。そうしないと、2 つの橋が同時に架かってしまうでしょう。
    同じ DB に書き込む → 競合、重複メッセージ、競合状態。

    純粋にローカル BACH (同期なし) の場合は、ロック ファイルで十分です。トーチシステム
    しかし、それも害にはなりません - 他の PC が勝てないときに常に勝てるというだけです
    

 競争します。

  心拍数:
    - アクティブなデーモンは 60 秒ごとにハートビートを送信します (DB 内のタイムスタンプ)
    - ハートビートが 5 分を超えない → トーチは期限切れとみなされます (クラッシュ保護)


  強制乗っ取り (ENT-45、2026 年 2 月 23 日から):
    - 最後にトーチを要求した人がトーチを受け取ります - 常に
    - 「ブロックされました」エラーはなくなりました
    - 古いホルダーはハートビート障害によって自動的に信号を受信します
=======================
トーチ損失: 有効期限

PC-B が PC-A からトーチを引き継ぐとき:


  1. PC-B は pc_name='PC-B' を Bridge_session_lock に書き込みます
  2. PC-A: 次のハートビートが失敗します (0 行が更新されました)
  3. PC-A チェック: check_fackel_mine() → False
  4. PC-A のログ: 「トーチが失われました: PC-B がトーチを奪いました」
  5. PC-A はテレグラム メッセージを送信します:「トーチは PC-B に引き渡されました」
  6. PC-A: 命令によるシャットダウン、終了コード 2 (FACKEL_LOST)
  7. PC-A のトレイ: 終了コード 2 を検出 → 再起動なし → トレイが終了
=========
TRAY-LOCK

ファイル: %TEMP%\bach_bridge_tray.lock


  - 同じ PC 上に 2 つのトレイ インスタンスが存在しないようにします
  - トレイがまだ実行中かどうかを確認するためにデーモンによって使用されます。
    (トレイ結合: トレイが停止するとデーモンが終了します)
  - トレイのfinallyブロックで削除されます(正常に終了した場合)
  - トレイがクラッシュした場合: ロックが残る → デーモンがデッドトレイを検出
    次のチェック (30 秒ごと) の後、終了します
=======================
デーモンの終了コード


  0 通常終了 (ユーザーが「終了」を選択)
  起動時に 1 つのエラー (ロックが占有されているなど)
  2 FACKEL_LOST — トーチが別の PC に引き継がれました
      → トレイは終了コード 2 でデーモンを再起動しません
====================================
アーキテクチャ: コネクタ VS. BRIDGE

Bridge (claude_bridge) は、独自のサービスを持つ唯一のサービスです。
デーモン プロセスには調整が必要です。

コネクタ (telegram_connector.py、discord_connector.py など) は次のとおりです。
独自のデーモンを持たない純粋なアダプター モジュール - ブリッジ デーモンによって使用されます。



 と呼ばれ、独自のロック/トーチ システムは必要ありません。  ブリッジデーモン → ロックファイル + トーチあり
  telegram_connector.py → アダプタ、ロックなし
  discord_connector.py → アダプター、ロックなし
  signal_connector.py → アダプター、ロックなし
  homeassistant_connector.py → アダプター、ロックなし
========
診断

  トーチのステータスを確認します。
    Python -c "
    sqlite3、jsonをインポート
    pathlibインポートパスから
    db = パス('data/bach.db')
    conn = sqlite3.connect(str(db))
    rows = conn.execute('SELECT * FROM Bridge_session_lock').fetchall()
    行内の r の場合: print(r)
    「
  ブリッジログ:

    データ/ログ/claude_bridge.log


  関連するログ メッセージ:
    「トーチ取得: トーチ取得 (X からの強制引き継ぎ)」 - 通常の引き継ぎ
    「TORCH LOST: X がトーチを受け取りました」 - この PC は負けます
    「ハートビートが失敗しました (DB の問題)」 - 短い DB エラー
=========================
関連する決定
