@openrouter/agent 0.8.0 → 0.10.0

package/esm/lib/doom-loop.js

@@ -0,0 +1,1221 @@
+/**
+ * Doom-loop detection for the tool-execution loop.
+ *
+ * A "doom loop" is a run that stops making progress while continuing to spend:
+ * the model re-issues the same tool call with identical arguments (including
+ * repeated *empty* calls and repeated unparseable calls), or emits the same
+ * text tokens over and over. This module provides the deterministic detection
+ * primitives; `ModelResult` wires them into the loop behind the `doomLoop`
+ * option on `callModel`.
+ *
+ * Design principles:
+ *
+ * - **Deterministic.** Every verdict is a pure function of the recorded
+ *   sequence of tool calls / assistant texts. The same scripted transcript
+ *   produces the same verdicts at the same indices — no wall clocks, no
+ *   randomness — so the feature is testable without a live model and
+ *   portable across SDK ports via shared test vectors.
+ * - **Cross-port fingerprints.** Key material is canonicalized per RFC 8785
+ *   (JCS) and hashed with SHA-256 over the UTF-8 bytes. Ports (Python/Go)
+ *   MUST use a JCS implementation (e.g. pip `jcs`,
+ *   `cyberphone/json-canonicalization`), not their stdlib JSON serializer —
+ *   the shared vector file `tests/vectors/doom-loop-fingerprints.json` is
+ *   the conformance contract.
+ * - **Tool-declared identity.** A tool opts into precise loop identity via
+ *   `loopKey` on its definition: a function computing key material
+ *   (e.g. `({ command, cwd }) => ({ command, cwd })`), a field-name array
+ *   (`['command', 'cwd']` — data, not code, so it can ride MCP tool caches
+ *   and the `_meta['openrouter/loopKey']` wire field), or `false` to exempt
+ *   the tool. Tools declare *what identifies a call*; this module owns
+ *   canonicalization and hashing so fingerprints are uniform across tools
+ *   and ports.
+ * - **Round-scoped streaks.** A streak measures the model *re-issuing a call
+ *   after seeing its result*, which requires a model round trip. N identical
+ *   calls fanned out in ONE round count once; the duplicates share that
+ *   round's decision. A round's identity for one tool is the *set* of
+ *   fingerprints it was called with, so a fan-out of distinct arguments
+ *   (`read(a), read(b), read(c)`) reissued verbatim accumulates, and every
+ *   call in the round reports the round's streak. Ports must declare a
+ *   round's complete set before scoring any of its calls (see
+ *   `declareRound`): scoring a set as it accumulates makes a superset round
+ *   transiently match the previous one, which both fires on real progress
+ *   and makes the outcome depend on emission order.
+ * - **Graduated response.** Detection feeds a configurable action ladder
+ *   (observe → steer → block → stop) rather than killing the run outright.
+ * - **Never the cause of failure.** Detection may only affect a run through
+ *   its defined actions. Any internal error (unhashable key material,
+ *   throwing `loopKey`, corrupt persisted state) degrades to a fallback
+ *   identity or skips detection for that call — it never rejects the call
+ *   or crashes the run.
+ */
+//#endregion
+//#region Defaults & Config Resolution
+/**
+ * Default ladder: observe at 2 consecutive identical rounds, block at 3,
+ * stop at 6. Steer is off by default (blocking already delivers feedback in
+ * the tool output, where the model looks first).
+ */
+export const DEFAULT_DOOM_LOOP_LADDER = Object.freeze({
+    observe: 2,
+    steer: false,
+    escalate: false,
+    block: 3,
+    stop: 6,
+});
+/** Default escalation budget when the rung is enabled without a cap. */
+export const DEFAULT_MAX_ESCALATIONS = 2;
+const DEFAULT_TEXT_OPTIONS = Object.freeze({
+    enabled: true,
+    maxPeriodTokens: 16,
+    minRepeats: 4,
+    minCoveredTokens: 12,
+    maxWindowTokens: 400,
+});
+function sanitizeThreshold(value, fallback) {
+    if (value === false) {
+        return false;
+    }
+    if (typeof value === 'number' && Number.isFinite(value) && value >= 1) {
+        return Math.floor(value);
+    }
+    return fallback;
+}
+/** Ladder rungs ordered weakest → strongest, for dead-rung analysis. */
+const LADDER_ORDER = [
+    'observe',
+    'steer',
+    'escalate',
+    'block',
+    'stop',
+];
+/**
+ * Warn about configurations that are accepted but probably not what the
+ * caller meant:
+ *
+ * - `block` enabled with `stop: false` — blocked calls still increment the
+ *   streak, so a model that keeps re-issuing the call produces an unbounded
+ *   block/re-issue ping-pong bounded only by `stopWhen` (which defaults to
+ *   unbounded). Explicitly allowed, loudly flagged.
+ * - Dead rungs — with strongest-wins resolution, a weaker rung whose
+ *   threshold is >= an enabled stronger rung's threshold can never fire
+ *   (e.g. `{ observe: 5, block: 2 }`: block wins from streak 2 on).
+ */
+function warnOnLadderHazards(ladder) {
+    if (ladder.block !== false && ladder.stop === false) {
+        console.warn('[DoomLoop] ladder has block enabled with stop disabled: a model that keeps ' +
+            're-issuing a blocked call loops indefinitely (each blocked round still costs a ' +
+            'model request). Bound the run with stopWhen, or enable the stop rung.');
+    }
+    for (let weak = 0; weak < LADDER_ORDER.length; weak++) {
+        const weakName = LADDER_ORDER[weak];
+        const weakThreshold = ladder[weakName];
+        if (weakThreshold === false) {
+            continue;
+        }
+        for (let strong = weak + 1; strong < LADDER_ORDER.length; strong++) {
+            const strongName = LADDER_ORDER[strong];
+            const strongThreshold = ladder[strongName];
+            if (strongThreshold !== false && weakThreshold >= strongThreshold) {
+                console.warn(`[DoomLoop] ladder rung "${weakName}" (${weakThreshold}) can never fire: ` +
+                    `stronger rung "${strongName}" (${strongThreshold}) already wins at that streak ` +
+                    '(strongest crossed rung is applied).');
+                break; // one warning per dead rung is enough
+            }
+        }
+    }
+}
+export function resolveDoomLoopOption(option) {
+    if (option === undefined || option === false) {
+        return null;
+    }
+    const config = option === true ? {} : option;
+    const ladderInput = config.ladder ?? {};
+    const textInput = config.text === undefined || config.text === true ? {} : config.text;
+    const ladder = {
+        observe: sanitizeThreshold(ladderInput.observe, DEFAULT_DOOM_LOOP_LADDER.observe),
+        steer: sanitizeThreshold(ladderInput.steer, DEFAULT_DOOM_LOOP_LADDER.steer),
+        escalate: sanitizeThreshold(ladderInput.escalate, DEFAULT_DOOM_LOOP_LADDER.escalate),
+        block: sanitizeThreshold(ladderInput.block, DEFAULT_DOOM_LOOP_LADDER.block),
+        stop: sanitizeThreshold(ladderInput.stop, DEFAULT_DOOM_LOOP_LADDER.stop),
+    };
+    warnOnLadderHazards(ladder);
+    // Escalation recovery: usable only when the config names at least one
+    // mechanism. An enabled rung without a mechanism (or vice versa, a
+    // mechanism without the rung) is probably a config mistake — warn, and
+    // treat the rung as absent so verdicts fall through to weaker rungs.
+    const escalationInput = config.escalation;
+    // `advisor: false` is an explicit opt-out, not a mechanism. The recovery step
+    // skips a disabled advisor (see model-result.ts), so counting it here would
+    // resolve an escalation rung that consumes budget and announces recovery
+    // without applying any override — `{ advisor: false }` alone must read the
+    // same as `{}`.
+    const hasAdvisor = escalationInput?.advisor !== undefined && escalationInput.advisor !== false;
+    const hasMechanism = escalationInput !== undefined && (escalationInput.model !== undefined || hasAdvisor);
+    let escalation = null;
+    if (hasMechanism) {
+        const cap = escalationInput.maxEscalations;
+        escalation = {
+            ...(escalationInput.model !== undefined && {
+                model: escalationInput.model,
+            }),
+            ...(hasAdvisor && {
+                advisor: escalationInput.advisor,
+            }),
+            maxEscalations: typeof cap === 'number' && Number.isFinite(cap) && cap >= 1
+                ? Math.floor(cap)
+                : DEFAULT_MAX_ESCALATIONS,
+        };
+        if (ladder.escalate === false) {
+            console.warn('[DoomLoop] escalation config provided but the escalate ladder rung is disabled; ' +
+                'set ladder.escalate to a streak threshold for recovery to trigger.');
+        }
+    }
+    else if (ladder.escalate !== false) {
+        console.warn('[DoomLoop] ladder.escalate is enabled but no escalation config (model/advisor) was ' +
+            'provided; the rung is skipped and verdicts fall through to weaker rungs.');
+    }
+    return {
+        ladder,
+        escalation,
+        text: textInput === false
+            ? {
+                ...DEFAULT_TEXT_OPTIONS,
+                enabled: false,
+            }
+            : {
+                enabled: textInput.enabled ?? DEFAULT_TEXT_OPTIONS.enabled,
+                maxPeriodTokens: textInput.maxPeriodTokens ?? DEFAULT_TEXT_OPTIONS.maxPeriodTokens,
+                minRepeats: textInput.minRepeats ?? DEFAULT_TEXT_OPTIONS.minRepeats,
+                minCoveredTokens: textInput.minCoveredTokens ?? DEFAULT_TEXT_OPTIONS.minCoveredTokens,
+                maxWindowTokens: textInput.maxWindowTokens ?? DEFAULT_TEXT_OPTIONS.maxWindowTokens,
+            },
+    };
+}
+//#endregion
+//#region loopKey Resolution
+/**
+ * Resolve a tool's `loopKey` declaration (function, `false`, or absent)
+ * against one call's validated arguments.
+ *
+ * - absent (`undefined` declaration) → the full arguments object.
+ * - `false` → the tool is statically exempt.
+ * - function → called with the arguments, like every other tool hook.
+ *   `null` exempts THIS call; `undefined` falls back to the full arguments
+ *   (with a warning — a bare `return;` is almost always a bug, and treating
+ *   it as key material would collide every call of the tool onto one
+ *   fingerprint); a throw falls back to the full arguments (detection must
+ *   never take down a run).
+ */
+export function resolveLoopKeyMaterial(loopKey, args) {
+    if (loopKey === undefined) {
+        return {
+            kind: 'key',
+            keyMaterial: args,
+        };
+    }
+    if (loopKey === false) {
+        return {
+            kind: 'exempt',
+        };
+    }
+    if (Array.isArray(loopKey)) {
+        /*
+         * An empty field list would make EVERY call to the tool fingerprint
+         * identically — `ls` and `rm -rf /` collapse to one identity — so a
+         * detector armed to block a repeat would refuse the second unrelated call.
+         * That is a footgun from a local declaration and a vector once the list can
+         * be advertised over the wire by an MCP server (`_meta['openrouter/loopKey']`).
+         * Fall back to full arguments with a warning, mirroring how the function
+         * form handles a degenerate result rather than trusting it.
+         */
+        if (loopKey.length === 0) {
+            return {
+                kind: 'fallback',
+                keyMaterial: args,
+                warning: 'loopKey is an empty field list, which would give every call to this tool the same identity; falling back to full arguments. Use `false` to exempt the tool.',
+            };
+        }
+        const subset = Object.create(null);
+        for (const field of loopKey) {
+            if (typeof field === 'string' && field in args) {
+                subset[field] = args[field];
+            }
+        }
+        /*
+         * Every declared field missing from the arguments is the same collapse by
+         * another route: the subset is empty, so identity is again constant.
+         */
+        if (Object.keys(subset).length === 0) {
+            return {
+                kind: 'fallback',
+                keyMaterial: args,
+                warning: `loopKey fields [${loopKey.filter((f) => typeof f === 'string').join(', ')}] are all absent from the arguments, which would give every call the same identity; falling back to full arguments.`,
+            };
+        }
+        return {
+            kind: 'key',
+            keyMaterial: subset,
+        };
+    }
+    if (typeof loopKey === 'function') {
+        let result;
+        try {
+            result = loopKey(args);
+        }
+        catch (error) {
+            return {
+                kind: 'fallback',
+                keyMaterial: args,
+                warning: `loopKey threw (${error instanceof Error ? error.message : String(error)}); falling back to full arguments`,
+            };
+        }
+        if (result === null) {
+            return {
+                kind: 'exempt',
+            };
+        }
+        if (result === undefined) {
+            return {
+                kind: 'fallback',
+                keyMaterial: args,
+                warning: 'loopKey returned undefined; falling back to full arguments. Return null to exempt a call, or a value to use as identity.',
+            };
+        }
+        return {
+            kind: 'key',
+            keyMaterial: result,
+        };
+    }
+    return {
+        kind: 'fallback',
+        keyMaterial: args,
+        warning: `loopKey has unsupported shape (${typeof loopKey}); falling back to full arguments`,
+    };
+}
+//#endregion
+//#region Canonicalization & Fingerprinting
+/**
+ * Maximum nesting depth accepted by {@link canonicalizeKeyMaterial}. Real
+ * tool arguments come from parsed JSON and stay shallow; anything deeper is
+ * hostile or buggy key material and must fail fast (with a catchable error)
+ * instead of overflowing the stack.
+ */
+export const MAX_CANONICALIZE_DEPTH = 64;
+/**
+ * RFC 8785 (JCS) canonical JSON: object keys sorted by UTF-16 code units
+ * (recursively), arrays in order, strings and finite numbers serialized per
+ * ECMAScript `JSON.stringify` (which IS the JCS serialization — e.g. `-0`
+ * canonicalizes to `0`, `1e21` to `1e+21`, lone surrogates to `\udXXX`
+ * escapes). Insensitive to key insertion order, so `{a:1,b:2}` and
+ * `{b:2,a:1}` canonicalize identically.
+ *
+ * This is the cross-port contract: Python and Go ports must produce
+ * byte-identical canonical strings for the same key material, which means
+ * they MUST use an RFC 8785 implementation (pip `jcs`,
+ * `cyberphone/json-canonicalization`), not their stdlib JSON serializer
+ * (Python's `json.dumps(-0.0)` is `-0.0`, which is NOT JCS).
+ *
+ * JSON-data-model semantics for JS-only values:
+ * - `undefined` / function / symbol object entries are dropped (as
+ *   `JSON.stringify` does); in arrays they serialize as `null`.
+ *
+ * @throws Error on values RFC 8785 cannot represent — non-finite numbers,
+ * bigint — plus circular references and nesting deeper than
+ * {@link MAX_CANONICALIZE_DEPTH}. Real tool arguments (parsed JSON) can
+ * never trigger these; only computed `loopKey` material can, and the engine
+ * catches the error and falls back to the full-arguments identity.
+ */
+export function canonicalizeKeyMaterial(value) {
+    const seen = new Set();
+    const canon = (v, depth) => {
+        if (depth > MAX_CANONICALIZE_DEPTH) {
+            throw new Error(`Cannot canonicalize key material nested deeper than ${MAX_CANONICALIZE_DEPTH} levels for doom-loop fingerprinting`);
+        }
+        if (v === null || v === undefined) {
+            return 'null';
+        }
+        switch (typeof v) {
+            case 'number':
+                if (!Number.isFinite(v)) {
+                    throw new Error('Cannot canonicalize non-finite number (NaN/Infinity) for doom-loop fingerprinting: RFC 8785 has no representation');
+                }
+                return JSON.stringify(v);
+            case 'string':
+            case 'boolean':
+                return JSON.stringify(v);
+            case 'bigint':
+                throw new Error('Cannot canonicalize bigint for doom-loop fingerprinting: RFC 8785 has no representation (convert to string or number in loopKey)');
+            case 'object':
+                break;
+            default:
+                // function / symbol — not representable; JSON semantics say null here.
+                return 'null';
+        }
+        const obj = v;
+        if (seen.has(obj)) {
+            throw new Error('Cannot canonicalize circular key material for doom-loop fingerprinting');
+        }
+        seen.add(obj);
+        try {
+            if (Array.isArray(obj)) {
+                return `[${obj.map((item) => canon(item, depth + 1)).join(',')}]`;
+            }
+            const record = obj;
+            const keys = Object.keys(record)
+                .filter((key) => {
+                const entry = record[key];
+                return entry !== undefined && typeof entry !== 'function' && typeof entry !== 'symbol';
+            })
+                .sort();
+            return `{${keys.map((key) => `${JSON.stringify(key)}:${canon(record[key], depth + 1)}`).join(',')}}`;
+        }
+        finally {
+            seen.delete(obj);
+        }
+    };
+    return canon(value, 0);
+}
+/**
+ * SHA-256 over UTF-8 bytes via WebCrypto — no dependency, no `node:`
+ * builtin, so the module stays edge/browser-safe. `globalThis.crypto` is
+ * available unflagged in Node ≥19 (Node 18 required
+ * `--experimental-global-webcrypto` and is EOL), Bun, Deno, workers, and
+ * browsers; the supported floor is the active Node LTS (CI runs 22).
+ * Lone surrogates never reach the encoder: `JSON.stringify` escapes them as
+ * `\udXXX` (ASCII) inside the canonical string.
+ */
+async function sha256Hex(canonical) {
+    const bytes = new TextEncoder().encode(canonical);
+    const digest = await globalThis.crypto.subtle.digest('SHA-256', bytes);
+    const view = new Uint8Array(digest);
+    let hex = '';
+    for (let i = 0; i < view.length; i++) {
+        hex += view[i].toString(16).padStart(2, '0');
+    }
+    return hex;
+}
+/**
+ * Fingerprint arbitrary key material: `sha256(utf8(jcs(keyMaterial)))`,
+ * lowercase hex (64 chars).
+ */
+export function fingerprintKeyMaterial(keyMaterial) {
+    return sha256Hex(canonicalizeKeyMaterial(keyMaterial));
+}
+/**
+ * Fingerprint a tool call: `sha256(utf8(toolName + '\n' + jcs(keyMaterial)))`,
+ * lowercase hex. The tool name participates so `search({q})` and
+ * `fetch({q})` with equal arguments never share a fingerprint. This exact
+ * construction is the cross-port contract — see
+ * `tests/vectors/doom-loop-fingerprints.json`.
+ */
+export function fingerprintToolCall(toolName, keyMaterial) {
+    return sha256Hex(`${toolName}\n${canonicalizeKeyMaterial(keyMaterial)}`);
+}
+/**
+ * Detect a period-p token block repeating at the *tail* of `text` — the
+ * canonical shape of an in-response token doom loop ("I am stuck. I am
+ * stuck. I am stuck. …"). Pure and deterministic: whitespace tokenization,
+ * suffix comparison, no heuristics beyond the thresholds.
+ *
+ * Only the trailing region of the text is examined: a fixed character
+ * budget (64 chars per window token) is sliced off the tail before
+ * tokenization, so multi-megabyte responses do not pay a full-text token
+ * split. The budget is part of the deterministic contract (same text ⇒
+ * same slice ⇒ same result).
+ *
+ * Ties on covered tokens prefer the smallest period (the most repeats), so
+ * "no no no no no no" reports p=1 × 6, not p=2 × 3 — the repeat count is
+ * what feeds the ladder.
+ *
+ * Returns null when no block meets `minRepeats` and `minCoveredTokens`
+ * within `maxPeriodTokens` / `maxWindowTokens`.
+ *
+ * KNOWN LIMIT: token blocks must repeat *exactly*. Paraphrased loops ("I am
+ * stuck" / "I appear to be stuck" / …) do not trip this detector.
+ */
+export function detectTextRepetition(text, options) {
+    const maxPeriodTokens = options?.maxPeriodTokens ?? DEFAULT_TEXT_OPTIONS.maxPeriodTokens;
+    const minRepeats = options?.minRepeats ?? DEFAULT_TEXT_OPTIONS.minRepeats;
+    const minCoveredTokens = options?.minCoveredTokens ?? DEFAULT_TEXT_OPTIONS.minCoveredTokens;
+    const maxWindowTokens = options?.maxWindowTokens ?? DEFAULT_TEXT_OPTIONS.maxWindowTokens;
+    // Bound the tokenization cost: 64 chars/token is a generous upper bound
+    // for whitespace-delimited tokens in practice; the window slice below
+    // still enforces the exact token count.
+    const charBudget = maxWindowTokens * 64;
+    const tail = text.length > charBudget ? text.slice(-charBudget) : text;
+    const allTokens = tail.trim().split(/\s+/).filter(Boolean);
+    const tokens = allTokens.slice(-maxWindowTokens);
+    if (tokens.length < Math.max(minCoveredTokens, 2)) {
+        return null;
+    }
+    let best = null;
+    const maxPeriod = Math.min(maxPeriodTokens, Math.floor(tokens.length / 2));
+    for (let period = 1; period <= maxPeriod; period++) {
+        let repeats = 1;
+        outer: for (let start = tokens.length - 2 * period; start >= 0; start -= period) {
+            for (let i = 0; i < period; i++) {
+                if (tokens[start + i] !== tokens[tokens.length - period + i]) {
+                    break outer;
+                }
+            }
+            repeats++;
+        }
+        const coveredTokens = repeats * period;
+        if (repeats >= minRepeats && coveredTokens >= minCoveredTokens) {
+            if (!best || coveredTokens > best.coveredTokens) {
+                best = {
+                    repeats,
+                    periodTokens: period,
+                    coveredTokens,
+                    sample: tokens.slice(-period).join(' '),
+                };
+            }
+        }
+    }
+    return best;
+}
+//#endregion
+//#region Ladder Resolution
+/**
+ * Map a streak onto the strongest crossed ladder rung.
+ *
+ * `allowBlock: false` is used for text and server-tool verdicts: the tokens
+ * are already emitted / the tool already ran server-side, so there is
+ * nothing to block — a block-level streak falls through to escalate/steer
+ * (when enabled) or observe, while stop still stops.
+ *
+ * `allowEscalate: false` disables the escalate rung for this resolution —
+ * used when no escalation mechanism is configured or the run's escalation
+ * budget is exhausted; the streak falls through to the weaker rungs.
+ * Escalation applies to the NEXT model request, so it is available to every
+ * detector kind (tool, server-tool, and text verdicts alike).
+ */
+export function resolveLadderAction(ladder, streak, options) {
+    const meets = (threshold) => threshold !== false && streak >= threshold;
+    if (meets(ladder.stop)) {
+        return 'stop';
+    }
+    if (options.allowBlock && meets(ladder.block)) {
+        return 'block';
+    }
+    if ((options.allowEscalate ?? true) && meets(ladder.escalate)) {
+        return 'escalate';
+    }
+    if (meets(ladder.steer)) {
+        return 'steer';
+    }
+    if (meets(ladder.observe)) {
+        return 'observe';
+    }
+    return undefined;
+}
+//#endregion
+//#region Monitor
+function isValidStreak(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.fingerprint === 'string' &&
+        typeof value.streak === 'number' &&
+        Number.isFinite(value.streak));
+}
+/**
+ * True when an entry's per-call counts carry no information beyond its round
+ * set and round streak, so getState() may omit them and restore() can rebuild
+ * them exactly. Holds in the steady state of a repeating fan-out — every
+ * member has been issued in the same consecutive rounds, so every count equals
+ * the round streak. Persisting both in that state stored each 64-char hash
+ * twice (once in the set, once as a count key): ~13 KB per width-100 round,
+ * copied on every save. The counts must also cover exactly the set members —
+ * a shrunk round (count > streak) or an extra recorded non-member is real
+ * evidence and is still persisted verbatim.
+ */
+function callStreaksReconstructible(entry) {
+    const counts = entry.callStreaks;
+    if (counts === undefined) {
+        return true;
+    }
+    const set = entry.roundFingerprints ?? [
+        entry.fingerprint,
+    ];
+    const keys = Object.keys(counts);
+    return (keys.length === set.length &&
+        keys.every((key) => set.includes(key) && counts[key] === entry.streak));
+}
+/**
+ * Rebuild one tool's in-memory streak entry from its persisted shape.
+ *
+ * The persisted set (when the last round was multi-call) restores the round's
+ * identity exactly, so a resumed fan-out continues its streak and a resumed
+ * SUBSET cannot match it — the false-positive and false-negative failure
+ * modes of a single-fingerprint save. Older blobs (and single-call rounds)
+ * carry no set; the lone fingerprint fully describes those rounds. Malformed
+ * sets fall back the same way rather than dropping the entry.
+ *
+ * Per-call counts restore into the CURRENT-round slot: the first resumed
+ * record is a new round, so `recordToolCall` rolls them into its baseline
+ * (`priorCallStreaks`) exactly as a live round transition would. Validated
+ * entry-by-entry — the blob is caller-writable JSON, and one malformed count
+ * must not poison the rest. `Object.create(null)` + direct assignment so a
+ * persisted "__proto__" key is inert data, mirroring the Map rationale at the
+ * `tools` field. `round` is intentionally absent from the result: the first
+ * resumed record is always a new round, whatever the numbering.
+ */
+function restoreStreakEntry(entry) {
+    const persistedSet = Array.isArray(entry.roundFingerprints) &&
+        entry.roundFingerprints.length > 1 &&
+        entry.roundFingerprints.every((value) => typeof value === 'string')
+        ? [
+            ...entry.roundFingerprints,
+        ].sort()
+        : [
+            entry.fingerprint,
+        ];
+    const persistedCallStreaks = Object.create(null);
+    if (typeof entry.callStreaks === 'object' && entry.callStreaks !== null) {
+        for (const [callFingerprint, count] of Object.entries(entry.callStreaks)) {
+            if (typeof count === 'number' && Number.isFinite(count) && count >= 1) {
+                persistedCallStreaks[callFingerprint] = Math.floor(count);
+            }
+        }
+    }
+    /*
+     * The round streak gets the same range validation as the per-call counts —
+     * the blob is caller-writable JSON, and `isValidStreak` only checks "finite
+     * number". A negative count would hold the guardrail below every rung for
+     * that tool (thresholds compare with `>=`); a fractional or absurd one
+     * would feed the ladder garbage. Clamped to a sane count rather than
+     * rejected: a corrupt streak must degrade the entry, not drop the tool's
+     * evidence entirely (fail-open, like every other restore path). The cap is
+     * generous — real streaks stop the run at single digits — and exists only
+     * to bound arithmetic, not to change semantics.
+     */
+    const streak = Math.min(Math.max(Math.floor(entry.streak), 1), 1000000);
+    return {
+        fingerprint: entry.fingerprint,
+        streak,
+        roundFingerprints: persistedSet,
+        /*
+         * Absent per-call counts mean getState() proved them reconstructible:
+         * every member of the round set carried exactly the round streak (the
+         * steady state of a repeating fan-out — see callStreaksReconstructible).
+         * Rebuild them for the WHOLE set, not just the last-recorded member, or a
+         * width-W fan-out would resume with W−1 members' evidence reset.
+         */
+        callStreaks: Object.keys(persistedCallStreaks).length > 0
+            ? persistedCallStreaks
+            : Object.fromEntries(persistedSet.map((member) => [
+                member,
+                streak,
+            ])),
+    };
+}
+/**
+ * Pure state machine over the recorded transcript: feed it tool calls and
+ * assistant texts, get verdicts back. Holds no engine concerns (hook
+ * emission, blocking, steering, stopping live in `ModelResult`), so its
+ * behavior is fully exercisable in unit tests and portable as a spec.
+ *
+ * State is bounded, plain JSON (one streak entry per distinct tool name +
+ * one text streak) and round-trips through `ConversationState`.
+ */
+export class DoomLoopMonitor {
+    constructor(config, initialState) {
+        // Map, not Record: tool names are dynamic runtime keys, and on restore
+        // they come from persisted (caller-writable) JSON — a Record's bracket
+        // setter would let a crafted "__proto__" key reassign the map's
+        // prototype and corrupt streak bookkeeping. Map keys are inert data, so
+        // hostile names (and legitimate tools named "__proto__") just work.
+        this.tools = new Map();
+        // Escalation recoveries consumed by this conversation. Persisted (see
+        // getState/restore) so a resumed run cannot reset its budget.
+        this.escalationsUsed = 0;
+        /**
+         * Fingerprint with a per-object memo. The engine hands the SAME key-material
+         * object to `declareRound` and then to `recordToolCall` (the resolved
+         * `loopKey` output is cached per call id), so without this every checked
+         * call is canonicalized and SHA-256'd twice per round. WeakMap keeps the
+         * memo from retaining arguments beyond their natural lifetime; primitive
+         * key material (raw-string malformed args) skips the memo — it cannot key a
+         * WeakMap, and such calls are rare and small. Callers that mutate key
+         * material between declare and record get the declare-time identity, which
+         * is the identity the round was declared with — the consistent choice.
+         */
+        this.fingerprintMemo = new WeakMap();
+        this.config = config;
+        if (initialState !== undefined) {
+            this.restore(initialState);
+        }
+    }
+    /**
+     * Declare the complete set of calls a round will make, before any of them
+     * is recorded. Each entry is one call's `(toolName, keyMaterial)`; the
+     * monitor groups them per tool into that tool's round set.
+     *
+     * A round's identity is the *set* of fingerprints a tool was called with,
+     * so that set has to be known up front. Accumulating it call by call meant
+     * a round that is a strict superset of the previous one transiently equaled
+     * it while filling — `[a,b]`, `[a,b]`, `[a,b,c]` scored a verdict on the `b`
+     * of the third round and refused a call that represented real progress. It
+     * was also emission-order dependent: `[c,a,b]` never formed the matching
+     * prefix and scored nothing. Declaring the whole set removes both.
+     *
+     * Idempotent per round, and safe to skip: PER-CALL detection needs no
+     * declaration — every repeated `(tool, arguments)` identity accumulates its
+     * own consecutive-round count regardless, so an undeclared repeating
+     * fan-out still flags each repeated member (server-tool records take that
+     * path). What the declaration adds is round-set evidence: the fan-out
+     * scored as one unit, with a shared verdict and one steer message, instead
+     * of member-by-member. Unhashable key material is skipped here with a
+     * warning; the caller's own fallback chain handles it at record time.
+     * Never serialized.
+     */
+    async declareRound(round, calls) {
+        /*
+         * Independent digests run concurrently — declaration gates dispatch of
+         * the whole batch, so serial awaits would add one hash latency per call
+         * to every round. Failures are per-call and fail open, as before.
+         */
+        const hashed = await Promise.all(calls.map(async (call) => {
+            try {
+                return {
+                    call,
+                    fingerprint: await this.fingerprintOnce(call.toolName, call.keyMaterial),
+                };
+            }
+            catch (error) {
+                // Unhashable: leave it out of the declared set — recordToolCall's
+                // fallback chain decides this call's identity on its own — but say
+                // so, like every other fail-open path: a direct consumer debugging
+                // an unexpectedly incomplete declaration needs the tool name and
+                // cause. (The engine warns separately on its own declaration path.)
+                console.warn(`[DoomLoop] could not fingerprint a "${call.toolName}" call while declaring round ` +
+                    `${round}; excluding it from the round set:`, error);
+                return null;
+            }
+        }));
+        /* Accumulate per tool, dedupe and sort ONCE per set — not per member. */
+        const collected = new Map();
+        for (const entry of hashed) {
+            if (entry === null) {
+                continue;
+            }
+            const set = collected.get(entry.call.toolName) ?? new Set();
+            set.add(entry.fingerprint);
+            collected.set(entry.call.toolName, set);
+        }
+        const fingerprints = new Map();
+        for (const [toolName, set] of collected) {
+            fingerprints.set(toolName, [
+                ...set,
+            ].sort());
+        }
+        this.declaredRound = {
+            round,
+            fingerprints,
+        };
+    }
+    async fingerprintOnce(toolName, keyMaterial) {
+        const memoizable = typeof keyMaterial === 'object' && keyMaterial !== null;
+        if (memoizable) {
+            // Keyed by object AND tool name: the tool name participates in the
+            // hash, so one arguments object used by two tools must not collide.
+            const hit = this.fingerprintMemo.get(keyMaterial)?.get(toolName);
+            if (hit !== undefined) {
+                return hit;
+            }
+        }
+        const fingerprint = await fingerprintToolCall(toolName, keyMaterial);
+        if (memoizable) {
+            const perTool = this.fingerprintMemo.get(keyMaterial) ?? new Map();
+            perTool.set(toolName, fingerprint);
+            this.fingerprintMemo.set(keyMaterial, perTool);
+        }
+        return fingerprint;
+    }
+    /**
+     * True when the escalate rung can still fire: a mechanism is configured
+     * and the budget is not exhausted.
+     */
+    canEscalate() {
+        return (this.config.escalation !== null &&
+            this.escalationsUsed < this.config.escalation.maxEscalations);
+    }
+    /**
+     * Consume one escalation from the budget. The ENGINE calls this when it
+     * actually applies the recovery (model swap / advisor forcing) — not at
+     * verdict time, so a verdict the engine ends up not honoring (e.g. a hook
+     * override) does not burn budget.
+     */
+    consumeEscalation() {
+        this.escalationsUsed++;
+    }
+    /**
+     * Snapshot the serializable detector state (deep copy). Round markers are
+     * deliberately dropped: rounds are meaningful only within one run.
+     * `stopVerdict`/`pendingSteer` are owned by the engine, which merges them
+     * into the persisted blob alongside this snapshot.
+     */
+    getState() {
+        return {
+            // Object.fromEntries defines OWN properties (CreateDataProperty), so
+            // even a tool named "__proto__" lands as plain data, not a setter hit.
+            tools: Object.fromEntries(Array.from(this.tools, ([name, entry]) => [
+                name,
+                {
+                    fingerprint: entry.fingerprint,
+                    streak: entry.streak,
+                    /*
+                     * A multi-call round persists its full set, so a resumed run knows
+                     * WHICH set earned the count. Without it, the streak either
+                     * attached to one arbitrary member — a resumed round of just that
+                     * call inherited a fan-out's whole evidence and could be refused
+                     * on its first appearance — or had to be discarded at every save,
+                     * which reset condemned fan-outs across approval pauses and made
+                     * per-turn-resume topologies never accumulate. Single-call rounds
+                     * omit it: their fingerprint fully describes the round.
+                     *
+                     * COPIED, not aliased: the in-memory array is shared with the live
+                     * streak entry (and, for declared rounds, with `declaredRound`
+                     * itself), and the snapshot is handed to the caller's
+                     * StateAccessor. An in-place mutation of the saved blob must not
+                     * corrupt the detector still running against it.
+                     */
+                    ...((entry.roundFingerprints?.length ?? 0) > 1
+                        ? {
+                            roundFingerprints: [
+                                ...entry.roundFingerprints,
+                            ],
+                        }
+                        : {}),
+                    /*
+                     * Per-call counts persist so a repeat spanning a save/resume
+                     * boundary keeps counting. Copied for the same isolation reason
+                     * as the set above. `fromEntries` for the same "__proto__" safety
+                     * as the outer record. Omitted only when `fingerprint`+`streak`
+                     * already carry the identical information (a single-call round
+                     * whose per-call count equals its round count — `restore`
+                     * reconstructs exactly that). The count-mismatch check matters:
+                     * when a round SHRINKS to one call, the round streak resets while
+                     * the per-call count keeps climbing, and dropping it would hand
+                     * the repeat a fresh grace window on resume.
+                     */
+                    ...(entry.callStreaks !== undefined && !callStreaksReconstructible(entry)
+                        ? {
+                            callStreaks: Object.fromEntries(Object.entries(entry.callStreaks)),
+                        }
+                        : {}),
+                },
+            ])),
+            ...(this.text && {
+                text: {
+                    fingerprint: this.text.fingerprint,
+                    streak: this.text.streak,
+                },
+            }),
+            ...(this.escalationsUsed > 0 && {
+                escalationsUsed: this.escalationsUsed,
+            }),
+        };
+    }
+    /**
+     * Restore persisted state (from `ConversationState.doomLoop`). Invalid
+     * blobs are ignored with a warning — a corrupt detector state must never
+     * take down a resumed run. Engine-owned fields (`stopVerdict`,
+     * `pendingSteer`) are ignored here; the engine restores them itself.
+     */
+    restore(state) {
+        if (typeof state !== 'object' || state === null || Array.isArray(state)) {
+            console.warn('[DoomLoop] Ignoring invalid persisted doom-loop state');
+            return;
+        }
+        const candidate = state;
+        const tools = new Map();
+        if (typeof candidate.tools === 'object' && candidate.tools !== null) {
+            for (const [name, entry] of Object.entries(candidate.tools)) {
+                if (isValidStreak(entry)) {
+                    tools.set(name, restoreStreakEntry(entry));
+                }
+            }
+        }
+        this.tools = tools;
+        this.text = isValidStreak(candidate.text)
+            ? {
+                fingerprint: candidate.text.fingerprint,
+                streak: candidate.text.streak,
+            }
+            : undefined;
+        this.escalationsUsed =
+            typeof candidate.escalationsUsed === 'number' &&
+                Number.isFinite(candidate.escalationsUsed) &&
+                candidate.escalationsUsed >= 0
+                ? Math.floor(candidate.escalationsUsed)
+                : 0;
+    }
+    /**
+     * Record one tool call and return the streak record plus any verdict.
+     *
+     * Streak semantics:
+     * - Per tool: interleaved calls to *other* tools do not reset a tool's
+     *   streak (so `search X, read file, search X, read file` still trips).
+     * - Per round: the same `(tool, fingerprint)` recorded again in the SAME
+     *   `round` is a duplicate — the streak does not increment
+     *   (`duplicateInRound: true`) and the caller should reuse the decision it
+     *   applied for the first occurrence. A streak measures the model
+     *   re-issuing a call *after seeing its result*, which requires a round
+     *   trip; N parallel identical calls in one turn are one piece of
+     *   evidence, not N.
+     * - A round's identity is the *set* of fingerprints the tool was called
+     *   with, not its last call, so a fan-out of distinct arguments reissued
+     *   verbatim accumulates. A round whose set differs from the previous
+     *   round's — in either direction, including a superset — resets to 1.
+     *   Every call in a round reports that round's streak, so the ladder
+     *   applies to the round as a unit. See {@link declareRound}: the set must
+     *   be declared before the round's first call for this to hold for
+     *   multi-call rounds.
+     *
+     * Blocked calls are recorded like any other — a model re-issuing a
+     * blocked call in a later round is stronger loop evidence, not progress.
+     *
+     * @throws Whatever {@link canonicalizeKeyMaterial} throws for unhashable
+     * key material. Callers (the engine) must catch and fall back — see
+     * `resolveLoopKeyMaterial` and the engine's fallback chain.
+     */
+    async recordToolCall(toolName, keyMaterial, round, options) {
+        const fingerprint = await this.fingerprintOnce(toolName, keyMaterial);
+        const previous = this.tools.get(toolName);
+        const isSameRound = previous?.round !== undefined && previous.round === round;
+        /*
+         * The round's declared membership, when the engine announced it (see
+         * `declareRound`). A declaration only speaks for the calls it contains: a
+         * call dropped as unhashable still records here via the caller's fallback
+         * chain, but as a NON-member — it cannot inherit or move the ROUND's
+         * counters. Its own repetition still counts: the per-call detector below
+         * needs no declaration, so a fallback-identity call reissued verbatim
+         * every round accumulates like any other repeat.
+         */
+        const declared = this.declaredRound?.round === round
+            ? this.declaredRound.fingerprints.get(toolName)
+            : undefined;
+        const declaredMember = declared?.includes(fingerprint) === true;
+        const seen = isSameRound ? (previous?.seenThisRound ?? EMPTY_SEEN) : EMPTY_SEEN;
+        const duplicateInRound = seen.has(fingerprint);
+        /*
+         * The baseline every call of this round is measured against: the set the
+         * PREVIOUS round was called with and the streak it earned. Fixed at the
+         * round transition and carried unchanged for the round's length, so
+         * arrival order within a round can never affect a score.
+         */
+        const priorSet = isSameRound
+            ? previous?.priorRoundFingerprints
+            : (previous?.roundFingerprints ??
+                (previous
+                    ? [
+                        previous.fingerprint,
+                    ]
+                    : undefined));
+        const priorStreak = isSameRound ? (previous?.priorStreak ?? 0) : (previous?.streak ?? 0);
+        const score = (set) => priorSet !== undefined && setsMatch(priorSet, set) ? priorStreak + 1 : 1;
+        /*
+         * PER-CALL evidence, alongside the round-set streak: the number of
+         * consecutive rounds THIS exact fingerprint has been issued in, whatever
+         * its round-mates did. Round identity treats any membership change as
+         * progress, which is right for the fan-out as a unit but blind to one
+         * call repeating inside varying company (`[a,b]`, `[a,c]`, `[a,d]` — the
+         * set differs every round, yet `a` is a 3-peat) and to a paused HITL
+         * member changing the resumed round's identity. The per-call count sees
+         * exactly those. Baseline fixed at the round transition, like the set
+         * baseline, so arrival order cannot affect it.
+         */
+        const priorCallStreaks = isSameRound
+            ? (previous?.priorCallStreaks ?? {})
+            : (previous?.callStreaks ?? {});
+        const callStreak = (Object.hasOwn(priorCallStreaks, fingerprint)
+            ? priorCallStreaks[fingerprint]
+            : 0) + 1;
+        /*
+         * Two identities, one scoring rule.
+         *
+         * What this CALL reports: the declared set when it is a member (every
+         * member of a repeating fan-out shares the round's streak, so the ladder
+         * applies to the round as a unit), its own singleton otherwise. On the
+         * undeclared path the singleton comparison is the pre-fan-out per-call
+         * semantics for single-call rounds; for undeclared MULTI-call rounds it
+         * accumulates only on whichever call lands last (see the README limit).
+         *
+         * What the ROUND stores: the declared set when there is one — a
+         * non-member must not overwrite the round's identity with its singleton,
+         * or the next round's members would compare against it and reset forever.
+         */
+        const callSet = declaredMember
+            ? declared
+            : [
+                fingerprint,
+            ];
+        const streak = score(callSet);
+        const roundSet = declared ?? [
+            fingerprint,
+        ];
+        this.tools.set(toolName, {
+            /*
+             * The identity that pairs with `streak` in persisted state: a non-member
+             * must not become it, or the saved count would attach to a call that
+             * never earned it (blocked on first appearance after a resume, while the
+             * real repeat lost its evidence).
+             */
+            fingerprint: declared !== undefined && !declaredMember && previous !== undefined
+                ? previous.fingerprint
+                : fingerprint,
+            round,
+            /*
+             * Grown in place, O(1) per record: run-local, never serialized, and only
+             * the latest entry's set is ever read, so sharing the object between the
+             * previous and next entry is fine. The shared EMPTY_SEEN sentinel is the
+             * one instance that must never be mutated.
+             */
+            seenThisRound: seen === EMPTY_SEEN
+                ? new Set([
+                    fingerprint,
+                ])
+                : seen.add(fingerprint),
+            roundFingerprints: roundSet,
+            streak: score(roundSet),
+            ...(priorSet !== undefined
+                ? {
+                    priorRoundFingerprints: priorSet,
+                }
+                : {}),
+            priorStreak,
+            priorCallStreaks,
+            callStreaks: growCallStreaks(isSameRound ? previous : undefined, fingerprint, callStreak),
+        });
+        /*
+         * The stronger of the two detectors decides. The round streak covers the
+         * reissued fan-out as a unit; the per-call streak covers a repeat whose
+         * round-mates keep changing. For an exactly-repeating round both counts
+         * are equal, so nothing double-fires — the counts only diverge when one
+         * detector sees something the other cannot.
+         */
+        const effectiveStreak = Math.max(streak, callStreak);
+        const allowBlock = options?.allowBlock ?? true;
+        const action = resolveLadderAction(this.config.ladder, effectiveStreak, {
+            allowBlock,
+            allowEscalate: this.canEscalate(),
+        });
+        if (!action) {
+            return {
+                fingerprint,
+                streak: effectiveStreak,
+                duplicateInRound,
+            };
+        }
+        return {
+            fingerprint,
+            streak: effectiveStreak,
+            duplicateInRound,
+            verdict: {
+                detector: options?.detector ?? 'tool-fingerprint',
+                action,
+                streak: effectiveStreak,
+                fingerprint,
+                toolName,
+                message: buildToolVerdictMessage({
+                    toolName,
+                    fingerprint,
+                    callSet,
+                    roundStreak: streak,
+                    callStreak,
+                    // An undeclared record's `callSet` is just this one call, which says
+                    // nothing about the round's real width — so it may not be described
+                    // as a set, nor have its fingerprint quoted as the round's identity.
+                    roundDeclared: declaredMember,
+                }),
+            },
+        };
+    }
+    /**
+     * Clear the cross-step text streak. Called by the engine when a late
+     * async-tool result is injected into the conversation: the run made
+     * observable forward progress, so a model that said "still waiting…"
+     * between deliveries must not accumulate a repetition streak toward a
+     * false-positive stop. Tool streaks are deliberately kept — re-issuing an
+     * identical tool call after a delivery is still loop evidence.
+     */
+    resetTextStreak() {
+        this.text = undefined;
+    }
+    /**
+     * Record one step's assistant text and return the strongest verdict from
+     * the two text detectors:
+     *
+     * - `text-repetition`: a token block repeating within THIS response; the
+     *   repeat count feeds the ladder directly, so a single response spinning
+     *   "I am stuck." dozens of times can stop the run immediately.
+     * - `text-streak`: byte-identical (whitespace-normalized) text across
+     *   consecutive steps. KNOWN LIMIT: paraphrased repetition does not trip.
+     *
+     * Empty/whitespace-only text (typical for tool-only turns) is a no-op:
+     * it neither counts nor resets the cross-step streak, mirroring how
+     * interleaved other-tool calls don't reset a tool streak.
+     */
+    async recordAssistantText(text) {
+        if (!this.config.text.enabled) {
+            return undefined;
+        }
+        const normalized = text.replace(/\s+/g, ' ').trim();
+        if (normalized.length === 0) {
+            return undefined;
+        }
+        let withinResponse;
+        const repetition = detectTextRepetition(normalized, this.config.text);
+        if (repetition) {
+            const action = resolveLadderAction(this.config.ladder, repetition.repeats, {
+                allowBlock: false,
+                allowEscalate: this.canEscalate(),
+            });
+            if (action) {
+                withinResponse = {
+                    detector: 'text-repetition',
+                    action,
+                    streak: repetition.repeats,
+                    fingerprint: await fingerprintKeyMaterial(repetition.sample),
+                    message: `Doom loop suspected: the response repeats "${repetition.sample}" ` +
+                        `${repetition.repeats} times in a row. Stop repeating and take a different approach.`,
+                };
+            }
+        }
+        const fingerprint = await fingerprintKeyMaterial(normalized);
+        const previous = this.text;
+        const streak = previous && previous.fingerprint === fingerprint ? previous.streak + 1 : 1;
+        this.text = {
+            fingerprint,
+            streak,
+        };
+        let crossStep;
+        const crossAction = resolveLadderAction(this.config.ladder, streak, {
+            allowBlock: false,
+            allowEscalate: this.canEscalate(),
+        });
+        if (crossAction) {
+            crossStep = {
+                detector: 'text-streak',
+                action: crossAction,
+                streak,
+                fingerprint,
+                message: `Doom loop suspected: the assistant produced identical text for ${streak} ` +
+                    'consecutive turns. Stop repeating and take a different approach.',
+            };
+        }
+        return strongerVerdict(withinResponse, crossStep);
+    }
+}
+const ACTION_STRENGTH = Object.freeze({
+    observe: 0,
+    steer: 1,
+    escalate: 2,
+    block: 3,
+    stop: 4,
+});
+function strongerVerdict(a, b) {
+    if (!a) {
+        return b;
+    }
+    if (!b) {
+        return a;
+    }
+    // Within-response wins ties: its message names the repeated block.
+    return ACTION_STRENGTH[b.action] > ACTION_STRENGTH[a.action] ? b : a;
+}
+//#endregion
+/**
+ * This round's per-call accumulator, grown in place — O(1) per record instead
+ * of an O(W) spread per call of a W-wide round. Safe because only the latest
+ * entry's object is ever read mid-round, and `priorCallStreaks` aliases the
+ * PREVIOUS round's object (a fresh object is created at each round
+ * transition), so mutating this round's accumulator never disturbs the
+ * baseline. getState() copies before persisting either.
+ */
+function growCallStreaks(previous, fingerprint, callStreak) {
+    if (previous?.callStreaks !== undefined) {
+        previous.callStreaks[fingerprint] = callStreak;
+        return previous.callStreaks;
+    }
+    return {
+        [fingerprint]: callStreak,
+    };
+}
+/**
+ * The empty seen-set, shared: `recordToolCall` runs per call, and most rounds
+ * open with no prior members — allocating a fresh empty Set for each would be
+ * churn for nothing. Never mutated (the write path copies before adding).
+ */
+const EMPTY_SEEN = new Set();
+/**
+ * Short, stable identity for a round's fingerprint set: the first members'
+ * prefixes, so every call of one round produces the same string (see the
+ * verdict message — steer dedupes on exact text).
+ */
+function summarizeRound(fingerprints) {
+    const shown = fingerprints.slice(0, 3).map((value) => value.slice(0, 8));
+    return fingerprints.length > 3
+        ? `${shown.join('+')}+${fingerprints.length - 3} more…`
+        : `${shown.join('+')}…`;
+}
+/** Set equality over two sorted fingerprint lists. */
+function setsMatch(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+/**
+ * Verdict text for a tool-fingerprint detection, naming what actually
+ * repeated. When the round streak decides (or ties), a multi-call round quotes
+ * the ROUND's identity — identical text for every call, deliberately, because
+ * the steer rung dedupes queued guidance by exact message text and one round
+ * of evidence must not queue N near-identical corrections. When the PER-CALL
+ * streak alone decides (its count exceeds the round's), the text carries
+ * neither the call's fingerprint nor its exact count: both vary between
+ * members of one round (an expanding fan-out holds counts 4, 3, 2 at once),
+ * and either would split one piece of guidance into per-member strings. The
+ * enforced bound is therefore at most TWO distinct messages per tool per
+ * round — one per-call text, one round-set text — each stating a distinct
+ * fact; exact counts live in the verdict payload's `streak`.
+ *
+ * `roundDeclared` says whether the detector was told the round's true
+ * membership. Only then does `callSet` describe the round, so only then may the
+ * text name a set or quote an argument fingerprint. On the UNDECLARED path
+ * (server-tool records, direct `DoomLoopMonitor` consumers, the SDK ports) each
+ * call is recorded alone, so `callSet` holds just that call however wide the
+ * round really was: the last-recorded call tied at `roundStreak == callStreak`
+ * and rendered the fingerprint-bearing single-call text while its round-mates
+ * rendered the per-call text — two strings for one round, which defeats the
+ * exact-text steer dedupe this shaping exists to preserve.
+ */
+function buildToolVerdictMessage(input) {
+    const { toolName, fingerprint, callSet, roundStreak, callStreak, roundDeclared } = input;
+    if (callStreak > roundStreak || !roundDeclared) {
+        /*
+         * Fingerprint-free AND count-free, so every per-call verdict of one tool
+         * renders byte-identical text and the steer dedupe collapses them to one
+         * correction. Reached when the per-call streak decides, and when the
+         * round's true membership is unknown (undeclared path). Both varying
+         * elements had to go for the dedupe to hold: quoting one call's hash
+         * diverged the members of a wide round, and quoting the exact count
+         * diverged members whose repeats started at different times (an expanding
+         * fan-out carries counts 4, 3, 2 in one round — three near-identical
+         * strings for one piece of guidance). The exact count still reaches
+         * consumers via the verdict payload's `streak`; the prose tells the model
+         * what to do about it, which does not depend on the number.
+         */
+        return (`Doom loop suspected: this exact "${toolName}" call has been repeated across ` +
+            'consecutive rounds. Repeating it will not change the result. ' +
+            'Take a different approach, or explain why repetition is required.');
+    }
+    if (callSet.length > 1) {
+        return (`Doom loop suspected: tool "${toolName}" was invoked in ${roundStreak} consecutive rounds ` +
+            `with the same set of ${callSet.length} parallel calls ` +
+            `(round identity ${summarizeRound(callSet)}). Reissuing the same fan-out ` +
+            'will not change the results. Take a different approach, or explain why repetition is required.');
+    }
+    return (`Doom loop suspected: tool "${toolName}" was invoked in ${roundStreak} consecutive rounds ` +
+        `with identical arguments (fingerprint ${fingerprint.slice(0, 16)}…). Repeating the call ` +
+        'will not change the result. Take a different approach, or explain why repetition is required.');
+}
+//# sourceMappingURL=doom-loop.js.map