Add persistent profile-routed analysis worker and shared workflow

docs/analysis-worker.md

@@ -0,0 +1,169 @@
+# 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.
+
+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.
+
+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
+```