# Dauerhafter Analyseworker

Der Worker verbindet die Übergabe-API mit dem vorhandenen Analyseablauf. Er nimmt
Pakete aus derselben Inbox auf, wählt die serverseitige Projektkonfiguration und
bearbeitet aktive Fälle bis zu Outbox oder Review. Er erstellt keine Patches,
führt keine Builds aus und verändert keine Projekt-Datenbank.

## Konfiguration

`config/worker.example.toml` verweist auf die Konfiguration der Übergabe-API.
API und Worker müssen denselben Workspace und Projektkatalog verwenden. Der
Worker benötigt die API-Clienttokens nicht, wohl aber die in seiner LLM-Konfiguration
genannten Provider-Zugangsdaten. Beide Prozesse dürfen getrennt laufen.

Für jedes freigegebene Projekt werden die Analysekonfigurationen in der
API-Konfiguration hinterlegt:

```toml
[[projects]]
id = "viano-core"
type = "wow"
profile = "vcore"
adapter = "vcore"
planning_mode = "joint"
[projects.settings]
project_config = "project.local.toml"
llm_config = "llm.early-review.local.toml"
investigation_config = "investigation.bounded.toml"
```

Die Pfade sind relativ zur API-Konfigurationsdatei. `llm_config` ist erforderlich.
Weitere optionale Einstellungen: `analysis_config`, `budget_config`,
`diagnosis_config`, `change_request_config`, `correction_config`. Ohne explizite
Datei gelten deren bestehende Standardwerte. Für den aktuellen Vcore-Betrieb die
erprobte `investigation.bounded.toml` verwenden; ältere ausführliche Promptmodi
können an der unveränderten 20.000-Zeichen-Grenze scheitern.

`planning_mode` ist je Projekt `joint` (Standard) oder `separate`. Die Profilbindung
einer Akte muss vollständig zum Katalog passen: `project.id`, `type`, `profile`.
Alte manuelle Pakete ohne `project.id` werden nicht automatisch zugeordnet.
Andere Projektadapter bleiben ein eigener Ausbauschritt.

## Start und Prüfung

```powershell
.\.venv\Scripts\python.exe -m viano_bug_analysis.worker check --config config/worker.local.toml
.\.venv\Scripts\python.exe -m viano_bug_analysis.worker run --config config/worker.local.toml
```

`check` lädt Konfiguration und prüft die Anwesenheit der LLM-Zugangsdaten. Es sendet
keine Modellanfrage und ist kein Erreichbarkeitstest für API, Datenbank oder
Repository. `run` verarbeitet angenommene Aufträge und kann deshalb kostenpflichtige
LLM-Aufrufe auslösen. Der reine Start ohne anstehende Fälle führt keine Modellaufrufe
aus. `run --once` führt genau einen Scheduler-Durchgang aus, nicht einen vollständigen
Buglauf. Auch dieser Modus kann LLM-Aufrufe auslösen.

API zusätzlich in einem zweiten Prozess starten:

```powershell
.\.venv\Scripts\python.exe -m viano_bug_analysis.api serve --config config/api.local.toml
```

Für diese Entwicklung wurden die zuvor nicht vorhandenen lokalen Dateien
`config/api.local.toml` und `config/worker.local.toml` mit dem Vcore-Profil vorbereitet.
Sie sind nicht versioniert und enthalten keine Zugangsschlüssel. Vorhandene lokale
Konfigurationen werden bei späteren Änderungen nicht automatisch überschrieben.

## Scheduling und Wiederanlauf

- Pro Durchgang erhält jeder berechtigte aktive Fall einen Dispatch. Danach
  darf der nächste Fall arbeiten. Gibt es Fortschritt, folgt der nächste Durchgang
  unmittelbar; nur im Leerlauf oder bei Wartefällen greift das Pollintervall.
- Der Dienst läuft als einzelner Analyseprozess. Eine OS-Dateisperre verhindert
  einen zweiten Worker im selben Workspace. Die Fall-Lease ist mit dem manuellen
  Trialbefehl geteilt. API-Veröffentlichungen verwenden weiterhin die kurzen
  Checkpoint-/Inbox-Sperren; während einer Modellanfrage bleibt die API benutzbar.
- Paketmanifest und Checkpoints bleiben maßgeblich. Es wird nur die neueste
  Generation pro Fall geprüft, nicht jede historische Generation erneut geöffnet.
- Bei Neustart werden verwaltete aktive Fälle und noch nicht übernommene Uploads
  wiedergefunden. PREPARED-Veröffentlichungen der API werden vor der Verarbeitung
  abgeschlossen. Rückläufer starten die bereits eröffnete neue Analyse-Revision;
  alte Interpretation und Hypothesen werden nicht als neue Ergebnisse behandelt.
- Bestehende LLM-Operationskennungen bleiben stabil. Der Dienst ändert keine
  Versuchskennungen, Budgets, Iterationsgrenzen oder Korrekturregeln, um einen
  blockierten Fall weiterzutreiben.
- `RETRY_PENDING`/`DEFERRED` beachten die gespeicherte Wartezeit. Ein unerwarteter
  Konfigurations-/Vorbereitungsfehler erhält einen lokalen Cooldown; andere Fälle
  werden weiterbearbeitet. Eine ausdrücklich zurückgegebene `ERROR`-Antwort oder
  unerwartete Exception während eines Dispatch erzeugt `ATTENTION`, statt dieselbe
  Fehlantwort endlos abzuspielen oder möglicherweise erneut Modellkosten auszulösen.
- BLOCKED bleibt BLOCKED, wenn eine menschliche Testerantwort benötigt wird,
  automatische Wiederholung untersagt ist, Modellvalidierung gescheitert ist oder
  die LLM-Wiederholungen ausgeschöpft sind. Explizit freigegebene, fällige technische
  Wiederholungen dürfen über den vorhandenen Resume-Checkpoint fortgesetzt werden.
- Outbox-/Review-Veröffentlichung wird nach Erfolg nicht ständig wiederholt. Nach
  einem Absturz zwischen Paketabschluss und Veröffentlichung kann der bestehende
  Outputvalidator die fehlende Veröffentlichung idempotent nachholen.

Ein Prozessabbruch während einer externen Modellanfrage kann deren bereits
berechnete Kosten nicht zurücknehmen. Ist die Antwort vor dem Checkpoint verloren
gegangen, lässt sich eine erneute Anfrage nicht grundsätzlich ausschließen. Der
Worker verspricht keine Exactly-once-Ausführung beim externen Anbieter.

## Betrieb und Fehlerbehandlung

```powershell
.\.venv\Scripts\python.exe -m viano_bug_analysis.worker status --config config/worker.local.toml
```

`runtime/worker/status.json` enthält den letzten Dienstzustand und gegebenenfalls
den bearbeiteten Fall. Es ist ein Snapshot, kein Beweis für einen noch lebenden
Prozess. Die bestehende Telemetrie liefert ergänzend Heartbeat, Phasen, Laufzeiten
und Modellverbrauch. `runtime/worker/cases/` enthält kleine lokale
Schedulingquittungen mit Status, Fehlercode, Wartezeit und Konfigurationshashes.
Keine Prompts, Antworten oder Geheimnisse werden diesen Quittungen hinzugefügt.
Die Statusantwort der Übergabe-API enthält für einen zugeordneten Fall zusätzlich
den letzten Workerstatus.

Die Akte bleibt vollständig transportabel. Die lokalen Quittungen sind keine
fachliche Beweisquelle und keine verteilte Jobdatenbank. Bei ihrer vollständigen
Entfernung müssen reine Scheduler-Cooldowns/Attention-Markierungen gegebenenfalls
neu erkannt werden; fachliche Sperren und LLM-Operationshistorie bleiben im Paket.

Konfigurationsdateien werden über ihre Hashes vor dem ersten Dispatch gebunden.
Eine geänderte Konfiguration wird nicht unbemerkt auf dieselbe aktive Revision
angewendet. Neue Profileinstellungen benötigen einen Worker-Neustart; laufende
Revisionen mit abweichender Bindung gehen auf `ATTENTION/WORKER_CONFIG_CHANGED`.
Auch abhängige Profil-/Relationsdateien nicht während einer Untersuchung ändern.
Eine allgemeine Migration laufender Modelloperationen auf neue Policies ist noch
kein Bestandteil dieses Dienstes.

Nach Behebung eines lokalen Schedulingfehlers kann der Betreiber den **gestoppten**
Worker freigeben:

```powershell
.\.venv\Scripts\python.exe -m viano_bug_analysis.worker retry --config config/worker.local.toml --case-id BUG-000020 --package-id api-PAKETIDENTITAET
```

Dies entfernt die lokale Warte-/Attention-Markierung, aber setzt keine LLM-Operation
oder fachliche Budgets zurück. Für einen fälligen `RESEARCH_UNAVAILABLE`-Fall
bestätigt der Befehl zusätzlich die Reparatur des Research-Dienstes und setzt dessen
Resume-Checkpoint fort. Andere BLOCKED-Gründe, ausstehende menschliche Rückmeldungen
und abweichende Konfigurationsbindungen werden damit nicht umgangen.

Bei zu wenig freiem Speicher pausiert der Worker mit `STORAGE_LOW`, ohne Akten zu
löschen oder Untersuchungsbudgets zu verbrauchen. Die konfigurierbare
`min_free_bytes`-Reserve ersetzt keine Speicherüberwachung oder Retention. Die
20-GB-Vorgabe für Entwicklungs-/Testdaten bleibt davon unabhängig. Der Worker
löscht keine Paketgenerationen und keine Inhalte erhaltener Akten.

Die [Web-Betriebssteuerung](web-console.md#betriebssteuerung) kann neue Fälle je
Projekt pausieren, während begonnene Analysen abschließen. Freigabeaufträge werden
dauerhaft gespeichert und zwischen Dispatches unter derselben Fall-Lease geprüft.
Damit ist für Web-Freigaben kein Worker-Stopp nötig. CLI-Freigaben benötigen
weiterhin den gestoppten Dienst. Alle fachlichen Retry- und Budgetregeln gelten
für beide Wege; ein veralteter Webauftrag entsperrt keinen neueren Paketstand.

Ctrl+C bzw. SIGTERM fordert einen geordneten Stopp an. Der laufende Dispatch darf
noch abschließen; erst danach wird die Prozess-Lease freigegeben. Ein Dispatch
kann mehrere interne Schritte/Modellanfragen enthalten und entsprechend dauern.
Bei hartem Beenden greift beim nächsten Start der Checkpoint-Wiederanlauf.

## Freigabe nach einer technischen Korrektur

Bei `ENTITY_RESOLUTION_INVALID_RESPONSES` bietet die aktuelle Fallansicht die
Aktion **Einen Reparaturversuch freigeben**. Vorher die technische Ursache beheben
und im Pflichtfeld kurz dokumentieren (keine Secrets). Die Freigabe wird über den
authentifizierten Betreiberzugang mit CSRF-Schutz vorgemerkt. Maschinenclients
dürfen sie nicht auslösen. Der Worker prüft Zustand, Projektbindung und aktuelle
Paketgeneration erneut. Doppelte oder veraltete Aufträge gewähren keinen weiteren Versuch.

Jede Freigabe erlaubt genau einen zusätzlichen Antwortversuch in der betroffenen
Namensauflösungsstufe (Suchplan oder Bewertung), ohne die bisherigen Versuche zu
löschen. Eine gültige Reparatur kann anschließend den regulären Ablauf fortsetzen.
Scheitert sie, bleibt der Fall erneut gesperrt. Weitere Versuche benötigen eine neue
ausdrückliche Freigabe. Akteur, Begründung, betroffener Antwort-Hash und Code-Hash
werden dauerhaft als Checkpoint in der Fallakte gespeichert. Revision, gültiger
Suchplan, Recherchebelege und Untersuchungsbudgets werden nicht zurückgesetzt.
Die Freigabe selbst führt keine Modellanfrage aus; die anschließende Bearbeitung
kann reguläre LLM-Kosten verursachen.

Alternativ bei gestopptem Worker als root unter Linux:

```sh
/opt/viano-bug-analysis/.venv/bin/python -m viano_bug_analysis.worker repair --config /etc/viano-bug-analysis/worker.toml --case-id BUG-000021 --package-id api-PAKETIDENTITAET --reason "Technische Korrektur installiert; Namensbewertung gezielt reparieren"
```

Danach den Worker wieder starten. Der CLI-Befehl benötigt keinen Cloud-Schlüssel,
weil er nur eine Freigabe protokolliert. Die vorhandene Projektkonfiguration muss
unverändert gebunden sein. Diese Freigabe ist derzeit bewusst auf ausgeschöpfte
Namensauflösung beschränkt. Sie umgeht weder menschliche Rückfragen noch
fachliche Budgetgrenzen und öffnet keine erfolgreich abgeschlossenen Fälle oder
`FAILED_TO_ANALYZE`-Revisionen. Für andere Fehlergründe bleiben die jeweiligen
Retry- beziehungsweise Review-Verfahren maßgeblich.

Für einen Server ist die Vorlage `deploy/viano-bug-analysis-worker.service`
vorbereitet. Sie wird nicht automatisch installiert oder gestartet. Dienstbenutzer,
Pfade, Zugangsdaten und gemeinsame Workspace-Berechtigungen müssen zum Zielserver
passen. Der Worker startet weder die lokale Testdatenbank noch einen Repository-
Synchronisationsdienst. Diese Abhängigkeiten werden separat betrieben.

## Lokale Tests

Worker-, Übergabe- und Wiederanlauftests verwenden künstliche Daten und lokale
Provideradapter; es werden keine kostenpflichtigen Modellanfragen ausgeführt:

```powershell
.\.venv\Scripts\python.exe -m pytest tests/test_worker.py tests/profiles/vcore/test_worker_intake.py tests/profiles/vcore/test_intake_api.py -q
```