pi-system/doku/fix-plan-orchestrator-wecker-v2026-06-02-18-19.md

Fix-Plan: Orchestrator wacht nicht auf, wenn Subagent auf Bestätigung wartet

Version: v2026-06-02-18-19 Status: Plan — Umsetzung in derselben Session direkt im Anschluss Betroffene Datei: extensions/rule-enforcer.ts (Repo) → deployed nach ~/.pi/agent/extensions/rule-enforcer.ts

---

1. Vorfall (log-belegt)

Quelle: Orchestrator-Session-Log ~/.pi/agent/sessions/--media-xray-NEU-Code-20260602-locosoft-recherche--/2026-06-02T14-29-08-398Z_019e88bd-...jsonl

15:21–15:24   watch_subagents-Schleife läuft sauber (alle ~30s ein toolResult,
              Orchestrator ruft watch_subagents jedes Mal neu auf). ✅
15:24:27      USER unterbricht mit neuer Anfrage.
15:25:00      Orchestrator startet Subagent lexware-arbeitsamt, schreibt Text
              "SubAgent lexware-arbeitsamt läuft:…"  → TURN ENDET, Orchestrator idle.
   ── 36,6 min KEIN watch_subagents, KEINE Aktivität ──
16:01:33      USER tippt → Orchestrator wacht auf.

Subagent-Log (…lexware-arbeitsamt…jsonl): letzter Eintrag 16:00:51 assistant OHNE folgendes toolResult = blockierender Bestätigungs-Dialog (Tool-Call gestellt, confirm-Dialog offen, Tool nie ausgeführt).

2. Root Cause (bewiesen)

watch_subagents ist ein Polling-Tool, das nach ~30s zurückkehrt. Die „Dauerüberwachung" existiert nur, solange das LLM es immer wieder selbst neu aufruft.

Um 15:24:27 hat die User-Zwischenfrage die Kette unterbrochen. Der Orchestrator beantwortete sie, kündigte um 15:25:00 den Subagenten an — und re-armte die watch_subagents-Schleife nicht. Der Turn endete mit einem Text → Orchestrator idle → Schleife für immer tot, bis ein externer Trigger (der Mensch) kam.

Das setInterval(30s) der Extension lief weiter und schrieb in die Alert-Datei /tmp/.pi-subagent-alert. Aber die Datei wird nur in before_agent_start gelesen (rule-enforcer.ts:196), und before_agent_start feuert nur bei Turn-Start. Kein Turn → Alert nie gelesen. Der passive Datei-Mechanismus kann einen idle Orchestrator strukturell nicht aufwecken.

3. Zwei unterschiedliche Lücken (wichtig fürs Design)

Lücke	Zeitraum	Zustand	Bisher erkannt?
B — verwaiste Überwachung	15:25:00–16:00:51 (~35 min)	Subagent arbeitet, KEIN Dialog offen, Orchestrator idle	nein
A — offener Bestätigungs-Dialog	16:00:51–16:01:33 (~40 s)	Subagent wartet auf „Erlauben?", Orchestrator idle	nur passiv (wirkungslos bei idle)

4. Belegte API-Grundlage (Pi 0.78.0)

~/.pi/.../dist/core/extensions/types.d.ts:

• Z. 843: pi.sendUserMessage(content, opts?) — „Send a user message to the agent. Always triggers a turn. When the agent is streaming, use deliverAs to specify how to queue."
• Z. 835: pi.sendMessage(msg, {triggerTurn?, deliverAs?})
• Z. 221: ctx.isIdle() — „Whether the agent is idle (not streaming)" (nur in Event-Handlern via ctx, nicht auf pi selbst → muss aus einem Handler in eine Closure-Variable übernommen werden)
• Z. 75: ctx.ui.notify(message, "warning") — sichtbare Meldung an den Menschen

5. Korrektur des Designs (Benutzer-Einwand, berechtigt)

Ursprünglich wollte ich nur den offenen Dialog (Trigger A) abfangen und „Subagent läuft, Orchestrator idle" auf später verschieben. Falsch. Die korrekte Invariante ist:

Solange mindestens ein Subagent läuft, darf der Orchestrator nicht idle sein.

„Idle Orchestrator + laufender Subagent" ist kein tolerierbarer Zustand, sondern der Bug selbst — und genau das war heute 35 min lang der Fall, bevor überhaupt ein Dialog aufkam. Der offene Dialog ist nur ein Spezialfall: ein wartender Subagent ist ein noch lebender pi-Prozess; die Prozess-Erkennung erfasst ihn ohnehin.

Zuverlässige „läuft ein Subagent?"-Erkennung (empirisch verifiziert 2026-06-02 18:2x)

pane_current_command ist unbrauchbar — meldet bash, obwohl Pi läuft (Pi ist Kindprozess der bash -c "… GlmPi …"). Verifizierte Methode = Prozessbaum:

für jede tmux-Session mit pane_current_path unter /home/xray/.pi/subagents/:
    pane_pid holen → hat sie ein Kind mit comm == "pi"?  → Subagent läuft.

Test an 2 echten Sessions: beide korrekt als „läuft" erkannt (pi-Kind 12335/13687). Fertige Session (bash auf read, kein pi-Kind) → korrekt „läuft nicht". Kein Keyword-Matching.

6. Fix — diese Session (invarianten-basiert)

Der 30s-Check:

1. laufendeSubagenten() per Prozessbaum bestimmen. Keiner → nichts tun (idle ist erlaubt).
2. Alert-Datei schreiben (passiver Pfad — greift, wenn der Orchestrator gerade in einem Turn ist).
3. Idle-Erkennung (ctx-unabhängig): Aktivitäts-Zeitstempel letzteAktivitaet wird in message_start/update/end, tool_execution_, turn_ aktualisiert. Idle = seit IDLE_SCHWELLE_MS (45 s) kein Event. (45 s > 30 s watch_subagents-Pollintervall ⇒ keine Fehlweckung während aktiver Überwachung.) Zusätzlich: wenn letzterCtx.isIdle() === false → definitiv beschäftigt, nicht wecken.
4. Idle und Subagent läuft → aktiv wecken: pi.sendUserMessage(…) (löst garantiert einen Turn aus) + letzterCtx.ui.notify(…) für den Menschen. Dialog-Inhalt reichert die Meldung an.

Eigenschaften:

• Bias zum Wecken: verpasster Wecker = teuer (heute 35 min), überflüssiger = nur kurz lästig.
• Spam-Schutz: höchstens 1 aktive Weckung pro WECK_MIN_ABSTAND_MS (60 s).
• Selbstterminierend: Hält der Orchestrator nach der Weckung seine watch_subagents-Schleife, bleibt er non-idle → keine weiteren Weckungen. Erst wenn alle Subagenten fertig sind, endet die Überwachung regulär.
• ctx-Robustheit: Idle wird primär zeitbasiert erkannt, nicht über ein evtl. veraltetes ctx-Objekt. isIdle() dient nur als zusätzliches „beschäftigt"-Veto.

Bekannter Trade-off (ehrlich)

Hält der Orchestrator die Schleife trotz Weckung wiederholt nicht, wird er ~1×/60 s erneut geweckt, solange der Subagent läuft. Das bläht den Kontext (je eine User-Nachricht pro Weckung). Im Normalfall (Orchestrator nimmt die Schleife nach 1. Weckung wieder auf) bleibt es bei einer Weckung. Responsivität wird höher gewichtet als Kontext-Sparsamkeit — bewusst.

7. Rollback

Vor der Änderung: Git-Commit des Ist-Stands (Repo) + Backup der deployten Datei.

# Repo zurück:
git checkout HEAD -- extensions/rule-enforcer.ts
# Deploy zurück (Backup wird vom install-Schritt mit Timestamp angelegt):
cp ~/.pi/agent/extensions/rule-enforcer.ts.bak-<ts> ~/.pi/agent/extensions/rule-enforcer.ts
# Wirksam nach Pi-Neustart bzw. /reload.

8. Erwartetes Verhalten & Live-Test (durch Benutzer)

Erwartung: Orchestrator ist idle, ein Subagent zeigt „Erlauben?". Innerhalb von ≤30 s erscheint im Orchestrator eine Auto-Weckung (sichtbare notify + neuer Turn), der Orchestrator ruft watch_subagents und reagiert auf den Dialog — ohne dass der Mensch tippen muss.

Testszenario (nur mit echtem Orchestrator+Subagent valide):

1. Pi-Orchestrator neu starten (lädt geänderte Extension) bzw. /reload.
2. Subagent starten, der einen Bestätigungs-Dialog auslöst (z. B. eine Aktion, die confirm-deletion.ts triggert).
3. Orchestrator nicht anfassen, idle lassen.
4. Beobachten: Kommt innerhalb ~30–60 s eine Auto-Weckung und reagiert der Orchestrator?

Ehrlich markiert: Ob pi.sendUserMessage() aus einem setInterval heraus in der laufenden Pi-Version genau dieses Verhalten zeigt, ist durch die Typdefinition belegt, aber noch nicht in einem Live-Lauf bestätigt. Erst der Test in Schritt 1–4 verifiziert den Fix. Bis dahin gilt der Fix als „implementiert, nicht verifiziert".