# Hermes Worker Watcher MVP

Read-only Überwachung von Jobs, KI-Workern und Automationen unabhängig vom Ausführungsort. Der VPS ist das primäre Überwachungs- und Datenzentrum; lokale oder externe Worker können über einen kleinen Agenten Heartbeats und Run-Events melden. Das Projekt ist ein lokaler MVP-Entwurf und nimmt keine produktiven Änderungen vor.

## Architektur

`lokaler Collector oder Remote-Agent -> Evidenz/Event -> zentrale Normalisierung/Evaluierung -> SQLite -> Statushistorie/API/Report`

Die Entitäten Job, Instanz, Run, Beobachtung, Collector-Lauf und Watcher-Ereignis sind getrennt. Operational State, Health Status, Observation Status und Severity sind unabhängige Achsen. Collector-Fehler werden als Collector-Läufe gespeichert und nicht automatisch als Jobfehler interpretiert.

## Lokale Entwicklung

Voraussetzung ist Python 3.12. Optional werden pytest, mypy und ruff aus den Dev-Abhängigkeiten installiert:

```bash
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e '.[dev]'
cp config.example.yaml config.yaml
watcher --config config.yaml validate-config
watcher --config config.yaml migrate
watcher --config config.yaml scan
watcher --config config.yaml report --format markdown
watcher --config config.yaml serve
watcher --config config.yaml retention
```

Die API bindet standardmäßig nur an `127.0.0.1`. Endpunkte sind `/health`, `/health/live`, `/health/ready`, `/api/v1/status`, `/api/v1/alerts/summary`, `/api/v1/jobs`, `/api/v1/jobs/{instance_id}`, `/api/v1/workers`, `/api/v1/agents`, `/api/v1/remote-events`, `/api/v1/events`, `/api/v1/collectors`, `/api/v1/collectors/runs` und `/api/v1/collectors/{collector_name}`. Externe Agenten verwenden zusätzlich die POST-Endpunkte `/api/v1/agents/register` und `/api/v1/agents/events`.

## Sicherheit und Grenzen

Die Collector-Adapter lesen nur Dateien, `/proc` oder `systemctl show`. Externe Agenten senden ausschließlich deklarierte JSON-Ereignisse; bei Netzunterbrechung puffert die lokale SQLite-Outbox. Es gibt keine Restart-, Stop-, Kill-, Docker- oder Auto-Healing-Funktion und keine beliebigen Shell-Befehle aus der Konfiguration. Rohdaten werden in diesem MVP auf 1 MiB je Statusdatei begrenzt; Agent-Events auf 512 KiB. Für externe API-Zugriffe kann `HERMES_WATCHER_AGENT_TOKEN` gesetzt werden. Produktive Zugangsdaten, Cronjobs, Container und Systemdienste werden nicht verändert.

Retention ist implementiert, standardmäßig aber deaktiviert. Ein geplanter Deployment-Pfad, erforderliche Leserechte, Backup und Rollback stehen in `docs/deployment-plan.md`; er wurde nicht ausgeführt.

## Tests

```bash
pytest -q
mypy src
ruff check src tests
```