@ian-pascoe/pi-minimal-subagents 0.2.1 → 0.2.3

package/README.md

@@ -141,26 +141,29 @@ the complete read-only discovery bundle.
 `agent_message` reports whether a message was delivered through an active
 parent wait, queued for the recipient, or failed. `subagent_wait` can return an
 intermediate Wait Event containing a Coordination Message before the child turn
-settles; call it again for the terminal turn result. Pass optional `turn_id` to
-address an older retained turn exactly. Without it, waits select the oldest
-observable claimed or pending turn before the active/latest turn. A caller may
-have only one outstanding wait for the same source turn; a concurrent duplicate
-is rejected instead of competing for one Wait Event.
+settles. That event claims only its message, so later unconsumed messages and the
+terminal result retain automatic fallback. If the turn has already settled, one
+wait returns its terminal result with queued messages in `messages`. Pass
+optional `turn_id` to address an older retained turn exactly. Without it, waits
+select the oldest observable claimed or pending turn before the active/latest
+turn. A caller may have only one outstanding wait for the same source turn; a
+concurrent duplicate is rejected instead of competing for one Wait Event.
 
 The persisted Delivery Ledger records Coordination Messages, terminal results,
 globally increasing sequence, and wait ownership before delivery. Existing
 items retain their sequence; gaps from skipped malformed records are valid.
-Claims can name only active, latest, or retained turns. Once a wait returns an
-intermediate message, that wait path owns the rest of the source turn across
-reloads, forks, and newer turns. Automatic fallback retains its ordered queue
-reservation, treats idle notifications as advisory, and rechecks actual
-recipient idleness before injecting a message. Destination-session Delivery
-Evidence settles and compacts ledger items, preventing duplicate delivery and
+Claims can name only active, latest, or retained turns. Wait-returned messages
+retain individual delivery evidence; terminal wait ownership remains durable
+across reloads, forks, and newer turns. Automatic fallback retains its ordered
+queue reservation while batching queued messages from one source turn into one
+Pi steer. Root-bound messages remain batchable while the root turn is active; a
+pending terminal result absorbs them. Child sessions drain all available steers
+before the next model call. Destination-session Delivery Evidence still settles
+each batched ledger item independently, preventing duplicate delivery and
 unbounded checkpoint growth. The pure Delivery Ledger state machine retains at
-most 20 pending wait-only terminal results per source agent; Coordination
-Messages are not removed by that terminal-retention limit. Delivered messages
-include stable delivery, source-agent, and source-turn identities in persisted
-details.
+most 20 pending wait-only terminal results per source agent; Coordination Messages
+are not removed by that terminal-retention limit. Delivered messages include
+stable delivery, source-agent, and source-turn identities in persisted details.
 
 Deleting a child first verifies its session header and persistent identity,
 then uses the optional `trash` command when available and falls back to

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ian-pascoe/pi-minimal-subagents",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "private": false,
   "description": "Persistent nested subagents with bounded delegation for Pi",
   "keywords": [

package/src/minimal-subagents-coordinator.ts

@@ -53,6 +53,7 @@ import type {
   StatusResult,
   TurnId,
   TurnResult,
+  WaitMessageResult,
   WaitResult,
 } from "./minimal-subagents-types.js";
 
@@ -85,11 +86,6 @@ interface PendingParentMessage {
   cancelGrace?: () => void;
 }
 
-interface CancelableWait {
-  promise: Promise<void>;
-  cancel: () => void;
-}
-
 function agentDeliveryKey(agentId: string, turnId: string): string {
   return `${agentId}\u0000${turnId}`;
 }
@@ -109,8 +105,27 @@ function terminalTurnResult(
   };
 }
 
-function terminalWaitResult(result: TurnResult): WaitResult {
-  return { event: "turn", ...structuredClone(result) };
+function terminalWaitResult(result: TurnResult, messages: WaitMessageResult[] = []): WaitResult {
+  const terminal = { event: "turn" as const, ...structuredClone(result) };
+  return messages.length === 0 ? terminal : { ...terminal, messages: structuredClone(messages) };
+}
+
+function combineCoordinatorMessages(messages: readonly CoordinatorMessage[]): CoordinatorMessage {
+  const latest = messages.at(-1);
+  if (!latest) throw new Error("Minimal subagents message batch must not be empty");
+  if (messages.length === 1) return latest;
+  const references = messages.flatMap(
+    (message) =>
+      message.details.messages ??
+      (message.details.delivery_id
+        ? [{ delivery_id: message.details.delivery_id, message_id: message.details.message_id }]
+        : []),
+  );
+  return {
+    ...latest,
+    content: messages.map((message) => message.content).join("\n\n"),
+    details: references.length > 0 ? { ...latest.details, messages: references } : latest.details,
+  };
 }
 
 /** One root-owned coordinator for persistent nested Pi child sessions. */
@@ -124,11 +139,9 @@ export class MinimalSubagentsCoordinator {
   private readonly waiters = new Map<string, Set<TurnWaiter>>();
   private readonly pendingParentMessages = new Map<string, PendingParentMessage[]>();
   private readonly recipientQueues = new Map<string, Promise<unknown>>();
-  private readonly recipientIdleWaiters = new Map<string, Set<() => void>>();
   private readonly automaticDeliveryKeys = new Set<string>();
   private readonly automaticCoordinationDeliveryIds = new Set<string>();
   private readonly waitHandedDeliveryIds = new Set<string>();
-  private readonly automaticDeliveryClaimWaiters = new Map<string, Set<() => void>>();
   private readonly backgroundOperations = new Set<Promise<void>>();
   private acceptingOperations = true;
   private lifecycleEpoch = 0;
@@ -363,15 +376,16 @@ export class MinimalSubagentsCoordinator {
         new Error(`Minimal subagents duplicate wait: ${callerId} is already waiting for ${turnId}`),
       );
     }
-    const pendingMessage = this.claimPendingParentMessage(callerId, agentId, turnId);
-    if (pendingMessage) return Promise.resolve(pendingMessage);
     const retainedResult =
       findTerminalDelivery(this.deliveryLedger, agentId, turnId)?.result ??
       (agent.latest_result?.turn_id === turnId ? agent.latest_result : undefined);
     if (retainedResult) {
+      const messages = this.drainPendingParentMessages(callerId, agentId, turnId);
       this.claimTerminalDelivery(callerId, retainedResult);
-      return Promise.resolve(terminalWaitResult(retainedResult));
+      return Promise.resolve(terminalWaitResult(retainedResult, messages));
     }
+    const pendingMessage = this.claimPendingParentMessage(callerId, agentId, turnId);
+    if (pendingMessage) return Promise.resolve(pendingMessage);
     if (agent.active_turn_id !== turnId) {
       return Promise.reject(
         new Error(`Minimal subagents wait: turn ${turnId} is no longer retained for ${agentId}`),
@@ -543,7 +557,6 @@ export class MinimalSubagentsCoordinator {
     this.agents.clear();
     this.deliveryLedger = createDeliveryLedger();
     this.pendingParentMessages.clear();
-    this.releaseAllRecipientIdleWaiters();
     this.recipientQueues.clear();
     this.backgroundOperations.clear();
     await Promise.allSettled(
@@ -558,12 +571,10 @@ export class MinimalSubagentsCoordinator {
     this.waiters.clear();
     this.pendingParentMessages.clear();
     this.waitHandedDeliveryIds.clear();
-    this.releaseAllRecipientIdleWaiters();
     this.recipientQueues.clear();
     this.backgroundOperations.clear();
     this.automaticDeliveryKeys.clear();
     this.automaticCoordinationDeliveryIds.clear();
-    this.automaticDeliveryClaimWaiters.clear();
     this.deliveryLedger = createDeliveryLedger({
       deliveries: snapshot.deliveries,
       coordination_deliveries: snapshot.coordination_deliveries,
@@ -720,13 +731,6 @@ export class MinimalSubagentsCoordinator {
     await Promise.allSettled(scheduled);
   }
 
-  /** Release ordered automatic deliveries after one recipient conversation becomes idle. */
-  markRecipientIdle(agentId: string): void {
-    const waiters = this.recipientIdleWaiters.get(agentId);
-    this.recipientIdleWaiters.delete(agentId);
-    for (const resolve of waiters ?? []) resolve();
-  }
-
   /** Clone complete child leaves for root fork ownership without ever sharing source session paths. */
   async prepareFork(sourceRootSessionFile: string): Promise<ForkSnapshot> {
     const activeRootChildren = this.childrenOf("root");
@@ -785,7 +789,6 @@ export class MinimalSubagentsCoordinator {
   shutdown(): Promise<void> {
     if (this.shutdownPromise) return this.shutdownPromise;
     this.acceptingOperations = false;
-    this.releaseAllRecipientIdleWaiters();
     this.shutdownPromise = this.finishShutdown();
     return this.shutdownPromise;
   }
@@ -999,7 +1002,6 @@ export class MinimalSubagentsCoordinator {
       });
     }
     if (result.status !== "completed") this.removeSettledEmptyTurnClaim(agent.agent_id, turnId);
-    this.markRecipientIdle(agent.agent_id);
   }
 
   private async deliverAutomaticResult(
@@ -1010,6 +1012,7 @@ export class MinimalSubagentsCoordinator {
     if (this.automaticDeliveryKeys.has(deliveryKey)) return;
     this.automaticDeliveryKeys.add(deliveryKey);
     const graceMs = this.deliveryGraceMs();
+    let batchedCoordinationDeliveries: PersistedCoordinationDelivery[] = [];
     try {
       await this.enqueueRecipientDelivery(delivery.destination_agent_id, async () => {
         if (delivery.destination_agent_id !== "root") {
@@ -1024,15 +1027,6 @@ export class MinimalSubagentsCoordinator {
           this.settleDelivery(delivery);
           return;
         }
-        while (!this.isRecipientIdle(delivery.destination_agent_id)) {
-          const idleWait = this.createRecipientIdleWait(delivery.destination_agent_id);
-          const claimWait = this.createAutomaticDeliveryClaimWait(deliveryKey);
-          await Promise.race([idleWait.promise, claimWait.promise]);
-          idleWait.cancel();
-          claimWait.cancel();
-          if (!this.acceptingOperations || this.shouldStopAutomaticTerminalDelivery(delivery))
-            return;
-        }
         if (!this.acceptingOperations || this.shouldStopAutomaticTerminalDelivery(delivery)) return;
         if (this.hasDeliveryEvidence(delivery)) {
           this.settleDelivery(delivery);
@@ -1051,14 +1045,28 @@ export class MinimalSubagentsCoordinator {
             usage: result.usage,
           },
         };
+        batchedCoordinationDeliveries = this.takePendingParentDeliveryBatch(
+          deliveryKey,
+          delivery.destination_agent_id,
+        );
+        for (const batchedDelivery of batchedCoordinationDeliveries) {
+          this.waitHandedDeliveryIds.add(batchedDelivery.delivery_id);
+        }
         await this.deliverToRecipient(
           delivery.destination_agent_id,
-          message,
-          () => this.isTerminalDeliveryCurrent(delivery),
-          true,
+          combineCoordinatorMessages([
+            ...batchedCoordinationDeliveries.map((item) => item.message),
+            message,
+          ]),
+          () =>
+            this.isTerminalDeliveryCurrent(delivery) &&
+            batchedCoordinationDeliveries.every((item) => this.isCoordinationDeliveryCurrent(item)),
         );
       });
     } catch (error) {
+      for (const batchedDelivery of batchedCoordinationDeliveries) {
+        this.waitHandedDeliveryIds.delete(batchedDelivery.delivery_id);
+      }
       if (!this.isTerminalDeliveryCurrent(delivery)) return;
       const deliveryError = error instanceof Error ? error.message : String(error);
       this.deliveryLedger = setTerminalDeliveryError(
@@ -1263,7 +1271,6 @@ export class MinimalSubagentsCoordinator {
     targetId: string,
     message: CoordinatorMessage,
     isCurrentDelivery: () => boolean = () => true,
-    requireIdleRecipient = false,
   ): Promise<void> {
     if (!isCurrentDelivery()) {
       throw new Error("Minimal subagents delivery abandoned after session branch change");
@@ -1281,9 +1288,6 @@ export class MinimalSubagentsCoordinator {
       throw new Error("Minimal subagents delivery abandoned after session branch change");
     }
     const visibleMessage = addCoordinatorMessageEnvelope(message);
-    if (requireIdleRecipient && (target.active_turn_id || runtime.isRunning)) {
-      throw new Error(`Minimal subagents automatic delivery recipient became active: ${targetId}`);
-    }
     if (target.active_turn_id || runtime.isRunning) {
       await runtime.queueCoordinatorMessage(visibleMessage);
       return;
@@ -1367,8 +1371,6 @@ export class MinimalSubagentsCoordinator {
   private applyDeliveryLedgerTransition(transition: DeliveryLedgerTransition): void {
     this.deliveryLedger = transition.ledger;
     for (const delivery of transition.prunedTerminalDeliveries) {
-      const key = agentDeliveryKey(delivery.source_agent_id, delivery.source_turn_id);
-      this.releaseAutomaticDeliveryClaimWaiters(key);
       this.dependencies.registry.append(
         createRegistryEvent(this.dependencies.registry.rootSessionId, "delivery-pruned", {
           source_agent_id: delivery.source_agent_id,
@@ -1504,16 +1506,8 @@ export class MinimalSubagentsCoordinator {
   }
 
   private pruneDeliveryStateForDeletedAgent(agentId: string): void {
-    const previousTerminalDeliveries = this.deliveryLedger.terminalDeliveries;
     const previousCoordinationDeliveries = this.deliveryLedger.coordinationDeliveries;
     this.deliveryLedger = pruneDeliveryLedgerAgents(this.deliveryLedger, [agentId]).ledger;
-    for (const delivery of previousTerminalDeliveries) {
-      if (!this.isTerminalDeliveryCurrent(delivery)) {
-        this.releaseAutomaticDeliveryClaimWaiters(
-          agentDeliveryKey(delivery.source_agent_id, delivery.source_turn_id),
-        );
-      }
-    }
     for (const delivery of previousCoordinationDeliveries) {
       if (!this.isCoordinationDeliveryCurrent(delivery)) {
         this.waitHandedDeliveryIds.delete(delivery.delivery_id);
@@ -1673,7 +1667,6 @@ export class MinimalSubagentsCoordinator {
       (candidate) => candidate.callerId === destinationAgentId,
     );
     if (!waiter) return false;
-    this.claimDeliveryTurn(message.details.source_agent_id, message.details.source_turn_id);
     this.deliveryLedger = setCoordinationDeliveryPath(
       this.deliveryLedger,
       delivery.delivery_id,
@@ -1698,7 +1691,7 @@ export class MinimalSubagentsCoordinator {
     callerId: string,
     sourceAgentId: string,
     sourceTurnId: string,
-  ): WaitResult | undefined {
+  ): WaitMessageResult | undefined {
     const key = agentDeliveryKey(sourceAgentId, sourceTurnId);
     const pendingMessages = this.pendingParentMessages.get(key);
     const index = pendingMessages?.findIndex(
@@ -1715,7 +1708,6 @@ export class MinimalSubagentsCoordinator {
         )
         .sort((left, right) => left.sequence - right.sequence)[0];
       if (!retained) return undefined;
-      this.claimDeliveryTurn(sourceAgentId, sourceTurnId);
       this.deliveryLedger = setCoordinationDeliveryPath(
         this.deliveryLedger,
         retained.delivery_id,
@@ -1735,7 +1727,6 @@ export class MinimalSubagentsCoordinator {
     }
     const pending = pendingMessages[index];
     if (!pending) return undefined;
-    this.claimDeliveryTurn(sourceAgentId, sourceTurnId);
     const delivery = findCoordinationDelivery(this.deliveryLedger, pending.deliveryId);
     if (delivery) {
       this.deliveryLedger = setCoordinationDeliveryPath(
@@ -1747,10 +1738,6 @@ export class MinimalSubagentsCoordinator {
       if (currentDelivery) this.persistCoordinationDeliveryState(currentDelivery);
       this.waitHandedDeliveryIds.add(delivery.delivery_id);
     }
-    const sourceResult = this.agents.get(sourceAgentId)?.latest_result;
-    if (sourceResult?.turn_id === sourceTurnId) {
-      this.setTerminalDeliveryPathToWait(callerId, sourceResult);
-    }
     pending.claimed = true;
     pending.cancelGrace?.();
     pending.releaseClaim();
@@ -1766,6 +1753,20 @@ export class MinimalSubagentsCoordinator {
     };
   }
 
+  private drainPendingParentMessages(
+    callerId: string,
+    sourceAgentId: string,
+    sourceTurnId: string,
+  ): WaitMessageResult[] {
+    const messages: WaitMessageResult[] = [];
+    let message = this.claimPendingParentMessage(callerId, sourceAgentId, sourceTurnId);
+    while (message) {
+      messages.push(message);
+      message = this.claimPendingParentMessage(callerId, sourceAgentId, sourceTurnId);
+    }
+    return messages;
+  }
+
   private queuePendingParentMessage(
     targetId: string,
     message: CoordinatorMessage,
@@ -1800,6 +1801,7 @@ export class MinimalSubagentsCoordinator {
     )
       return;
 
+    let automaticBatch = [delivery];
     const operation = this.enqueueRecipientDelivery(targetId, async () => {
       if (targetId !== "root") {
         await this.ensureRuntime(this.requireUsableAgent(targetId, "message"));
@@ -1821,34 +1823,63 @@ export class MinimalSubagentsCoordinator {
       pending.cancelGrace?.();
       pending.cancelGrace = undefined;
       if (!this.acceptingOperations || pending.claimed || turnClaimed()) return;
-      while (!this.isRecipientIdle(targetId)) {
-        const idleWait = this.createRecipientIdleWait(targetId);
-        await Promise.race([pending.claimPromise, idleWait.promise]);
-        idleWait.cancel();
-        if (!this.acceptingOperations || pending.claimed || turnClaimed()) return;
+      while (
+        targetId === "root" &&
+        !this.dependencies.root.isIdle() &&
+        !findTerminalDelivery(
+          this.deliveryLedger,
+          message.details.source_agent_id,
+          message.details.source_turn_id,
+        ) &&
+        this.acceptingOperations &&
+        !pending.claimed &&
+        !turnClaimed()
+      ) {
+        await Promise.race([
+          pending.claimPromise,
+          new Promise((resolve) => setTimeout(resolve, 25)),
+        ]);
       }
       if (!this.acceptingOperations || pending.claimed || turnClaimed()) return;
-      this.removePendingParentMessage(key, pending);
-      this.waitHandedDeliveryIds.add(delivery.delivery_id);
+      const terminalDelivery = findTerminalDelivery(
+        this.deliveryLedger,
+        message.details.source_agent_id,
+        message.details.source_turn_id,
+      );
+      if (
+        terminalDelivery?.destination_agent_id === targetId &&
+        terminalDelivery.path === "message"
+      ) {
+        for (const queued of this.pendingParentMessages.get(key) ?? []) {
+          queued.cancelGrace?.();
+          queued.releaseClaim();
+        }
+        return;
+      }
+      automaticBatch = this.takePendingParentDeliveryBatch(key, targetId);
+      for (const batchedDelivery of automaticBatch) {
+        this.waitHandedDeliveryIds.add(batchedDelivery.delivery_id);
+      }
+      if (automaticBatch.length === 0) return;
       await this.deliverToRecipient(
         targetId,
-        message,
-        () => this.isCoordinationDeliveryCurrent(delivery),
-        true,
+        combineCoordinatorMessages(automaticBatch.map((item) => item.message)),
+        () => automaticBatch.every((item) => this.isCoordinationDeliveryCurrent(item)),
       );
     });
     void operation.catch((cause) => {
-      this.removePendingParentMessage(key, pending);
-      this.waitHandedDeliveryIds.delete(delivery.delivery_id);
-      if (!this.isCoordinationDeliveryCurrent(delivery)) return;
       const deliveryError = cause instanceof Error ? cause.message : String(cause);
-      this.deliveryLedger = setCoordinationDeliveryError(
-        this.deliveryLedger,
-        delivery.delivery_id,
-        deliveryError,
-      );
-      const current = findCoordinationDelivery(this.deliveryLedger, delivery.delivery_id);
-      if (current) this.persistCoordinationDeliveryState(current);
+      for (const batchedDelivery of automaticBatch) {
+        this.waitHandedDeliveryIds.delete(batchedDelivery.delivery_id);
+        if (!this.isCoordinationDeliveryCurrent(batchedDelivery)) continue;
+        this.deliveryLedger = setCoordinationDeliveryError(
+          this.deliveryLedger,
+          batchedDelivery.delivery_id,
+          deliveryError,
+        );
+        const current = findCoordinationDelivery(this.deliveryLedger, batchedDelivery.delivery_id);
+        if (current) this.persistCoordinationDeliveryState(current);
+      }
       this.dependencies.notify?.({
         type: "failure",
         agentId: message.details.source_agent_id,
@@ -1859,6 +1890,25 @@ export class MinimalSubagentsCoordinator {
     });
   }
 
+  private takePendingParentDeliveryBatch(
+    key: string,
+    targetId: string,
+  ): PersistedCoordinationDelivery[] {
+    const batch = (this.pendingParentMessages.get(key) ?? []).filter(
+      (pending) => pending.destinationAgentId === targetId && !pending.claimed,
+    );
+    for (const pending of batch) {
+      pending.claimed = true;
+      pending.cancelGrace?.();
+      pending.releaseClaim();
+      this.removePendingParentMessage(key, pending);
+    }
+    return batch.flatMap((pending) => {
+      const delivery = findCoordinationDelivery(this.deliveryLedger, pending.deliveryId);
+      return delivery ? [delivery] : [];
+    });
+  }
+
   private removePendingParentMessage(key: string, pending: PendingParentMessage): void {
     const pendingMessages = this.pendingParentMessages.get(key);
     if (!pendingMessages) return;
@@ -1874,14 +1924,12 @@ export class MinimalSubagentsCoordinator {
   }
 
   private setTerminalDeliveryPathToWait(callerId: string, result: TurnResult): void {
-    const key = agentDeliveryKey(result.agent_id, result.turn_id);
     const delivery = findTerminalDelivery(this.deliveryLedger, result.agent_id, result.turn_id);
     if (!delivery || delivery.destination_agent_id !== callerId || delivery.path === "wait") return;
     this.applyDeliveryLedgerTransition(
       setTerminalDeliveryPath(this.deliveryLedger, result.agent_id, result.turn_id, "wait"),
     );
     const retained = findTerminalDelivery(this.deliveryLedger, result.agent_id, result.turn_id);
-    this.releaseAutomaticDeliveryClaimWaiters(key);
     if (!retained) return;
     this.dependencies.registry.append(
       createRegistryEvent(this.dependencies.registry.rootSessionId, "delivery-pending", {
@@ -1890,57 +1938,6 @@ export class MinimalSubagentsCoordinator {
     );
   }
 
-  private isRecipientIdle(agentId: string): boolean {
-    if (agentId === "root") return this.dependencies.root.isIdle();
-    const agent = this.agents.get(agentId);
-    if (!agent || agent.active_turn_id) return false;
-    return !this.runtimes.get(agentId)?.isRunning;
-  }
-
-  private createRecipientIdleWait(agentId: string): CancelableWait {
-    const { promise, resolve: release } = Promise.withResolvers<void>();
-    const waiters = this.recipientIdleWaiters.get(agentId) ?? new Set();
-    waiters.add(release);
-    this.recipientIdleWaiters.set(agentId, waiters);
-    return {
-      promise,
-      cancel: () => {
-        const currentWaiters = this.recipientIdleWaiters.get(agentId);
-        currentWaiters?.delete(release);
-        if (currentWaiters?.size === 0) this.recipientIdleWaiters.delete(agentId);
-      },
-    };
-  }
-
-  private createAutomaticDeliveryClaimWait(deliveryKey: string): CancelableWait {
-    const { promise, resolve: release } = Promise.withResolvers<void>();
-    const waiters = this.automaticDeliveryClaimWaiters.get(deliveryKey) ?? new Set();
-    waiters.add(release);
-    this.automaticDeliveryClaimWaiters.set(deliveryKey, waiters);
-    return {
-      promise,
-      cancel: () => {
-        const currentWaiters = this.automaticDeliveryClaimWaiters.get(deliveryKey);
-        currentWaiters?.delete(release);
-        if (currentWaiters?.size === 0) this.automaticDeliveryClaimWaiters.delete(deliveryKey);
-      },
-    };
-  }
-
-  private releaseAutomaticDeliveryClaimWaiters(deliveryKey: string): void {
-    const waiters = this.automaticDeliveryClaimWaiters.get(deliveryKey);
-    this.automaticDeliveryClaimWaiters.delete(deliveryKey);
-    for (const resolve of waiters ?? []) resolve();
-  }
-
-  private releaseAllRecipientIdleWaiters(): void {
-    const allWaiters = [...this.recipientIdleWaiters.values()];
-    this.recipientIdleWaiters.clear();
-    for (const waiters of allWaiters) {
-      for (const resolve of waiters) resolve();
-    }
-  }
-
   private async cancelDuringShutdown(agentId: string): Promise<void> {
     const target = this.agents.get(agentId);
     if (!target) return;

package/src/minimal-subagents-extension.ts

@@ -5,7 +5,6 @@ import {
   getAgentDir,
   SessionManager,
   SettingsManager,
-  type AgentSettledEvent,
   type ExtensionAPI,
   type ExtensionContext,
   type ExtensionFactory,
@@ -100,6 +99,7 @@ function createRootConversationEndpoint(
         },
       );
     },
+    isIdle: () => context.isIdle(),
     hasDeliveryEvidence: (sourceAgentId, sourceTurnId, deliveryId) =>
       findDeliveryEvidence(
         context.sessionManager.getBranch(),
@@ -107,7 +107,6 @@ function createRootConversationEndpoint(
         sourceTurnId,
         deliveryId,
       ),
-    isIdle: () => context.isIdle(),
   };
 }
 
@@ -331,7 +330,6 @@ export class MinimalSubagentsLifecycleController {
     this.pi.on("session_before_fork", (event, context) => this.prepareSessionFork(event, context));
     this.pi.on("session_tree", (event, context) => this.restoreSessionTree(event, context));
     this.pi.on("message_end", (event, context) => this.reconcileMessageDelivery(event, context));
-    this.pi.on("agent_settled", (event, context) => this.releaseSettledRecipient(event, context));
     this.pi.on("session_shutdown", (event, context) => this.shutdownSession(event, context));
   }
 
@@ -554,12 +552,6 @@ export class MinimalSubagentsLifecycleController {
     }
   }
 
-  private releaseSettledRecipient(_event: AgentSettledEvent, context: ExtensionContext): void {
-    if (!this.coordinator) return;
-    if (context.isIdle()) this.coordinator.markRecipientIdle("root");
-    this.uiController?.refresh();
-  }
-
   private async shutdownSession(
     event: SessionShutdownEvent,
     context: ExtensionContext,

package/src/minimal-subagents-render-contract.ts

@@ -132,6 +132,7 @@ const WaitMessageDetailsSchema = Type.Object({
   agent_id: Type.String(),
   turn_id: Type.String(),
   message_id: Type.String(),
+  delivery_id: Type.Optional(Type.String()),
   message: Type.String(),
   elapsed_ms: Type.Optional(Type.Number()),
   usage: Type.Optional(RenderUsageSchema),
@@ -145,6 +146,7 @@ const WaitTurnDetailsSchema = Type.Object({
   error: Type.Optional(Type.String()),
   elapsed_ms: Type.Optional(Type.Number()),
   usage: Type.Optional(RenderUsageSchema),
+  messages: Type.Optional(Type.Array(WaitMessageDetailsSchema)),
 });
 const StatusDetailsSchema = Type.Union([
   Type.Object({

package/src/minimal-subagents-rendering.ts

@@ -341,9 +341,12 @@ function renderWaitResult(
       : details.status;
   const duration = formatSubagentDuration(details.elapsed_ms);
   const tokens = formatSubagentTokenCount(details.usage?.totalTokens);
-  const metrics = [duration, tokens ? `${tokens} tokens` : undefined].filter(
-    (metric): metric is string => metric !== undefined,
-  );
+  const drainedMessageCount = details.event === "message" ? 0 : (details.messages?.length ?? 0);
+  const metrics = [
+    duration,
+    tokens ? `${tokens} tokens` : undefined,
+    drainedMessageCount > 0 ? `${drainedMessageCount} messages` : undefined,
+  ].filter((metric): metric is string => metric !== undefined);
   const summary = renderSubagentSummary(theme, status, agentId, metrics);
   if (options.isPartial || !options.expanded) {
     return new Text(`${summary}${options.isPartial ? "" : collapsedExpansionHint(theme)}`, 0, 0);
@@ -356,6 +359,14 @@ function renderWaitResult(
     container.addChild(renderLabelValue(theme, "Message ID", details.message_id));
     return container;
   }
+  if (details.messages && details.messages.length > 0) {
+    appendTextSection(
+      container,
+      theme,
+      "Messages",
+      details.messages.map((message) => message.message).join("\n\n"),
+    );
+  }
   const output = details.output ?? "";
   if (status === "completed") {
     if (output.length > 0) {

package/src/minimal-subagents-session-wire.ts

@@ -28,6 +28,11 @@ export const ForkOwnershipRecordSchema = Type.Object({
   direct_parent_id: Type.String(),
 });
 
+const DeliveryEvidenceMessageSchema = Type.Object({
+  delivery_id: Type.Optional(Type.String()),
+  message_id: Type.Optional(Type.String()),
+});
+
 /** Parses durable custom-message and wait-tool Delivery Evidence details. */
 export const DeliveryEvidenceDetailsSchema = Type.Object({
   event: Type.Optional(Type.String()),
@@ -35,6 +40,7 @@ export const DeliveryEvidenceDetailsSchema = Type.Object({
   source_turn_id: Type.String(),
   delivery_id: Type.Optional(Type.String()),
   message_id: Type.Optional(Type.String()),
+  messages: Type.Optional(Type.Array(DeliveryEvidenceMessageSchema)),
 });
 
 export type ChildSessionIdentityRecord = Static<typeof ChildSessionIdentityRecordSchema>;

package/src/minimal-subagents-sessions.ts

@@ -411,7 +411,11 @@ export function findDeliveryEvidence(
       return (
         details.source_agent_id === sourceAgentId &&
         details.source_turn_id === sourceTurnId &&
-        (details.delivery_id === deliveryId || details.message_id === deliveryId)
+        (details.delivery_id === deliveryId ||
+          details.message_id === deliveryId ||
+          details.messages?.some(
+            (message) => message.delivery_id === deliveryId || message.message_id === deliveryId,
+          ))
       );
     }
     if (waitToolResult && details.event === "message") return false;
@@ -516,6 +520,8 @@ class PiChildAgentRuntime implements ChildAgentRuntime {
     private readonly modelById: ReadonlyMap<string, Model<any>>,
     onSessionActivity?: () => void,
   ) {
+    // Keep this child-only; AgentSession.setSteeringMode would overwrite the user's global setting.
+    session.agent.steeringMode = "all";
     this.unsubscribe = session.subscribe((event) => {
       if (event.type !== "entry_appended") return;
       if (

package/src/minimal-subagents-tools.ts

@@ -202,7 +202,7 @@ export function createCoordinatorToolDefinitions(
     name: "subagent_wait",
     label: "Subagent Wait",
     description:
-      "Wait for one direct child's oldest observable turn, or select an exact retained turn_id. A Wait Event containing a Coordination Message may arrive first as event=message; call again for the terminal turn result. A successful wait durably claims that turn so later messages and its terminal result return through wait without duplicate automatic delivery. Timeout never cancels the child.",
+      "Wait for one direct child's oldest observable turn, or select an exact retained turn_id. An active child may first return event=message; later unconsumed items still fall back automatically. An already settled turn returns event=turn once with queued messages in messages. Timeout never cancels the child.",
     promptSnippet: "Wait for one direct child's exact turn",
     parameters: options.schemas.subagent_wait,
     async execute(_toolCallId, parameters, signal, onUpdate) {

package/src/minimal-subagents-types.ts

@@ -75,8 +75,14 @@ export interface WaitMessageResult {
   message: string;
 }
 
+/** Reports one terminal child turn and any earlier messages drained by the same wait. */
+export interface WaitTurnResult extends TurnResult {
+  event: "turn";
+  messages?: WaitMessageResult[];
+}
+
 /** Reports one terminal child turn returned by subagent_wait. */
-export type WaitResult = WaitMessageResult | ({ event: "turn" } & TurnResult);
+export type WaitResult = WaitMessageResult | WaitTurnResult;
 
 /** Provides bounded hierarchy, usage, and best-known Runtime Profile data for one persistent agent. */
 export interface AgentSummary extends RuntimeProfile {
@@ -182,6 +188,7 @@ export interface CoordinatorMessage {
     status?: TurnStatus;
     elapsed_ms?: number;
     usage?: Usage;
+    messages?: Array<{ delivery_id?: string; message_id?: string }>;
   };
 }
 
@@ -242,9 +249,9 @@ export interface AgentSessionFactory {
 export interface RootConversationEndpoint {
   /** Queue one typed coordinator message into the root conversation. */
   queueCoordinatorMessage(message: CoordinatorMessage): Promise<void>;
-  hasDeliveryEvidence(sourceAgentId: string, sourceTurnId: string, deliveryId?: string): boolean;
-  /** Report whether automatic delivery can start a new root turn without racing an active wait. */
+  /** Whether a coordinator message can start immediately instead of joining Pi's steer queue. */
   isIdle(): boolean;
+  hasDeliveryEvidence(sourceAgentId: string, sourceTurnId: string, deliveryId?: string): boolean;
 }
 
 /** Stores root-owned agent identity, launch contract, availability, and latest activity. */