Flush coalesced tool-failure audits on terminal paths

Author: TheGreatAxios

src/subagent/nudge-director.test.ts

@@ -209,6 +209,53 @@ describe("SubAgentDirector tool failure recovery", () => {
     expect(records).toEqual([{ id: "tool-failure-recovery", count: 2 }]);
   });
 
+  test("a single failed tool audit omits the count field", async () => {
+    const director = new SubAgentDirector("system", [], undefined, 30);
+    const caps = capabilities();
+    const records: { id: string; count: number | null }[] = [];
+    director.observeInterventions((event) => {
+      records.push({ id: event.id, count: event.count ?? null });
+    });
+
+    await director.decide(inferenceDone(["fail-a"]), state, caps);
+    await director.decide(toolDone("fail-a", true), state, caps);
+    await director.decide(inferenceDoneText(REPORT_ENVELOPE), state, caps);
+
+    expect(records).toEqual([{ id: "tool-failure-recovery", count: null }]);
+  });
+
+  test("flushes an undelivered recovery burst when the run goes terminal", 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 },
+      );
+    });
+
+    // ok-c stays pending so the armed recovery nudge never reaches an infer.
+    await director.decide(
+      inferenceDone(["fail-a", "fail-b", "ok-c"]),
+      state,
+      caps,
+    );
+    await director.decide(toolDone("fail-a", true), state, caps);
+    await director.decide(toolDone("fail-b", true), state, caps);
+    expect(records).toEqual([]);
+
+    const result = actions(
+      await director.decide(inferenceDoneText(REPORT_ENVELOPE), state, caps),
+    );
+    expect(result).toContainEqual({
+      type: "checkpoint",
+      message: "subagent-complete",
+    });
+    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

@@ -325,6 +325,7 @@ export class SubAgentDirector extends DefaultDirector {
 
       if (stop === "complete") {
         this.reportReplied = true;
+        this.flushToolFailureRecoveryAudit();
         const terminal: ReactorAction[] = [
           capabilities.checkpoint("subagent-complete"),
           capabilities.reply(lastText(content)),
@@ -384,6 +385,7 @@ export class SubAgentDirector extends DefaultDirector {
         });
         this.onForcedStop("incomplete-report");
         this.reportReplied = true;
+        this.flushToolFailureRecoveryAudit();
         const terminal: ReactorAction[] = [
           capabilities.checkpoint("subagent-incomplete-report"),
           capabilities.reply(
@@ -480,6 +482,7 @@ export class SubAgentDirector extends DefaultDirector {
     });
     this.onForcedStop("stalled");
     this.reportReplied = true;
+    this.flushToolFailureRecoveryAudit();
     const terminal: ReactorAction[] = [
       capabilities.checkpoint("subagent-stalled"),
       capabilities.reply(
@@ -492,6 +495,25 @@ export class SubAgentDirector extends DefaultDirector {
     return terminal;
   }
 
+  /**
+   * Write the coalesced tool-failure-recovery audit once the burst ends —
+   * when the armed nudge lands on an infer, or when the run goes terminal
+   * (complete / forced stop / stalled) with the nudge still undelivered.
+   * Without the terminal-path flush a burst that is never followed by an
+   * infer would vanish from the audit trail entirely.
+   */
+  private flushToolFailureRecoveryAudit(): void {
+    if (this.pendingToolFailureRecoveryCount === 0) return;
+    const count = this.pendingToolFailureRecoveryCount;
+    this.pendingToolFailureRecoveryCount = 0;
+    this.interventions({
+      id: "tool-failure-recovery",
+      class: "nudge",
+      ...(count > 1 ? { count } : {}),
+      state: this.interventionState(),
+    });
+  }
+
   /**
    * Rewrite the infer action in a fall-through actions batch to carry the
    * armed nudge, once — this matches the infer after report-forced or
@@ -507,15 +529,7 @@ 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;
-    }
+    this.flushToolFailureRecoveryAudit();
     const existing = actions[inferIndex] as Extract<
       ReactorAction,
       { type: "infer" }