fix(agent): detect a repeated same-tool fan-out

[LukasParke]

The gap

#73 keys a tool's streak on its last fingerprint (this.tools.get(toolName)), so a fan-out of distinct arguments reissued verbatim never accumulates evidence. Each round's first call has a different fingerprint than the previous round's last call, which resets the streak to 1 before the matching call arrives.

Measured against main before this change:

8 rounds x 3 distinct-arg calls (read a/b/c):  detections = 0
control, 1 call per round (read a):            none, observe, block, block

Zero detections across 24 calls the model had no business making. read(a), read(b), read(c) on repeat is the dominant shape in parallel-tool-calling agents, so this is the common case rather than an edge one.

Worth being precise about what #73 does handle: N identical calls fanned out in one round correctly count once (the duplicateInRound path, B3 in the remediation suite). The miss is specifically distinct arguments across a repeating round.

The fix

A round's identity for one tool is now the set of fingerprints it was called with, compared across rounds — not the last call.

The set is only complete once every call in the round has arrived, so a fan-out scores on the call that completes the match, and the round's earlier calls report the pre-match streak. That is deliberate: a partial fan-out genuinely is not yet a repeat.

r0: none, none, none
r1: none, none, observe     <- set matches r0 on the third call
r2: none, none, block

Ordering within the round does not matter (the set is sorted), a changed member resets the streak, and a strict subset is not a repeat.

Unchanged: single-call round timing, in-round duplicate collapsing, and verdict payload shape (same fields). Verdict message TEXT changed on two paths: undeclared records (server tools, direct monitor consumers) now render fingerprint-free per-call wording, and multi-call round verdicts quote the round's set identity — both deliberate, so calls carrying the same evidence produce byte-identical text and the steer dedupe holds. The persisted shape gains additive optional fields (roundFingerprints, callStreaks on DoomLoopStreak) so fan-out and per-call evidence survive save/resume; old blobs restore with their old semantics. Resumed single-call streaks behave exactly as before.

Tests

7 new tests in doom-loop-fanout.test.ts:

• accumulates across repeated fan-out rounds
• order-insensitive within a round
• resets when membership changes
• a strict subset is not a repeat
• single-call rounds behave exactly as before
• in-round duplicates still count once
• a resumed streak still increments after restore()

3 of the 7 fail without the fix — verified by stashing the change and re-running.

Verification

• vitest run (packages/agent): 685 passed at head (counts moved with main merges; all pre-existing doom-loop tests still pass)
• tsc --noEmit: clean (needed exactOptionalPropertyTypes care on the new optional fields)
• biome check: clean
• Changeset: minor (new public API: DoomLoopMonitor.declareRound, resolveDoomLoopOption, ResolvedDoomLoopConfig exports)

Context

Found while evaluating whether #73 supersedes the router-side port in openrouter-web#30170. It largely does — the ladder, escalation, text detectors, and in-loop stop are all things the router plugin cannot do from resolveEndpoints. This was the one axis where the router port was stronger, because the same gap was caught there in review and fixed by keying on a round fingerprint. Closing it here so the router can drop its duplicate and depend on the SDK.

Also verified while I was in here, no action needed: the two-tier fail-open in model-result.ts:1344 (raw-args fallback, then skip-detection) is correctly per-call, so one unhashable value cannot zero a whole request's detection.

One thing I did not change, flagging for a decision: the detector ignores tool results, so identical arguments with changing results reach block by round 3 — a polling tool returning running then done looks like a loop. loopKey: false is the intended exemption, but it is opt-out per tool rather than automatic. Folding a result digest into the round identity would make polling self-exempting; happy to follow up if you want that.

API example

For callModel users, doomLoop is configured exactly as before — what changed is when it fires:

import { callModel } from '@openrouter/agent';

const result = callModel(client, {
  model: 'z-ai/glm-5.2',
  input: 'Summarize these files.',
  tools: [readTool],
  // Unchanged config; ladder default is observe@2, block@3, stop@6.
  doomLoop: true,
});

// Model reissues the SAME three-call fan-out every round:
//   round 1: read(a), read(b), read(c)
//   round 2: read(a), read(b), read(c)   <- identical set
//
// was: no detection, ever — each round's first call reset the streak, so a
//      fan-out spun indefinitely while single calls tripped at round 2.
// now: round 2 -> streak 2 (observe), round 3 -> streak 3 (block), and EVERY
//      call of the round is refused at block, so the fan-out stops spending.
//
// A round that ADDS work is progress, and resets to 1:
//   round 3: read(a), read(b), read(c), read(d)   <- no verdict
//
// `loopKey` still runs exactly once per checked call. Persisted state gains
// one additive optional field so fan-out streaks survive save/resume.

API example — new public surface

This PR adds public API: DoomLoopMonitor.declareRound, plus resolveDoomLoopOption and ResolvedDoomLoopConfig exports (the monitor was previously exported without its config resolver, so it could not be constructed from the package at all). Consumer usage:

import { DoomLoopMonitor, resolveDoomLoopOption } from '@openrouter/agent';

// now: constructible from the public entrypoint (was: TS2345 / not exported)
const monitor = new DoomLoopMonitor(resolveDoomLoopOption(true));

for (const [round, batch] of batches.entries()) {
  // NEW: declare the round's complete set BEFORE recording any of its calls.
  // Undeclared multi-call rounds are scored per call and accumulate only on
  // the last-recorded member, order-dependently.
  await monitor.declareRound(
    round,
    batch.map((call) => ({ toolName: call.name, keyMaterial: call.arguments })),
  );
  for (const call of batch) {
    const { verdict } = await monitor.recordToolCall(call.name, call.arguments, round);
    if (verdict?.action === 'block') refuse(call, verdict.message);
  }
}

// State round-trips as plain JSON, so per-turn serverless topologies
// accumulate fan-out evidence across process boundaries.

Note on the implementation, since review

The first commit scored a round's fingerprint set as it accumulated, which
made a superset round transiently match its predecessor — blocking calls that
represented real progress, order-dependently. The engine now declares a round's
complete set before any of its calls is scored (declareRound). Subsequent
commits fixed fallout from that seam: streak sharing is scoped to declared
members, a non-member can no longer clobber the round's set, and loopKey runs
once per checked call. See the review threads for the full trail.

---

[cortex-github-agent]

Summary

Keys a tool's per-round doom-loop identity on the set of fingerprints seen in the round instead of the last call, which genuinely closes the repeated-fan-out gap. But because the set is compared after every call while the round is still filling, a round that is a strict superset of the previous round transiently matches it and can fire observe/block/stop on a call that represents real progress — order-dependently, and untested.

Findings (5)

🟠 major · packages/agent/src/lib/doom-loop.ts:994-998
Mid-round set comparison makes a superset round match the previous round transiently. With r0=[a,b], r1=[a,b], r2=[a,b,c], the b call of r2 sees set [a,b] == prior [a,b] and scores streak 3 -> block, so a legitimate call is refused via checkDoomLoopBeforeExecution/runToolWithHooks (model-result.ts) even though the round added new work. On main nothing fires. The behavior is also emission-order dependent (r2 emitted as [c,a,b] fires nothing), contradicting the PR's 'ordering within the round does not matter'. Expanding fan-outs ([a], [a,b], [a,b,c], …) likewise accumulate streaks they should not.

🟡 minor · packages/agent/tests/unit/doom-loop-fanout.test.ts:150-166
The suite tests the strict-subset direction ('a strict subset is not a repeat') but not the superset direction, which is the case that actually produces a verdict. Add [a,b], [a,b], [a,b,c] asserting no verdict on the middle call, plus an order-permuted variant of the same superset round.

🟡 minor · packages/agent/src/lib/doom-loop.ts:907-914
restore() sets priorStreak: entry.streak, but round is intentionally left undefined, so isSameRound can never be true on the first resumed record and that field is never read — dead state that suggests a semantic it does not have.

🟡 minor · packages/agent/src/lib/doom-loop.ts:1035-1041
Docs are now inconsistent with the implemented semantics: the recordToolCall docstring still states 'A different fingerprint for the same tool resets the streak to 1', the file-header 'Round-scoped streaks' bullet and DoomLoopVerdict.streak ('consecutive identical-fingerprint round count') describe last-call keying, and the verdict message tells the model the tool was invoked 'with identical arguments (fingerprint X…)' — false for a distinct-argument fan-out, where the quoted fingerprint is only the completing call. Since the module advertises itself as the cross-port spec, the round-set identity should also be stated for Python/Go ports.

1 more finding(s)

🟡 minor · packages/agent/src/lib/doom-loop.ts:992-998
At the block rung only the call that completes the set is refused; the other N-1 calls of a repeating fan-out still execute every round (they report the pre-match streak). Detection now works, but mitigation is partial until the stop rung is reached — worth documenting so users do not expect a blocked fan-out to stop spending.

[cortex-github-agent]

• Keep up to date — merge the base branch into this PR as it moves
• Merge when ready — GitHub auto-merges once its required checks and approvals pass

cortex review — 1d74522

✅ Security · ✅ Experience (DX · UX · A11y) · 💬 Performance (2)

Performance

🟡 minor · packages/agent/src/lib/doom-loop.ts:1155-1208
Persisted doom-loop state still duplicates each wide round's hashes. getState() emits both roundFingerprints and callStreaks; for a normally declared and fully recorded fan-out, every 64-character fingerprint in the former is repeated as a key in the latter. A width-100 round therefore adds roughly 13 KB of JSON string data before object/serialization overhead, and both structures are copied on every state snapshot. A compact representation using indices/references into one fingerprint collection would avoid the duplication.

🟡 minor · packages/agent/src/lib/doom-loop.ts:1291-1408
Wide fan-outs still incur quadratic scans and copying while calls are dispatched. For each of W calls, declared.includes, seen.includes, and setsMatch scan arrays up to width W; mergeFingerprint scans again and then copies/sorts the growing seenThisRound, while updating callStreaks spreads the growing record. Recording one W-wide declared round therefore remains O(W²) in work/allocation even though declaration itself deduplicates efficiently. Mutable Set/Map state for membership, seen calls, and counts would make dispatch bookkeeping approximately linear, with arrays/records materialized only for persistence.

_{Automatic first-pass review · updated in place on every push}

[LukasParke]

Re the design question (round-set scoring dominated by per-call scoring): your dominance analysis is correct for state this codebase writes, and I verified your ablation result independently — but the round detector is load-bearing for state it READS, so I recommend keeping it. Final call flagged to @LukasParke.

Your invariant-based argument holds: whenever declared members are all recorded, callStreak >= streak, so Math.max never selects the round count. I reproduced your Experiment 2 (per-call-only scoring passes the full suite).

The counter-example is a persisted blob that carries roundFingerprints without callStreaks — which OUR getState cannot emit, but the persisted shape is a cross-port conformance contract, and callStreaks is an optional field. A Python/Go port (or an older TS writer, or any hand-constructed state) that persists only the required fields plus roundFingerprints produces exactly this shape. Measured at head:

blob with roundFingerprints, callStreaks stripped; identical fan-out resumed:
  with round scoring (head):     3:block  3:block  3:block
  per-call only (your ablation): all members restart at 1 (restore synthesizes
                                 {fingerprint: streak} for ONE member only)

So collapsing to per-call scoring makes fan-out detection across process boundaries silently dependent on every state writer populating an optional field. The round detector is the reader-side guarantee that the required round identity keeps working.

On the invariant cost: agreed the declared-member invariant's teeth are the price. Two mitigations shipped since your review: the end-to-end callModel test now asserts the round-form verdict message on every detection — which is precisely the assertion that catches a mirroring regression (verified by injecting both breakage classes; the natural action/streak assertions passed under both, the message-form assertion fails both). And the failure mode under a missed mirror is now degradation to per-call detection rather than to nothing, which your own analysis shows covers every scenario the suite pins.

Minor items from your review: PR body's "753 passed" and "Changeset: patch" were stale and are fixed (685 at head, minor).

If the author prefers the simplification anyway, the right sequencing is: make callStreaks required in the persisted shape for multi-call rounds (a port-coordinated change), then collapse scoring — not the reverse.

[cortex-github-agent]

cortex panel verdict: comment — details in the consolidated review comment.

[devin-ai-integration]

Devin Review found 2 new potential issues.

[devin-ai-integration]

Devin Review found 2 new potential issues.

stale review