Coalesce consecutive tool-failure recovery audits into one count

Several failed tool.done events before the pending recovery nudge is
consumed were each writing a separate intervention line. Keep the
recovery nudge text and arming behavior the same, but count the burst
in director memory and flush a single record with count when the nudge
is applied. Forensics treats missing count as one.

Author: TheGreatAxios

scripts/intervention-forensics.ts

@@ -151,15 +151,19 @@ for (const file of files) {
       bucket = emptyBucket();
       buckets.set(key, bucket);
     }
-    bucket.count++;
+    const occurrence = record.count ?? 1;
+    bucket.count += occurrence;
     const family = record.family ?? record.model ?? "unknown";
-    bucket.byFamily.set(family, (bucket.byFamily.get(family) ?? 0) + 1);
+    bucket.byFamily.set(
+      family,
+      (bucket.byFamily.get(family) ?? 0) + occurrence,
+    );
     const model = record.model ?? "unknown";
-    bucket.byModel.set(model, (bucket.byModel.get(model) ?? 0) + 1);
+    bucket.byModel.set(model, (bucket.byModel.get(model) ?? 0) + occurrence);
     if (record.class === "stop" || record.class === "nudge") {
       interventionsByModel.set(
         model,
-        (interventionsByModel.get(model) ?? 0) + 1,
+        (interventionsByModel.get(model) ?? 0) + occurrence,
       );
     }
     if (record.measurement !== undefined) {

src/subagent/intervention-log.test.ts

@@ -76,6 +76,16 @@ describe("intervention log", () => {
     expect(records.map((r) => r.id)).toEqual(["report-forced", "turn-budget"]);
   });
 
+  test("preserves an optional coalesced count on the record", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "intervention-log-"));
+    const sink = createInterventionLog(dir, { role: "leaf" });
+    sink({ id: "tool-failure-recovery", class: "nudge", count: 3 });
+    await flush();
+
+    const [record] = await readRecords(dir);
+    expect(record?.count).toBe(3);
+  });
+
   test("a write failure never throws into the caller", async () => {
     const sink = createInterventionLog(
       join(tmpdir(), "intervention-log-missing-dir-xyz"),

src/subagent/intervention-log.ts

@@ -90,6 +90,12 @@ export interface InterventionRecord {
   };
   /** Free-form specifics, kept short (a looped window, a refused fingerprint). */
   detail?: string;
+  /**
+   * How many consecutive same-trigger audits this record represents. Present when
+   * the director coalesced a burst (e.g. several failed tool.done events before
+   * the pending recovery nudge was consumed) into one flush. Absent means one.
+   */
+  count?: number;
 }
 
 /** Fields every record from one run shares, supplied once at construction. */

src/subagent/nudge-director.test.ts

@@ -179,6 +179,36 @@ describe("SubAgentDirector tool failure recovery", () => {
     expect(texts?.[0]).toContain("report the blocker");
   });
 
+  test("coalesces consecutive failed tool audits into one counted intervention", async () => {
+    const director = new SubAgentDirector("system", [], undefined, 30);
+    const caps = capabilities();
+    const records: { id: string; count?: number }[] = [];
+    director.observeInterventions((event) => {
+      records.push(
+        event.count === undefined
+          ? { id: event.id }
+          : { id: event.id, count: event.count },
+      );
+    });
+
+    await director.decide(
+      inferenceDone(["fail-a", "fail-b", "ok-c"]),
+      state,
+      caps,
+    );
+    await director.decide(toolDone("fail-a", true), state, caps);
+    expect(records).toEqual([]);
+    await director.decide(toolDone("fail-b", true), state, caps);
+    expect(records).toEqual([]);
+
+    const texts = ephemeralTexts(
+      inferAction(await director.decide(toolDone("ok-c"), state, caps)),
+    );
+    expect(texts).toHaveLength(1);
+    expect(texts?.[0]).toContain("A tool call failed");
+    expect(records).toEqual([{ id: "tool-failure-recovery", count: 2 }]);
+  });
+
   test("successful tool result has no ephemeral recovery turn", async () => {
     const director = new SubAgentDirector("system", [], undefined, 30);
     const caps = capabilities();

src/subagent/nudge-director.ts

@@ -132,6 +132,10 @@ export class SubAgentDirector extends DefaultDirector {
   // overflow compact (interceptOverflow re-arms from lastConsumedNudgeText if
   // the infer that consumed pending never completed).
   private pendingNudgeText: string | null = null;
+  // How many consecutive failed tool.done audits are waiting to be flushed as
+  // one tool-failure-recovery intervention when applyPendingNudge consumes the
+  // pending recovery nudge. Coalesces the audit trail without changing nudge text.
+  private pendingToolFailureRecoveryCount = 0;
   // The text applyPendingNudge last attached to a returned infer. Overflow of
   // that infer means the model never saw it, so interceptOverflow re-arms
   // pending from this when pending is still null. Cleared on a successful
@@ -402,13 +406,10 @@ export class SubAgentDirector extends DefaultDirector {
       this.lastActivityAt = this.now();
       this.consecutiveStalls = 0;
       if (event.result.isError === true) {
-        // Failed-tool recovery guidance.
+        // Failed-tool recovery guidance. Arm once; coalesce consecutive failure
+        // audits until applyPendingNudge flushes a single counted record.
         this.pendingNudgeText = TOOL_FAILURE_RECOVERY_NUDGE;
-        this.interventions({
-          id: "tool-failure-recovery",
-          class: "nudge",
-          state: this.interventionState(),
-        });
+        this.pendingToolFailureRecoveryCount += 1;
       }
     }
     const base = await super.decide(event, state, capabilities);
@@ -506,6 +507,15 @@ export class SubAgentDirector extends DefaultDirector {
     const text = this.pendingNudgeText;
     this.pendingNudgeText = null;
     this.lastConsumedNudgeText = text;
+    if (this.pendingToolFailureRecoveryCount > 0) {
+      this.interventions({
+        id: "tool-failure-recovery",
+        class: "nudge",
+        count: this.pendingToolFailureRecoveryCount,
+        state: this.interventionState(),
+      });
+      this.pendingToolFailureRecoveryCount = 0;
+    }
     const existing = actions[inferIndex] as Extract<
       ReactorAction,
       { type: "infer" }