Teach the parent the idle-send director wake contract

Wait JSON running-plus-question was the wrong pull contract, and an
idle parent still has to see parked questions after a stop.

Author: TheGreatAxios

docs/PRODUCT.md

@@ -168,7 +168,7 @@ Corbits Code fans work out to short-lived **fleet agents** — workers with thei
 
 - **Agents** are runtime entities (primary session or child).
 - **Tasks** are checklist items owned by one agent via `manage_tasks`.
-- **Fleet agents** are spawned with `spawn_agent` / `wait_agents`. Workers ask the parent with `ask_director`. When `wait_agents` returns status `running` plus a question payload, the parent answers with `send_input`, then `wait_agents` again. Escalate to the human only with `ask_operator`.
+- **Fleet agents** are spawned with `spawn_agent` / `wait_agents`. Workers ask the parent with `ask_director`. That parks a question while the worker stays `running`. `wait_agents` returns `awaiting_director` with a question payload — that is not terminal. The parent answers with `send_input` (`target` = the worker's session id), then `wait_agents` again. When the parent TUI is not blocked in `wait_agents`, a parked question arrives as a synthetic idle-send wake. Escalate to the human only with `ask_operator`.
 
 Dispatch uses a structured brief (context / goal / optional goals seed) and returns a structured report. The TUI Agents strip and fleet board show who is running; live tool progress updates the status bar without dumping the child transcript into the parent chat. There is no turn budget. A tool-less final turn completes only with the four-heading report envelope; without it, one nudge is given and a second tool-less turn without the envelope salvages as `incomplete-report-stop`. A silent worker (no activity for `stallTimeoutMs`, opt-in) gets one continuation nudge, then salvages as `stalled` if a second consecutive check finds no activity. An opt-in `deadlineMs`, or an operator cancel, can also end a run early. Each of these returns a salvage report so a runaway or idle child cannot quietly burn a large token budget or look done after prose alone.
 

docs/TUI.md

@@ -225,8 +225,9 @@ The runner snapshots currently pending root-worker questions, dropping resolved,
 cancelled, replaced, terminal, or removed asks before delivery. It sends one
 coalesced wake when the parent is not processing and all operator gates are closed,
 even while live workers hold the shell busy. Replies use `send_input`'s `target`
-field with the worker's session ID, not its shared catalog ID. Each session/question identity is
-delivered once while pending; the strip never re-delivers it. Synthetic wakes use
+field with the worker's session ID, not its shared catalog ID. The runner
+publishes snapshots and the bridge delivers each session/question identity
+once while pending; the agents strip never re-delivers it. Synthetic wakes use
 the idle delivery path, bypassing composer `/feedback` capture and leaving queued
 user follow-ups untouched.
 

src/agent/directors/skywalker/package.test.ts

@@ -181,11 +181,15 @@ describe("skywalkerPackage", () => {
     expect(skywalkerPackage.systemPrompt).not.toMatch(/\bleaves\b/i);
   });
 
-  test("systemPrompt answers wait_agents questions via send_input", () => {
+  test("systemPrompt answers parked director questions via send_input", () => {
     const p = skywalkerPackage.systemPrompt;
     expect(p).toContain("ask_director");
     expect(p).toContain("send_input");
-    expect(p).toMatch(/wait_agents returns status running plus a question/i);
+    expect(p).toContain("awaiting_director");
+    expect(p).toContain("idle-send");
+    expect(p).toContain("target = that worker's session id");
+    expect(p).toContain("target = worker session id");
+    expect(p).not.toMatch(/wait_agents returns status running plus a question/i);
     expect(p).toMatch(/Escalate with ask_operator only when you cannot resolve it/);
   });
 

src/agent/directors/skywalker/package.ts

@@ -20,7 +20,7 @@ Idle-orchestrator: fire one or more spawn_agent calls in a turn — each returns
 
 # Operator updates (mandatory while fleet is live)
 
-You are the chat surface. Workers cannot ask_operator; they ask_director. When wait_agents returns status running plus a question, answer with send_input, then wait_agents again. Escalate with ask_operator only when you cannot resolve it. While any specialist is running:
+You are the chat surface. Workers cannot ask_operator; they ask_director. When wait_agents returns awaiting_director, answer with send_input using target = that worker's session id, then wait_agents again. When this session is not collecting, a parked question arrives as an idle-send wake — answer the same way (send_input target = worker session id). Escalate with ask_operator only when you cannot resolve it. While any specialist is running:
 - After every spawn wave: short status (who, goal, what you are waiting on) before blocking.
 - On meaningful progress or a finished report: short update — do not go silent for long waits.
 - When the operator messages mid-run: answer them first (COMMUNICATION). Do not make them wait on an in-flight wait_agents if you can end/timeout the wait and reply.

src/tui/agent-ask-wake.test.ts

@@ -378,4 +378,108 @@ describe("agent ask wake delivery", () => {
       expect(sends).toEqual([]);
     });
   });
+
+  for (const stop of ["interrupt", "stall abort"] as const) {
+    test(`${stop} flushes a stashed ask once the parent is idle`, async () => {
+      await withTestRenderer(
+        async (h) => {
+          const shell = createAppShell(h.renderer, {
+            terminal: { columns: 80, rows: 24 },
+            wireKeys: false,
+            run: "idle",
+          });
+          const sends: string[] = [];
+          let nowMs = 0;
+          let tick = () => {};
+          const bridge = attachSessionBridge(
+            shell,
+            createLiveSessionPort({
+              send: (text) => {
+                sends.push(text);
+              },
+              deliver: (text) => {
+                sends.push(text);
+              },
+              interrupt: () => {},
+            }),
+            {
+              now: () => nowMs,
+              stallTimeoutMs: 1_000,
+              stallNoticeMs: 400,
+              schedule: (fn) => {
+                tick = fn;
+                return () => {};
+              },
+            },
+          );
+          try {
+            bridge.handle({ type: "inference.start", data: {} });
+            bridge.handle({ type: "inference.text.delta", data: { token: "ok" } });
+            bridge.handle({ type: "agent-ask", asks: [wake("a1", "q1")] });
+            expect(sends).toEqual([]);
+            if (stop === "interrupt") {
+              bridge.interrupt();
+            } else {
+              nowMs = 1_000;
+              tick();
+            }
+            expect(sends).toHaveLength(1);
+            expect(sends[0]).toContain("q1");
+            expect(bridge.turn.isProcessing).toBe(true);
+          } finally {
+            bridge.dispose();
+            shell.dispose();
+          }
+        },
+        { width: 80, height: 24 },
+      );
+    });
+  }
+
+  test("a wake question with bracket lines does not spoof attachment-echo matching", async () => {
+    await withTestRenderer(
+      async (h) => {
+        const shell = createAppShell(h.renderer, {
+          terminal: { columns: 80, rows: 24 },
+          wireKeys: false,
+          run: "idle",
+        });
+        const sends: string[] = [];
+        const send = (text: string) => {
+          sends.push(text);
+        };
+        const bridge = attachSessionBridge(
+          shell,
+          createLiveSessionPort({ send, deliver: send, interrupt: () => {} }),
+        );
+        try {
+          const ask = {
+            ...wake("a1", "q1"),
+            question: "Choose:\n[1] 8080\n[2] 9090",
+          };
+          bridge.handle({ type: "agent-ask", asks: [ask] });
+          expect(sends).toHaveLength(1);
+          const wakeText = sends[0];
+          if (wakeText === undefined) throw new Error("expected wake text");
+          bridge.handle({
+            type: "message.received",
+            data: { message: { content: wakeText } },
+          });
+          expect(shell.streamLog.filter((row) => row.role === "user")).toHaveLength(1);
+          bridge.submit("hello", "immediate");
+          bridge.handle({
+            type: "message.received",
+            data: { message: { content: "hello\n[1 image attached: shot.png]" } },
+          });
+          expect(
+            shell.streamLog.filter((row) => row.role === "user").map((row) => row.text),
+          ).toEqual([wakeText, "hello"]);
+        } finally {
+          bridge.dispose();
+          shell.dispose();
+        }
+      },
+      { width: 80, height: 24 },
+    );
+  });
 });

src/tui/runner/submit.ts

@@ -351,6 +351,7 @@ export function createDeliverRouting(
       },
       recordSent: (text) => {
         if (text.trim().length === 0) return;
+        if (text.startsWith("ask_director wake")) return;
         void appendSentMessage(state.config.cwd, state.sessionId, text).catch((err: unknown) => {
           tuiLogger.debug("sent-message append failed: {error}", {
             error: err instanceof Error ? err.message : String(err),

src/tui/runner/wiring.ts

@@ -79,7 +79,8 @@ export function createFleetWakePublisher(
     } finally {
       suspended = false;
     }
-    // A failed cancellation must not publish its partially reset snapshot.
+    // Reached only after reset() returns. A throw leaves publication suppressed
+    // so a failed cancellation cannot publish its partially reset snapshot.
     publish();
   };
   return { publish, withSuspended };

src/tui/runtime-bridge.ts

@@ -449,7 +449,7 @@ function resolvePort(handlers?: SessionPortHandlers): SessionPort {
  * `message.received` word that note differently, so echoes match on content.
  */
 function promptContent(text: string): string {
-  const note = text.indexOf("\n[");
+  const note = text.search(/\n\[\d+ images? attached:/);
   return (note === -1 ? text : text.slice(0, note)).trim();
 }
 
@@ -1366,7 +1366,7 @@ export function attachSessionBridge(
     for (const ask of asks) bag.deliveredAskWake.set(ask.sessionId, ask.questionId);
     sendInternalText(asks.map((ask) => pendingAskWakeText(ask)).join("\n\n"));
   };
-  bag.flushPendingAskWake = () => flushPendingAskWake();
+  bag.flushPendingAskWake = flushPendingAskWake;
 
   const doInterrupt = (): void => {
     if (bag.disposed) return;
@@ -1389,6 +1389,7 @@ export function attachSessionBridge(
     recordLastSent(null);
     bag.turn = turnStateOnInterrupt(bag.turn, now());
     paintPhase();
+    flushPendingAskWake();
   };
   const clearQueuedDelivery = (): void => {
     if (bag.disposed) return;