@ian-pascoe/pi-minimal-subagents 0.12.0 → 0.14.0

package/src/minimal-subagents-coordinator.ts

@@ -2,10 +2,14 @@ import { randomUUID } from "node:crypto";
 import {
   assembleImportedContext,
   boundRecentAgentText,
+  buildActiveTurnProgress,
+  buildInheritedContextTaskPrompt,
   buildRecentAgentActivity,
   contextContainsImages,
+  selectActiveTurnTranscript,
   selectChildAgentTranscript,
 } from "./minimal-subagents-context.js";
+
 import {
   canAgentContractSpawn,
   DEFAULT_MAX_SUBAGENT_DEPTH,
@@ -19,6 +23,7 @@ import {
   claimDeliveryLedgerTurn,
   createDeliveryLedger,
   deliveryLedgerSnapshot,
+  deliveryTurnKey,
   findCoordinationDelivery,
   findTerminalDelivery,
   isDeliveryLedgerTurnClaimed,
@@ -38,7 +43,9 @@ import { withTroubleshootingHint } from "./troubleshooting-skill.js";
 import { addCoordinatorMessageEnvelope } from "./minimal-subagents-message-envelope.js";
 import { unavailableAgent } from "./minimal-subagents-sessions.js";
 import { createRegistryEvent } from "./minimal-subagents-registry.js";
+import type { MinimalSubagentsModelRole } from "./minimal-subagents-config.js";
 import type {
+  ActiveTurnProgress,
   AgentDetail,
   AgentMessageDisposition,
   AgentMessageResult,
@@ -70,6 +77,16 @@ const RESERVED_AGENT_IDS = new Set(["root", "parent"]);
 const RECENT_MESSAGE_LIMIT = 20;
 const DEFAULT_AUTOMATIC_DELIVERY_GRACE_MS = 1_000;
 
+/** Assistant messages a waiting parent's live view renders from the child's running turn. */
+const ACTIVE_TURN_TRANSCRIPT_ASSISTANT_MESSAGES = 3;
+
+/** A direct child's running turn as its waiting parent may observe it. */
+interface ObservedActiveTurn {
+  turnId: string;
+  startedAtMs: number;
+  runtime: ChildAgentRuntime;
+}
+
 interface MessageParameters {
   agent_id?: string;
   message: string;
@@ -94,6 +111,16 @@ interface PendingParentMessage {
   cancelGrace?: () => void;
 }
 
+/** One terminal result queued to its parent, until Delivery Evidence settles it or Pi discards it. */
+interface TerminalHandOff {
+  /** Hand-off order, compared with the root's last ended message at a turn boundary. */
+  order: number;
+  /** Whether the result entered Pi's clearable steer queue instead of starting a root turn. */
+  queued: boolean;
+  /** Coordination Messages batched into the same steer. */
+  coordinationDeliveryIds: readonly string[];
+}
+
 function agentDeliveryKey(agentId: string, turnId: string): string {
   return `${agentId}\u0000${turnId}`;
 }
@@ -147,9 +174,18 @@ 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 automaticDeliveryKeys = new Set<string>();
+  /** In-flight automatic result hand-offs, each with the lifecycle epoch that owns it. */
+  private readonly automaticDeliveryKeys = new Map<string, number>();
   private readonly automaticCoordinationDeliveryIds = new Set<string>();
   private readonly waitHandedDeliveryIds = new Set<string>();
+  /** Terminal results already queued to their parent, until Delivery Evidence settles them. */
+  private readonly handedTerminalKeys = new Map<string, TerminalHandOff>();
+  /** Monotonic order of hand-offs, compared against the root's last ended message. */
+  private handOffOrder = 0;
+  /** The latest hand-off order a root `message_end` has seen; later hand-offs may postdate Pi's queue snapshot. */
+  private rootMessageEndOrder = 0;
+  /** Root results Pi discarded, awaiting the root's next run; each keeps its Delivery Ledger sequence. */
+  private readonly discardedRootResultKeys = new Set<string>();
   private readonly backgroundOperations = new Set<Promise<void>>();
   private acceptingOperations = true;
   private lifecycleEpoch = 0;
@@ -197,16 +233,20 @@ export class MinimalSubagentsCoordinator {
     this.validateFriendlyId(friendlyId);
     const agentId = this.buildChildAgentId(callerId, friendlyId);
     if (this.tombstones.has(agentId)) {
-      throw new Error(`Minimal subagents agent ID is tombstoned: ${agentId}`);
+      throw new Error(
+        `Minimal subagents agent ID ${agentId} belonged to a deleted agent and cannot be reused; choose a different agent_id`,
+      );
     }
     if (this.agents.has(agentId) || this.pendingAgentIds.has(agentId)) {
       throw new Error(`Minimal subagents duplicate agent ID: ${agentId}`);
     }
 
-    const sessionContext = parameters.session_context ?? "inherit";
+    const sessionContext = parameters.session_context ?? "omit";
     const projectContext = parameters.project_context ?? "inherit";
-    const model = parameters.model ?? caller.model;
-    const requestedThinking = parameters.thinking_level ?? caller.thinkingLevel;
+    const role = parameters.role === undefined ? undefined : this.requireModelRole(parameters.role);
+    const model = parameters.model ?? role?.model ?? caller.model;
+    const requestedThinking =
+      parameters.thinking_level ?? role?.thinkingLevel ?? caller.thinkingLevel;
     const thinkingLevel = this.dependencies.sessions.resolveThinkingLevel(model, requestedThinking);
     const {
       ordinaryTools,
@@ -218,7 +258,7 @@ export class MinimalSubagentsCoordinator {
       toolsets: this.dependencies.toolsets,
     });
     const committedMessages = structuredClone(caller.messages);
-    const imported = assembleImportedContext(sessionContext, committedMessages);
+    const imported = assembleImportedContext(sessionContext, committedMessages, callerId);
     if (
       contextContainsImages(imported.messages) &&
       !this.dependencies.sessions.modelSupportsImages(model)
@@ -251,6 +291,8 @@ export class MinimalSubagentsCoordinator {
       missing_dependencies: [],
       recent_messages: [],
     };
+    // Added after `delegation`, matching the key order of replayed Launch Contracts.
+    if (role) agent.launch_contract.role = role.name;
     this.pendingAgentIds.add(agentId);
     let identity: ReturnType<AgentSessionFactory["createIdentity"]>;
     try {
@@ -296,11 +338,12 @@ export class MinimalSubagentsCoordinator {
       createRegistryEvent(this.dependencies.registry.rootSessionId, "agent-created", { agent }),
     );
     const turnId = this.beginTurn(agent);
-    if (toolWarnings.length > 0) {
+    const warnings = [...new Set(toolWarnings)];
+    if (warnings.length > 0) {
       this.dependencies.notify?.({
         type: "tool-warning",
         agentId,
-        message: `Minimal subagents tool warnings for ${agentId}:\n- ${[...new Set(toolWarnings)].join("\n- ")}`,
+        message: `Minimal subagents tool warnings for ${agentId}:\n- ${warnings.join("\n- ")}`,
       });
     }
     this.dependencies.notify?.({
@@ -313,13 +356,38 @@ export class MinimalSubagentsCoordinator {
       this.initializeAndRunPrompt(
         agentId,
         turnId,
-        parameters.task,
+        imported.messages.length > 0
+          ? buildInheritedContextTaskPrompt(parameters.task, agentId, callerId)
+          : parameters.task,
         imported.compact,
         caller.model,
         caller.thinkingLevel,
       ),
     );
-    return { agent_id: agentId, turn_id: turnId, status: "running" };
+    const result: SpawnResult = {
+      agent_id: agentId,
+      turn_id: turnId,
+      status: "running",
+      model: agent.launch_contract.model,
+      thinking_level: agent.launch_contract.thinking_level,
+      tools: [...agent.launch_contract.ordinary_tools],
+      delegation: agent.launch_contract.delegation ?? "none",
+    };
+    if (warnings.length > 0) result.warnings = warnings;
+    return result;
+  }
+
+  private requireModelRole(name: string): MinimalSubagentsModelRole {
+    const roles = this.dependencies.modelRoles ?? [];
+    const role = roles.find((candidate) => candidate.name === name);
+    if (role) return role;
+    throw new Error(
+      `Minimal subagents spawn validation: unknown role ${JSON.stringify(name)}; ${
+        roles.length === 0
+          ? "no model roles are configured"
+          : `configured roles: ${roles.map((candidate) => candidate.name).join(", ")}`
+      }`,
+    );
   }
 
   /** Capture immutable launch defaults for a nested caller from its active child runtime. */
@@ -365,10 +433,12 @@ export class MinimalSubagentsCoordinator {
         this.queuePendingParentMessage(targetId, message, delivery);
         return { agent_id: targetId, message_id: messageId, disposition: "queued" };
       }
-      const disposition = await this.enqueueRecipientDelivery(targetId, async () =>
+      const { disposition, turnId } = await this.enqueueRecipientDelivery(targetId, async () =>
         this.deliverExplicitMessage(message, targetId, delivery),
       );
-      return { agent_id: targetId, message_id: messageId, disposition };
+      const result: AgentMessageResult = { agent_id: targetId, message_id: messageId, disposition };
+      if (turnId) result.turn_id = turnId;
+      return result;
     } catch (error) {
       const deliveryError = error instanceof Error ? error.message : String(error);
       if (this.isCoordinationDeliveryCurrent(delivery)) {
@@ -423,7 +493,9 @@ export class MinimalSubagentsCoordinator {
     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}`),
+        new Error(
+          `Minimal subagents wait: turn ${turnId} is unknown or no longer retained for ${agentId}; omit turn_id to wait for its oldest observable turn you have neither claimed nor received`,
+        ),
       );
     }
 
@@ -460,11 +532,11 @@ export class MinimalSubagentsCoordinator {
     });
   }
 
-  /** Return direct-child status authorized for one root or child caller. */
+  /** Return direct-child status for a child caller; the root may inspect any descendant. */
   status(callerId: string, agentId?: string): StatusResult {
     this.assertCallerExists(callerId);
     if (agentId !== undefined) {
-      this.assertCallerTargetsDirectChild(callerId, agentId, "status");
+      if (callerId !== "root") this.assertCallerTargetsDirectChild(callerId, agentId, "status");
       return { agent: this.buildAgentDetail(this.requireAgent(agentId), false) };
     }
     return {
@@ -482,6 +554,56 @@ export class MinimalSubagentsCoordinator {
     };
   }
 
+  /**
+   * Find a direct child's running turn for its parent's live wait view. Only the direct parent
+   * observes it, and a requested `turnId` must be the active turn.
+   */
+  private observeActiveTurn(
+    callerId: string,
+    agentId: string,
+    turnId: string | undefined,
+  ): ObservedActiveTurn | undefined {
+    const agent = this.agents.get(agentId);
+    if (!agent || agent.parent_id !== callerId) return undefined;
+    const activeTurnId = agent.active_turn_id;
+    const startedAt = agent.active_turn_started_at;
+    if (!activeTurnId || !startedAt || (turnId !== undefined && turnId !== activeTurnId)) {
+      return undefined;
+    }
+    const runtime = this.runtimes.get(agentId);
+    if (!runtime) return undefined;
+    return { turnId: activeTurnId, startedAtMs: Date.parse(startedAt), runtime };
+  }
+
+  /** Count a direct child's running-turn tool calls for its waiting parent. */
+  previewActiveTurn(
+    callerId: string,
+    agentId: string,
+    turnId?: string,
+  ): ActiveTurnProgress | undefined {
+    const turn = this.observeActiveTurn(callerId, agentId, turnId);
+    if (!turn) return undefined;
+    return {
+      turn_id: turn.turnId,
+      ...buildActiveTurnProgress(turn.runtime.snapshotActivityMessages(), turn.startedAtMs),
+    };
+  }
+
+  /** Return a direct child's Active Turn Tail, with its tool definitions, for its waiting parent. */
+  inspectActiveTurnTranscript(
+    callerId: string,
+    agentId: string,
+    turnId?: string,
+  ): ChildAgentTranscriptSnapshot | undefined {
+    const turn = this.observeActiveTurn(callerId, agentId, turnId);
+    if (!turn) return undefined;
+    return selectActiveTurnTranscript(
+      this.inspectTranscript(agentId),
+      turn.startedAtMs,
+      ACTIVE_TURN_TRANSCRIPT_ASSISTANT_MESSAGES,
+    );
+  }
+
   /** Lazily inspect one Child Session Transcript without restoring a missing runtime. */
   inspectTranscript(agentId: string): ChildAgentTranscriptSnapshot {
     const agent = this.requireAgent(agentId);
@@ -528,15 +650,18 @@ export class MinimalSubagentsCoordinator {
     this.assertCallerCanManageAgent(callerId, agentId, "cancel");
     const target = this.requireUsableAgent(agentId, "cancel");
     const affected = recursive ? [target, ...this.descendantsOf(agentId)] : [target];
+    const affectedAgentIds: string[] = [];
     const cancelledTurnIds: string[] = [];
     for (const agent of affected) {
       const cancelledTurnId = await this.cancelActiveTurn(agent);
-      if (cancelledTurnId) cancelledTurnIds.push(cancelledTurnId);
+      if (!cancelledTurnId) continue;
+      affectedAgentIds.push(agent.agent_id);
+      cancelledTurnIds.push(cancelledTurnId);
     }
     return {
       agent_id: agentId,
       recursive,
-      affected_agent_ids: affected.map((agent) => agent.agent_id),
+      affected_agent_ids: affectedAgentIds,
       cancelled_turn_ids: cancelledTurnIds,
     };
   }
@@ -633,6 +758,8 @@ export class MinimalSubagentsCoordinator {
     this.waiters.clear();
     this.waitHandedDeliveryIds.clear();
     this.automaticDeliveryKeys.clear();
+    this.handedTerminalKeys.clear();
+    this.discardedRootResultKeys.clear();
     this.automaticCoordinationDeliveryIds.clear();
     this.deliveryLedger = createDeliveryLedger({
       deliveries: snapshot.deliveries,
@@ -777,6 +904,102 @@ export class MinimalSubagentsCoordinator {
     await Promise.allSettled(scheduled);
   }
 
+  /** Note that a root message ended; results handed before it reached Pi's queue before the next turn boundary. */
+  recordRootMessageEnd(): void {
+    this.rootMessageEndOrder = this.handOffOrder;
+  }
+
+  /**
+   * Release results Pi discarded from the root's steer queue, as Esc does.
+   *
+   * Call only at a root turn boundary whose pending-message snapshot is empty. Pi persists a
+   * consumed steer before that boundary, so a queued result handed before the turn's last message
+   * either has Delivery Evidence and settles, or was discarded. A discarded result is selectable
+   * by a default wait again at once, with its batched Coordination Messages; automatic fallback
+   * re-sends it when the root's next run starts (`deliverDiscardedRootResults`).
+   */
+  requeueDiscardedRootResults(): void {
+    if (!this.acceptingOperations) return;
+    const candidates = this.deliveryLedger.terminalDeliveries
+      .filter((delivery) => {
+        if (delivery.destination_agent_id !== "root") return false;
+        const handOff = this.handedTerminalKeys.get(
+          deliveryTurnKey(delivery.source_agent_id, delivery.source_turn_id),
+        );
+        return handOff?.queued === true && handOff.order <= this.rootMessageEndOrder;
+      })
+      .sort(
+        (left, right) =>
+          (left.sequence ?? Number.MAX_SAFE_INTEGER) - (right.sequence ?? Number.MAX_SAFE_INTEGER),
+      );
+
+    for (const delivery of candidates) {
+      const handedKey = deliveryTurnKey(delivery.source_agent_id, delivery.source_turn_id);
+      const handOff = this.handedTerminalKeys.get(handedKey);
+      if (!handOff) continue;
+      const batched = handOff.coordinationDeliveryIds.flatMap((deliveryId) => {
+        const item = findCoordinationDelivery(this.deliveryLedger, deliveryId);
+        return item ? [item] : [];
+      });
+      if (this.hasDeliveryEvidence(delivery)) {
+        for (const item of batched) {
+          if (this.hasCoordinationDeliveryEvidence(item)) this.settleCoordinationDelivery(item);
+        }
+        this.settleDelivery(delivery);
+        continue;
+      }
+
+      this.handedTerminalKeys.delete(handedKey);
+      this.discardedRootResultKeys.add(handedKey);
+      for (const item of batched) {
+        this.waitHandedDeliveryIds.delete(item.delivery_id);
+        this.queuePendingParentMessage("root", item.message, item);
+      }
+    }
+  }
+
+  /** Whether a root result waits in Pi's clearable steer queue, so turn boundaries must be watched. */
+  hasQueuedRootHandOffs(): boolean {
+    for (const handOff of this.handedTerminalKeys.values()) if (handOff.queued) return true;
+    return false;
+  }
+
+  /**
+   * Queue results Pi discarded into a root run that just started, in Delivery Ledger sequence.
+   *
+   * Recovery never starts a root turn by itself, so Esc stays respected: the results wait, still
+   * selectable by a default wait, until the user or another delivery starts the root's next run.
+   */
+  deliverDiscardedRootResults(): void {
+    if (
+      this.discardedRootResultKeys.size === 0 ||
+      !this.acceptingOperations ||
+      this.dependencies.root.isIdle()
+    )
+      return;
+    const discarded = this.deliveryLedger.terminalDeliveries
+      .filter((delivery) =>
+        this.discardedRootResultKeys.has(
+          deliveryTurnKey(delivery.source_agent_id, delivery.source_turn_id),
+        ),
+      )
+      .sort(
+        (left, right) =>
+          (left.sequence ?? Number.MAX_SAFE_INTEGER) - (right.sequence ?? Number.MAX_SAFE_INTEGER),
+      );
+    this.discardedRootResultKeys.clear();
+    for (const delivery of discarded) {
+      const result = delivery.result ?? this.agents.get(delivery.source_agent_id)?.latest_result;
+      if (
+        delivery.path !== "message" ||
+        result?.status !== "completed" ||
+        result.turn_id !== delivery.source_turn_id
+      )
+        continue;
+      this.trackBackgroundOperation(this.deliverAutomaticResult(result, delivery, true));
+    }
+  }
+
   /** 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");
@@ -1070,17 +1293,27 @@ export class MinimalSubagentsCoordinator {
     if (result.status !== "completed") this.removeSettledEmptyTurnClaim(agent.agent_id, turnId);
   }
 
+  /**
+   * Hand one terminal result to its parent through automatic fallback.
+   *
+   * By default it waits its turn in the recipient queue, then the wait-claim grace period. A
+   * `resume` hand-off re-sends a root result Pi discarded: its grace period has passed and its
+   * sequence precedes everything still queued, so it is handed at once, synchronously up to Pi.
+   */
   private async deliverAutomaticResult(
     result: TurnResult,
     delivery: PersistedDelivery,
+    resume = false,
   ): Promise<void> {
     const deliveryKey = agentDeliveryKey(delivery.source_agent_id, delivery.source_turn_id);
+    const handedKey = deliveryTurnKey(delivery.source_agent_id, delivery.source_turn_id);
     if (this.automaticDeliveryKeys.has(deliveryKey)) return;
-    this.automaticDeliveryKeys.add(deliveryKey);
-    const graceMs = this.deliveryGraceMs();
+    const epoch = this.lifecycleEpoch;
+    this.automaticDeliveryKeys.set(deliveryKey, epoch);
+    const graceMs = resume ? 0 : this.deliveryGraceMs();
     let batchedCoordinationDeliveries: PersistedCoordinationDelivery[] = [];
     try {
-      await this.enqueueRecipientDelivery(delivery.destination_agent_id, async () => {
+      const handOff = async () => {
         if (delivery.destination_agent_id !== "root") {
           await this.ensureRuntime(
             this.requireUsableAgent(delivery.destination_agent_id, "message"),
@@ -1088,6 +1321,8 @@ export class MinimalSubagentsCoordinator {
           if (!this.isTerminalDeliveryCurrent(delivery)) return;
         }
         if (graceMs > 0) await new Promise((resolve) => setTimeout(resolve, graceMs));
+        // A branch change during the grace period abandons this hand-off; restore replays it.
+        if (epoch !== this.lifecycleEpoch) return;
         if (!this.acceptingOperations || this.shouldStopAutomaticTerminalDelivery(delivery)) return;
         if (this.hasDeliveryEvidence(delivery)) {
           this.settleDelivery(delivery);
@@ -1113,6 +1348,13 @@ export class MinimalSubagentsCoordinator {
         for (const batchedDelivery of batchedCoordinationDeliveries) {
           this.waitHandedDeliveryIds.add(batchedDelivery.delivery_id);
         }
+        // Installed before delivery so a settlement inside it removes the marker. Delivery up to
+        // Pi's `sendMessage` is synchronous, so the idle check predicts a steer versus a new turn.
+        this.handedTerminalKeys.set(handedKey, {
+          order: ++this.handOffOrder,
+          queued: delivery.destination_agent_id === "root" && !this.dependencies.root.isIdle(),
+          coordinationDeliveryIds: batchedCoordinationDeliveries.map((item) => item.delivery_id),
+        });
         await this.deliverToRecipient(
           delivery.destination_agent_id,
           combineCoordinatorMessages([
@@ -1123,8 +1365,14 @@ export class MinimalSubagentsCoordinator {
             this.isTerminalDeliveryCurrent(delivery) &&
             batchedCoordinationDeliveries.every((item) => this.isCoordinationDeliveryCurrent(item)),
         );
-      });
+      };
+      await (resume
+        ? handOff()
+        : this.enqueueRecipientDelivery(delivery.destination_agent_id, handOff));
     } catch (error) {
+      // A hand-off abandoned by a branch change must not touch the restored branch's state.
+      if (epoch !== this.lifecycleEpoch) return;
+      this.handedTerminalKeys.delete(handedKey);
       for (const batchedDelivery of batchedCoordinationDeliveries) {
         this.waitHandedDeliveryIds.delete(batchedDelivery.delivery_id);
       }
@@ -1144,7 +1392,10 @@ export class MinimalSubagentsCoordinator {
         }),
       );
     } finally {
-      this.automaticDeliveryKeys.delete(deliveryKey);
+      // Restore's replay may own the key again; release it only from the call that holds it.
+      if (this.automaticDeliveryKeys.get(deliveryKey) === epoch) {
+        this.automaticDeliveryKeys.delete(deliveryKey);
+      }
     }
   }
 
@@ -1230,6 +1481,7 @@ export class MinimalSubagentsCoordinator {
       sourceAgentId,
       destinationAgentId,
       waitHandedDeliveryIds: this.waitHandedDeliveryIds,
+      handedTurnKeys: this.handedTerminalKeys,
       activeTurnId: agent?.active_turn_id,
       latestResultTurnId: agent?.latest_result?.turn_id,
     });
@@ -1315,24 +1567,27 @@ export class MinimalSubagentsCoordinator {
     message: CoordinatorMessage,
     targetId: string,
     delivery: PersistedCoordinationDelivery,
-  ): Promise<AgentMessageDisposition> {
+  ): Promise<{ disposition: AgentMessageDisposition; turnId?: string }> {
     this.waitHandedDeliveryIds.add(delivery.delivery_id);
     try {
-      await this.deliverToRecipient(targetId, message, () =>
+      const startedTurnId = await this.deliverToRecipient(targetId, message, () =>
         this.isCoordinationDeliveryCurrent(delivery),
       );
-      return "queued";
+      return startedTurnId
+        ? { disposition: "started-turn", turnId: startedTurnId }
+        : { disposition: "queued" };
     } catch (error) {
       this.waitHandedDeliveryIds.delete(delivery.delivery_id);
       throw error;
     }
   }
 
+  /** Deliver one message, returning the turn ID when it starts a new turn on an idle child. */
   private async deliverToRecipient(
     targetId: string,
     message: CoordinatorMessage,
     isCurrentDelivery: () => boolean = () => true,
-  ): Promise<void> {
+  ): Promise<string | undefined> {
     if (!isCurrentDelivery()) {
       throw new Error("Minimal subagents delivery abandoned after session branch change");
     }
@@ -1352,7 +1607,7 @@ export class MinimalSubagentsCoordinator {
     const visibleMessage = addCoordinatorMessageEnvelope(message);
     if (target.active_turn_id || runtime.isRunning) {
       await runtime.queueCoordinatorMessage(visibleMessage);
-      return;
+      return undefined;
     }
     const turnId = this.beginTurn(target);
     const runMessage = runtime
@@ -1374,6 +1629,7 @@ export class MinimalSubagentsCoordinator {
         }
       });
     this.trackBackgroundOperation(runMessage);
+    return turnId;
   }
 
   private trackBackgroundOperation(operation: Promise<void>): void {
@@ -1441,6 +1697,19 @@ export class MinimalSubagentsCoordinator {
         }),
       );
     }
+    this.dropStaleHandedTerminalKeys();
+  }
+
+  /** Forget handed markers whose terminal delivery left the ledger by settlement, pruning, or deletion. */
+  private dropStaleHandedTerminalKeys(): void {
+    const pending = new Set(
+      this.deliveryLedger.terminalDeliveries.map((delivery) =>
+        deliveryTurnKey(delivery.source_agent_id, delivery.source_turn_id),
+      ),
+    );
+    for (const key of this.handedTerminalKeys.keys()) {
+      if (!pending.has(key)) this.handedTerminalKeys.delete(key);
+    }
   }
 
   private isTerminalDeliveryCurrent(delivery: PersistedDelivery): boolean {
@@ -1516,6 +1785,7 @@ export class MinimalSubagentsCoordinator {
       delivery.source_agent_id,
       delivery.source_turn_id,
     ).ledger;
+    this.dropStaleHandedTerminalKeys();
     this.dependencies.registry.append(
       createRegistryEvent(this.dependencies.registry.rootSessionId, "delivery-settled", {
         source_agent_id: delivery.source_agent_id,
@@ -1527,9 +1797,6 @@ export class MinimalSubagentsCoordinator {
 
   private buildAgentSummary(agent: PersistedAgent, includeDescendants = true): AgentSummary {
     const directChildren = this.childrenOf(agent.agent_id);
-    const children = includeDescendants
-      ? directChildren.map((child) => this.buildAgentSummary(child))
-      : [];
     const elapsed = agent.active_turn_started_at
       ? Math.max(0, this.now().getTime() - new Date(agent.active_turn_started_at).getTime())
       : undefined;
@@ -1538,7 +1805,7 @@ export class MinimalSubagentsCoordinator {
       model: agent.launch_contract.model,
       thinking_level: agent.launch_contract.thinking_level,
     };
-    return {
+    const summary: AgentSummary = {
       agent_id: agent.agent_id,
       parent_id: agent.parent_id,
       state: agent.active_turn_id ? "running" : "idle",
@@ -1553,8 +1820,11 @@ export class MinimalSubagentsCoordinator {
       latest_activity_at: agent.latest_activity_at ?? agent.created_at,
       task: agent.task,
       child_count: directChildren.length,
-      children,
     };
+    if (includeDescendants) {
+      summary.children = directChildren.map((child) => this.buildAgentSummary(child));
+    }
+    return summary;
   }
 
   private buildAgentDetail(agent: PersistedAgent, includeDescendants = true): AgentDetail {
@@ -1581,6 +1851,7 @@ export class MinimalSubagentsCoordinator {
   private pruneDeliveryStateForDeletedAgent(agentId: string): void {
     const previousCoordinationDeliveries = this.deliveryLedger.coordinationDeliveries;
     this.deliveryLedger = pruneDeliveryLedgerAgents(this.deliveryLedger, [agentId]).ledger;
+    this.dropStaleHandedTerminalKeys();
     for (const delivery of previousCoordinationDeliveries) {
       if (!this.isCoordinationDeliveryCurrent(delivery)) {
         this.waitHandedDeliveryIds.delete(delivery.delivery_id);

package/src/minimal-subagents-delivery-ledger.ts

@@ -45,16 +45,19 @@ export interface AddedCoordinationDelivery extends DeliveryLedgerTransition {
   delivery: PersistedCoordinationDelivery;
 }
 
-/** Describes caller-visible inputs used to select the oldest observable source turn. */
+/** Describes caller-visible inputs used to select the oldest observable source turn the destination has neither claimed nor received. */
 export interface SelectObservableDeliveryTurnOptions {
   sourceAgentId: string;
   destinationAgentId: string;
   waitHandedDeliveryIds: ReadonlySet<string>;
+  /** `deliveryTurnKey`s of terminal results already queued to the destination automatically. */
+  handedTurnKeys?: { has(key: string): boolean };
   activeTurnId?: string;
   latestResultTurnId?: string;
 }
 
-function deliveryTurnKey(sourceAgentId: string, sourceTurnId: string): string {
+/** Compound source-agent and source-turn key shared by claims and process-local handed markers. */
+export function deliveryTurnKey(sourceAgentId: string, sourceTurnId: string): string {
   return `${sourceAgentId}\u0000${sourceTurnId}`;
 }
 
@@ -420,19 +423,20 @@ export function releaseEmptyDeliveryLedgerTurn(
     : releaseDeliveryLedgerTurn(ledger, sourceAgentId, sourceTurnId);
 }
 
-/** Select the oldest claimed, then oldest sequenced, observable source turn. */
+/**
+ * Select the oldest sequenced observable source turn whose terminal result the caller has neither
+ * claimed nor been handed automatically, falling back to the active, then latest, turn.
+ */
 export function selectObservableDeliveryTurn(
   ledger: DeliveryLedger,
   options: SelectObservableDeliveryTurnOptions,
 ): string | undefined {
-  const candidates = new Map<string, { claimed: boolean; sequence: number }>();
+  const candidates = new Map<string, number>();
   const addCandidate = (turnId: string, sequence: number) => {
-    const candidate = {
-      claimed: ledger.waitClaimedTurns.includes(deliveryTurnKey(options.sourceAgentId, turnId)),
-      sequence,
-    };
+    const turnKey = deliveryTurnKey(options.sourceAgentId, turnId);
+    if (ledger.waitClaimedTurns.includes(turnKey) || options.handedTurnKeys?.has(turnKey)) return;
     const existing = candidates.get(turnId);
-    if (!existing || sequence < existing.sequence) candidates.set(turnId, candidate);
+    if (existing === undefined || sequence < existing) candidates.set(turnId, sequence);
   };
   for (const delivery of ledger.coordinationDeliveries) {
     if (
@@ -451,10 +455,7 @@ export function selectObservableDeliveryTurn(
       addCandidate(delivery.source_turn_id, delivery.sequence ?? Number.MAX_SAFE_INTEGER);
     }
   }
-  const retained = [...candidates.entries()].sort((left, right) => {
-    if (left[1].claimed !== right[1].claimed) return left[1].claimed ? -1 : 1;
-    return left[1].sequence - right[1].sequence;
-  })[0]?.[0];
+  const retained = [...candidates.entries()].sort((left, right) => left[1] - right[1])[0]?.[0];
   return retained ?? options.activeTurnId ?? options.latestResultTurnId;
 }