docs: Session 2026-06-02 18:33 — Orchestrator-Idle-Bug Root Cause + Fix dokumentiert

SESSION_HANDOVER.md

@@ -205,3 +205,50 @@ Diese Ordner müssen in der nächsten Session entweder committed oder entschiede
 **Danach:**
 3. pi-web Session-Store auf SQLite umstellen (wiederkehrender Schmerz — nach jedem `docker restart pi-web` müssen User sich neu einloggen)
 4. Forgejo-Repos MyPi und AgentPi prüfen — nützliche Inhalte ins PiSystem-Repo übernehmen
+
+---
+
+## Session: 2026-06-02 18:33 — Orchestrator-Idle-Bug (Root Cause + Fix)
+
+### Vorfall (log-belegt)
+
+Orchestrator reagierte ~36 min nicht, während Subagent `lexware-arbeitsamt` lief und
+zuletzt auf einen „Erlauben?"-Dialog wartete. Beweis im Orchestrator-Log
+(`…locosoft-recherche…jsonl`): Lücke **15:25:00 (assistant „SubAgent läuft") → 16:01:33
+(user)** — 36,6 min ohne jede Aktivität. Erst die User-Eingabe weckte ihn.
+
+### Root Cause (bewiesen, nicht vermutet)
+
+`watch_subagents` ist ein Polling-Tool (kehrt nach ~30s zurück). Die Überwachung lebt nur,
+solange das LLM es immer wieder neu aufruft. Eine User-Zwischenfrage um 15:24:27 riss die
+Schleife ab; der Orchestrator kündigte den Subagenten an und ging idle. Der passive
+Alert-File-Pfad (`/tmp/.pi-subagent-alert`) wird **nur in `before_agent_start` gelesen**,
+das bei idle nie feuert → Alert blieb ungelesen.
+
+### Benutzer-Einwand (zentral)
+
+„Warum sollte der Orchestrator idle sein, wenn noch Subagenten laufen?" → Die korrekte
+Invariante: **Solange ein Subagent läuft, darf der Orchestrator NICHT idle sein.** Der
+offene Dialog war nur ein Spezialfall (= noch lebender pi-Prozess).
+
+### Fix (committed `aa1539c`, deployed)
+
+`extensions/rule-enforcer.ts` neu: 30s-Check erkennt laufende Subagenten per **Prozessbaum**
+(lebt ein `pi`-Kind unter dem tmux-Pane? — `pane_current_command` ist unbrauchbar, meldet
+`bash`). Idle (zeitbasiert, 45s) + laufender Subagent → aktive Weckung via
+`pi.sendUserMessage()` (löst garantiert einen Turn aus) + `ui.notify`. Selbstterminierend,
+max. 1 Weckung/60s.
+
+- **Deployed:** `~/.pi/agent/extensions/rule-enforcer.ts`, Backup `*.bak-20260602-183309`
+- **Greift erst nach Pi-Neustart / `/reload`** — laufender Orchestrator hat noch die alte Version!
+- **Verifiziert:** Syntax, Modul-Load, 9 Handler, Prompt-Injection, W06, Prozessbaum an echten Sessions
+- **NICHT verifiziert:** Live-Weckpfad — Test nötig (siehe `doku/fix-plan-orchestrator-wecker-v2026-06-02-18-19.md` §8)
+
+### Offen / nächste Session
+
+1. **Live-Test des Weckers:** Pi neu starten → Subagent mit Bestätigungs-Dialog starten →
+   Orchestrator idle lassen → kommt binnen ~30–75s eine Auto-Weckung? (Erwartet: ja)
+2. Rollback bei Fehlverhalten: `cp ~/.pi/agent/extensions/rule-enforcer.ts.bak-20260602-183309
+   ~/.pi/agent/extensions/rule-enforcer.ts` + `git checkout aa1539c~1 -- extensions/rule-enforcer.ts`
+3. **Trade-off beobachten:** Hält der Orchestrator die Schleife trotz Weckung nicht, wird er
+   ~1×/60s erneut geweckt (Kontext-Bloat). Im Normalfall nur 1 Weckung.