docs(tui): state and pin the bounded ask_director stall policy

Author: bwachman

src/tui/stall-watchdog.test.ts

@@ -182,6 +182,53 @@ describe("shouldAbortForStall — execution-watchdog-exempt tools do not pin for
     ).toBe(true);
   });
 
+  // ask_director is bounded, not exempt (CL-10206): the primary never mounts
+  // it, so the name is a guard, and a stray mount must notice, then abort,
+  // like wait_agents. Both shapes the turn state can hold are pinned: the
+  // announced call, and a leftover tracked only per-id after a sibling
+  // cleared currentToolName and the shared callIdByName slot.
+  test.each([
+    {
+      representation: "direct",
+      currentToolName: "ask_director",
+      activeToolCalls: ["ask-1"],
+      callIdByName: { ask_director: "ask-1" },
+      callNameById: { "ask-1": "ask_director" },
+    },
+    {
+      representation: "mapping-only",
+      currentToolName: null,
+      activeToolCalls: ["ask-1"],
+      callIdByName: {},
+      callNameById: { "ask-1": "ask_director" },
+    },
+  ])(
+    "in-flight ask_director ($representation) is quiet, then notices, then aborts, and every surface agrees",
+    (ask) => {
+      const inFlightAsk = {
+        ...collect,
+        ...ask,
+        streamingType: "tool" as const,
+        stallNoticeMs: STALL_NOTICE_MS,
+        repeating: false,
+      };
+      const points = [
+        { nowMs: STALL_NOTICE_MS - 1, level: "quiet" },
+        { nowMs: STALL_NOTICE_MS, level: "notice" },
+        { nowMs: STALL_TIMEOUT_MS - 1, level: "notice" },
+        { nowMs: STALL_TIMEOUT_MS, level: "abort" },
+      ] as const;
+
+      for (const { nowMs, level } of points) {
+        const args = { ...inFlightAsk, nowMs };
+        expect(stallLevel(args)).toBe(level);
+        expect(shouldAbortForStall(args)).toBe(level === "abort");
+        expect(shouldNoticeStall(args)).toBe(level === "notice");
+        expect(isStalledForDisplay(args)).toBe(level !== "quiet");
+      }
+    },
+  );
+
   // tool.done of a sibling bash clears currentToolName and streamingType
   // while wait_agents is still in activeToolCalls. Keying only the last
   // name would leave that poll unbounded forever.

src/tui/stall-watchdog.ts

@@ -49,10 +49,13 @@ function silentPastThreshold(
   // sub-agent's tool call finishes, even while siblings are still running.
   // Outstanding calls mean the run is not silent, regardless of that flag.
   if (args.awaitingResponse && args.activeToolCalls.length === 0) return true;
-  // Execution-watchdog-exempt polls (collect, wait_agents, ask_director) emit
-  // no parent stream events. That must not pin the stall clock forever: they
-  // have no other wall-clock bound, so the stall budget is the backstop.
-  // TUI primary does not mount wait_agents; the name is kept so a stray mount cannot pin the clock.
+  // Policy: an in-flight wait_agents or ask_director is stall-bounded, never
+  // exempt. The TUI primary mounts neither (wait_agents is mount-gated off and
+  // ask_director exists only in worker loops), so both names are defensive
+  // guards that keep a stray mount from pinning the clock. A worker's parked
+  // ask is bounded elsewhere: an unanswered ask expires after ASK_DEADLINE_MS
+  // via expireStaleAsks, and the director's silent ask-wake turn is aborted by
+  // this watchdog via abortStalledWakeTurn, which re-surfaces the question.
   if (isStallBoundedInFlightTool(args) && args.isProcessing) return true;
   // Mid-stream hang: model stream stalled after first token. Ordinary in-flight
   // tool runs still do not emit parent stream events; leave those to the
@@ -79,6 +82,7 @@ function isStallBoundedToolName(name: string | null | undefined): boolean {
   return isSameTool(name, "wait_agents") || isSameTool(name, "ask_director");
 }
 
+/** Why these names are bounded guards, not exemptions: see `silentPastThreshold`. */
 function isStallBoundedInFlightTool(args: ShouldAbortForStallArgs): boolean {
   if (isStallBoundedToolName(args.currentToolName)) return true;
   for (const [name, id] of Object.entries(args.callIdByName)) {