pi-system/SESSION_HANDOVER.md

# PiSystem — Session Handover

> Diese Datei dient als Kontext-Übergabe zwischen Sessions.
> Neue Session: Lies diese Datei zuerst.

---

## Projekt: Pi-Orchestrator-Infrastruktur — deterministisch, maschinenübergreifend

**Verzeichnis:** `/media/xray/NEU/Code/PiSystem20260602/`

**Ziel:** Alle Pi-Orchestrator-Infrastrukturkomponenten in einem Git-Repo zentralisieren,
sodass auf jedem Rechner via `git clone` + `./install.sh` exakt derselbe Stand entsteht.
Kein Drift mehr zwischen Maschinen, keine unterschiedlichen Fehlersymptome.

---

## Kontext: Warum dieses Repo

Bisher war die Infrastruktur verteilt auf:
- `~/bin/Sub*` — SubAgenten, SubStatus, SubWatcher
- `~/.pi/agent/extensions/` — confirm-deletion, arbeitsweise-guard, etc.
- `~/.pi/agent/memory/` — arbeitsweise, subagent-autocheck
- `~/.pi/agent/AGENTS.md` — Orchestrator-Instruktionen

Jeder Rechner hatte einen anderen Stand. Das PiSystem-Repo ist die **Single Source of Truth**.

### Architektur des Stasis-Detektors (SubConfirm)

**Problem:** Der Orchestrator bemerkte nicht, wenn ein Subagent auf Bestätigung wartete.
**Ursache:** SubWatcher nutzte Keyword-Matching — `confirm-deletion.ts`-Dialoge wurden nicht erkannt.
**Lösung:** SubConfirm — prüft alle 30s ob Session-Output stasis ist (unverändert), schreibt
dann den vollständigen Pane-Inhalt in `/tmp/.pi-subagent-alert`. Die Extension
`arbeitsweise-guard.ts` zeigt das dem Orchestrator beim nächsten Tool-Call.
Kein Keyword-Matching — der Orchestrator beurteilt selbst.

**Datenfluss:**
```
SubConfirm (Bash-Daemon) → /tmp/.pi-subagent-alert → arbeitsweise-guard.ts → Orchestrator
```

---

## ✅ Entscheidungen

| # | Entscheidung | Begründung | Datum |
|---|---|---|---|
| 1 | Stasis-Erkennung statt Keyword-Matching | Genereller, funktioniert für alle Dialog-Typen — nicht nur bekannte | 2026-06-02 |
| 2 | Alert-File-Mechanismus (`/tmp/.pi-subagent-alert`) | bestehende Infrastruktur in arbeitsweise-guard.ts, keine neue Komponente nötig | 2026-06-02 |
| 3 | `intercom` ist kein Shell-Binary | intercom ist ein Pi-internes Tool (Extension), kein bash-Kommando — SubConfirm nutzt daher Alert-File | 2026-06-02 |
| 4 | SubConfirm via `--skip` die Orchestrator-Session ausschließen | Orchestrator-Session soll nicht als Stasis erkannt werden | 2026-06-02 |
| 5 | install.sh idempotent mit Backups | Mehrfaches Ausführen sicher, bestehende Dateien werden mit Timestamp gesichert | 2026-06-02 |

---

## 🔜 Nächste Schritte

| # | Aktion | Priorität | Status |
|---|---|---|---|
| 1 | **Socket Firewall installieren** — `npx socket` als Pre-Install-Hook für pnpm/npm, via Subagent (`socket-firewall-install/` Ordner liegt bereits im Repo, noch uncommitted) | 1 | ⬜ |
| 2 | Verbleibende 5 PNPM-Sicherheitstipps aus Video umsetzen (Block Git-Dependencies, etc.) | 2 | ⬜ |
| 3 | **pi-web Session-Store auf SQLite umstellen** — `connect-sqlite3`, DB `/root/.pi-web/sessions.db` (keine Eile, Workaround: sign-out → sign-in) | 3 | ⬜ |
| 4 | Forgejo-Repos **MyPi** und **AgentPi** prüfen — nützliche Inhalte ins PiSystem-Repo übernehmen | 4 | ⬜ |
| 5 | SubConfirm in SubAgenten einbauen: beim ersten SubAgent-Start automatisch starten wenn noch nicht läuft | 5 | ⬜ |

---

## Session: 2026-06-02 11:55

### Erreichtes

- **Root Cause analysiert:** SubWatcher hat `confirm-deletion.ts`-Dialoge nicht erkannt weil Keyword-Patterns fehlten — aber Keyword-Matching ist generell der falsche Ansatz
- **SubConfirm geschrieben** (`bin/SubConfirm`): Stasis-Detektor, 30s-Intervall, schreibt Pane-Inhalt in Alert-File, kein Keyword-Matching
- **AGENTS.md erweitert**: Neuer Abschnitt "SubConfirm — Reaktionslogik" mit konkreten `tmux send-keys`-Befehlen für Yes/No
- **subagent-autocheck.md aktualisiert**: Verweist jetzt auf SubConfirm statt manuelle Befehle
- **install.sh erstellt**: Deterministisch, idempotent, mit Dry-Run-Modus, prüft Voraussetzungen
- **Git-Repo initialisiert**: Erster Commit `fb3daab`

### Offene Fragen

- Forgejo-Repos **MyPi** und **AgentPi** enthalten möglicherweise weitere nützliche Infrastruktur die übernommen werden sollte — wurde noch nicht geprüft
- SubConfirm wurde noch nicht auf dem aktuellen Rechner deployed (nur ins Repo geschrieben)
- Autostart von SubConfirm in SubAgenten noch nicht eingebaut

### Kontext für nächste Session

Die nächste Session soll:
1. Forgejo-Repos MyPi und AgentPi lesen (via CrowdBrain/Forgejo-API)
2. Relevante Inhalte ins PiSystem-Repo übernehmen
3. Dann Forgejo-Repo `pi-system` anlegen und pushen

---

## Session: 2026-06-02 15:27

### Erreichtes

- **pi.ccpn.cc Modell auf `minimax-m3:cloud` umgestellt** (war `kimi-k2.6` — down): settings.json + index.html gesetzt, pi-web neugestartet. Modell steht bereit, wird aber aktuell nicht aktiv genutzt.

- **Session-Loss-Bug verstanden:** `express-session` in pi-web nutzt In-Memory-Store → nach jedem `docker restart pi-web` sind alle Sessions weg → WebSocket bekommt 401 → Enter/Senden funktioniert nicht. Workaround: `https://pi.ccpn.cc/logto/sign-out` → neu einloggen.

- **AGENTS.md erweitert (autorisierte Änderungen durch Orchestrator heute):**
  - Session-Start-Checkliste Punkte 5–8: CrowdBrain-Skill immer laden, watch_subagents, SubConfirm
  - Kommunikationsstil: max. 3–4 Zeilen, keine Tabellen/Zusammenfassungen
  - Selbst-Lesen verboten: Orchestrator liest keine Logs/Quellcode selbst
  - Orchestrator-Scope: nur tun was explizit beauftragt wurde
  - **Installationen immer delegieren (W10):** npm/npx/pip/apt nie direkt ausführen — immer Subagent

- **confirm-deletion.ts gefixt:** `SubAgenten`-Aufrufe wurden als Package-Installation erkannt, weil die Aufgabenbeschreibung `npx socket` enthielt → `SubAgenten` zu `SAFE_PACKAGE_COMMANDS` hinzugefügt

- **PNPM-Sicherheitssetup:** pnpm 11.5.1 installiert, 7-Tage Release-Age-Gating aktiv (`registry.age=7`)

### Offene Fragen

- Ob `minimax-m3:cloud` auf pi.ccpn.cc stabil läuft muss noch bestätigt werden (Frontend nach Login testen)
- 5 weitere PNPM-Sicherheitstipps aus Video noch nicht umgesetzt (Block Git-Dependencies, Socket Firewall, Pre-Install-Audit, etc.)
- Socket Firewall Installation abgebrochen — noch ausständig

### Wichtige Pfade (Server: agentserver 116.203.222.129:2222, User: xray)

- Pi-Web Quellcode: `/home/xray/pi-web/` (server.js, public/index.html)
- Pi-Web Container: `pi-web` (docker)
- Pi-Agent Container: `pi-agent` (docker, teilt Volume `/home/xray/.pi`)
- Settings (shared Volume): `/home/xray/.pi/agent/settings.json`
- SSH: `ssh -o ControlPath=~/.ssh/sockets/xray@116.203.222.129-2222 agentserver "<cmd>"`

### Kontext für nächste Session

1. **Zuerst:** pi-web Session-Store auf SQLite umstellen (Priorität 1 — wiederkehrender Schmerz)
2. Dann Socket Firewall via Subagent installieren
3. Nach jedem pi-web-Neustart bis zum Fix: `https://pi.ccpn.cc/logto/sign-out` → neu einloggen

---

## Session: 2026-06-02 15:33 — Session-Abbruch wegen Kontext-Durcheinander

### Was passiert ist

Claude hat in dieser Session angefangen, pnpm-bezogene Arbeiten (Socket Firewall) fortzuführen, obwohl der Benutzer das Gespräch neu begonnen hatte. Der Benutzer hat das Durcheinander bemerkt und die Session sauber beendet.

**Keine Code-Änderungen wurden in dieser Session gemacht.**

### Uncommitted Ordner im Repo (git status)

```
?? socket-firewall-install/    # Arbeitsergebnis aus Session 15:27 — noch nicht committed
?? terminal-flackern-analyse/  # Analyse-Ordner — noch nicht committed
```

Diese Ordner müssen in der nächsten Session entweder committed oder entschieden werden.

### Kontext für nächste Session

**Diese Datei zuerst lesen**, dann:

1. **`socket-firewall-install/` prüfen** — was ist drin? Wenn fertig → committen. Wenn unvollständig → Socket Firewall via Subagent fertigstellen (Priorität 1 aus Nächste-Schritte-Tabelle oben).
2. **`terminal-flackern-analyse/` prüfen** — relevanter Inhalt? Wenn ja committen, sonst löschen.
3. Weiter nach der Prioritätsliste oben (pi-web Session-Store, PNPM-Sicherheitstipps, etc.)

**Wichtige Erinnerung:** Nächste Session MIT DEM RICHTIGEN PROJEKT starten — immer zuerst diese Datei lesen: `/media/xray/NEU/Code/PiSystem20260602/SESSION_HANDOVER.md`

---

## Session: 2026-06-02 15:56 — Regel-Enforcement und Extension-Fixes

### Erreichtes

- **Repo bereinigt:** `socket-firewall-install/`, `terminal-flackern-analyse/`, `pi-web-session-debug/` aus dem Repo-Verzeichnis nach `/media/xray/NEU/Code/20260602/` verschoben — diese Ordner gehören nicht ins Pi-System-Repo

- **Extension-Bug gefixt** (`session-header.ts` + `session-index.ts`): Pi's `setWidget`-API erwartet als zweiten Parameter eine Factory-Funktion `(_ui, theme) => widget`, nicht direkt das Widget-Objekt. Beide Extensions übergaben direkt `makeWidget(...)` → "content is not a function". Fix: alle `setWidget`-Aufrufe auf `(_ui, theme) => makeWidget(...)` umgestellt. Deployed + committed.

- **AGENTS.md: 5 neue Regeln dokumentiert** (W06–W10):
  - **W06** Kein internes Deliberieren ("Let me check...", "Actually...", "Weil ich...") in User-Output
  - **W07** Subagenten-Strategie nie eigenständig aufgeben — Benutzer informieren, auf Anweisung warten
  - **W08** Erlaubte Edit-Pfade: nur `~/.pi/agent/` und CWD direkt editierbar, `~/.bashrc` etc. immer via Subagent
  - **W09** `sleep` in jeder Form verboten — `watch_subagents` nutzen
  - **W10** Subagent nie doppelt starten — einmal starten, dann warten

- **Neue Extension `rule-enforcer.ts`** deployed nach `~/.pi/agent/extensions/`:
  - `before_agent_start`: injiziert W06–W10 + WATCH-Regel in **jeden** System-Prompt-Turn (nicht nur beim Session-Start)
  - `message_end`: scannt Pi's Ausgabe auf Deliberations-Muster, setzt Korrektur-Flag für nächsten Turn
  - `setInterval` 30s: Background-Check auf tmux-Bestätigungs-Dialoge, unabhängig von Pi's Tool-Calls → schreibt in `/tmp/.pi-subagent-alert`
  - `before_agent_start` liest Alert-File und zeigt 🚨-Hinweis prominent im System-Prompt

### Entscheidungen

| # | Entscheidung | Begründung | Datum |
|---|---|---|---|
| 6 | rule-enforcer.ts als eigene Extension statt arbeitsweise-guard.ts-Erweiterung | Trennung der Verantwortlichkeiten: arbeitsweise-guard blockiert Tools, rule-enforcer enforced Output-Verhalten | 2026-06-02 |
| 7 | setInterval 30s in Extension statt nur SubConfirm | SubConfirm kann nicht laufen — Extension läuft immer im Pi-Prozess | 2026-06-02 |
| 8 | before_agent_start systemPrompt-Injection statt nur AGENTS.md | AGENTS.md wird einmal beim Start geladen, before_agent_start feuert bei jedem Turn — Regeln bleiben im Context-Window frisch | 2026-06-02 |

### Noch nicht getestet

- `rule-enforcer.ts` wurde noch **nicht live getestet** — Pi muss neu gestartet werden damit die Extension geladen wird
- Ob der W06-Scan die richtigen Phrases erkennt ohne False Positives muss im Betrieb validiert werden
- Ob `before_agent_start` systemPrompt wirklich appended (nicht replaced) muss beim ersten Start beobachtet werden

### Kontext für nächste Session

**Sofort nach Session-Start:**
1. Pi neu starten (damit `rule-enforcer.ts` geladen wird): `OrchestratorPi` aufrufen
2. Beobachten ob W06-Violations weniger werden — wenn rule-enforcer falsch-positive erzeugt: Muster in `DELIBERATIONS_MUSTER` Array anpassen ([extensions/rule-enforcer.ts](extensions/rule-enforcer.ts) Zeile ~50)

**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.