Bound leaf-progress backstop resets between operator messages

Author: TheGreatAxios

docs/ARCHITECTURE.md

@@ -148,7 +148,7 @@ Round 5 fixes the reset condition's shape instead of patching another instance:
 
 Because the operator explicitly wants long autonomous runs to keep going, reaching the backstop threshold (`TURNS_SINCE_USER_MESSAGE_BACKSTOP`, 100) does not pause on its own — it fires a one-shot nudge asking the model for a progress summary, the same ephemeral-turn rewrite mechanism as the check-in nudge. Only if that nudge goes unheeded — `turnsSinceUserMessage` advances a further full `TURNS_SINCE_USER_MESSAGE_BACKSTOP` turns with still no user message and no thrash detected — does the director hard-pause, with a distinct message ("Auto-paused: went N turns without a message from the operator, and a progress-summary nudge went unanswered for a further N turns...") tagged `toolOnlyPauseReason: "backstop"` to distinguish it from a thrash pause in logs and messages. A genuine cycle (thrash) still preempts this escalation at any point and pauses immediately, since that is a fast, unambiguous no-progress signal on its own.
 
-**Fleet-heavy work does not falsely trip this (CL-5893).** A primary that is productively blocked on many concurrent/sequential `task` dispatches racks up `turnsSinceUserMessage` at one tool.done→infer cycle per leaf, with no operator message in between — a successful leaf completion (`tool.done` for a `task` call, not a tool error, and no salvage-classifiable envelope in the report body) re-arms the interval exactly like a fresh operator message would (resetting `turnsSinceUserMessage` and clearing any pending backstop nudge) without being treated as one, so a productive multi-dispatch streak never hard-pauses no matter how many parent turns elapse. A failed or salvaged leaf completion earns no such credit, so true no-progress tool-only churn still nudges then pauses as above.
+**Fleet-heavy work does not falsely trip this (CL-5893).** A primary that is productively blocked on many concurrent/sequential `task` dispatches racks up `turnsSinceUserMessage` at one tool.done→infer cycle per leaf, with no operator message in between — a successful leaf completion (`tool.done` for a `task` call, not a tool error, a string result body, and no salvage-classifiable envelope in the report) re-arms the interval exactly like a fresh operator message would (resetting `turnsSinceUserMessage` and clearing any pending backstop nudge) without being treated as one, so a productive multi-dispatch streak gets meaningfully more room before the backstop can fire. A failed or salvaged leaf completion earns no such credit, so true no-progress tool-only churn still nudges then pauses as above. This reset is bounded, not unlimited: it is capped at `MAX_LEAF_PROGRESS_BACKSTOP_RESETS` (5) leaf-credited resets between genuine operator messages, so an unbroken run of trivial always-succeeding leaf tasks still exhausts the cap and lets the ordinary nudge/pause escalation force an operator checkpoint.
 
 #### Sub-agent stall management
 

src/agent/director.test.ts

@@ -821,18 +821,71 @@ describe("ChatDirector tool-only loop protection", () => {
   // will see, so it must re-arm the backstop interval regardless of how many
   // parent turns (tool.done -> infer cycles) that takes in total.
   describe("CL-5893: successful leaf task completions re-arm the backstop", () => {
-    test("a productive streak of successful task completions never hard-pauses, however many parent turns elapse", async () => {
+    test("a back-to-back streak of successful task completions is bounded — the cap exhausts and the nudge/pause escalation eventually fires", async () => {
       const director = createChatDirector("system", [], {
         onTasksChange: () => {},
         provider: providerlessPolicy,
       });
       const capabilities = makeCapabilities();
 
-      let sawPauseOrNudge = false;
-      for (let i = 0; i < 300; i++) {
+      // Every success here lands one turn after the last reset, so the
+      // MAX_LEAF_PROGRESS_BACKSTOP_RESETS credits are consumed almost
+      // immediately (the worst case for the bound — a genuinely spaced-out
+      // fleet gets far more turns before exhausting the same cap). Once
+      // exhausted, successes stop resetting the interval and the ordinary
+      // nudge (at the 100-turn threshold) then pause (a further 100 turns
+      // unheeded) fire on schedule.
+      let nudgedAt: number | null = null;
+      let pausedAt: number | null = null;
+      for (let i = 0; i < 300 && pausedAt === null; i++) {
         const id = `task-ok-${i}`;
         await director.decide(taskTurn(id), mockState, capabilities);
         const result = actionsArray(await director.decide(taskDoneEvent(id), mockState, capabilities));
+        if (result.some((a) => a.type === "reply" && a.content.includes("Auto-paused"))) {
+          pausedAt = i;
+        } else if (
+          nudgedAt === null &&
+          result.some((a) => a.type === "infer" && ephemeralText(a)?.includes("progress summary"))
+        ) {
+          nudgedAt = i;
+        }
+      }
+
+      expect(nudgedAt).not.toBeNull();
+      expect(pausedAt).not.toBeNull();
+      // A runaway trivial-success loop still pauses — it just gets the cap's
+      // worth of extra headroom first, well past the plain 100-turn
+      // threshold, before the escalation is forced.
+      expect(pausedAt as number).toBeGreaterThan(150);
+    });
+
+    test("an operator message re-arms the full leaf-progress cap", async () => {
+      const director = createChatDirector("system", [], {
+        onTasksChange: () => {},
+        provider: providerlessPolicy,
+      });
+      const capabilities = makeCapabilities();
+
+      // Exhaust the cap with MAX_LEAF_PROGRESS_BACKSTOP_RESETS (5) successes.
+      for (let i = 0; i < 5; i++) {
+        const id = `task-ok-a-${i}`;
+        await director.decide(taskTurn(id), mockState, capabilities);
+        await director.decide(taskDoneEvent(id), mockState, capabilities);
+      }
+
+      await director.decide(messageReceived(), mockState, capabilities);
+
+      // If the cap were not re-armed by the operator message, all 100 of
+      // these would get zero credit and turnsSinceUserMessage would climb
+      // straight to the 100-turn nudge threshold by the last iteration. With
+      // the cap re-armed, the first 5 are credited again (holding the
+      // interval near zero) and the remaining 95 only climb to 95 — no
+      // nudge or pause.
+      let sawPauseOrNudge = false;
+      for (let i = 0; i < 100; i++) {
+        const id = `task-ok-b-${i}`;
+        await director.decide(taskTurn(id), mockState, capabilities);
+        const result = actionsArray(await director.decide(taskDoneEvent(id), mockState, capabilities));
         if (
           result.some((a) => a.type === "reply" && a.content.includes("Auto-paused")) ||
           result.some((a) => a.type === "infer" && ephemeralText(a)?.includes("progress summary"))
@@ -843,6 +896,35 @@ describe("ChatDirector tool-only loop protection", () => {
       expect(sawPauseOrNudge).toBe(false);
     });
 
+    test("non-string tool result content gets no backstop credit — the backstop still nudges then pauses", async () => {
+      const director = createChatDirector("system", [], {
+        onTasksChange: () => {},
+        provider: providerlessPolicy,
+      });
+      const capabilities = makeCapabilities();
+
+      let nudged = false;
+      let paused = false;
+      for (let i = 0; i < 200 && !paused; i++) {
+        const id = `task-nonstring-${i}`;
+        await director.decide(taskTurn(id), mockState, capabilities);
+        const result = actionsArray(
+          await director.decide(
+            { type: "tool.done", result: { callId: id, isError: false, content: undefined } } as unknown as ReactorInboundEvent,
+            mockState,
+            capabilities,
+          ),
+        );
+        if (result.some((a) => a.type === "reply" && a.content.includes("Auto-paused"))) {
+          paused = true;
+        } else if (result.some((a) => a.type === "infer" && ephemeralText(a)?.includes("progress summary"))) {
+          nudged = true;
+        }
+      }
+      expect(nudged).toBe(true);
+      expect(paused).toBe(true);
+    });
+
     test("periodic successful task completions amid other tool-only turns keep resetting the backstop", async () => {
       const director = createChatDirector("system", [], {
         onTasksChange: () => {},

src/agent/director.ts

@@ -27,6 +27,7 @@ import {
   detectToolFingerprintThrash,
   detectTurnsSinceUserMessageBackstop,
   TURNS_SINCE_USER_MESSAGE_BACKSTOP,
+  MAX_LEAF_PROGRESS_BACKSTOP_RESETS,
   TOOL_FINGERPRINT_HISTORY_CAP,
   type ToolFingerprintThrashCheck,
 } from "../subagent/stop-policy.js";
@@ -431,6 +432,14 @@ class ChatDirectorImpl extends DefaultDirector {
   // is in effect (the next operator message clears both together).
   private backstopNudgeFiredAtTurn: number | null = null;
   private pendingBackstopNudge = false;
+  // CL-5893: how many times a successful leaf task completion has re-armed
+  // the backstop since the last genuine operator message. Capped at
+  // MAX_LEAF_PROGRESS_BACKSTOP_RESETS so an unbroken run of trivial
+  // always-succeeding leaf tasks cannot reset the backstop forever — once
+  // exhausted, leaf successes stop resetting the interval and the ordinary
+  // nudge/pause escalation proceeds. Reset to 0 only alongside the other
+  // operator-message resets below, never by the leaf-success path itself.
+  private leafProgressBackstopResets = 0;
   // Which mechanism triggered pausedForToolOnly — the period-detection fast
   // path (a recognized cycle) or the backstop escalation (nudge went
   // unheeded for a further full interval with no user message). Drives the
@@ -679,6 +688,7 @@ class ChatDirectorImpl extends DefaultDirector {
         this.turnsSinceUserMessage = 0;
         this.backstopNudgeFiredAtTurn = null;
         this.pendingBackstopNudge = false;
+        this.leafProgressBackstopResets = 0;
         this.salvageNudgeFired = false;
         this.pendingSalvageNudge = null;
         this.pendingTaskCallIds.clear();
@@ -869,10 +879,26 @@ class ChatDirectorImpl extends DefaultDirector {
       // which a completed task says nothing about) or salvageNudgeFired.
       // True no-progress (tool-only churn with no successful leaf completions)
       // still nudges then pauses exactly as before.
-      if (!event.result.isError && salvage === null) {
+      //
+      // Bounded (round 2): this reset is capped at
+      // MAX_LEAF_PROGRESS_BACKSTOP_RESETS per operator message so an
+      // unbroken loop of trivial always-succeeding leaf tasks cannot reset
+      // the backstop forever — once the cap is exhausted, leaf successes
+      // stop resetting the interval and the nudge/pause escalation
+      // eventually forces an operator checkpoint. Credit also requires the
+      // tool result content to actually be a string: non-string content is
+      // coerced to "" above only for salvage classification (an empty body
+      // classifies as success), which must not also buy backstop credit.
+      if (
+        !event.result.isError &&
+        salvage === null &&
+        typeof event.result.content === "string" &&
+        this.leafProgressBackstopResets < MAX_LEAF_PROGRESS_BACKSTOP_RESETS
+      ) {
         this.turnsSinceUserMessage = 0;
         this.backstopNudgeFiredAtTurn = null;
         this.pendingBackstopNudge = false;
+        this.leafProgressBackstopResets++;
       }
     }
 

src/subagent/stop-policy.ts

@@ -217,7 +217,9 @@ export function detectToolFingerprintThrash(
 // narration-sensitive counter. Model-emitted text does not reset this
 // counter; only a genuine user/operator message does (see director.ts). That
 // is deliberate: this answers "how long since the operator last saw a real
-// checkpoint," not "is the model narrating."
+// checkpoint," not "is the model narrating." (CL-5893: a successful leaf
+// task completion also resets it, bounded by MAX_LEAF_PROGRESS_BACKSTOP_RESETS
+// below — see director.ts.)
 //
 // Because narration no longer resets it, reaching this threshold does not
 // hard-pause on its own — it only fires a nudge asking for a progress
@@ -245,6 +247,16 @@ export function detectToolFingerprintThrash(
 // ever actually measured.
 export const TURNS_SINCE_USER_MESSAGE_BACKSTOP = 100;
 
+// CL-5893: cap on how many times a successful leaf task completion may
+// re-arm the backstop interval before a genuine operator message is
+// required. Without a cap, a loop of trivial always-succeeding leaf tasks
+// would reset the backstop forever and never force an operator checkpoint.
+// At 5 resets (~500 turns of headroom before this bound, vs. the plain
+// 100-turn threshold) a runaway trivial-success loop still nudges then
+// pauses, while genuine fleet-heavy work gets meaningfully more room than
+// the unbounded reset before this cap existed.
+export const MAX_LEAF_PROGRESS_BACKSTOP_RESETS = 5;
+
 /** True once turns-since-last-user-message reaches the backstop threshold. */
 export function detectTurnsSinceUserMessageBackstop(turnsSinceUserMessage: number): boolean {
   return turnsSinceUserMessage >= TURNS_SINCE_USER_MESSAGE_BACKSTOP;