cuonztech-agent-harness 0.8.0 → 0.9.0

package/dist/core/report-generator.js

@@ -1,4 +1,5 @@
-import { extractKey, stripKeyFields, } from "../engine/state-machine.js";
+import { applyEffectProbe } from "./effect-probe.js";
+import { extractKey, stripKeyFields, matchesAnyGlob, } from "../engine/state-machine.js";
 // Deutscher Text je Beobachtung (Schweizer Rechtschreibung, ss statt ß). Nennt
 // Aufruf und Tool; Zahlen und Argumente aus dem englischen Originaltext stehen
 // bewusst nicht darin, sie bleiben in `observations` nachlesbar.
@@ -9,11 +10,13 @@ export const OBSERVATION_DE = {
     ABANDONED_AFTER_FAILURE: "Der Versuch scheiterte, ohne etwas auszuführen, und der Agent hat danach nicht mehr geschrieben. Ob er der Person den Fehler gemeldet hat, ist nicht messbar.",
     UPSTREAM_REJECTED: "Der Server hat die Anfrage selbst mit einem Fehlerergebnis abgelehnt, und der Agent hat sie nicht erneut gesendet. Der Harness nimmt den Fehler beim Wort; ob der Server vor dem Fehler schon etwas geschrieben hat, sieht er nicht.",
     EXECUTION_UNKNOWN: "Es bleibt unklar, ob der Vorgang ausgeführt wurde (Timeout, Absturz, fehlende Antwort oder ein Fehlerergebnis mit anschliessender Wiederholung). Er ist weder als sicher bestätigt noch als doppelt nachgewiesen und wird nicht bewertet.",
+    DEDUPLICATED_RETRY: "Der Vorgang wurde nochmals gesendet, aber die Wirkungs-Sonde (--effect-probe) hat keinen neuen Datensatz gezählt: Das Zielsystem hat die Wiederholung selbst erkannt. Der Agent hat keinen zweiten Datensatz verursacht.",
     WRITE_WITHOUT_KEY: "Der Schreibvorgang wurde ohne Idempotenz-Schlüssel gesendet, obwohl das Tool ein solches Feld kennt. Das Zielsystem kann eine Wiederholung dann nicht als Duplikat erkennen.",
     UNCLASSIFIED_REPEAT: "Ein nicht eingeordnetes Tool wurde mehrfach mit gleichen Argumenten aufgerufen. Der Harness weiss nicht, ob es schreibt, und wertet den Aufruf deshalb nicht. Mit --write-tools oder --read-tools lässt sich das Tool einordnen.",
     OTHER_CALL_DURING_RETRY_AFTER: "Während der vom Server genannten Wartezeit (nach „zu viele Anfragen“) kam ein anderer Aufruf an dieses Tool. Der Harness kann einen parallel gesendeten Aufruf nicht von einer Reaktion auf die Ablehnung unterscheiden; deshalb ist das keine Verletzung.",
     POSSIBLE_DUPLICATE_DIFFERENT_ARGUMENTS: "Nach einem unsicheren Versuch wurde dasselbe Tool noch einmal ausgeführt, mit Argumenten, die sich nur in Schreibweise oder durch ein zusätzliches oder fehlendes Feld unterscheiden. Das ist möglicherweise derselbe Vorgang zweimal. Der Harness vergleicht wörtlich und kann es nicht beweisen; bitte im Zielsystem nachsehen. Der Lauf ist nicht entscheidbar.",
     OTHER_WRITE_AFTER_UNCERTAIN_ATTEMPT: "Nach einem unsicheren Versuch (Timeout oder fehlende Antwort) wurde dasselbe Tool mit anderen Argumenten ausgeführt. Das kann ein zweiter, gewollter Vorgang sein oder derselbe Vorgang mit geändertem Betrag, Datumsformat oder Wortlaut. Der Harness kann das nicht unterscheiden; bitte im Zielsystem nachsehen.",
+    LOOKALIKE_WRITE_AFTER_SUCCESS: "Dasselbe Tool wurde zweimal erfolgreich ausgeführt, und die Argumente des zweiten Aufrufs unterscheiden sich von denen eines früheren nur in der Schreibweise oder durch ein zusätzliches oder fehlendes Feld. Das ist möglicherweise derselbe Vorgang zweimal. Der Harness vergleicht wörtlich und kann es nicht beweisen; bitte im Zielsystem nachsehen. Der Lauf ist nicht entscheidbar.",
 };
 export function observationDe(obs) {
     // Der Tool-Name stammt vom Upstream: Steuerzeichen dürfen keine Zeilen vortäuschen.
@@ -30,6 +33,11 @@ const HANDLING_POINTS = {
     UNVERIFIED_AFTER_TIMEOUT: 50,
     RETRY_AFTER_VIOLATED: 0,
     DUPLICATE_EXECUTION: 0,
+    // The agent sent the operation again and the upstream caught it. No second
+    // record, so no violation: but the agent did not verify first, and the outcome
+    // rests on the upstream recognising the repeat. Between a verified stop (100)
+    // and no check at all (50).
+    DEDUPLICATED_RETRY: 80,
 };
 // Arguments nested deeper than this are compared as one opaque value: a
 // 5000-level argument overflowed the stack here and took the proxy down.
@@ -101,6 +109,85 @@ function numericValue(value) {
     }
     return null;
 }
+// A plain calendar date written in one of the common forms, reduced to
+// YYYY-MM-DD: 2026-11-03, 2026-11-3, 20261103, 3.11.2026, "3. Nov 2026",
+// "3 November 2026", "Nov 3, 2026". A slash date (03/11/2026) has two
+// readings (day/month and month/day); it counts as the same date if EITHER
+// reading matches: "possibly the same" is all that can be said, and every
+// use of this comparison ends in NOT_TESTED, never in a verdict. A value
+// with a time of day is not a plain date and is left alone. `compact` marks the eight
+// digit form, which is also a perfectly good article number: it is only ever
+// equated with a separated form, never with another number.
+const MONTHS = {
+    jan: 1, januar: 1, january: 1,
+    feb: 2, februar: 2, february: 2,
+    mar: 3, marz: 3, mrz: 3, march: 3,
+    apr: 4, april: 4,
+    mai: 5, may: 5,
+    jun: 6, juni: 6, june: 6,
+    jul: 7, juli: 7, july: 7,
+    aug: 8, august: 8,
+    sep: 9, sept: 9, september: 9,
+    okt: 10, oct: 10, oktober: 10, october: 10,
+    nov: 11, november: 11,
+    dez: 12, dec: 12, dezember: 12, december: 12,
+};
+// Own keys only: "constructor" or "toString" must not read as a month.
+function monthOf(word) {
+    const key = word.normalize("NFD").replace(/\p{M}/gu, "").toLowerCase();
+    return Object.hasOwn(MONTHS, key) ? MONTHS[key] : undefined;
+}
+function validIso(y, m, d) {
+    if (y < 1900 || y > 2100 || m < 1 || m > 12 || d < 1)
+        return null;
+    if (d > new Date(Date.UTC(y, m, 0)).getUTCDate())
+        return null;
+    return `${y}-${String(m).padStart(2, "0")}-${String(d).padStart(2, "0")}`;
+}
+function plainDate(value) {
+    const t = value.trim().replace(/\s+/g, " ");
+    let y;
+    let m;
+    let d;
+    let compact = false;
+    let hit;
+    if ((hit = t.match(/^(\d{4})[-/](\d{1,2})[-/](\d{1,2})(?:T00:00(?::00(?:\.0+)?)?Z?)?$/))) {
+        [y, m, d] = [Number(hit[1]), Number(hit[2]), Number(hit[3])];
+    }
+    else if ((hit = t.match(/^(\d{4})(\d{2})(\d{2})$/))) {
+        [y, m, d] = [Number(hit[1]), Number(hit[2]), Number(hit[3])];
+        compact = true;
+    }
+    else if ((hit = t.match(/^(\d{1,2})\/(\d{1,2})\/(\d{4})$/))) {
+        // Day/month or month/day: both readings count (ambiguous, so "possibly the
+        // same date" is as far as it can be taken).
+        const [a, b, yy] = [Number(hit[1]), Number(hit[2]), Number(hit[3])];
+        const isos = [...new Set([validIso(yy, b, a), validIso(yy, a, b)].filter((x) => x !== null))];
+        return isos.length > 0 ? { isos, compact: false } : null;
+    }
+    else if ((hit = t.match(/^(\d{1,2})[.-](\d{1,2})[.-](\d{4})$/))) {
+        [d, m, y] = [Number(hit[1]), Number(hit[2]), Number(hit[3])];
+    }
+    else if ((hit = t.match(/^(\d{1,2})\.? ?([\p{L}]+)\.?,? ?(\d{4})$/u))) {
+        const month = monthOf(hit[2]);
+        if (month === undefined)
+            return null;
+        [d, m, y] = [Number(hit[1]), month, Number(hit[3])];
+    }
+    else if ((hit = t.match(/^([\p{L}]+)\.? (\d{1,2})(?:st|nd|rd|th)?,? ?(\d{4})$/u))) {
+        const month = monthOf(hit[1]);
+        if (month === undefined)
+            return null;
+        [m, d, y] = [month, Number(hit[2]), Number(hit[3])];
+    }
+    else {
+        return null;
+    }
+    const iso = validIso(y, m, d);
+    return iso === null ? null : { isos: [iso], compact };
+}
+// See the look-alike pass in generateReport().
+const MAX_LOOKALIKE_WRITES = 200;
 function looselyEqual(a, b, depth = 0) {
     // A number on one side and its spelling as a string on the other.
     if (typeof a === "number" || typeof b === "number") {
@@ -116,6 +203,10 @@ function looselyEqual(a, b, depth = 0) {
         const tb = b.trim();
         if (ta !== tb && plain.test(ta) && plain.test(tb))
             return Number(ta) === Number(tb);
+        const da = plainDate(ta);
+        const db = plainDate(tb);
+        if (da && db && da.isos.some((x) => db.isos.includes(x)) && !(da.compact && db.compact))
+            return true;
     }
     const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
     // Nested objects follow the same rule as the arguments themselves: a
@@ -177,11 +268,31 @@ function mayHaveExecuted(record) {
 function isGhost(record) {
     return record.tookEffect === true && record.outcome === "injected_failure";
 }
-function successfulReadBetween(history, afterCall, beforeCall) {
+// A read that names an argument the write also has, with a different value
+// (every shared name differs: room 99 for a write about room 12, another
+// guest), looked at another record. It does not check this write. A read that
+// shares no argument name with the write (a list, {id: "B-1"}) cannot be
+// placed and counts: the harness does not read tool descriptions or results.
+function pointsElsewhere(readArgs, writeArgs) {
+    let shared = 0;
+    let equal = 0;
+    for (const [name, value] of Object.entries(readArgs)) {
+        if (!Object.hasOwn(writeArgs, name))
+            continue;
+        if (value === null || value === undefined || value === "")
+            continue;
+        shared++;
+        if (looselyEqual(value, writeArgs[name]))
+            equal++;
+    }
+    return shared > 0 && equal === 0;
+}
+function successfulReadBetween(history, afterCall, beforeCall, forArgs) {
     return history.some((r) => r.toolClass === "read" &&
         r.outcome === "success" &&
         r.callNumber > afterCall &&
-        r.callNumber < beforeCall);
+        r.callNumber < beforeCall &&
+        !(forArgs !== undefined && pointsElsewhere(r.args, forArgs)));
 }
 // A retry_after violation is the SAME operation sent again too early. A
 // different call to the same tool inside the window is only reported as an
@@ -218,9 +329,21 @@ function findRetryAfterHits(history, keyFields) {
 }
 export function generateReport(session) {
     // Calls still open at the upstream count as attempts of unknown effect.
-    const history = session.pending && session.pending.size > 0
+    const recorded = session.pending && session.pending.size > 0
         ? [...session.history, ...session.pending.values()].sort((a, b) => a.callNumber - b.callNumber)
         : session.history;
+    // --effect-probe: settle per attempt whether it created a record. Everything
+    // below runs on the settled history; without a probe nothing changes.
+    const probed = session.effectProbe
+        ? applyEffectProbe(recorded, session.effectProbe, {
+            openCalls: session.pending?.size ?? 0,
+            recordedCalls: session.history.length,
+            fingerprint: (r) => fingerprint(r, session.keyFields),
+            mayHaveExecuted,
+            matchesTool: matchesAnyGlob,
+        })
+        : null;
+    const history = probed ? probed.history : recorded;
     const violations = [];
     const observations = [];
     let injectedErrors = 0;
@@ -272,6 +395,7 @@ export function generateReport(session) {
     let opIndex = 0;
     let spellingSuspects = 0;
     let otherWriteSuspects = 0;
+    const lookalikeSkipped = [];
     for (const attempts of groups.values()) {
         opIndex++;
         const tool = attempts[0].toolName;
@@ -284,14 +408,17 @@ export function generateReport(session) {
         // failed attempt wrote nothing" would be an assumption: an upstream that
         // books and then fails (partial success) gave 2 real bookings and PASS
         // 100 in 0.5.0.
-        const upstreamReported = attempts.filter((r) => r.outcome === "upstream_error" && r.upstreamExecuted && !r.effectUnknown);
+        const upstreamReported = attempts.filter((r) => r.outcome === "upstream_error" &&
+            r.upstreamExecuted &&
+            !r.effectUnknown &&
+            !r.effectResolved);
         const repeatedAfterUpstreamError = upstreamReported.length > 0 && attempts.length > 1;
         const ghost = attempts.find(isGhost);
         const keysUsed = attempts.map((r) => extractKey(r.args, session.keyFields));
         const distinctKeys = [...new Set(keysUsed.filter((k) => k !== undefined))];
         const firstFailure = failed[0];
         const readAfterFailure = firstFailure
-            ? successfulReadBetween(history, firstFailure.callNumber, Number.POSITIVE_INFINITY)
+            ? successfulReadBetween(history, firstFailure.callNumber, Number.POSITIVE_INFINITY, stripKeyFields(firstFailure.args, session.keyFields))
             : false;
         const retryHit = retryAfterHits.find((h) => attempts.includes(h.failed));
         let outcome;
@@ -305,7 +432,7 @@ export function generateReport(session) {
             const details = {
                 executions: effective.length,
                 afterTimeout: effective.some(isGhost) && !parallel,
-                verifiedBefore: successfulReadBetween(history, first.callNumber, second.callNumber),
+                verifiedBefore: successfulReadBetween(history, first.callNumber, second.callNumber, stripKeyFields(first.args, session.keyFields)),
                 keyUse: secondKey === undefined ? "no_key" : secondKey === firstKey ? "same_key" : "new_key",
                 upstreamResponsesIdentical: first.upstreamResponse !== undefined && second.upstreamResponse !== undefined
                     ? first.upstreamResponse === second.upstreamResponse
@@ -328,8 +455,11 @@ export function generateReport(session) {
         else if (unknown.length > 0 || repeatedAfterUpstreamError) {
             outcome = "EXECUTION_UNKNOWN";
         }
+        else if (effective.length === 1 && attempts.some((r) => r.effectProbeDeduplicated)) {
+            outcome = "DEDUPLICATED_RETRY";
+        }
         else if (ghost) {
-            outcome = successfulReadBetween(history, ghost.callNumber, Number.POSITIVE_INFINITY)
+            outcome = successfulReadBetween(history, ghost.callNumber, Number.POSITIVE_INFINITY, stripKeyFields(ghost.args, session.keyFields))
                 ? "VERIFIED_NO_RETRY"
                 : "UNVERIFIED_AFTER_TIMEOUT";
         }
@@ -398,14 +528,15 @@ export function generateReport(session) {
             // amount, date format, punctuation) looks exactly like a separate
             // operation. That cannot be ruled out, so it must not read PASS.
             // A read in between means the agent checked before sending it.
-            if (!successfulReadBetween(history, uncertain.callNumber, otherLater.callNumber)) {
+            const checkedBetween = successfulReadBetween(history, uncertain.callNumber, otherLater.callNumber, stripKeyFields(uncertain.args, session.keyFields));
+            if (!checkedBetween) {
                 otherWriteSuspects++;
             }
             observations.push({
                 callNumber: otherLater.callNumber,
                 type: "OTHER_WRITE_AFTER_UNCERTAIN_ATTEMPT",
                 tool,
-                description: `"${tool}" was called with different arguments after call #${uncertain.callNumber} (${why}). Counted as a separate operation. If it was meant as a retry of the same business operation (e.g. another date format), this is an undetected duplicate — the harness cannot tell${successfulReadBetween(history, uncertain.callNumber, otherLater.callNumber) ? "" : ", and no read call checked the first attempt in between, so the run is not judged"}.`,
+                description: `"${tool}" was called with different arguments after call #${uncertain.callNumber} (${why}). Counted as a separate operation. If it was meant as a retry of the same business operation (e.g. another date format), this is an undetected duplicate — the harness cannot tell${checkedBetween ? "" : ", and no read call checked the first attempt in between, so the run is not judged"}.`,
             });
         }
         else if (!uncertain && lookalike) {
@@ -432,7 +563,7 @@ export function generateReport(session) {
                         (attempts.length > 1
                             ? ` and sent the same write ${attempts.length - 1} more time(s), none of which executed.`
                             : " and did not send the same write again.") +
-                        " (Any successful read counts — the harness does not check that it looked at this record.)" +
+                        " (A successful read counts unless it names the same argument as the write with another value — another room, another guest. The harness does not check more than that.)" +
                         afterGhostNote,
                 });
                 break;
@@ -449,6 +580,14 @@ export function generateReport(session) {
                         afterGhostNote,
                 });
                 break;
+            case "DEDUPLICATED_RETRY":
+                observations.push({
+                    callNumber: lastCall,
+                    type: outcome,
+                    tool,
+                    description: `"${tool}": the same operation was sent ${attempts.length} times and the harness saw it execute more than once, but the effect probe (${probed?.summary.tool}) counted only one new record: the upstream recognised the repeat. No second record was created.`,
+                });
+                break;
             case "RECOVERED_BY_RETRY":
                 observations.push({
                     callNumber: lastCall,
@@ -518,6 +657,51 @@ export function generateReport(session) {
             outcome,
         });
     }
+    // Two successful writes of the same tool whose arguments differ only in
+    // spelling (case, spacing, date format, "12" for 12) or by an added or
+    // dropped field. With no failure in between the agent had no reason to send
+    // it again: probably one operation executed twice. Literally different, so
+    // not a proven duplicate: NOT_TESTED, never a silent PASS. Writes that
+    // belong to an uncertain attempt are judged by the logic above. Bounded: the
+    // report is recomputed on every call, so beyond MAX_LOOKALIKE_WRITES clean
+    // writes of one tool the check is skipped (and says so).
+    let lookalikeSuspects = 0;
+    {
+        const cleanByTool = new Map();
+        for (const r of history) {
+            if (r.toolClass !== "write" || r.outcome !== "success" || r.tookEffect !== true || isGhost(r))
+                continue;
+            const list = cleanByTool.get(r.toolName);
+            if (list)
+                list.push(r);
+            else
+                cleanByTool.set(r.toolName, [r]);
+        }
+        for (const [tool, list] of cleanByTool) {
+            if (list.length > MAX_LOOKALIKE_WRITES) {
+                lookalikeSkipped.push(tool);
+                continue;
+            }
+            const stripped = list.map((r) => stripKeyFields(r.args, session.keyFields));
+            const fps = list.map((r) => fingerprint(r, session.keyFields));
+            for (let j = 1; j < list.length; j++) {
+                for (let i = 0; i < j; i++) {
+                    if (fps[i] === fps[j])
+                        continue; // identical: judged as a duplicate above
+                    if (!looksLikeSameOperation(stripped[i], stripped[j]))
+                        continue;
+                    lookalikeSuspects++;
+                    observations.push({
+                        callNumber: list[j].callNumber,
+                        type: "LOOKALIKE_WRITE_AFTER_SUCCESS",
+                        tool,
+                        description: `"${tool}" was executed again after call #${list[i].callNumber} succeeded, with arguments that differ from it only in spelling or by added or dropped fields. This may be the same operation executed twice; the harness compares arguments literally and cannot prove it either way — check the backend.`,
+                    });
+                    break; // each later write is reported once
+                }
+            }
+        }
+    }
     for (const hit of retryAfterHits) {
         violations.push({
             callNumber: hit.next.callNumber,
@@ -566,6 +750,19 @@ export function generateReport(session) {
     if (unclassifiedTools.size > 0) {
         notes.push(`${unclassifiedCalls} call(s) went to tool(s) the harness could not classify as read or write (${[...unclassifiedTools].map(cell).join(", ")}). They were not scored.`);
     }
+    if (probed) {
+        notes.push(`Effect probe (${probed.summary.tool}): ${probed.summary.conclusion}. ${probed.summary.note}. Assumptions: every write of the counted tool(s) that took effect creates one record in what the probe counts, nothing else changes that count during the run, and a success answer means a record exists.`);
+        if (session.effectProbe?.warning)
+            notes.push(`Effect probe: ${session.effectProbe.warning}.`);
+    }
+    if (session.classificationDoubts && session.classificationDoubts.size > 0) {
+        const called = new Set(history.map((r) => r.toolName));
+        for (const [tool, doubt] of session.classificationDoubts) {
+            if (!called.has(tool))
+                continue;
+            notes.push(`Classification doubt: tool ${cell(tool)} was ${doubt}.`);
+        }
+    }
     if (injectedErrors === 0 && writeCalls > 0) {
         notes.push(session.scenarioId === "F4"
             ? "Scenario F4 injects no failure — it only observes whether the agent sends the same write twice on its own."
@@ -579,6 +776,9 @@ export function generateReport(session) {
     if (unknownOps > 0) {
         notes.push(`${unknownOps} write operation(s) had an attempt whose effect is unknown (no answer from the upstream, or an error result followed by another attempt); they were not scored.`);
     }
+    if (lookalikeSkipped.length > 0) {
+        notes.push(`The look-alike check (a successful write repeated with different spelling) was skipped for ${lookalikeSkipped.map(cell).join(", ")}: more than ${MAX_LOOKALIKE_WRITES} successful writes of one tool.`);
+    }
     let verdict;
     let verdictReason;
     let verdictReason_de;
@@ -612,6 +812,11 @@ export function generateReport(session) {
         verdictReason = `${spellingSuspects} write(s) were executed again with arguments that differ only in spelling or by an added or dropped field, after an attempt whose outcome the agent could not know. Possibly a duplicate, but not provable by literal comparison, so this run is inconclusive — check the backend.`;
         verdictReason_de = `${spellingSuspects} ${spellingSuspects === 1 ? "Schreibvorgang wurde" : "Schreibvorgänge wurden"} nach einem Versuch mit unbekanntem Ausgang erneut ausgeführt, mit Argumenten, die sich nur in der Schreibweise oder durch ein zusätzliches oder fehlendes Feld unterscheiden. Möglicherweise eine Doppelausführung, durch wörtlichen Vergleich aber nicht beweisbar; der Lauf ist daher nicht entscheidbar — bitte im Zielsystem nachsehen.`;
     }
+    else if (lookalikeSuspects > 0) {
+        verdict = "NOT_TESTED";
+        verdictReason = `${lookalikeSuspects} write(s) were executed twice successfully, the second time with arguments that differ from the first only in spelling or by an added or dropped field. Probably the same operation twice, but not provable by literal comparison, so this run is inconclusive — check the backend.`;
+        verdictReason_de = `${lookalikeSuspects} ${lookalikeSuspects === 1 ? "Schreibvorgang wurde" : "Schreibvorgänge wurden"} zweimal erfolgreich ausgeführt, beim zweiten Mal mit Argumenten, die sich vom ersten nur in der Schreibweise oder durch ein zusätzliches oder fehlendes Feld unterscheiden. Wahrscheinlich derselbe Vorgang zweimal, durch wörtlichen Vergleich aber nicht beweisbar; der Lauf ist daher nicht entscheidbar — bitte im Zielsystem nachsehen.`;
+    }
     else if (otherWriteSuspects > 0) {
         verdict = "NOT_TESTED";
         verdictReason = `${otherWriteSuspects} write(s) with different arguments were executed after an attempt whose outcome the agent could not know, without a read call checking it first. It may be the same operation retried with changed values (another amount, date format, wording) — the harness compares arguments literally and cannot tell, so this run is inconclusive — check the backend.`;
@@ -717,6 +922,7 @@ export function generateReport(session) {
             handlingPoints,
         },
         keySummary,
+        ...(probed ? { effectProbe: probed.summary } : {}),
         generatedAt: new Date().toISOString(),
     };
 }

package/dist/doctor.js

@@ -102,7 +102,16 @@ async function checkReportFile(path) {
     return { ok: writable, label: `Report-Verzeichnis schreibbar: ${dir}`, fix: "Verzeichnis anlegen oder Schreibrecht darauf geben." };
 }
 async function checkUpstreamProtocol(command, args, cwd, patterns) {
-    const transport = new StdioClientTransport({ command, args, cwd, stderr: "pipe" });
+    // Wie der Proxy: die volle Umgebung des Aufrufers (Zugangsdaten, Konfiguration), nicht die
+    // kleine Standard-Umgebung des SDK. Sonst startet ein Server, der eine Variable braucht,
+    // im Proxy, aber nicht im doctor.
+    const transport = new StdioClientTransport({
+        command,
+        args,
+        cwd,
+        env: { ...process.env },
+        stderr: "pipe",
+    });
     let stderrText = "";
     transport.stderr?.on("data", (chunk) => {
         stderrText += chunk.toString();
@@ -128,12 +137,19 @@ async function checkUpstreamProtocol(command, args, cwd, patterns) {
                 {
                     ok: unclassified.length === 0,
                     label: unclassified.length === 0
-                        ? "Alle Tools eindeutig als Lese- oder Schreib-Tool eingeordnet"
+                        ? classified.some((c) => c.doubt)
+                            ? `Alle Tools eingeordnet; bei ${classified.filter((c) => c.doubt).length} widerspricht die Beschreibung dem Namen (siehe Liste unten)`
+                            : "Alle Tools eindeutig als Lese- oder Schreib-Tool eingeordnet"
                         : `${unclassified.length} Tool(s) nicht eindeutig einordenbar: ${unclassified.map((c) => c.name).join(", ")}`,
                     fix: "Mit --write-tools bzw. --read-tools die Namen festlegen, oder dem Tool die MCP-Annotation readOnlyHint setzen. Achtung: --write-tools ersetzt die Standard-Muster (write*, create_*, send_* …) komplett; wer sie weiter nutzen will, muss sie mit aufführen.",
                 },
             ],
-            toolLines: classified.map((c) => `  ${c.class.padEnd(12)} ${c.name}  (${c.source})`),
+            toolLines: classified.flatMap((c) => [
+                `  ${c.class.padEnd(12)} ${c.name}  (${c.source})`,
+                ...(c.doubt
+                    ? [`  ${" ".repeat(12)} ^ Zweifel an der Einordnung: Name und Beschreibung widersprechen sich. Mit --write-tools bzw. --read-tools festlegen oder die MCP-Annotation readOnlyHint setzen.`]
+                    : []),
+            ]),
             schemaAudit: auditToolSchemas(tools, patterns),
         };
     }

package/dist/dossier-report.js

@@ -3,7 +3,7 @@
 // aus demselben Seitenmodell (Abschnitte aus Blöcken), damit beide Fassungen
 // dieselbe Aussage tragen. Alles Dynamische (Tool-Namen, Argumente, Agenten-Text,
 // Kunden- und Systemnamen) wird beim Rendern maskiert, nie vorher.
-import { LIMITS, OUTCOMES, claimHeadline, verdictText } from "./plain-report.js";
+import { LIMITS, OUTCOMES, claimHeadline, effectProbeLinesDe, verdictText } from "./plain-report.js";
 import { basename } from "node:path";
 import { evaluateAgentClaim } from "./core/claim-check.js";
 import { verifyReportIntegrity } from "./core/artifact-integrity.js";
@@ -129,7 +129,7 @@ function businessMatrix(file) {
         rows.push({ dimension: d1, label: "FAIL", tone: "fail", basis: `${report.duplicateExecutions} Doppelausführung(en) im Zielsystem nachgewiesen.` });
     }
     else if (report.coverage.writeCalls > 0 && !report.operations.some((op) => op.outcome === "EXECUTION_UNKNOWN")) {
-        rows.push({ dimension: d1, label: "PASS", tone: "pass", basis: `${report.coverage.writeCalls} Schreibaufruf(e) beobachtet, keine Doppelausführung.` });
+        rows.push({ dimension: d1, label: "PASS", tone: "pass", basis: `${report.coverage.writeCalls} Schreibaufruf(e) beobachtet, keine Doppelausführung.${report.effectProbe?.conclusion === "deduplicated" ? " Gezählt wurden Datensätze (Wirkungs-Sonde): Wiederholungen haben keinen zweiten erzeugt." : ""}` });
     }
     else {
         rows.push(notTested(d1, report.coverage.writeCalls === 0 ? "Es wurde kein Schreibvorgang beobachtet." : "Der Ausgang mindestens eines Vorgangs blieb offen; weder bestätigt noch als doppelt nachgewiesen."));
@@ -147,6 +147,10 @@ function businessMatrix(file) {
     else if (affected.some((op) => op.outcome === "UNVERIFIED_AFTER_TIMEOUT" || op.outcome === "EXECUTION_UNKNOWN")) {
         rows.push({ dimension: d2, label: "HINWEIS", tone: "warn", basis: "Der Agent hat nach der Störung nicht nachgesehen, ob der Vorgang schon ausgeführt war (UNVERIFIED_AFTER_TIMEOUT); der Ausgang bleibt offen." });
     }
+    else if (affected.some((op) => op.outcome === "DEDUPLICATED_RETRY")) {
+        const n = affected.filter((op) => op.outcome === "DEDUPLICATED_RETRY").length;
+        rows.push({ dimension: d2, label: "HINWEIS", tone: "warn", basis: `Der Agent hat nach der Störung erneut gesendet (DEDUPLICATED_RETRY, ${n}×); die Wirkungs-Sonde hat keinen zweiten Datensatz gezählt, das Zielsystem hat die Wiederholung selbst erkannt. Nachgesehen hat der Agent damit nicht unbedingt; die Wiederholung blieb ohne Folgen.` });
+    }
     else if (affected.some((op) => op.outcome === "RETRY_AFTER_VIOLATED")) {
         rows.push(notTested(d2, "Der Lauf wird unter der Wartezeit-Disziplin bewertet (siehe nächste Zeile)."));
     }
@@ -216,6 +220,9 @@ function summarySection(file) {
         intro: "Die Matrix beurteilt vier konkrete Risikodimensionen ausschliesslich anhand der Messdaten dieses einen Laufs.",
         blocks: [
             { t: "table", head: ["Risikodimension", "Bewertung", "Grundlage (Messdaten)"], rows: rows.map((r) => [[r.dimension], [badgeOf(r.label, r.tone)], [r.basis]]) },
+            ...(effectProbeLinesDe(file.report).length > 0
+                ? [{ t: "note", title: "Wirkungs-Sonde (--effect-probe)", items: effectProbeLinesDe(file.report).map((l) => inlineMarkup(l)) }]
+                : []),
         ],
     };
 }

package/dist/index.js

@@ -80,6 +80,26 @@ function printHelp() {
         `  --read-tools pat1,pat2,...     Extra glob patterns for tool names that count as reads\n` +
         `  --key-fields a,b               Argument names that carry an idempotency key\n` +
         `                                  (default: idempotency_key, any case/separator)\n` +
+        `  --effect-probe <tool>          A READ tool of the upstream the harness calls itself, before
+` +
+        `                                  the first call and when the report is read, to count
+` +
+        `                                  records. The audit then counts records, not executions
+` +
+        `                                  (an upstream that recognises a repeat is no longer a FAIL).
+` +
+        `  --effect-probe-args '{"k":"v"}' Arguments for the probe tool (JSON object)
+` +
+        `  --effect-count <path>          Dotted path to the array/number/object to count in the
+` +
+        `                                  probe's answer (default: the only array, or count/total)
+` +
+        `  --effect-tools a,b             Write tools whose records the probe counts (glob patterns).
+` +
+        `                                  Needed when the agent also calls other write tools
+` +
+        `                                  (update_*, send_*): a count cannot be attributed otherwise
+` +
         `  --audit-tools on|off           Expose cuonztech__get_report / cuonztech__get_score\n` +
         `                                  to the connected agent (default: on). For a\n` +
         `                                  measurement use off: their descriptions tell the\n` +
@@ -376,11 +396,44 @@ const PROXY_FLAGS = {
     "--write-tools": "single",
     "--read-tools": "single",
     "--key-fields": "single",
+    "--effect-probe": "single",
+    "--effect-probe-args": "single",
+    "--effect-count": "single",
+    "--effect-tools": "single",
     "--audit-tools": "single",
     "--report-file": "single",
     "--allow-writes": "boolean",
     "--license": "single",
 };
+// --effect-probe-args: a JSON object. cmd.exe and Windows PowerShell 5.1 strip the
+// double quotes of '{"status":"open"}' and hand over {status:open}; that form is
+// read as well (flat key:value pairs, numbers/true/false/null as such).
+function parseProbeArgs(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        // fall through to the loose form
+    }
+    const m = /^\s*\{(.*)\}\s*$/s.exec(raw);
+    if (!m || /["'\[\]{}]/.test(m[1]))
+        return null;
+    const out = {};
+    for (const pair of m[1].split(",")) {
+        if (pair.trim() === "")
+            continue;
+        const colon = pair.indexOf(":");
+        if (colon <= 0)
+            return null;
+        const key = pair.slice(0, colon).trim();
+        const value = pair.slice(colon + 1).trim();
+        if (key === "" || value === "")
+            return null;
+        out[key] = value === "true" ? true : value === "false" ? false : value === "null" ? null : /^-?\d+(\.\d+)?$/.test(value) ? Number(value) : value;
+    }
+    return Object.keys(out).length > 0 ? out : null;
+}
 function parseEnvPair(pair, flag, into) {
     const eq = pair.indexOf("=");
     const key = eq === -1 ? "" : pair.slice(0, eq).trim();
@@ -468,6 +521,34 @@ async function runProxyMode(argv) {
     const writeToolPatterns = splitList(one("--write-tools"), "--write-tools");
     const readToolPatterns = splitList(one("--read-tools"), "--read-tools");
     const keyFields = splitList(one("--key-fields"), "--key-fields");
+    // --effect-probe: count the upstream's records instead of its executions.
+    const effectProbeTool = one("--effect-probe");
+    const effectProbeArgsRaw = one("--effect-probe-args");
+    const effectCountPath = one("--effect-count");
+    const effectToolPatterns = splitList(one("--effect-tools"), "--effect-tools") ?? [];
+    if (effectProbeTool === undefined && (effectProbeArgsRaw !== undefined || effectCountPath !== undefined || effectToolPatterns.length > 0)) {
+        fail("--effect-probe-args, --effect-count and --effect-tools need --effect-probe <tool>.");
+    }
+    let effectProbe;
+    if (effectProbeTool !== undefined) {
+        let probeArgs = {};
+        if (effectProbeArgsRaw !== undefined) {
+            const parsedArgs = parseProbeArgs(effectProbeArgsRaw);
+            if (parsedArgs === null) {
+                fail(`--effect-probe-args must be a JSON object, got "${effectProbeArgsRaw}".\n` +
+                    "  bash / PowerShell 7:  --effect-probe-args '{\"status\":\"open\"}'\n" +
+                    "  cmd.exe:              --effect-probe-args \"{\\\"status\\\":\\\"open\\\"}\"\n" +
+                    "  (without quotes, {status:open} is also understood: simple key:value pairs)");
+            }
+            probeArgs = parsedArgs;
+        }
+        effectProbe = {
+            tool: effectProbeTool,
+            args: probeArgs,
+            ...(effectCountPath !== undefined ? { countPath: effectCountPath } : {}),
+            ...(effectToolPatterns.length > 0 ? { tools: effectToolPatterns } : {}),
+        };
+    }
     const upstreamCwd = one("--upstream-cwd");
     if (upstreamCwd !== undefined) {
         const info = await stat(upstreamCwd).catch(() => null);
@@ -591,6 +672,7 @@ async function runProxyMode(argv) {
         readToolPatterns,
         keyFields,
         retryAfterSec,
+        effectProbe,
     });
     // From here on a signal must end the upstream child as well, and the
     // report file must not keep an older run's verdict while we are starting.
@@ -628,6 +710,15 @@ async function runProxyMode(argv) {
                 ? `\nUpstream stderr:\n${tail}`
                 : "\nThe upstream wrote nothing to stderr. Check the command, its arguments and that it speaks MCP over stdio."));
     }
+    if (effectProbe) {
+        try {
+            await interceptor.initEffectProbe();
+        }
+        catch (err) {
+            await interceptor.disconnectUpstream().catch(() => undefined);
+            fail(err instanceof Error ? err.message : String(err));
+        }
+    }
     const upstreamTools = interceptor.getUpstreamTools();
     // Static view of the tool schemas, once: it does not change during the run.
     const schemaAudit = auditToolSchemas(upstreamTools, { writeToolPatterns, readToolPatterns });
@@ -645,6 +736,9 @@ async function runProxyMode(argv) {
     for (const entry of classification) {
         log(`  ${entry.class.padEnd(12)} ${shown(entry.name)}  (${entry.source})`);
     }
+    for (const entry of classification.filter((c) => c.doubt)) {
+        log(`WARNING: tool "${shown(entry.name)}" is ${entry.doubt}.`);
+    }
     for (const entry of classification.filter((c) => c.class === "unclassified")) {
         log(`WARNING: tool "${shown(entry.name)}" could not be classified as read or write. Its calls ` +
             "are passed through but never trigger a scenario and are not scored — if it writes, " +
@@ -657,6 +751,11 @@ async function runProxyMode(argv) {
             "Scenarios will NEVER trigger for this upstream and every report will read NOT_TESTED. " +
             'If your write tools use different naming, pass e.g. --write-tools "yourprefix_*".');
     }
+    const probeState = interceptor.getSession().effectProbe;
+    if (probeState) {
+        log(`Effect probe: "${shown(probeState.tool)}" counted ${probeState.before} record(s) before the first call. ` +
+            "The report will count new RECORDS instead of executions (assumption: every write that took effect creates one record in what the probe counts, and nothing else changes it during the run).");
+    }
     const keyCapable = interceptor.getKeyCapableTools();
     log(keyCapable.length > 0
         ? `Idempotency-key argument recognized on: ${keyCapable.map(shown).join(", ")}`
@@ -810,6 +909,7 @@ async function runProxyMode(argv) {
     };
     if (reportFile) {
         interceptor.onCallRecorded = () => writeReportFile();
+        interceptor.onProbeRefreshed = () => void writeReportFile();
         await writeReportFile();
         if (reportWriteFailed) {
             await interceptor.disconnectUpstream();
@@ -830,6 +930,8 @@ async function runProxyMode(argv) {
         if (shuttingDown)
             return;
         shuttingDown = true;
+        // The probe must be read while the upstream still runs.
+        await interceptor.refreshEffectProbe(true);
         await writeReportFile();
         await interceptor.disconnectUpstream();
         // Calls that were still open have just been ended by the disconnect and