fix(generative): Timeout-Retry im legacy-Profil + verlorene Konzepte sichtbar (#210)

[TillQuandel]

Problem (#210)

Das Subscription-Backend (claude CLI) verlor bei einem 300s-Timeout Konzepte auf zwei Wegen — beide belegt in generative/.cache/runs/:

1. Planner-Timeout killt den Lauf. runtime-config zeigte timeout_retries=0 fürs legacy-Profil → ein transienter CLI-Hänger warf RuntimeError, der Orchestrator starb mit Traceback (Exit 1) inkl. bereits gelaufener Stages 1–4.
2. Extractor-Timeout wird still verschluckt. Planner plant 2 Konzepte, Extractor-Call 1 stirbt am Timeout (Error-Record im Trace, 0 Tokens), Call 2 läuft. Ergebnis: === Fertig: 1 Notes ===, Exit 0, keine Warnung — das verlorene Konzept war nur im Trace sichtbar.

Fix-Ansatz

1. Retry-Budget auch im legacy-Profil. LEGACY.timeout_retries 0 → 1 in runtime_config.py. fast/balanced erben den Default; quality hatte schon 1. Die Retry-Schicht bleibt bewusst in der Config, NICHT im Backend — der bestehende Backend-Kontrakt (test_sub_call_full_does_not_retry_timeout_by_default: übergebenes timeout_retries=0 wird treu geehrt) bleibt intakt. Das Backend spawnt pro Versuch bereits einen frischen CLI-Prozess (subprocess.run / create_subprocess_exec in der Retry-Schleife) und gilt für sync- UND async-Pfad.

2. Kein stilles Verschlucken + Exit-Code. run_extractors_per_concept trennt jetzt harte Call-Ausfälle (Exception: Timeout/CLI-Fehler nach Retries) von legitimen Leer-Extraktionen (run_per_concept → None, Konzept zu schwach im Text) und gibt sie als failures-Liste zurück. main() druckt einen Warn-Block direkt im Run-Summary („N von M Konzepten beim Extrahieren verloren …") und beendet den Prozess mit einem eigenen Exit-Code.

Exit-Code-Semantik: 0 = voller Erfolg, 1 = harter Abbruch (unbehandelte Exception, z.B. Planner-Timeout nach Retries → kein Plan), 3 = Lauf abgeschlossen, aber ≥1 Konzept endgültig verloren. 3 hält den Teilverlust von einem harten Absturz unterscheidbar (CLI/GUI/CI können reagieren). __main__ propagiert via sys.exit(main()); cli.py reicht orchestrator.main() or 0 durch.

pipeline_runs: Kein Schema-Change. n_dropped existiert bereits und zählt Ausfälle schon mit (dropped_total = Fehler + Leer-Extraktionen) → das Dashboard sieht den Verlust in der Aggregat-Zahl.

Konfigurierbares Call-Timeout (#210 Punkt 3): bereits vorhanden via ATOMIC_AGENT_CALL_TIMEOUT (runtime_config → base.py → Backend) — nichts zu tun.

Bewusst NICHT enthalten (separate PRs): Stage-Outcome-Events (#197), pipeline_runs-Insert-Entkopplung von der Eval (#198).

RED-Beweis (TDD)

Vor dem Fix:

• test_orchestrator_timeout_visibility.py → ImportError: cannot import name 'format_extractor_failure_report' (Helfer/4-Tupel existierten nicht).
• test_legacy_profile_retries_transient_timeout_once → AssertionError: assert 0 >= 1 (RuntimeConfig(...timeout_retries=0...)).

Nach dem Fix: beide grün. Backend mockt Timeout beim 1. Call + Erfolg beim Retry / Timeout bei allen Calls (keine echten CLI-/LLM-Calls).

Suite-Ergebnis

pytest generative lib/decision_engine/tests shared/tests -q → 5702 passed, 3 skipped, 0 failed (inkl. 9 neuer Tests aus diesem PR). ruff format --check . und ruff check . grün.

Cross-Model-Review

Mistral magistral-medium-latest (voller Diff): keine echten Funde. Gezielt geprüft und als korrekt bestätigt: 4-Tupel-Entpackung (by-chapter akkumuliert failures, single-doc reassigned), Exit-Code-Pfade (0/1/3 inkl. No-Drafts → leere Failures → Exit 0), Config-Änderung. Keine Regressionen/Race-Conditions.

Closes #210

Nachbesserung (Fable-Kontrollreview, Mistral-Resample + Qwen ohne weitere Funde)

Nebeneffekt dokumentiert: timeout_retries erreicht auch das litellm-Backend. _backend_runtime_kwargs() (agents/base.py) reicht timeout_retries unterschiedslos an beide Backends durch — nicht nur ans Subscription-/CLI-Backend. Im litellm-Pfad (_litellm_backend.py:_resolve_num_retries) wird derselbe Wert 1:1 zu num_retries gemappt, das dort aber eine breitere Fehlerklasse abdeckt als beim CLI-Backend (dort ausschließlich subprocess.TimeoutExpired): litellm retryt bei Timeout UND APIError UND APIConnectionError einheitlich (Doku-String in _resolve_num_retries, Parität #148). D.h. das legacy-Profil-Retry-Budget (0→1, dieser PR) senkt nicht nur die Timeout-Toleranz des CLI-Pfads, sondern erhöht im litellm-Pfad zusätzlich die Toleranz gegenüber generischen API-/Verbindungsfehlern. Bewusster Nebeneffekt der gemeinsamen Config-Quelle, kein Bug — aber kein reines "CLI-Timeout-Feature", wie der PR-Titel nahelegen könnte.

GUI: Exit-Code 3 (Teilverlust) wurde bislang wie ein Absturz behandelt. generative/gui/static/app.js hat rc===3 im exited-Handler in den generischen Fehler-Zweig fallen lassen: markStageError() färbte die zuletzt aktive Stage (typischerweise die erfolgreich gelaufene Stage 8) rot, das Log meldete „Lauf mit Fehlercode 3 beendet.", und loadOutputs() lief nur bei rc===0 — die tatsächlich geschriebenen Notes wurden dem GUI-Nutzer also gar nicht angezeigt. Fix: rc===3 läuft jetzt im selben Zweig wie rc===0 (Stages als erledigt statt Fehler markiert, Outputs geladen, Fokus auf die Ergebnis-Sektion), zusätzlich eine eigene Warnzeile/Banner „Teilverlust: N Konzept(en) beim Extrahieren verloren (Timeout/CLI-Fehler, auch nach Retry) — Notes trotzdem geschrieben." (Wortlaut an format_extractor_failure_report() in orchestrator.py angelehnt; N wird aus der entsprechenden Log-Zeile geparst, fällt ohne Treffer auf eine zahlenfreie Formulierung zurück statt zu raten). Der Verlaufs-Badge (addHistoryEntry) zeigt für rc===3 konsistent „Teilverlust (Timeout)" statt des generischen „Fehlercode 3". Keine dedizierte JS-Testinfrastruktur im Repo vorhanden (kein package.json/jsdom/jest, geprüft) — Verhalten per node --check (Syntax) + Code-Inspektion belegt, kein neues Test-Framework eingeführt.

Testbeleg präzisiert (Punkt 1 oben, test_sub_call_full_does_not_retry_timeout_by_default). Der bestehende Test ruft sub_call_full(...) ohne timeout_retries-Argument auf und prüft damit nur den Modul-Default (_TIMEOUT_RETRIES, zufällig ebenfalls 0). Er hätte einen Bug wie timeout_retries or _TIMEOUT_RETRIES (0 ist falsy → fiele fälschlich auf den Default zurück) nicht erkannt. Neuer Test test_sub_call_full_explicit_timeout_retries_zero_does_not_retry setzt den Modul-Default explizit auf 1 (monkeypatch.setattr(sub_backend, "_TIMEOUT_RETRIES", 1)) und übergibt trotzdem explizit timeout_retries=0 — beweist, dass der explizite Wert den Default überstimmt (call_count == 1, kein Retry). Die is None-Weiche in call_full() war bereits korrekt; der Test hält das jetzt regressionssicher fest.

Suite: pytest generative lib/decision_engine/tests shared/tests -q → 5703 passed, 3 skipped, 0 failed (inkl. 1 neuer Test aus dieser Nachbesserung). ruff format --check . + ruff check . grün.

Nachbesserung Runde 2 (Opus-bestätigter Fund)

Teilverlust-Banner behauptete auch bei 0 geschriebenen Notes „Notes trotzdem geschrieben". rc=3 kann laut Orchestrator-Early-Return (if not drafts: bei nicht-leeren extractor_failures) auch auftreten, wenn ALLE Konzepte verloren gingen und gar keine Note geschrieben wurde — der bisherige Banner-Text war dann falsch. Fix: buildExtractorLossText() erhält jetzt den echten Notes-Count aus loadOutputs()//api/outputs (nicht den geparsten Verlust-Count) und wählt bei writtenCount === 0 die neutrale Formulierung „... — keine Notes geschrieben." statt „... — Notes trotzdem geschrieben."; zusätzlich das Verlaufs-Label für rc=3 von „Teilverlust (Timeout)" auf „Teilverlust (Timeout/CLI-Fehler)" verallgemeinert, da die Ursache auch ein CLI-Fehler sein kann.