fix(subagents): wake the parent for deferred results

Results that settled while the parent was busy were deliberately flushed as
nextTurn at agent_settled. Pi only consumes that queue on another user prompt,
so fire-and-forget results could not fulfill their documented automatic
re-invocation contract.

Flush the pending batch as one follow-up at the authoritative parent boundary,
while preserving wait consumption, exactly-once delivery, synchronous retry,
and aborted-turn suppression.

Closes #47

Author: tt-a1i

extensions/subagents/docs/design-plan.md

@@ -71,13 +71,17 @@ the parent conversation.
 ### 1.3 Result delivery back to the parent
 
 - When a child settles **unconsumed**, `onSettled` defers it into a tiny
-  `createDeferredResultDelivery` buffer (defer/consume/drain/clear keyed by id).
+  `createSubagentResultDelivery` buffer (defer/consume/clear keyed by id).
 - Flush happens when the parent goes idle: immediately if `sessionContext.isIdle()`,
-  otherwise on the parent's `agent_settled` event. A later `subagent_wait` can still
-  consume a deferred result before flush (that's why it is a buffer, not an immediate
-  send).
-- Delivery = `pi.sendMessage({ customType: "subagent-result", content, display: true,
-  details: { id, title, status } }, { deliverAs: "followUp", triggerTurn: true })`.
+  otherwise on the parent's authoritative `agent_settled` event. Busy-period results
+  are batched into one automatic wake-up so none can be stranded until the user's next
+  prompt. A later `subagent_wait` can still consume a deferred result before flush.
+  If the parent run was aborted, delivery uses `nextTurn` rather than resurrecting
+  work the user explicitly stopped.
+- Normal delivery = `pi.sendMessage({ customType: "subagent-result", content,
+  display: false, details: { id, title, status } },
+  { deliverAs: "followUp", triggerTurn: true })`; a separate session entry renders the
+  report at its actual completion point.
   Content is built by `buildSubagentResultMessage` (`Subagent sa-N "title"
   finished/failed.` + optional `Error:` line + output truncated to 24KB/600 lines with a
   pointer to the child session file for the full transcript).

extensions/subagents/index.test.ts

@@ -9,9 +9,12 @@ import type {
   ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
 import { PLAN_MODE_CHANNEL } from "../shared/plan-mode-state.ts";
-import subagents, { createSubagentResultDispatcher } from "./index.ts";
+import subagents, {
+  createSubagentResultDispatcher,
+  registerSubagentResultDeliveryLifecycle,
+} from "./index.ts";
 
-test("deferred subagent results render before a hidden next-turn injection", () => {
+test("subagent results render before the hidden wake-up message", () => {
   const events: unknown[] = [];
   const pi = {
     appendEntry(customType: string, data: unknown) {
@@ -23,29 +26,26 @@ test("deferred subagent results render before a hidden next-turn injection", ()
   } as unknown as ExtensionAPI;
   const dispatch = createSubagentResultDispatcher(pi, () => "report");
 
-  dispatch(
-    [
-      {
-        id: "sa-3",
-        origin: "model",
-        backend: "pi",
-        title: "investigate plan mode",
-        prompt: "inspect",
-        cwd: process.cwd(),
-        status: "done",
-        createdAt: 0,
-        settledAt: 1_000,
-        meta: { backend: "pi" },
-        usage: {},
-        transcript: [],
-        liveTools: [],
-        queued: [],
-        finalText: "report",
-        turns: 1,
-      },
-    ],
-    false,
-  );
+  dispatch([
+    {
+      id: "sa-3",
+      origin: "model",
+      backend: "pi",
+      title: "investigate plan mode",
+      prompt: "inspect",
+      cwd: process.cwd(),
+      status: "done",
+      createdAt: 0,
+      settledAt: 1_000,
+      meta: { backend: "pi" },
+      usage: {},
+      transcript: [],
+      liveTools: [],
+      queued: [],
+      finalText: "report",
+      turns: 1,
+    },
+  ]);
 
   assert.deepEqual(events, [
     {
@@ -74,9 +74,70 @@ test("deferred subagent results render before a hidden next-turn injection", ()
           status: "done",
         },
       },
-      options: { deliverAs: "nextTurn" },
+      options: { deliverAs: "followUp", triggerTurn: true },
     },
   ]);
+
+  events.length = 0;
+  dispatch(
+    [
+      {
+        id: "sa-4",
+        origin: "model",
+        backend: "pi",
+        title: "aborted parent",
+        prompt: "inspect",
+        cwd: process.cwd(),
+        status: "done",
+        createdAt: 0,
+        settledAt: 1_000,
+        meta: { backend: "pi" },
+        usage: {},
+        transcript: [],
+        liveTools: [],
+        queued: [],
+        finalText: "report",
+        turns: 1,
+      },
+    ],
+    false,
+  );
+  assert.deepEqual((events.at(-1) as { options: unknown }).options, {
+    deliverAs: "nextTurn",
+  });
+});
+
+test("the parent lifecycle wakes deferred results unless the run was aborted", () => {
+  const handlers = new Map<string, (event: never) => void>();
+  const pi = {
+    on(event: string, handler: (event: never) => void) {
+      handlers.set(event, handler);
+    },
+  } as unknown as ExtensionAPI;
+  const settled: Array<boolean | undefined> = [];
+  registerSubagentResultDeliveryLifecycle(pi, {
+    parentSettled: (aborted) => settled.push(aborted),
+  });
+
+  handlers.get("agent_start")?.({ type: "agent_start" } as never);
+  handlers.get("agent_end")?.({
+    type: "agent_end",
+    messages: [{ role: "assistant", stopReason: "stop" }],
+  } as never);
+  handlers.get("agent_settled")?.({ type: "agent_settled" } as never);
+
+  handlers.get("agent_start")?.({ type: "agent_start" } as never);
+  handlers.get("agent_end")?.({
+    type: "agent_end",
+    messages: [
+      { role: "assistant", stopReason: "stop" },
+      { role: "toolResult" },
+      { role: "assistant", stopReason: "aborted" },
+    ],
+  } as never);
+  handlers.get("agent_settled")?.({ type: "agent_settled" } as never);
+
+  assert.deepEqual(settled, [false, true]);
 });
 
 test("the visible subagent result entry renders the completed report", () => {

extensions/subagents/index.ts

@@ -95,8 +95,7 @@ import {
   SUBAGENT_WAIT_PARAMETER_DESCRIPTIONS,
   SUBAGENT_WAIT_TOOL_DESCRIPTION,
 } from "./src/prompt.ts";
-import { createDeferredResultDelivery } from "./src/result-delivery.ts";
-import { resultDeliveryOptions } from "../background-terminals/src/result-delivery.ts";
+import { createSubagentResultDelivery } from "./src/result-delivery.ts";
 import {
   effectiveChildToolAllowlist,
   resolveStandaloneChildProjectTrust,
@@ -210,7 +209,7 @@ export function createSubagentResultDispatcher(
   pi: ExtensionAPI,
   outputFor: (snap: SubagentSnapshot) => string = truncatedOutput,
 ) {
-  return (snaps: readonly SubagentSnapshot[], wake: boolean) => {
+  return (snaps: readonly SubagentSnapshot[], wake = true) => {
     if (snaps.length === 0) return;
     const content = snaps
       .map((snap) =>
@@ -249,11 +248,37 @@ export function createSubagentResultDispatcher(
         display: false,
         details,
       },
-      resultDeliveryOptions(wake),
+      wake
+        ? { deliverAs: "followUp", triggerTurn: true }
+        : { deliverAs: "nextTurn" },
     );
   };
 }
 
+export function registerSubagentResultDeliveryLifecycle(
+  pi: ExtensionAPI,
+  delivery: { parentSettled(aborted?: boolean): void },
+) {
+  let parentRunAborted = false;
+
+  pi.on("agent_start", () => {
+    parentRunAborted = false;
+  });
+  pi.on("agent_end", (event) => {
+    for (let index = event.messages.length - 1; index >= 0; index--) {
+      const message = event.messages[index];
+      if (message?.role !== "assistant") continue;
+      parentRunAborted = message.stopReason === "aborted";
+      break;
+    }
+  });
+  pi.on("agent_settled", () => delivery.parentSettled(parentRunAborted));
+
+  return () => {
+    parentRunAborted = false;
+  };
+}
+
 type SubagentResultTheme = Parameters<MessageRenderer>[2];
 
 function renderSubagentResult(
@@ -322,8 +347,17 @@ export default function (pi: ExtensionAPI) {
   let requestWidgetRender: (() => void) | undefined;
   let navigationLayerRegistered = false;
   let dashboardOpen = false;
-  const resultDelivery = createDeferredResultDelivery<SubagentSnapshot>();
   const dispatchResults = createSubagentResultDispatcher(pi);
+  const resultDelivery = createSubagentResultDelivery<SubagentSnapshot>({
+    isIdle: () => sessionContext?.isIdle() === true,
+    // Every unconsumed fire-and-forget result must reach the parent. The
+    // delivery coordinator batches results that settled while it was busy.
+    deliver: dispatchResults,
+  });
+  const resetResultDeliveryLifecycle = registerSubagentResultDeliveryLifecycle(
+    pi,
+    resultDelivery,
+  );
   const hideLifecycleTools = () =>
     patchOwnedTools(pi, "subagents", {
       disable: OPENPI_TOOL_SURFACE.subagents.deferred,
@@ -436,25 +470,6 @@ export default function (pi: ExtensionAPI) {
     navigationLayerRegistered = true;
   };
 
-  /**
-   * `wake` decides whether this costs the model a turn. A subagent that
-   * settled while the model sits idle is the result it is waiting on. A
-   * backlog that piled up while it worked is not: waking once per stale
-   * subagent forces a turn each, and the model can only answer "that one
-   * already finished". `nextTurn` still enters context with the user's next
-   * message, without demanding a reply.
-   */
-  const deliverResults = (
-    snaps: readonly SubagentSnapshot[],
-    wake: boolean,
-  ) => {
-    dispatchResults(snaps, wake);
-  };
-
-  const flushResults = (wake: boolean) => {
-    deliverResults(resultDelivery.drain(), wake);
-  };
-
   const deliverBtwResult = (snap: SubagentSnapshot) => {
     // appendEntry is a synchronous SessionManager operation and emits an
     // entry_appended event, so it is safe while the parent is streaming and
@@ -500,10 +515,10 @@ export default function (pi: ExtensionAPI) {
     // subagent_wait can consume it before agent_settled flushes follow-ups.
     // Defer a copy: the live snapshot keeps mutating if the subagent is
     // restarted before the deferred result flushes.
+    // The delivery coordinator closes both sides of the wake-up race: it
+    // flushes now if the parent is already idle, otherwise the parent's next
+    // agent_settled edge rechecks this same pending Map.
     resultDelivery.defer({ ...snap, meta: { ...snap.meta } });
-    // Settled while the model sits idle: it has nothing else in flight, so
-    // this is the result it is waiting on — wake it.
-    if (sessionContext?.isIdle()) flushResults(true);
   };
 
   pi.on("session_start", (_event, ctx) => {
@@ -530,10 +545,6 @@ export default function (pi: ExtensionAPI) {
     managerPromise?.then(updateStatus).catch(() => undefined);
   });
 
-  // These settled while the model was working on something else, so they go
-  // into context without forcing a turn per stale subagent.
-  pi.on("agent_settled", () => flushResults(false));
-
   pi.on("session_shutdown", async () => {
     if (navigationLayerRegistered) {
       removeEditorLayer(pi, "subagents");
@@ -555,6 +566,7 @@ export default function (pi: ExtensionAPI) {
     requestWidgetRender = undefined;
     stripState.focused = false;
     dashboardOpen = false;
+    resetResultDeliveryLifecycle();
     const closing = runtime;
     runtime = undefined;
     managerPromise = undefined;