PTY und Prozess-Supervision Plan

1. Problem und Ziel

Wir brauchen einen zuverlässigen Lifecycle für lang laufende Befehlsausführung über:

• exec Vordergrund-Runs
• exec Hintergrund-Runs
• process Folgeaktionen (poll, log, send-keys, paste, submit, kill, remove)
• CLI-Agent-Runner-Subprozesse

Das Ziel ist nicht nur PTY-Unterstützung. Das Ziel ist vorhersagbares Ownership, Abbruch, Timeout und Cleanup ohne unsichere Prozess-Matching-Heuristiken.

2. Scope und Grenzen

• Implementierung intern in src/process/supervisor halten.
• Kein neues Paket dafür erstellen.
• Aktuelle Verhaltenskompatibilität wo praktikabel beibehalten.
• Scope nicht auf Terminal-Replay oder tmux-artige Session-Persistenz erweitern.

3. In diesem Branch implementiert

Supervisor-Baseline bereits vorhanden

• Supervisor-Modul ist unter src/process/supervisor/* eingerichtet.
• Exec-Runtime und CLI-Runner sind bereits über Supervisor-Spawn und -Wait geroutet.
• Registry-Finalisierung ist idempotent.

Dieser Durchgang abgeschlossen

1. Expliziter PTY-Befehlsvertrag

• SpawnInput ist jetzt eine diskriminierte Union in src/process/supervisor/types.ts.
• PTY-Runs erfordern ptyCommand statt der generischen argv-Wiederverwendung.
• Supervisor rekonstruiert PTY-Befehlsstrings nicht mehr aus argv-Joins in src/process/supervisor/supervisor.ts.
• Exec-Runtime übergibt ptyCommand jetzt direkt in src/agents/bash-tools.exec-runtime.ts.

2. Prozessschicht-Typentkopplung

• Supervisor-Typen importieren nicht mehr SessionStdin aus Agents.
• Prozesslokaler Stdin-Vertrag lebt in src/process/supervisor/types.ts (ManagedRunStdin).
• Adapter hängen nur noch von Prozessebenen-Typen ab:
  • src/process/supervisor/adapters/child.ts
  • src/process/supervisor/adapters/pty.ts

3. Prozess-Tool-Lifecycle-Ownership-Verbesserung

• src/agents/bash-tools.process.ts fordert Abbruch jetzt zuerst über den Supervisor an.
• process kill/remove nutzt jetzt Prozesstree-Fallback-Terminierung wenn Supervisor-Lookup fehlt.
• remove behält deterministisches Remove-Verhalten bei, indem laufende Session-Einträge sofort nach Terminierungsanforderung entfernt werden.

4. Single-Source-Watchdog-Defaults

• Gemeinsame Defaults in src/agents/cli-watchdog-defaults.ts hinzugefügt.
• src/agents/cli-backends.ts konsumiert die gemeinsamen Defaults.
• src/agents/cli-runner/reliability.ts konsumiert dieselben gemeinsamen Defaults.

5. Toter-Helper-Cleanup

• Ungenutzten killSession-Helper-Pfad aus src/agents/bash-tools.shared.ts entfernt.

6. Direkte Supervisor-Pfad-Tests hinzugefügt

• src/agents/bash-tools.process.supervisor.test.ts hinzugefügt für Kill- und Remove-Routing über Supervisor-Abbruch.

7. Zuverlässigkeitslücken-Fixes abgeschlossen

• src/agents/bash-tools.process.ts fällt jetzt auf echte OS-Level-Prozess-Terminierung zurück wenn Supervisor-Lookup fehlt.
• src/process/supervisor/adapters/child.ts nutzt jetzt Prozesstree-Terminierungssemantik für Standard-Cancel/Timeout-Kill-Pfade.
• Gemeinsames Prozesstree-Utility in src/process/kill-tree.ts hinzugefügt.

8. PTY-Vertrag-Randfälle-Coverage hinzugefügt

• src/process/supervisor/supervisor.pty-command.test.ts für wörtliche PTY-Befehlsweiterleitung und Leer-Befehl-Ablehnung hinzugefügt.
• src/process/supervisor/adapters/child.test.ts für Prozesstree-Kill-Verhalten bei Child-Adapter-Abbruch hinzugefügt.

4. Verbleibende Lücken und Entscheidungen

Zuverlässigkeitsstatus

Die zwei erforderlichen Zuverlässigkeitslücken für diesen Durchgang sind jetzt geschlossen:

• process kill/remove hat jetzt einen echten OS-Terminierungs-Fallback wenn Supervisor-Lookup fehlt.
• Child-Cancel/Timeout nutzt jetzt Prozesstree-Kill-Semantik für den Standard-Kill-Pfad.
• Regressionstests wurden für beide Verhaltensweisen hinzugefügt.

Dauerhaftigkeit und Start-Abgleich

Restart-Verhalten ist jetzt explizit als reiner In-Memory-Lifecycle definiert.

• reconcileOrphans() bleibt in src/process/supervisor/supervisor.ts bewusst ein No-op.
• Aktive Runs werden nach Prozess-Neustart nicht wiederhergestellt.
• Diese Grenze ist für diesen Implementierungsdurchgang beabsichtigt, um partielle Persistenzrisiken zu vermeiden.

Wartbarkeits-Follow-ups

1. runExecProcess in src/agents/bash-tools.exec-runtime.ts behandelt noch mehrere Verantwortlichkeiten und kann in einem Follow-up in fokussierte Helper aufgeteilt werden.

5. Implementierungsplan

Der Implementierungsdurchgang für erforderliche Zuverlässigkeits- und Vertragspunkte ist abgeschlossen.

Abgeschlossen:

• process kill/remove Fallback-reale-Terminierung
• Prozesstree-Abbruch für Child-Adapter-Standard-Kill-Pfad
• Regressionstests für Fallback-Kill und Child-Adapter-Kill-Pfad
• PTY-Befehl-Randfälle-Tests unter explizitem ptyCommand
• Explizite In-Memory-Restart-Grenze mit reconcileOrphans() No-op by Design

Optionaler Follow-up:

• runExecProcess in fokussierte Helper aufteilen ohne Verhaltensdrift

6. Dateiübersicht

Prozess-Supervisor

• src/process/supervisor/types.ts aktualisiert mit diskriminiertem Spawn-Input und prozesslokalem Stdin-Vertrag.
• src/process/supervisor/supervisor.ts aktualisiert für explizites ptyCommand.
• src/process/supervisor/adapters/child.ts und src/process/supervisor/adapters/pty.ts von Agent-Typen entkoppelt.
• src/process/supervisor/registry.ts idempotentes Finalize unverändert beibehalten.

Exec- und Prozess-Integration

• src/agents/bash-tools.exec-runtime.ts aktualisiert für explizite PTY-Befehlsübergabe und Fallback-Pfad.
• src/agents/bash-tools.process.ts aktualisiert für Abbruch über Supervisor mit echtem Prozesstree-Fallback-Terminierung.
• src/agents/bash-tools.shared.ts direkten Kill-Helper-Pfad entfernt.

CLI-Zuverlässigkeit

• src/agents/cli-watchdog-defaults.ts als gemeinsame Baseline hinzugefügt.
• src/agents/cli-backends.ts und src/agents/cli-runner/reliability.ts konsumieren jetzt dieselben Defaults.

7. Validierungslauf in diesem Durchgang

Unit-Tests:

• pnpm vitest src/process/supervisor/registry.test.ts
• pnpm vitest src/process/supervisor/supervisor.test.ts
• pnpm vitest src/process/supervisor/supervisor.pty-command.test.ts
• pnpm vitest src/process/supervisor/adapters/child.test.ts
• pnpm vitest src/agents/cli-backends.test.ts
• pnpm vitest src/agents/bash-tools.exec.pty-cleanup.test.ts
• pnpm vitest src/agents/bash-tools.process.poll-timeout.test.ts
• pnpm vitest src/agents/bash-tools.process.supervisor.test.ts
• pnpm vitest src/process/exec.test.ts

E2E-Ziele:

• pnpm vitest src/agents/cli-runner.test.ts
• pnpm vitest run src/agents/bash-tools.exec.pty-fallback.test.ts src/agents/bash-tools.exec.background-abort.test.ts src/agents/bash-tools.process.send-keys.test.ts

Typecheck-Hinweis:

• pnpm build (und pnpm check für vollständiges Lint/Docs-Gate) in diesem Repo verwenden. Ältere Hinweise, die pnpm tsgo erwähnen, sind veraltet.

8. Betriebsgarantien beibehalten

• Exec-Env-Härtungsverhalten ist unverändert.
• Approval- und Allowlist-Flow ist unverändert.
• Output-Sanitization und Output-Caps sind unverändert.
• PTY-Adapter garantiert weiterhin Wait-Settlement bei erzwungenem Kill und Listener-Disposal.

9. Definition of Done

1. Supervisor ist Lifecycle-Owner für verwaltete Runs.
2. PTY-Spawn nutzt expliziten Befehlsvertrag ohne argv-Rekonstruktion.
3. Prozessschicht hat keine Typabhängigkeit von der Agent-Schicht für Supervisor-Stdin-Verträge.
4. Watchdog-Defaults sind Single Source.
5. Gezielte Unit- und E2E-Tests bleiben grün.
6. Restart-Dauerhaftigkeitsgrenze ist explizit dokumentiert oder vollständig implementiert.

10. Zusammenfassung

Der Branch hat jetzt eine kohärente und sicherere Supervision-Form:

• Expliziter PTY-Vertrag
• Sauberere Prozess-Schichtung
• Supervisor-gesteuerter Abbruchpfad für Prozessoperationen
• Echte Fallback-Terminierung wenn Supervisor-Lookup fehlt
• Prozesstree-Abbruch für Child-Run-Standard-Kill-Pfade
• Vereinheitlichte Watchdog-Defaults
• Explizite In-Memory-Restart-Grenze (kein Orphan-Abgleich über Restart in diesem Durchgang)