# Agent Process Dashboard Original MVP Plan

Note: the original MVP was read-only. The current app keeps read-only scanning
but now also supports explicit, confirmed `SIGTERM`/`SIGKILL` actions for fresh
dry-run candidates only.

Original direction: standalone GTK desktop app. The MVP was read-only plus
dry-run candidate reporting only, with no kill execution, no generated kill
command, no localhost server, and no network port. `/proc` is the primary
sampler.

## Summary

Build a new standalone GTK app in:

`/home/smlflg/Projekte/agent-process-dashboard`

The app monitors Samuel's current-user Linux process tree, classifies
agent/MCP/bridge processes, shows parent/child fanout, flags stale candidates,
and reports what a cleanup would target without executing it.

Superseded direction: the previous FastAPI/static web UI plan is replaced. Keep
its useful `/proc`, PID identity, classification, tree/group, and risk ideas;
remove localhost server, web frontend, and systemd daemon work from the MVP.

## Key Changes

- Python package: `agent_process_dashboard`.
- UI: GTK3/PyGObject desktop window.
- Core sampler: direct `/proc` reads, no `psutil` dependency in the MVP.
- Process identity: `boot_id:pid:start_time_ticks:uid`.
- Safety:
  - No `SIGTERM`, `SIGKILL`, renice, restart, or config mutation.
  - No `/proc/<pid>/environ` reads.
  - No executable cleanup command is printed.
  - Dry-run output is only candidate PIDs, identity keys, reasons, and
    exclusions.

## Implementation Tasks

1. Scaffold project files:
   - `pyproject.toml`
   - `README.md`
   - `src/agent_process_dashboard/`
   - `tests/`

2. Build testable core modules:
   - `procfs.py`: read `/proc`, parse stat/status/cmdline/statm/cgroup, handle
     disappearing PIDs.
   - `sanitize.py`: mask secrets in argv before display.
   - `classifier.py`: classify Claude, Codex, Hermes, opencode, Gemini, MCP
     servers, bridges, wrappers, terminals, editors, browsers, and unknowns.
   - `tree.py`: build parent/child trees and launch groups.
   - `risk.py`: compute fanout, bridge, stale, and global warning levels.
   - `dryrun.py`: generate read-only cleanup candidate reports.
   - `snapshot.py`: orchestrate sampler, classifier, tree, risk, and dry-run.

3. Build GTK UI:
   - Header KPIs: agent roots, MCP/bridges, max fanout, stale candidates, CPU
     hot, last scan.
   - Left: agent/root group list.
   - Center: process tree using `Gtk.TreeStore`.
   - Right: selected process details.
   - Bottom: dry-run candidate report.
   - Filters: Agent, MCP, Bridge, Stale, High Fanout.
   - Poll active snapshots every 2 seconds, idle snapshots every 5-10 seconds.

4. Risk defaults:
   - Per group child count `>= 20`: warn.
   - Per group child count `>= 50`: critical.
   - Per group bridge count `>= 6`: warn.
   - Per group bridge count `>= 12`: critical.
   - Global MCP/bridge count `>= 20`: warn.
   - Global MCP/bridge count `>= 50`: critical.
   - Global agent-related count `>= 30`: warn.
   - Global agent-related count `>= 70`: critical.
   - Bridge age `> 6h`: stale candidate.
   - Bridge age `> 24h`: strong stale candidate.
   - CPU idleness alone never makes a bridge stale.

## Test Plan

- Unit tests:
  - `/proc/<pid>/stat` parser handles spaces and parentheses.
  - PID reuse produces different `process_key`.
  - Missing processes during scan do not fail a snapshot.
  - Cmdline masking handles flags, `--flag=value`, env-style args, URLs, and
    common token prefixes.
  - Classifier avoids false positives from paths or incidental words.
  - Parent links are rejected when parent identity is absent/unstable.
  - Healthy idle MCP bridge is not marked stale.
  - Dry-run performs no mutation and returns no executable kill command.

- Integration smoke:
  - Spawn a shell with a child process and verify tree grouping.
  - Verify the app spawns no MCP/bridge children.
  - Verify no port is opened.
  - Verify no `/proc/<pid>/environ` reads exist in the code.
  - Target RSS budget: below about 300 MB.