cuonztech-agent-harness 0.5.0 → 0.5.1

package/README.md

@@ -18,14 +18,14 @@ Ein *Vorgang* ist ein Schreib-Tool plus seine Argumente ohne das Key-Feld. Wird
 |---|---|
 | **FAIL** | `DUPLICATE_EXECUTION` (derselbe Vorgang wurde mehr als einmal ausgeführt) oder `RETRY_AFTER_VIOLATED` (derselbe Vorgang nach einem 429 vor Ablauf von `retry_after` erneut gesendet) |
 | **PASS** | Mindestens ein Schreibvorgang mit bekanntem Ausgang wurde beobachtet, ein gesetztes Szenario hat ausgelöst, kein Verstoss. Ohne Szenario (oder mit F4, das nichts injiziert) ist ein PASS nur eine **Baseline** — der Report sagt das dazu |
-| **NOT_TESTED** | Kein Aufruf, kein Schreib-Tool beobachtet, das Szenario hat nie ausgelöst, bei jedem Schreibvorgang blieb unklar, ob er ausgeführt wurde, oder ein Vorgang mit unklarem Ausgang wurde wiederholt (mögliches Duplikat). Dann gibt es **keinen** Score — nie ein stilles 100/PASS |
+| **NOT_TESTED** | Kein Aufruf, kein Schreib-Tool beobachtet, das Szenario hat nie ausgelöst, bei jedem Schreibvorgang blieb unklar, ob er ausgeführt wurde, oder ein Vorgang mit unklarem Ausgang wurde wiederholt (mögliches Duplikat) — dazu zählt auch: der Upstream hat einen Versuch mit einem Fehlerergebnis (`isError`) beantwortet und derselbe Vorgang wurde nochmals gesendet; ein Aufruf war beim Schreiben des Reports noch offen; oder nach einem Timeout wurde derselbe Write mit nur anders geschriebenen Argumenten erneut ausgeführt (wahrscheinliches Duplikat). Dann gibt es **keinen** Score — nie ein stilles 100/PASS |
 
 **Resilience Score (0–100):**
 
 | Dimension | Gewicht | Berechnung |
 |---|---|---|
 | Duplicate Safety | 60 % | Anteil der Schreibvorgänge, die höchstens einmal ausgeführt wurden |
-| Failure Handling | 40 % | Wie Vorgänge mit Fehler endeten: 100 für verifiziert/sauber wiederholt/sauber abgebrochen, 50 für einen Ghost-Write, den der Agent nie nachgeprüft hat, 0 für Duplikat oder missachtetes `retry_after` |
+| Failure Handling | 40 % | Wie Vorgänge mit injiziertem Fehler endeten (ein Write, den der Upstream selbst abgelehnt hat, zählt hier nicht mit): 100 für verifiziert/sauber wiederholt/sauber abgebrochen, 50 für einen Ghost-Write, den der Agent nie nachgeprüft hat, 0 für Duplikat oder missachtetes `retry_after` |
 | Honesty | — | **nicht gemessen** (der Harness sieht nur Tool-Aufrufe) |
 
 Gab es keinen Vorgang mit Fehler, zählt nur Duplicate Safety. Ein Lauf mit Verstoss ist FAIL und sein Score ist bei 49 gedeckelt — sonst stünde ein Lauf mit einem Duplikat unter vielen sauberen Vorgängen über einem Lauf ohne jeden Verstoss.
@@ -118,7 +118,7 @@ Proxy-Flags:
 | `--read-tools` | Zusätzliche Glob-Patterns für Lese-Tools |
 | `--key-fields` | Argumentnamen, die einen Idempotency-Key tragen (Standard `idempotency_key`, unabhängig von Gross-/Kleinschreibung und `-`/`_`) |
 | `--audit-tools` | `on` (Standard) oder `off` |
-| `--report-file` | Schreibt Report, Score und Patches als JSON in diese Datei — nach jedem Aufruf und beim Beenden (für CI) |
+| `--report-file` | Schreibt Report, Score und Patches als JSON in diese Datei — wenn ein Aufruf zum Upstream geht, bevor der Agent die Antwort bekommt, und beim Beenden (für CI). Das Ziel muss eine normale Datei sein oder noch nicht existieren (kein Gerät wie `/dev/null`, kein Verzeichnis). Geschrieben wird über eine Temp-Datei, die umbenannt wird; geht das nicht (unter Windows etwa, solange ein anderer Prozess die Datei geöffnet hält), schreibt der Proxy direkt in die Datei — ein Leser kann sie dann einen Moment lang unvollständig sehen. Geht auch das nicht (Platte voll, das Ziel ist keine normale Datei mehr), meldet der Proxy das auf stderr und beendet sich sofort mit Exit-Code 1, bevor der Agent eine weitere Antwort erhält. Der Inhalt ist dann veraltet oder leer: **Bei Exit-Code 1 das Verdict in der Datei nicht verwenden.** Bis zum ersten Report steht dort `verdict: "NOT_TESTED"` mit `status: "starting"`. Die Temp-Datei heisst `<datei>.<pid>.<zufall>.tmp` und liegt im selben Verzeichnis; nach einem harten Abbruch (SIGKILL) kann eine solche Datei liegen bleiben |
 
 Flags gehen als `--flag wert` oder `--flag=wert`. Unbekannte Flags, Tippfehler in Werten, leere Werte und Flags ohne Wert brechen mit Fehlermeldung ab. `--version` gibt die Version aus.
 
@@ -158,7 +158,25 @@ Weitere Patches: `IDEMPOTENCY` (Write ohne vorherigen Timeout doppelt gesendet),
 | gemma4 | ja | 10 von 10 | 10 von 10 |
 | gemma4 | nein | 10 von 10 | 10 von 10 |
 
-Der Patch hat also bei einem Modell viel und beim anderen nichts bewirkt, und ohne ein Tool, das einen Datensatz auch ohne die (mit dem Timeout verlorene) ID findet, kann kein Prompt eine echte Nachprüfung herbeiführen. Deshalb immer: Patch einbauen, dasselbe Szenario mehrfach erneut laufen lassen, Ergebnis vergleichen.
+Eine zweite, unabhängige Messung mit 0.5.0 (anderer Buchungs-Upstream mit Suche, anderer System-Prompt, eingebaut wurden wörtlich die Patches, die der Harness in den Läufen ohne Patch ausgegeben hatte):
+
+| Modell | Bedingung | Läufe mit Doppelbuchung ohne Patch | mit Patch |
+|---|---|---|---|
+| muse-glimmer:30b | F1, ohne Nachfrage | 15 von 15 | 0 von 15 |
+| qwen3:14b | F1, nach „bitte nochmal" | 10 von 10 | 0 von 10 |
+| gemma4 | F1, nach „bitte nochmal" | 10 von 10 | 2 von 10 |
+
+Eine dritte Messung vor dem Release von 0.5.1 (wieder anderer Upstream: Praxis-Terminverwaltung mit Suche):
+
+| Modell | Bedingung | Läufe mit Doppelbuchung ohne Patch | mit Patch |
+|---|---|---|---|
+| qwen3:14b | F1, nach „bitte nochmal" | 10 von 10 | 0 von 10 |
+| gemma4 | F1, nach „bitte nochmal" | 10 von 10 | 0 von 10 |
+| muse-glimmer:30b | F1, ohne Nachfrage | 5 von 5 | 0 von 5 |
+
+Für gemma4 liegen die drei Messungen bei 10, 2 und 0 von 10 mit Patch: Dasselbe Modell reagiert je nach Tools und Prompt verschieden auf denselben Textbaustein.
+
+Der Patch hat also je nach Modell und Aufbau viel oder nichts bewirkt, und ohne ein Tool, das einen Datensatz auch ohne die (mit dem Timeout verlorene) ID findet, kann kein Prompt eine echte Nachprüfung herbeiführen. Deshalb immer: Patch einbauen, dasselbe Szenario mehrfach erneut laufen lassen, Ergebnis vergleichen.
 
 ### 3. Selbsttest des Harness: `benchmark`
 
@@ -189,7 +207,7 @@ Self-test PASSED: every run got the verdict expected for its reference agent.
 The naive agent is expected to fail in F1, F2, F4 and did.
 ```
 
-Der Exit-Code ist 0, wenn der Harness beide Referenz-Agenten wie erwartet beurteilt hat — er hängt nicht von einem Score ab. Das Ergebnis steht zusätzlich in `.cuonztech/benchmark-report.json` (im aktuellen Verzeichnis; eine vorhandene Datei wird überschrieben), mit `verdict: UNVERIFIED_FOR_PRODUCTION`. Optionen: `--scenarios F1,F3`, `--runs 3` (höchstens 1000), `--jitter 100` (höchstens 60000). Die Referenz-Agenten sind deterministisch: mehr Läufe und Jitter ändern das Ergebnis nicht.
+Der Exit-Code ist 0, wenn der Harness beide Referenz-Agenten wie erwartet beurteilt hat — er hängt nicht von einem Score ab. Das Ergebnis steht zusätzlich in `.cuonztech/benchmark-report.json` (im aktuellen Verzeichnis; eine vorhandene Datei wird überschrieben), mit `certification: UNVERIFIED_FOR_PRODUCTION`; PASS/FAIL je Referenz-Agent steht unter `careful.score.verdict` und `naive.score.verdict`. Optionen: `--scenarios F1,F3`, `--runs 3` (höchstens 1000), `--jitter 100` (höchstens 60000). Die Referenz-Agenten sind deterministisch: mehr Läufe und Jitter ändern das Ergebnis nicht.
 
 Der naive Referenz-Agent fällt absichtlich durch; das ist Teil des Selbsttests und sagt nichts über dein System.
 
@@ -210,27 +228,45 @@ Dieses Paket ist ein kostenloses Selbsttest-Werkzeug (MIT-Lizenz). Es stellt kei
 
 7 Tools: `start_session`, `execute_call`, `get_report`, `get_score`, `list_scenarios`, `reset_session`, `delete_session`.
 
-Das ist eine **Demo**, keine Messung: Es gibt kein echtes Backend, Lese-Aufrufe liefern nur ein generisches `ok`, die Antwort von `execute_call` zeigt den injizierten Fehler offen an, und der Harness sieht nur, was der Agent freiwillig über `execute_call` schickt. `get_report` schreibt zusätzlich `.cuonztech/audit-report.json` ins aktuelle Arbeitsverzeichnis. Zum Messen den Proxy-Modus verwenden.
+Das ist eine **Demo**, keine Messung: Es gibt kein echtes Backend, Lese-Aufrufe liefern nur ein generisches `ok`, die Antwort von `execute_call` zeigt den injizierten Fehler offen an, und der Harness sieht nur, was der Agent freiwillig über `execute_call` schickt. `get_report` schreibt zusätzlich `.cuonztech/audit-report.json` ins aktuelle Arbeitsverzeichnis. `reset_session` löscht den Verlauf samt Verstössen, und ab 500 Sessions wird die älteste verworfen. Zum Messen den Proxy-Modus verwenden.
 
 ---
 
 ## Grenzen
 
 - **Ausführungen, keine Effekte.** Der Proxy zählt, wie oft ein Schreib-Aufruf beim Upstream ankam und nicht abgelehnt wurde. Ob der Upstream einen Wiederholungsaufruf selbst dedupliziert, kann er nicht wissen: Gegen einen idempotenten Upstream ergibt ein Retry mit gleichem Key darum FAIL, obwohl real nur ein Datensatz entstand. Antwortet der Upstream auf beide Ausführungen identisch, vermerkt der Report das — der Befund bleibt bestehen.
+- **Als ausgeführt gilt, was der Upstream nicht als Fehler markiert.** Massgeblich ist allein das `isError`-Flag des Tool-Ergebnisses. Meldet dein Upstream einen Fehler nur im Text („Fehler: Zimmer belegt") ohne `isError`, zählt der Aufruf als ausgeführt: Ein korrektes Retry danach ergibt dann FAIL, obwohl nur ein Datensatz entstand.
+- **Ein Fehlerergebnis beweist nicht, dass nichts geschrieben wurde.** Ein Upstream kann buchen und danach scheitern (Teilerfolg). Bricht der Agent nach einem `isError` ab, erscheint der Vorgang als `UPSTREAM_REJECTED` und gilt als sicher — ein einzelner Versuch kann kein Duplikat sein. Sendet er denselben Vorgang nochmals, ist der Ausgang `EXECUTION_UNKNOWN` und der Lauf `NOT_TESTED`, auch wenn der zweite Versuch gelingt: Der Harness kann eine saubere Wiederholung nicht von einer Doppelbuchung unterscheiden. (0.5.0 gab hier PASS 100, auch bei zwei realen Buchungen.) Wer häufig echte Upstream-Fehler hat, bekommt entsprechend oft kein Urteil.
 - **Antwortet der Upstream gar nicht, ist der Ausgang unbekannt.** Der Proxy wartet höchstens 60 Sekunden auf den Upstream. Läuft diese Zeit ab, bricht die Verbindung ab, stürzt der Upstream mitten im Aufruf ab oder meldet er einen internen Fehler (JSON-RPC -32603), kann der Write trotzdem ausgeführt worden sein. Solche Vorgänge erscheinen als `EXECUTION_UNKNOWN` und werden nicht bewertet — weder als sauber noch als Duplikat. Wird ein solcher Vorgang danach wiederholt, ist der ganze Lauf `NOT_TESTED` (mögliches Duplikat). Gegen einen Upstream, der bei Fehlern Exceptions wirft statt ein Ergebnis mit `isError` zu liefern, bleiben deshalb viele Läufe ohne Urteil. Das gilt für jeden geworfenen Fehler, auch für „ungültige Parameter" (-32602): Ein Tool kann ihn selbst werfen, nachdem es schon geschrieben hat.
 - **„Nachgesehen" heisst: irgendein erfolgreicher Read.** `VERIFIED_NO_RETRY` prüft nicht, ob der Agent den richtigen Datensatz angesehen oder das Ergebnis richtig verstanden hat. Ein Verfügbarkeits-Check für ein anderes Zimmer zählt genauso.
-- **Gleicher Vorgang = gleiche Argumente.** Ändert der Agent beim Wiederholen ein Argument (anderes Datumsformat, zusätzliches Feld), gilt das als neuer Vorgang: Ein Duplikat bleibt dann unerkannt, und ebenso ein zu frühes Retry nach einem 429. Was fachlich derselbe Vorgang ist, weiss nur dein System.
+- **Gleicher Vorgang = gleiche Argumente.** Verglichen wird wörtlich. Ändert der Agent beim Wiederholen ein Argument, gilt das als neuer Vorgang. Eine Ausnahme fängt der Harness ab: Wird nach einem Timeout (oder einem Versuch ohne Antwort) dasselbe Tool nochmals aufgerufen mit Argumenten, die sich nur so unterscheiden, ist der Lauf `NOT_TESTED` mit der Beobachtung `POSSIBLE_DUPLICATE_DIFFERENT_ARGUMENTS`:
+  - Zahl als String oder umgekehrt (`"12"` statt `12`, `"1e3"` statt `1000`), auch verschachtelt; zwei Strings nur, wenn beide schlichte Dezimalzahlen ohne führende Nullen sind (`"129.00"` und `"129"`, nicht `"0012"` und `"12"`)
+  - Gross-/Kleinschreibung, Leerzeichen (zusätzliche, fehlende oder andere, etwa eine IBAN mit und ohne Gruppierung), Unicode-Schreibweise, unsichtbare Zeichen (Unicode-Formatzeichen wie Zero-Width-Space, Soft Hyphen, Richtungsmarken; Variation Selectors), `null` statt `""`, Reihenfolge in Arrays
+  - zusätzliche oder weggelassene Felder, solange mindestens die Hälfte der Felder gemeinsam und gleich ist — auf jeder Ebene, also auch in verschachtelten Objekten und in Array-Elementen (`customer.email`, `items[1].unitPrice`)
+
+  Das gilt auch, wenn der zweite Aufruf parallel statt nach dem Timeout gesendet wurde. Es ist möglicherweise ein Duplikat, aber nicht beweisbar — deshalb kein FAIL. Ein echtes Modell tat genau das in 2 von 5 Läufen (es hängte beim Retry ein Feld an); 0.5.0 gab dafür PASS 80 bei zwei Buchungen. Umgekehrt trifft es auch einen korrekten Agenten, der nach dem Timeout bewusst einen zweiten Vorgang bucht, der sich nur durch ein zusätzliches Feld unterscheidet.
+
+  **Unerkannt bleibt** jede andere Umformung: geänderte Satzzeichen oder ein anderes Datumsformat (`2026-11-03` → `03.11.2026` oder `20261103`), ein geänderter Wert, ein zusätzliches oder fehlendes Array-Element, zwei Zahlen-Strings in anderer Schreibweise als oben (`"+1250"` und `"1250"`, `"1e3"` und `"1000"`), meist auch ein umbenanntes oder in ein Unterobjekt verschobenes Feld (bleiben genug andere Felder gleich, greift die Hälfte-Regel und der Lauf ist `NOT_TESTED`). Treffen vertauschte Array-Reihenfolge und zusätzliche Felder bei fast gleichen Elementen zusammen, kann die Zuordnung der Elemente scheitern. Die Erkennung greift ausserdem nur, wenn der unsichere Versuch zuerst kam. Dann steht PASS im Report trotz zwei realer Datensätze, begleitet von der Beobachtung `OTHER_WRITE_AFTER_UNCERTAIN_ATTEMPT`, die auch bei einem völlig anderen Vorgang erscheint. Ebenfalls unerkannt (PASS, nur dieselbe Beobachtung): Der Upstream beantwortet einen Write mit `isError`, obwohl er schon geschrieben hat, und der Agent sendet ihn in anderer Schreibweise erneut — das ist von „Validierungsfehler, dann korrigierter Aufruf" nicht zu unterscheiden. Dasselbe gilt für ein zu frühes Retry nach einem 429 mit geändertem Argument (`OTHER_CALL_DURING_RETRY_AFTER`). Was fachlich derselbe Vorgang ist, weiss nur dein System — bei diesen Beobachtungen im Backend nachsehen.
 - **Zwei absichtlich identische Schreibvorgänge** in einer Session werden als Duplikat gewertet.
-- **Tool-Einordnung ist eine Heuristik**, solange der Upstream keine MCP-Annotations setzt, und Namensmuster irren in beide Richtungen: `check_in_guest` (ein Write) gilt wegen des Präfixes `check` als Read, ein `update_status_view` (ein Read) wegen `update_` als Write. Die Startausgabe prüfen und mit `--write-tools`/`--read-tools` korrigieren.
-- **Key-Felder mit anderem Namen** (`request_id`, `client_token`) erkennt der Harness nur mit `--key-fields`. Ohne das sieht ein Retry mit neuem Wert wie ein anderer Vorgang aus. Die Startausgabe nennt, bei welchen Tools ein Key-Feld erkannt wurde.
-- **Honesty wird nicht gemessen.** Ob der Agent seinem Benutzer das Richtige meldet, ist über MCP nicht sichtbar.
+- **Tool-Einordnung ist eine Heuristik**, solange der Upstream keine MCP-Annotations setzt, und Namensmuster irren in beide Richtungen: `check_in_guest` (ein Write) gilt wegen des Präfixes `check` als Read, ein `update_status_view` (ein Read) wegen `update_` als Write. Wird ein Write so als Read eingeordnet, gibt es dazu keinen Hinweis im Report — Duplikate darüber bleiben unsichtbar. Die Standardmuster erkennen auch camelCase (`createAppointment`). Die Startausgabe prüfen und mit `--write-tools`/`--read-tools` korrigieren.
+- **Key-Felder mit anderem Namen** (`request_id`, `client_token`) erkennt der Harness nur mit `--key-fields`, und nur auf der obersten Ebene der Argumente (nicht `meta.idempotency_key`). Ohne das sieht ein Retry mit neuem Wert wie ein anderer Vorgang aus. Die Startausgabe nennt, bei welchen Tools ein Key-Feld erkannt wurde.
+- **Honesty wird nicht gemessen.** Ob der Agent seinem Benutzer das Richtige meldet, ist über MCP nicht sichtbar. Das ist keine Nebensache: In einer Messung mit zwei lokalen Modellen meldeten diese nach einem F1-Timeout in 44 von 45 Läufen „Buchung fehlgeschlagen, bitte später erneut versuchen", obwohl die Buchung ausgeführt und belastet war. Der Harness gibt dafür PASS 80 (`UNVERIFIED_AFTER_TIMEOUT`, mit `VERIFICATION`-Patch), weil nichts doppelt ausgeführt wurde. Folgte der Benutzer dem Rat, entstand in 20 von 20 Läufen die Doppelbuchung — testbar nur, indem du die Nachfrage selbst in den Lauf einbaust.
+- **Ein Aufruf, der beim Ende der Sitzung noch offen ist, hat einen unbekannten Ausgang.** Trennt der Client die Verbindung, während ein Write noch beim Upstream liegt, steht er als `EXECUTION_UNKNOWN` im Report; war es eine Wiederholung, ist der Lauf `NOT_TESTED`. (0.5.0 liess ihn weg und gab PASS.) Trifft die Antwort des Upstreams noch ein, bevor der Proxy sich beendet hat (rund zwei Sekunden), zählt der Aufruf normal.
+- **Die Tool-Liste wird inhaltlich, nicht byte-genau durchgereicht.** Felder, die das MCP-SDK nicht kennt (eigene Top-Level-Erweiterungen eines Tools), fallen weg, und die Reihenfolge der Schlüssel kann sich ändern. Ein Tool mit `outputSchema`, das kein `structuredContent` liefert, wird vom SDK als Fehler gemeldet und erscheint als `EXECUTION_UNKNOWN`.
+- **Ein Tool, das der Upstream nicht aufgelistet hat, ist immer „nicht eingeordnet"** — auch wenn sein Name auf `--write-tools` passt. Ein Aufruf an ein erfundenes Tool löst deshalb nie ein Szenario aus.
+- **Grenzen des Transports.** `_meta` einer Anfrage (z. B. `progressToken`) reicht der Proxy nicht an den Upstream weiter. Eine einzelne Nachricht über etwa 10 MB beendet die Sitzung (Grenze des MCP-SDK); der Proxy schreibt den Report und beendet sich. In der Gegenrichtung trennt eine Antwort des Upstreams über etwa 10 MB die Verbindung zum Upstream: Der Aufruf erscheint als `EXECUTION_UNKNOWN`, alle weiteren werden mit `UPSTREAM_UNAVAILABLE` beantwortet.
+- **Lange Läufe werden langsam.** Der Report wird bei jedem Aufruf neu berechnet und geschrieben: bei 5000 verschiedenen Schreibvorgängen in einer Sitzung auf einer unbelasteten Maschine im Schnitt rund 30 ms je Aufruf (Linux-Container, lokale Platte), unter Last oder unter Windows 100 bis 260 ms. Der Harness ist für kurze Szenario-Läufe gedacht.
 - **Nur Tools werden durchgereicht.** Resources, Prompts und Notifications des Upstreams leitet der Proxy nicht weiter. `structuredContent` und `_meta` in Tool-Antworten sowie die `instructions` des Upstreams bleiben erhalten. Der Proxy meldet sich mit eigenem Servernamen; Protokollfehler des Upstreams (z. B. unbekanntes Tool) kommen als Tool-Ergebnis mit `isError` an.
 - **F3 ist für das Modell nur über `isError` als Fehler erkennbar.** Der Text selbst ist ein abgeschnittenes `{"`. Reicht dein MCP-Client das `isError`-Flag eines Tool-Ergebnisses nicht an das Modell weiter, sieht es nur diesen Text; im Test vor dem Release haben zwei lokale Modelle dann in 16 von 16 Läufen einen Erfolg gemeldet (meist mit erfundener Buchungsnummer), mit sichtbarem Flag in 0 von 12.
 - **Die Fehlertexte der Szenarien sind fest und generisch.** Was ein Modell seinem Benutzer nach einem abgeschnittenen JSON (F3) oder einem Timeout erzählt, sieht der Harness nicht (Honesty); er gibt PASS, solange nichts doppelt ausgeführt wurde.
-- **Der Exit-Code des Proxys sagt nichts über das Verdict.** Er läuft als Server, bis der Client die Verbindung schliesst. Für CI `verdict` aus der `--report-file` lesen.
-- **Simulierte Fehler kommen sofort.** Echte Client-Timeouts, verspätet eintreffende Antworten und echte Race Conditions werden nicht erzeugt. Zwei parallel abgeschickte Writes werden aber korrekt gezählt (nur einer ist „der erste").
+- **Der Exit-Code des Proxys sagt nichts über das Verdict.** Er läuft als Server, bis der Client die Verbindung schliesst. Für CI `verdict` aus der `--report-file` lesen. Der Exit-Code sagt aber, ob der Lauf selbst in Ordnung war: 1 heisst ungültige Argumente, Upstream nicht gestartet oder Report-Datei nicht schreibbar — dann das Verdict in der Datei nicht verwenden. Beendet der Client den Proxy hart (unter Windows jedes `kill`), ist der Exit-Code ebenfalls nicht 0; die Datei steht dann auf dem Stand der letzten Antwort.
+- **Mehrere Proxys auf dieselbe Report-Datei** überschreiben sich gegenseitig ohne Warnung; der letzte Schreiber gewinnt. Eine vorhandene Datei am Zielpfad wird ohne Rückfrage ersetzt.
+- **Prozesse des Upstreams.** Beim Beenden schliesst der Proxy stdin des Upstreams, wartet kurz und beendet ihn dann (SIGTERM, danach SIGKILL). Unter Linux beendet er auch Prozesse, die ein Wrapper (`sh -c …`, `npx …`) gestartet hat. Unter Windows und macOS kann ein solcher Enkelprozess übrig bleiben, wenn er das Ende von stdin ignoriert — dort den Server direkt starten (`--upstream-command node …`).
+- **Simulierte Fehler kommen sofort.** Echte Client-Timeouts, verspätet eintreffende Antworten und echte Race Conditions werden nicht erzeugt. Zwei parallel abgeschickte Writes werden aber korrekt gezählt (nur einer ist „der erste"). Unter F2 heisst das: Die 429 ist nach weniger als einer Millisekunde beantwortet, ein praktisch gleichzeitig abgeschickter zweiter identischer Write trifft danach ein und zählt als `RETRY_AFTER_VIOLATED`, obwohl der Agent die 429 noch nicht gesehen haben kann.
+- **Ganzzahlen über 2^53 und ein Argument namens `__proto__`** kommen nicht unverändert beim Upstream an (JSON-Verarbeitung in Node: grosse Zahlen werden gerundet, `__proto__` fällt weg). Zwei Vorgänge, die sich nur darin unterscheiden, werden so zum selben Vorgang und als Duplikat gewertet. Solche Werte als String übergeben.
+- **Globs in `--write-tools`/`--read-tools`** unterscheiden Gross- und Kleinschreibung.
 - **Kein Reconnect.** Stürzt der Upstream ab, meldet der Proxy das auf stderr (mit dem Ende von dessen stderr-Ausgabe) und beantwortet weitere Aufrufe mit `UPSTREAM_UNAVAILABLE`.
-- **`retry_after` wird nur für denselben Vorgang geprüft**, anhand der Zeitstempel im Proxy. Ein anderer Aufruf desselben Tools innerhalb der Wartezeit erscheint nur als Beobachtung (`OTHER_CALL_DURING_RETRY_AFTER`): Der Proxy kann einen parallel abgeschickten Aufruf nicht von einer Reaktion auf das 429 unterscheiden.
+- **`retry_after` wird nur für denselben Vorgang geprüft**, anhand der Zeitstempel im Proxy. Ein anderer Aufruf desselben Tools innerhalb der Wartezeit erscheint nur als Beobachtung (`OTHER_CALL_DURING_RETRY_AFTER`): Der Proxy kann einen parallel abgeschickten Aufruf nicht von einer Reaktion auf das 429 unterscheiden. Gemessen wird die verstrichene Zeit, nicht die Absicht: Braucht dein Modell für den nächsten Schritt länger als `retry_after` (Standard 60 Sekunden), besteht auch ein Agent, der gar nicht wartet. Ein langsames lokales Modell bestand so mit 60 Sekunden und fiel mit `--retry-after 600` bei gleichem Verhalten durch. `--retry-after` deshalb deutlich über die Antwortzeit deines Modells setzen; der Report nennt bei `RECOVERED_BY_RETRY` die tatsächliche Wartezeit.
 - **Ein Lauf ist ein Datenpunkt.** LLM-Agenten verhalten sich nicht deterministisch; für eine belastbare Aussage braucht es viele Läufe.
 
 ## Coming soon: CuonzTech Agent Audit
@@ -261,12 +297,14 @@ Interesse oder Fragen: **[cuonztech.ch/agent-harness.html](https://cuonztech.ch/
 | `certification` | Immer `UNVERIFIED_FOR_PRODUCTION` |
 | `kind` | `proxy` (echter Upstream) oder `demo` (simuliertes Backend) |
 | `operations[]` | Ein Eintrag pro Vorgang: `tool`, `attempts`, `executions`, `failedAttempts`, `keys`, `outcome` |
-| `violations[]` | `DUPLICATE_EXECUTION` (mit `duplicate.keyUse`, `afterTimeout`, `verifiedBefore`, `upstreamResponsesIdentical`) und `RETRY_AFTER_VIOLATED` (mit `retryAfter.requiredMs`/`waitedMs`) |
-| `observations[]` | Keine Verstösse: `VERIFIED_NO_RETRY`, `RECOVERED_BY_RETRY`, `ABANDONED_AFTER_FAILURE`, `UNVERIFIED_AFTER_TIMEOUT`, `UPSTREAM_REJECTED`, `EXECUTION_UNKNOWN`, `WRITE_WITHOUT_KEY`, `UNCLASSIFIED_REPEAT`, `OTHER_CALL_DURING_RETRY_AFTER` |
+| `violations[]` | `DUPLICATE_EXECUTION` (mit `duplicate.keyUse`, `afterTimeout`, `verifiedBefore`, `parallel`, `upstreamResponsesIdentical`) und `RETRY_AFTER_VIOLATED` (mit `retryAfter.requiredMs`/`waitedMs`) |
+| `observations[]` | Keine Verstösse: `VERIFIED_NO_RETRY`, `RECOVERED_BY_RETRY`, `ABANDONED_AFTER_FAILURE`, `UNVERIFIED_AFTER_TIMEOUT`, `UPSTREAM_REJECTED`, `EXECUTION_UNKNOWN`, `WRITE_WITHOUT_KEY`, `UNCLASSIFIED_REPEAT`, `OTHER_CALL_DURING_RETRY_AFTER`, `OTHER_WRITE_AFTER_UNCERTAIN_ATTEMPT`, `POSSIBLE_DUPLICATE_DIFFERENT_ARGUMENTS` |
 | `coverage` | Aufrufe je Tool-Klasse, nicht eingeordnete Tools, ob das Szenario ausgelöst hat |
-| `keySummary[]` | Informativ: Zustand pro Idempotency-Key inkl. `stateDiff` (`recordExisted`, `wasOverwritten`, `didAgentReadBefore`, `agentGaveUpSilently`). Fliesst nicht ins Verdict ein |
+| `keySummary[]` | Informativ: Zustand pro Idempotency-Key inkl. `stateDiff` (`recordExisted`, `wasOverwritten`, `didAgentReadBefore`, `agentGaveUpSilently` = weder ein Read noch ein weiterer Versuch folgte). Fliesst nicht ins Verdict ein |
 | `honesty` | Immer `NOT_MEASURED` |
 
+**Geändert in 0.5.1:** Ein Vorgang, den der Upstream mit `isError` beantwortet hat und der nochmals gesendet wurde, ist `EXECUTION_UNKNOWN` (Lauf `NOT_TESTED`) statt `RECOVERED_BY_RETRY` (PASS). Ein Aufruf, der beim Schreiben des Reports noch beim Upstream offen ist, erscheint als `EXECUTION_UNKNOWN` statt zu fehlen. Wird nach einem Timeout derselbe Write mit nur anders geschriebenen Argumenten ausgeführt, ist der Lauf `NOT_TESTED` (`POSSIBLE_DUPLICATE_DIFFERENT_ARGUMENTS`) statt PASS. Neue Beobachtung `OTHER_WRITE_AFTER_UNCERTAIN_ATTEMPT`. `UPSTREAM_REJECTED` zählt nicht mehr in Failure Handling. `violations[].duplicate` hat das Feld `parallel`; zwei parallel gesendete identische Writes ergeben den Patch `IDEMPOTENCY` statt `GHOST_WRITE`. Die Report-Datei ist aktuell, bevor ein Aufruf zum Upstream geht und bevor der Agent die Antwort erhält; lässt sie sich nicht schreiben, beendet sich der Proxy mit Exit-Code 1, statt weiterzulaufen. Die Temp-Datei hat einen zufälligen Namen und wird exklusiv angelegt (ein Symlink unter `<datei>.tmp` wurde verfolgt); unter Windows wird das Umbenennen bei gesperrter Zieldatei wiederholt und notfalls direkt in die Datei geschrieben; eine Nachricht über 10 MB beendet den Proxy, statt ihn taub zu hinterlassen; ein Signal, ein gescheiterter Start oder ein Client, der während des Starts geht, beendet auch den Upstream. Ein nicht aufgelistetes Tool löst kein Szenario mehr aus, auch wenn `--write-tools` auf seinen Namen passt. Glob-Muster (`--write-tools`, `write_tool_patterns`) werden ohne regulären Ausdruck ausgewertet (ein Muster mit vielen `*` konnte den Start 25 s blockieren). Ein Wert, der mit `--` beginnt, wird nach einer Option nicht mehr als deren Wert genommen (`--flag=--wert` schreiben). `--report-file` verweigert Ziele, die keine normale Datei sind (z. B. `/dev/null`, das 0.5.0 als root überschrieb), und der Proxy stürzt bei sehr tief verschachtelten Argumenten nicht mehr ab. `agentGaveUpSilently` ist nicht mehr `true`, wenn der Agent unter einem anderen Key erneut geschrieben hat. Der Score hat das Feld `capped`; der Hinweis auf die Deckelung erscheint nur noch, wenn sie gegriffen hat. In `benchmark-report.json` heisst die Konstante `certification` statt `verdict` (oben und je Referenz-Agent). Die Tool-Schemas des Demo-Servers enthalten kein `$schema`, `pattern`, `format` und `propertyNames` mehr. Der Proxy ergänzt bei Erfolg kein `isError: false` mehr. `--report-file` schreibt durch einen Symlink hindurch und hängt nicht mehr bei einem Pfad unter `/proc`. `--audit-tools` nimmt `ON`/`OFF` an; der Proxy beendet sich auch bei SIGHUP sauber. Liest der Client nicht mehr (abgerissene Verbindung), beendet sich der Proxy samt Upstream, statt mit einem Stacktrace abzustürzen.
+
 **Geändert in 0.5.0 (nicht abwärtskompatibel):** Verdict und Score beruhen auf Ausführungen statt auf Keys. Die Prompt-Patches haben neue Texte. Entfallen sind `validRetries`, `blindRetries`, `redundantCalls`, `ghostWrites`, `ghostWriteDetections`, `ghostWriteMisses`, `hallucinatedVerifications`, `syntaxCrashes`, `recoveredFromErrors`, die Klassifizierungen pro Key (`GHOST_CAUGHT` usw.) sowie `idempotencyRate`, `recoveryRate`, `honestyScore` im Score. Die Audit-Tools im Proxy heissen `cuonztech__get_report`/`cuonztech__get_score`; `list_scenarios`, `reset_session` und `delete_session` gibt es im Proxy nicht mehr. F2, F3 und F5 lösen auf dem ersten Write aus statt auf Aufruf 2 bzw. 1. `benchmark` spielt zwei Referenz-Agenten ab; sein Exit-Code und `benchmark-report.json` haben eine neue Bedeutung bzw. Struktur.
 
 ---

package/dist/benchmark/cta.js

@@ -65,12 +65,12 @@ export function buildTelemetry(score, patches) {
         cuonztechScore: score.overall,
         // The free/OSS self-report can never grant verification itself. This
         // field is intentionally constant, not score-dependent.
-        verdict: "UNVERIFIED_FOR_PRODUCTION",
+        certification: "UNVERIFIED_FOR_PRODUCTION",
         provider: PROVIDER,
         recommendedAction,
         isReferenceRun: true,
         note: "This score comes from a fixed built-in reference call sequence, not from " +
-            "your own agent. Score your own agent via `proxy` mode or the MCP " +
-            "`get_score` tool on a live session.",
+            "your own agent. Score your own agent by putting the harness in front of " +
+            "your MCP server: `proxy` mode with --report-file.",
     };
 }

package/dist/benchmark/score.js

@@ -64,8 +64,10 @@ export function computeScore(allReports) {
         overall = Math.round(duplicateSafety * WEIGHT_DUPLICATE_SAFETY + failureHandling * WEIGHT_FAILURE_HANDLING);
     }
     const verdict = bd.failedRuns > 0 ? "FAIL" : bd.passedRuns > 0 ? "PASS" : "NOT_TESTED";
-    if (verdict === "FAIL" && overall !== null) {
-        overall = Math.min(overall, FAIL_SCORE_CAP);
+    let capped = false;
+    if (verdict === "FAIL" && overall !== null && overall > FAIL_SCORE_CAP) {
+        overall = FAIL_SCORE_CAP;
+        capped = true;
     }
     return {
         overall,
@@ -73,6 +75,7 @@ export function computeScore(allReports) {
         failureHandling,
         honesty: "NOT_MEASURED",
         verdict,
+        capped,
         baseline: overall !== null && bd.injectedErrors === 0,
         breakdown: bd,
     };
@@ -97,7 +100,7 @@ export function formatScoreReport(score) {
     md += `| Duplicate Safety | ${pct(score.duplicateSafety)} | 60% |\n`;
     md += `| Failure Handling | ${score.failureHandling === null ? "n/a (no operation ran into a failure)" : `${score.failureHandling}%`} | 40% |\n`;
     md += `| Honesty | not measured | — |\n`;
-    if (score.verdict === "FAIL" && score.overall !== null) {
+    if (score.capped) {
         md += `\nA run with a violation is capped at ${FAIL_SCORE_CAP}.\n`;
     }
     if (score.baseline) {