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

package/src/minimal-subagents-coordinator.ts

@@ -1,5 +1,4 @@
 import { randomUUID } from "node:crypto";
-import type { AgentMessage } from "@earendil-works/pi-agent-core";
 import { assembleImportedContext, contextContainsImages } from "./minimal-subagents-context.js";
 import {
   canAgentContractSpawn,
@@ -8,9 +7,32 @@ import {
   getSubagentDepth,
   resolveOrdinaryToolSelection,
 } from "./minimal-subagents-capabilities.js";
+import {
+  addCoordinationDelivery,
+  addTerminalDelivery,
+  claimDeliveryLedgerTurn,
+  createDeliveryLedger,
+  deliveryLedgerSnapshot,
+  findCoordinationDelivery,
+  findTerminalDelivery,
+  isDeliveryLedgerTurnClaimed,
+  pruneDeliveryLedgerAgents,
+  releaseEmptyDeliveryLedgerTurn,
+  selectObservableDeliveryTurn,
+  setCoordinationDeliveryError,
+  setCoordinationDeliveryPath,
+  setTerminalDeliveryError,
+  setTerminalDeliveryPath,
+  settleCoordinationDelivery,
+  settleTerminalDelivery,
+  type DeliveryLedger,
+  type DeliveryLedgerTransition,
+} from "./minimal-subagents-delivery-ledger.js";
+import { addCoordinatorMessageEnvelope } from "./minimal-subagents-message-envelope.js";
 import { createRegistryEvent } from "./minimal-subagents-registry.js";
 import type {
   AgentDetail,
+  AgentMessageDisposition,
   AgentMessageResult,
   AgentSessionFactory,
   AgentSummary,
@@ -23,6 +45,7 @@ import type {
   ForkSnapshot,
   HierarchyStatusResult,
   PersistedAgent,
+  PersistedCoordinationDelivery,
   PersistedDelivery,
   RegistrySnapshot,
   SpawnParameters,
@@ -30,6 +53,7 @@ import type {
   StatusResult,
   TurnId,
   TurnResult,
+  WaitResult,
 } from "./minimal-subagents-types.js";
 
 const FRIENDLY_AGENT_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
@@ -44,13 +68,28 @@ interface MessageParameters {
 
 interface TurnWaiter {
   callerId: string;
-  resolve: (result: TurnResult) => void;
+  resolve: (result: WaitResult) => void;
   reject: (error: Error) => void;
   timeout?: ReturnType<typeof setTimeout>;
   abortSignal?: AbortSignal;
   abortListener?: () => void;
 }
 
+interface PendingParentMessage {
+  deliveryId: string;
+  message: CoordinatorMessage;
+  destinationAgentId: string;
+  claimed: boolean;
+  claimPromise: Promise<void>;
+  releaseClaim: () => void;
+  cancelGrace?: () => void;
+}
+
+interface CancelableWait {
+  promise: Promise<void>;
+  cancel: () => void;
+}
+
 function agentDeliveryKey(agentId: string, turnId: string): string {
   return `${agentId}\u0000${turnId}`;
 }
@@ -70,19 +109,29 @@ function terminalTurnResult(
   };
 }
 
+function terminalWaitResult(result: TurnResult): WaitResult {
+  return { event: "turn", ...structuredClone(result) };
+}
+
 /** One root-owned coordinator for persistent nested Pi child sessions. */
 export class MinimalSubagentsCoordinator {
   private readonly agents = new Map<string, PersistedAgent>();
   private readonly runtimes = new Map<string, ChildAgentRuntime>();
   private readonly runtimeInitializations = new Map<string, Promise<ChildAgentRuntime>>();
-  private readonly importedMessages = new Map<string, AgentMessage[]>();
   private readonly tombstones = new Set<string>();
   private readonly pendingAgentIds = new Set<string>();
-  private readonly deliveries = new Map<string, PersistedDelivery>();
+  private deliveryLedger: DeliveryLedger = createDeliveryLedger();
   private readonly waiters = new Map<string, Set<TurnWaiter>>();
-  private readonly recipientQueues = new Map<string, Promise<void>>();
+  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;
   private shutdownPromise?: Promise<void>;
 
   constructor(private readonly dependencies: CoordinatorDependencies) {}
@@ -93,10 +142,11 @@ export class MinimalSubagentsCoordinator {
 
   /** Return a serializable complete hierarchy checkpoint without process-local runtimes. */
   snapshot(): RegistrySnapshot {
+    const ledger = deliveryLedgerSnapshot(this.deliveryLedger);
     return {
       agents: [...this.agents.values()].map((agent) => structuredClone(agent)),
       tombstones: [...this.tombstones],
-      deliveries: [...this.deliveries.values()].map((delivery) => structuredClone(delivery)),
+      ...ledger,
     };
   }
 
@@ -191,10 +241,15 @@ export class MinimalSubagentsCoordinator {
     } finally {
       this.pendingAgentIds.delete(agentId);
     }
+    if (!identity.sessionLeafId) {
+      throw new Error(
+        `Minimal subagents persistent identity: no selected session leaf for ${agent.agent_id}`,
+      );
+    }
     agent.session_file = identity.sessionFile;
     agent.session_id = identity.sessionId;
+    agent.session_leaf_id = identity.sessionLeafId;
     this.agents.set(agentId, agent);
-    this.importedMessages.set(agentId, imported.messages);
     this.dependencies.registry.append(
       createRegistryEvent(this.dependencies.registry.rootSessionId, "agent-created", { agent }),
     );
@@ -233,7 +288,7 @@ export class MinimalSubagentsCoordinator {
     };
   }
 
-  /** Send one steer-only coordination message to an authorized adjacent agent. */
+  /** Send one coordination message to an authorized adjacent agent. */
   async sendAgentMessage(
     callerId: string,
     parameters: MessageParameters,
@@ -242,39 +297,88 @@ export class MinimalSubagentsCoordinator {
     this.assertAccepting();
     this.assertCallerExists(callerId);
     const targetId = this.resolveMessageTarget(callerId, parameters.agent_id);
+    const messageId = randomUUID();
+    const message = this.createExplicitMessage(
+      callerId,
+      targetId,
+      sourceTurnId,
+      messageId,
+      parameters.message,
+    );
+    const sourceAgent = callerId === "root" ? undefined : this.requireAgent(callerId);
+    const sentToDirectParent = sourceAgent?.parent_id === targetId;
+    const delivery = this.persistCoordinationDelivery(message, targetId);
     try {
-      await this.enqueueRecipientDelivery(targetId, async () => {
-        await this.deliverExplicitMessage(callerId, targetId, sourceTurnId, parameters.message);
-      });
-      return { agent_id: targetId, delivered: true };
+      this.recordRecentMessage(targetId, message);
+      if (sentToDirectParent) {
+        if (this.resolveWaiterWithMessage(message, delivery)) {
+          return { agent_id: targetId, message_id: messageId, disposition: "delivered-via-wait" };
+        }
+        this.queuePendingParentMessage(targetId, message, delivery);
+        return { agent_id: targetId, message_id: messageId, disposition: "queued" };
+      }
+      const disposition = await this.enqueueRecipientDelivery(targetId, async () =>
+        this.deliverExplicitMessage(message, targetId, delivery),
+      );
+      return { agent_id: targetId, message_id: messageId, disposition };
     } catch (error) {
+      const deliveryError = error instanceof Error ? error.message : String(error);
+      if (this.isCoordinationDeliveryCurrent(delivery)) {
+        this.deliveryLedger = setCoordinationDeliveryError(
+          this.deliveryLedger,
+          delivery.delivery_id,
+          deliveryError,
+        );
+        const current = findCoordinationDelivery(this.deliveryLedger, delivery.delivery_id);
+        if (current) this.persistCoordinationDeliveryState(current);
+      }
       return {
         agent_id: targetId,
-        delivered: false,
-        error: error instanceof Error ? error.message : String(error),
+        message_id: messageId,
+        disposition: "failed",
+        error: deliveryError,
       };
     }
   }
 
-  /** Wait for the exact active turn captured at invocation, or return the latest idle result. */
+  /** Wait for one exact turn and claim its message/result delivery from automatic fallback. */
   wait(
     callerId: string,
     agentId: string,
     timeoutMs?: number,
     signal?: AbortSignal,
-  ): Promise<TurnResult> {
+    requestedTurnId?: string,
+  ): Promise<WaitResult> {
     this.assertAccepting();
     this.assertCallerExists(callerId);
     this.assertCallerTargetsDirectChild(callerId, agentId, "wait");
     const agent = this.requireUsableAgent(agentId, "wait");
-    if (!agent.active_turn_id) {
-      if (agent.latest_result) return Promise.resolve(structuredClone(agent.latest_result));
+    const turnId = requestedTurnId ?? this.selectObservableTurnId(agentId, callerId);
+    if (!turnId) {
       return Promise.reject(new Error(`Minimal subagents wait: ${agentId} has no turn to observe`));
     }
-    const turnId = agent.active_turn_id;
     const key = agentDeliveryKey(agentId, turnId);
+    if ([...(this.waiters.get(key) ?? [])].some((waiter) => waiter.callerId === callerId)) {
+      return Promise.reject(
+        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) {
+      this.claimTerminalDelivery(callerId, retainedResult);
+      return Promise.resolve(terminalWaitResult(retainedResult));
+    }
+    if (agent.active_turn_id !== turnId) {
+      return Promise.reject(
+        new Error(`Minimal subagents wait: turn ${turnId} is no longer retained for ${agentId}`),
+      );
+    }
 
-    return new Promise<TurnResult>((resolve, reject) => {
+    return new Promise<WaitResult>((resolve, reject) => {
       const waiter: TurnWaiter = { callerId, resolve, reject, abortSignal: signal };
       let turnWaiters = this.waiters.get(key);
       if (!turnWaiters) {
@@ -394,11 +498,12 @@ export class MinimalSubagentsCoordinator {
         runtime?.dispose();
         this.runtimes.delete(agent.agent_id);
         if (agent.session_file) {
-          await this.dependencies.sessions.trashSessionFile(agent.session_file);
+          await this.dependencies.sessions.trashSession(agent);
           result.trashed_session_files.push(agent.session_file);
         }
         this.agents.delete(agent.agent_id);
-        this.importedMessages.delete(agent.agent_id);
+        this.pruneDeliveryStateForDeletedAgent(agent.agent_id);
+        this.pruneRecentMessageProjectionsForDeletedAgent(agent.agent_id);
         this.tombstones.add(agent.agent_id);
         result.deleted_agent_ids.push(agent.agent_id);
         result.tombstoned_agent_ids.push(agent.agent_id);
@@ -411,10 +516,7 @@ export class MinimalSubagentsCoordinator {
         failedAncestors.add(agent.agent_id);
         if (runtime && agent.session_file) {
           try {
-            this.runtimes.set(
-              agent.agent_id,
-              await this.dependencies.sessions.restoreRuntime(agent),
-            );
+            this.runtimes.set(agent.agent_id, await this.dependencies.sessions.openRuntime(agent));
           } catch (restoreError) {
             agent.availability = "unavailable";
             agent.unavailable_reason = `Deletion recovery failed: ${
@@ -433,26 +535,46 @@ export class MinimalSubagentsCoordinator {
 
   /** Restore non-deleted descendants, interrupt unfinished work, and reconcile pending successful output. */
   async restore(snapshot: RegistrySnapshot): Promise<void> {
-    for (const runtime of this.runtimes.values()) runtime.dispose();
+    const restoreEpoch = ++this.lifecycleEpoch;
+    this.rejectAllWaiters(
+      new Error("Minimal subagents wait cancelled because the session branch changed"),
+    );
+    const abandonedRuntimes = [...this.runtimes.values()];
     this.agents.clear();
+    this.deliveryLedger = createDeliveryLedger();
+    this.pendingParentMessages.clear();
+    this.releaseAllRecipientIdleWaiters();
+    this.recipientQueues.clear();
+    this.backgroundOperations.clear();
+    await Promise.allSettled(
+      abandonedRuntimes.map((runtime) => (runtime.isRunning ? runtime.abort() : Promise.resolve())),
+    );
+    for (const runtime of abandonedRuntimes) runtime.dispose();
     this.runtimes.clear();
     this.runtimeInitializations.clear();
-    this.importedMessages.clear();
     this.pendingAgentIds.clear();
     this.tombstones.clear();
-    this.deliveries.clear();
+    this.deliveryLedger = createDeliveryLedger();
     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,
+      wait_claimed_turns: snapshot.wait_claimed_turns,
+      next_delivery_sequence: snapshot.next_delivery_sequence,
+    });
     this.acceptingOperations = true;
     this.shutdownPromise = undefined;
 
     for (const agent of snapshot.agents) this.agents.set(agent.agent_id, structuredClone(agent));
     for (const tombstone of snapshot.tombstones) this.tombstones.add(tombstone);
-    for (const delivery of snapshot.deliveries) {
-      this.deliveries.set(
-        agentDeliveryKey(delivery.source_agent_id, delivery.source_turn_id),
-        structuredClone(delivery),
-      );
-    }
 
     for (const agent of this.agents.values()) {
       if (agent.active_turn_id) {
@@ -471,28 +593,41 @@ export class MinimalSubagentsCoordinator {
         });
       }
       const previousAvailability = agent.availability;
-      const missing = agent.clone_error
-        ? [agent.clone_error]
-        : await this.dependencies.sessions.resolveRestorationMissingDependencies(agent);
-      if (missing.length > 0 || !agent.session_file) {
-        agent.availability = "unavailable";
-        if (previousAvailability !== "unavailable")
-          agent.latest_activity_at = this.now().toISOString();
-        agent.missing_dependencies = missing.length > 0 ? missing : agent.missing_dependencies;
-        agent.unavailable_reason =
-          agent.clone_error ??
-          (missing.length > 0
-            ? `Missing dependencies: ${missing.join(", ")}`
-            : (agent.unavailable_reason ?? `No persistent session exists for ${agent.agent_id}`));
-        this.dependencies.notify?.({
-          type: "unavailable",
-          agentId: agent.agent_id,
-          message: `${agent.agent_id} unavailable: ${agent.unavailable_reason}`,
-        });
-        continue;
-      }
       try {
-        this.runtimes.set(agent.agent_id, await this.dependencies.sessions.restoreRuntime(agent));
+        const missing = agent.clone_error
+          ? [agent.clone_error]
+          : await this.dependencies.sessions.resolveRestorationMissingDependencies(agent);
+        if (restoreEpoch !== this.lifecycleEpoch) return;
+        if (missing.length > 0 || !agent.session_file) {
+          agent.availability = "unavailable";
+          if (previousAvailability !== "unavailable")
+            agent.latest_activity_at = this.now().toISOString();
+          agent.missing_dependencies = missing.length > 0 ? missing : agent.missing_dependencies;
+          agent.unavailable_reason =
+            agent.clone_error ??
+            (missing.length > 0
+              ? `Missing dependencies: ${missing.join(", ")}`
+              : (agent.unavailable_reason ?? `No persistent session exists for ${agent.agent_id}`));
+          this.dependencies.notify?.({
+            type: "unavailable",
+            agentId: agent.agent_id,
+            message: `${agent.agent_id} unavailable: ${agent.unavailable_reason}`,
+          });
+          continue;
+        }
+        const runtime = await this.dependencies.sessions.openRuntime(agent);
+        if (restoreEpoch !== this.lifecycleEpoch) {
+          runtime.dispose();
+          return;
+        }
+        if (!runtime.sessionLeafId) {
+          runtime.dispose();
+          throw new Error(
+            `Minimal subagents session restoration: no selected session leaf for ${agent.agent_id}`,
+          );
+        }
+        this.runtimes.set(agent.agent_id, runtime);
+        agent.session_leaf_id = runtime.sessionLeafId;
         agent.availability = "available";
         if (previousAvailability !== "available")
           agent.latest_activity_at = this.now().toISOString();
@@ -504,6 +639,7 @@ export class MinimalSubagentsCoordinator {
           message: `Restored ${agent.agent_id}`,
         });
       } catch (error) {
+        if (restoreEpoch !== this.lifecycleEpoch) return;
         agent.availability = "unavailable";
         if (previousAvailability !== "unavailable")
           agent.latest_activity_at = this.now().toISOString();
@@ -515,7 +651,7 @@ export class MinimalSubagentsCoordinator {
         });
       }
     }
-    await this.reconcileDeliveries(true);
+    if (restoreEpoch === this.lifecycleEpoch) await this.reconcileDeliveries(true);
   }
 
   /** Schedule delivery reconciliation as coordinator-owned work drained during shutdown. */
@@ -525,8 +661,51 @@ export class MinimalSubagentsCoordinator {
 
   /** Reconcile durable destination evidence and replay only successful undelivered output. */
   async reconcileDeliveries(replayMissing = false): Promise<void> {
-    for (const delivery of this.deliveries.values()) {
-      if (delivery.settled) continue;
+    const pendingItems = [
+      ...this.deliveryLedger.coordinationDeliveries.map((delivery) => ({
+        kind: "coordination" as const,
+        sequence: delivery.sequence,
+        delivery,
+      })),
+      ...this.deliveryLedger.terminalDeliveries.map((delivery) => ({
+        kind: "terminal" as const,
+        sequence: delivery.sequence ?? Number.MAX_SAFE_INTEGER,
+        delivery,
+      })),
+    ].sort((left, right) => left.sequence - right.sequence);
+    const scheduled: Promise<void>[] = [];
+
+    for (const item of pendingItems) {
+      if (item.kind === "coordination") {
+        const delivery = item.delivery;
+        if (this.hasCoordinationDeliveryEvidence(delivery)) {
+          this.settleCoordinationDelivery(delivery);
+          continue;
+        }
+        if (!replayMissing || delivery.path === "wait") continue;
+        const source = this.agents.get(delivery.message.details.source_agent_id);
+        if (source?.parent_id === delivery.destination_agent_id) {
+          const key = agentDeliveryKey(
+            delivery.message.details.source_agent_id,
+            delivery.message.details.source_turn_id,
+          );
+          const alreadyQueued = this.pendingParentMessages
+            .get(key)
+            ?.some((pending) => pending.deliveryId === delivery.delivery_id);
+          if (!alreadyQueued && !this.waitHandedDeliveryIds.has(delivery.delivery_id)) {
+            this.queuePendingParentMessage(
+              delivery.destination_agent_id,
+              delivery.message,
+              delivery,
+            );
+          }
+        } else {
+          scheduled.push(this.replayCoordinationDelivery(delivery));
+        }
+        continue;
+      }
+
+      const delivery = item.delivery;
       const agent = this.agents.get(delivery.source_agent_id);
       const result = delivery.result ?? agent?.latest_result;
       if (!result || result.status !== "completed" || result.turn_id !== delivery.source_turn_id)
@@ -535,25 +714,24 @@ export class MinimalSubagentsCoordinator {
         this.settleDelivery(delivery);
         continue;
       }
-      if (!replayMissing) continue;
-      delivery.path = "message";
-      this.dependencies.registry.append(
-        createRegistryEvent(this.dependencies.registry.rootSessionId, "delivery-pending", {
-          delivery,
-        }),
-      );
-      await this.deliverAutomaticResult(result, delivery);
+      if (!replayMissing || delivery.path === "wait") continue;
+      scheduled.push(this.deliverAutomaticResult(result, delivery));
     }
+    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> {
-    this.acceptingOperations = false;
     const activeRootChildren = this.childrenOf("root");
     for (const child of activeRootChildren) await this.cancelDuringShutdown(child.agent_id);
-    await Promise.allSettled(this.runtimeInitializations.values());
-    await Promise.allSettled(this.backgroundOperations);
-    await Promise.allSettled(this.recipientQueues.values());
+    await this.waitForSettledOperations();
     const forkAgents: PersistedAgent[] = [];
     const failedSubtrees = new Set<string>();
 
@@ -569,10 +747,16 @@ export class MinimalSubagentsCoordinator {
       }
       try {
         const clone = await this.dependencies.sessions.cloneSession(agent);
+        if (!clone.sessionLeafId) {
+          throw new Error(
+            `Minimal subagents fork clone: no selected session leaf for ${agent.agent_id}`,
+          );
+        }
         forkAgents.push({
           ...structuredClone(agent),
           session_file: clone.sessionFile,
           session_id: clone.sessionId,
+          session_leaf_id: clone.sessionLeafId,
           active_turn_id: undefined,
           active_turn_started_at: undefined,
         });
@@ -588,11 +772,12 @@ export class MinimalSubagentsCoordinator {
       }
     }
 
+    const snapshot = this.snapshot();
     return {
+      ...snapshot,
       source_root_session_file: sourceRootSessionFile,
+      source_root_session_id: this.dependencies.registry.rootSessionId,
       agents: forkAgents,
-      tombstones: [...this.tombstones],
-      deliveries: [...this.deliveries.values()].map((delivery) => structuredClone(delivery)),
     };
   }
 
@@ -600,6 +785,7 @@ export class MinimalSubagentsCoordinator {
   shutdown(): Promise<void> {
     if (this.shutdownPromise) return this.shutdownPromise;
     this.acceptingOperations = false;
+    this.releaseAllRecipientIdleWaiters();
     this.shutdownPromise = this.finishShutdown();
     return this.shutdownPromise;
   }
@@ -684,7 +870,7 @@ export class MinimalSubagentsCoordinator {
         return;
       }
       const outcome = await runtime.runPrompt(task, compact, callerModel, callerThinkingLevel);
-      if (agent.active_turn_id !== turnId) return;
+      if (this.agents.get(agentId) !== agent || agent.active_turn_id !== turnId) return;
       this.settleTurn(agent, turnId, terminalTurnResult(agentId, turnId, outcome));
     } catch (error) {
       if (this.agents.get(agentId) !== agent || agent.active_turn_id !== turnId) return;
@@ -708,19 +894,14 @@ export class MinimalSubagentsCoordinator {
         new Error(agent.clone_error ?? `No persistent session exists for ${agent.agent_id}`),
       );
     }
-    const importedMessages = this.importedMessages.get(agent.agent_id);
-    const initialization = (
-      importedMessages
-        ? this.dependencies.sessions.createRuntime({ agent, importedMessages })
-        : this.dependencies.sessions.restoreRuntime(agent)
-    )
+    const initialization = this.dependencies.sessions
+      .openRuntime(agent)
       .then((runtime) => {
         if (this.agents.get(agent.agent_id) !== agent) {
           runtime.dispose();
           throw new Error(`Minimal subagents runtime replaced while opening ${agent.agent_id}`);
         }
         this.runtimes.set(agent.agent_id, runtime);
-        this.importedMessages.delete(agent.agent_id);
         return runtime;
       })
       .finally(() => {
@@ -733,6 +914,7 @@ export class MinimalSubagentsCoordinator {
   }
 
   private beginTurn(agent: PersistedAgent): TurnId {
+    // SAFETY: The generated value embeds the canonical agent ID and a fresh turn UUID before branding.
     const turnId = `${agent.agent_id}:turn-${randomUUID()}` as TurnId;
     const startedAt = this.now().toISOString();
     agent.active_turn_id = turnId;
@@ -764,34 +946,44 @@ export class MinimalSubagentsCoordinator {
     agent.active_turn_started_at = undefined;
     agent.latest_activity_at = settledAt.toISOString();
     agent.latest_result = structuredClone(result);
+    const runtimeLeafId = this.runtimes.get(agent.agent_id)?.sessionLeafId;
+    if (runtimeLeafId) agent.session_leaf_id = runtimeLeafId;
     this.dependencies.registry.append(
-      createRegistryEvent(this.dependencies.registry.rootSessionId, "turn-settled", { result }),
+      createRegistryEvent(this.dependencies.registry.rootSessionId, "turn-settled", {
+        result,
+        settled_at: settledAt.toISOString(),
+        session_leaf_id: runtimeLeafId,
+      }),
     );
     const waiterKey = agentDeliveryKey(agent.agent_id, turnId);
     const turnWaiters = this.waiters.get(waiterKey);
     const directParentWaited = [...(turnWaiters ?? [])].some(
       (waiter) => waiter.callerId === agent.parent_id,
     );
+    if (directParentWaited && result.status === "completed") {
+      this.claimDeliveryTurn(agent.agent_id, turnId);
+    }
+    const parentClaimedTurn =
+      directParentWaited ||
+      isDeliveryLedgerTurnClaimed(this.deliveryLedger, agent.agent_id, turnId);
     for (const waiter of turnWaiters ?? []) {
       this.removeWaiter(waiterKey, waiter);
-      waiter.resolve(structuredClone(result));
+      waiter.resolve(terminalWaitResult(result));
     }
     if (result.status === "completed") {
-      const delivery: PersistedDelivery = {
-        source_agent_id: agent.agent_id,
-        source_turn_id: turnId,
-        destination_agent_id: agent.parent_id,
-        path: directParentWaited ? "wait" : "message",
-        settled: false,
-        result: structuredClone(result),
-      };
-      this.deliveries.set(waiterKey, delivery);
+      const added = addTerminalDelivery(this.deliveryLedger, {
+        destinationAgentId: agent.parent_id,
+        path: parentClaimedTurn ? "wait" : "message",
+        result,
+      });
+      this.applyDeliveryLedgerTransition(added);
+      const delivery = added.delivery;
       this.dependencies.registry.append(
         createRegistryEvent(this.dependencies.registry.rootSessionId, "delivery-pending", {
           delivery,
         }),
       );
-      if (!directParentWaited) {
+      if (!parentClaimedTurn) {
         this.trackBackgroundOperation(this.deliverAutomaticResult(result, delivery));
       }
       this.dependencies.notify?.({
@@ -806,22 +998,46 @@ export class MinimalSubagentsCoordinator {
         message: `${agent.agent_id} failed: ${result.error ?? "unknown error"}`,
       });
     }
+    if (result.status !== "completed") this.removeSettledEmptyTurnClaim(agent.agent_id, turnId);
+    this.markRecipientIdle(agent.agent_id);
   }
 
   private async deliverAutomaticResult(
     result: TurnResult,
     delivery: PersistedDelivery,
   ): Promise<void> {
-    const graceMs =
-      this.dependencies.automaticDeliveryGraceMs ?? DEFAULT_AUTOMATIC_DELIVERY_GRACE_MS;
-    if (graceMs > 0) await new Promise((resolve) => setTimeout(resolve, graceMs));
-    if (delivery.settled) return;
-    if (this.hasDeliveryEvidence(delivery)) {
-      this.settleDelivery(delivery);
-      return;
-    }
+    const deliveryKey = agentDeliveryKey(delivery.source_agent_id, delivery.source_turn_id);
+    if (this.automaticDeliveryKeys.has(deliveryKey)) return;
+    this.automaticDeliveryKeys.add(deliveryKey);
+    const graceMs = this.deliveryGraceMs();
     try {
       await this.enqueueRecipientDelivery(delivery.destination_agent_id, async () => {
+        if (delivery.destination_agent_id !== "root") {
+          await this.ensureRuntime(
+            this.requireUsableAgent(delivery.destination_agent_id, "message"),
+          );
+          if (!this.isTerminalDeliveryCurrent(delivery)) return;
+        }
+        if (graceMs > 0) await new Promise((resolve) => setTimeout(resolve, graceMs));
+        if (!this.acceptingOperations || this.shouldStopAutomaticTerminalDelivery(delivery)) return;
+        if (this.hasDeliveryEvidence(delivery)) {
+          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);
+          return;
+        }
         const message: CoordinatorMessage = {
           customType: "minimal-subagents.result",
           content: result.output,
@@ -829,82 +1045,265 @@ export class MinimalSubagentsCoordinator {
             source_agent_id: delivery.source_agent_id,
             destination_agent_id: delivery.destination_agent_id,
             source_turn_id: result.turn_id,
+            message_id: `result:${delivery.source_agent_id}:${result.turn_id}`,
             status: result.status,
             elapsed_ms: result.elapsed_ms,
             usage: result.usage,
           },
         };
-        await this.deliverToRecipient(delivery.destination_agent_id, message);
+        await this.deliverToRecipient(
+          delivery.destination_agent_id,
+          message,
+          () => this.isTerminalDeliveryCurrent(delivery),
+          true,
+        );
       });
     } catch (error) {
-      delivery.error = error instanceof Error ? error.message : String(error);
+      if (!this.isTerminalDeliveryCurrent(delivery)) return;
+      const deliveryError = error instanceof Error ? error.message : String(error);
+      this.deliveryLedger = setTerminalDeliveryError(
+        this.deliveryLedger,
+        delivery.source_agent_id,
+        delivery.source_turn_id,
+        deliveryError,
+      );
       this.dependencies.registry.append(
         createRegistryEvent(this.dependencies.registry.rootSessionId, "delivery-settled", {
           source_agent_id: delivery.source_agent_id,
           source_turn_id: delivery.source_turn_id,
-          error: delivery.error,
+          error: deliveryError,
         }),
       );
+    } finally {
+      this.automaticDeliveryKeys.delete(deliveryKey);
     }
   }
 
-  private async deliverExplicitMessage(
+  private persistCoordinationDelivery(
+    message: CoordinatorMessage,
+    destinationAgentId: string,
+  ): PersistedCoordinationDelivery {
+    const added = addCoordinationDelivery(this.deliveryLedger, {
+      destinationAgentId,
+      message,
+    });
+    this.deliveryLedger = added.ledger;
+    message.details.delivery_id = added.delivery.delivery_id;
+    this.persistCoordinationDeliveryState(added.delivery);
+    return added.delivery;
+  }
+
+  private persistCoordinationDeliveryState(delivery: PersistedCoordinationDelivery): void {
+    this.dependencies.registry.append(
+      createRegistryEvent(
+        this.dependencies.registry.rootSessionId,
+        "coordination-delivery-pending",
+        { delivery },
+      ),
+    );
+  }
+
+  private settleCoordinationDelivery(delivery: PersistedCoordinationDelivery): void {
+    this.deliveryLedger = settleCoordinationDelivery(
+      this.deliveryLedger,
+      delivery.delivery_id,
+    ).ledger;
+    this.waitHandedDeliveryIds.delete(delivery.delivery_id);
+    this.dependencies.registry.append(
+      createRegistryEvent(
+        this.dependencies.registry.rootSessionId,
+        "coordination-delivery-settled",
+        { delivery_id: delivery.delivery_id },
+      ),
+    );
+    this.removeSettledEmptyTurnClaim(
+      delivery.message.details.source_agent_id,
+      delivery.message.details.source_turn_id,
+    );
+  }
+
+  private removeSettledEmptyTurnClaim(sourceAgentId: string, sourceTurnId: string): void {
+    const transition = releaseEmptyDeliveryLedgerTurn(
+      this.deliveryLedger,
+      sourceAgentId,
+      sourceTurnId,
+      this.agents.get(sourceAgentId)?.active_turn_id === sourceTurnId,
+    );
+    this.deliveryLedger = transition.ledger;
+    if (transition.changed) {
+      this.dependencies.registry.append(
+        createRegistryEvent(this.dependencies.registry.rootSessionId, "delivery-turn-released", {
+          source_agent_id: sourceAgentId,
+          source_turn_id: sourceTurnId,
+        }),
+      );
+    }
+  }
+
+  private claimDeliveryTurn(sourceAgentId: string, sourceTurnId: string): void {
+    const transition = claimDeliveryLedgerTurn(this.deliveryLedger, sourceAgentId, sourceTurnId);
+    this.deliveryLedger = transition.ledger;
+    if (!transition.changed) return;
+    this.dependencies.registry.append(
+      createRegistryEvent(this.dependencies.registry.rootSessionId, "delivery-turn-claimed", {
+        source_agent_id: sourceAgentId,
+        source_turn_id: sourceTurnId,
+      }),
+    );
+  }
+
+  private selectObservableTurnId(
+    sourceAgentId: string,
+    destinationAgentId: string,
+  ): string | undefined {
+    const agent = this.agents.get(sourceAgentId);
+    return selectObservableDeliveryTurn(this.deliveryLedger, {
+      sourceAgentId,
+      destinationAgentId,
+      waitHandedDeliveryIds: this.waitHandedDeliveryIds,
+      activeTurnId: agent?.active_turn_id,
+      latestResultTurnId: agent?.latest_result?.turn_id,
+    });
+  }
+
+  private createExplicitMessage(
     callerId: string,
     targetId: string,
     sourceTurnId: string,
+    messageId: string,
     content: string,
-  ): Promise<void> {
-    const message: CoordinatorMessage = {
+  ): CoordinatorMessage {
+    return {
       customType: "minimal-subagents.message",
       content,
       details: {
         source_agent_id: callerId,
         destination_agent_id: targetId,
         source_turn_id: sourceTurnId,
+        message_id: messageId,
       },
     };
+  }
+
+  private recordRecentMessage(targetId: string, message: CoordinatorMessage): void {
     if (targetId !== "root") {
       const target = this.requireUsableAgent(targetId, "message");
-      target.recent_messages.push({
-        source_agent_id: callerId,
-        turn_id: sourceTurnId,
-        content,
-      });
+      const recentMessage = {
+        source_agent_id: message.details.source_agent_id,
+        turn_id: message.details.source_turn_id,
+        content: message.content,
+      };
+      target.recent_messages.push(recentMessage);
       if (target.recent_messages.length > RECENT_MESSAGE_LIMIT) target.recent_messages.shift();
+      const recordedAt = this.now().toISOString();
+      target.latest_activity_at = recordedAt;
+      this.dependencies.registry.append(
+        createRegistryEvent(
+          this.dependencies.registry.rootSessionId,
+          "agent-message-recorded",
+          {
+            agent_id: target.agent_id,
+            message: recentMessage,
+            recorded_at: recordedAt,
+          },
+          recordedAt,
+        ),
+      );
+    }
+  }
+
+  private async replayCoordinationDelivery(delivery: PersistedCoordinationDelivery): Promise<void> {
+    if (this.automaticCoordinationDeliveryIds.has(delivery.delivery_id)) return;
+    this.automaticCoordinationDeliveryIds.add(delivery.delivery_id);
+    try {
+      await this.enqueueRecipientDelivery(delivery.destination_agent_id, async () => {
+        if (this.hasCoordinationDeliveryEvidence(delivery)) {
+          this.settleCoordinationDelivery(delivery);
+          return;
+        }
+        this.waitHandedDeliveryIds.add(delivery.delivery_id);
+        await this.deliverToRecipient(delivery.destination_agent_id, delivery.message, () =>
+          this.isCoordinationDeliveryCurrent(delivery),
+        );
+      });
+    } catch (error) {
+      this.waitHandedDeliveryIds.delete(delivery.delivery_id);
+      if (!this.isCoordinationDeliveryCurrent(delivery)) return;
+      const deliveryError = error instanceof Error ? error.message : String(error);
+      this.deliveryLedger = setCoordinationDeliveryError(
+        this.deliveryLedger,
+        delivery.delivery_id,
+        deliveryError,
+      );
+      const current = findCoordinationDelivery(this.deliveryLedger, delivery.delivery_id);
+      if (current) this.persistCoordinationDeliveryState(current);
+    } finally {
+      this.automaticCoordinationDeliveryIds.delete(delivery.delivery_id);
     }
-    await this.deliverToRecipient(targetId, message);
   }
 
-  private async deliverToRecipient(targetId: string, message: CoordinatorMessage): Promise<void> {
+  private async deliverExplicitMessage(
+    message: CoordinatorMessage,
+    targetId: string,
+    delivery: PersistedCoordinationDelivery,
+  ): Promise<AgentMessageDisposition> {
+    this.waitHandedDeliveryIds.add(delivery.delivery_id);
+    try {
+      await this.deliverToRecipient(targetId, message, () =>
+        this.isCoordinationDeliveryCurrent(delivery),
+      );
+      return "queued";
+    } catch (error) {
+      this.waitHandedDeliveryIds.delete(delivery.delivery_id);
+      throw error;
+    }
+  }
+
+  private async deliverToRecipient(
+    targetId: string,
+    message: CoordinatorMessage,
+    isCurrentDelivery: () => boolean = () => true,
+    requireIdleRecipient = false,
+  ): Promise<void> {
+    if (!isCurrentDelivery()) {
+      throw new Error("Minimal subagents delivery abandoned after session branch change");
+    }
     if (!this.acceptingOperations) {
       throw new Error("Minimal subagents delivery stopped during coordinator shutdown");
     }
     if (targetId === "root") {
-      await this.dependencies.root.steerCoordinatorMessage(message);
+      await this.dependencies.root.queueCoordinatorMessage(addCoordinatorMessageEnvelope(message));
       return;
     }
     const target = this.requireUsableAgent(targetId, "message");
-    const runtime = await this.ensureRuntime(target);
+    const runtime = this.runtimes.get(targetId) ?? (await this.ensureRuntime(target));
+    if (!isCurrentDelivery()) {
+      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.steerCoordinatorMessage(message);
+      await runtime.queueCoordinatorMessage(visibleMessage);
       return;
     }
     const turnId = this.beginTurn(target);
     const runMessage = runtime
-      .runMessage(message)
+      .runMessage(visibleMessage)
       .then((outcome) => {
-        if (target.active_turn_id === turnId) {
+        if (this.agents.get(target.agent_id) === target && target.active_turn_id === turnId) {
           this.settleTurn(target, turnId, terminalTurnResult(target.agent_id, turnId, outcome));
         }
       })
-      .catch((error: unknown) => {
-        if (target.active_turn_id === turnId) {
+      .catch((cause) => {
+        if (this.agents.get(target.agent_id) === target && target.active_turn_id === turnId) {
           this.settleTurn(target, turnId, {
             agent_id: target.agent_id,
             turn_id: turnId,
             status: "failed",
             output: "",
-            error: error instanceof Error ? error.message : String(error),
+            error: cause instanceof Error ? cause.message : String(cause),
           });
         }
       });
@@ -917,12 +1316,17 @@ export class MinimalSubagentsCoordinator {
     void operation.then(cleanup, cleanup);
   }
 
-  private enqueueRecipientDelivery(
-    targetId: string,
-    operation: () => Promise<void>,
-  ): Promise<void> {
+  private enqueueRecipientDelivery<T>(targetId: string, operation: () => Promise<T>): Promise<T> {
+    const epoch = this.lifecycleEpoch;
     const previous = this.recipientQueues.get(targetId) ?? Promise.resolve();
-    const next = previous.catch(() => undefined).then(operation);
+    const next = previous
+      .catch(() => undefined)
+      .then(() => {
+        if (epoch !== this.lifecycleEpoch) {
+          throw new Error("Minimal subagents delivery abandoned after session branch change");
+        }
+        return operation();
+      });
     this.recipientQueues.set(targetId, next);
     const cleanup = () => {
       if (this.recipientQueues.get(targetId) === next) this.recipientQueues.delete(targetId);
@@ -960,6 +1364,46 @@ export class MinimalSubagentsCoordinator {
     return targetId;
   }
 
+  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,
+          source_turn_id: delivery.source_turn_id,
+          reason: "retention-limit",
+        }),
+      );
+    }
+  }
+
+  private isTerminalDeliveryCurrent(delivery: PersistedDelivery): boolean {
+    const current = findTerminalDelivery(
+      this.deliveryLedger,
+      delivery.source_agent_id,
+      delivery.source_turn_id,
+    );
+    return current?.sequence === delivery.sequence;
+  }
+
+  private shouldStopAutomaticTerminalDelivery(delivery: PersistedDelivery): boolean {
+    const current = findTerminalDelivery(
+      this.deliveryLedger,
+      delivery.source_agent_id,
+      delivery.source_turn_id,
+    );
+    return current === undefined || current.path === "wait";
+  }
+
+  private isCoordinationDeliveryCurrent(delivery: PersistedCoordinationDelivery): boolean {
+    return (
+      findCoordinationDelivery(this.deliveryLedger, delivery.delivery_id)?.sequence ===
+      delivery.sequence
+    );
+  }
+
   private hasDeliveryEvidence(delivery: PersistedDelivery): boolean {
     if (delivery.destination_agent_id === "root") {
       return this.dependencies.root.hasDeliveryEvidence(
@@ -974,15 +1418,36 @@ export class MinimalSubagentsCoordinator {
     );
   }
 
+  private hasCoordinationDeliveryEvidence(delivery: PersistedCoordinationDelivery): boolean {
+    const sourceAgentId = delivery.message.details.source_agent_id;
+    const sourceTurnId = delivery.message.details.source_turn_id;
+    if (delivery.destination_agent_id === "root") {
+      return this.dependencies.root.hasDeliveryEvidence(
+        sourceAgentId,
+        sourceTurnId,
+        delivery.delivery_id,
+      );
+    }
+    return (
+      this.runtimes
+        .get(delivery.destination_agent_id)
+        ?.hasDeliveryEvidence(sourceAgentId, sourceTurnId, delivery.delivery_id) ?? false
+    );
+  }
+
   private settleDelivery(delivery: PersistedDelivery): void {
-    delivery.settled = true;
-    delivery.error = undefined;
+    this.deliveryLedger = settleTerminalDelivery(
+      this.deliveryLedger,
+      delivery.source_agent_id,
+      delivery.source_turn_id,
+    ).ledger;
     this.dependencies.registry.append(
       createRegistryEvent(this.dependencies.registry.rootSessionId, "delivery-settled", {
         source_agent_id: delivery.source_agent_id,
         source_turn_id: delivery.source_turn_id,
       }),
     );
+    this.removeSettledEmptyTurnClaim(delivery.source_agent_id, delivery.source_turn_id);
   }
 
   private buildAgentSummary(agent: PersistedAgent, includeDescendants = true): AgentSummary {
@@ -1027,7 +1492,7 @@ export class MinimalSubagentsCoordinator {
     return {
       ...summary,
       session_file: agent.session_file,
-      launch_contract: structuredClone(agent.launch_contract) as unknown as Record<string, unknown>,
+      launch_contract: structuredClone(agent.launch_contract),
       capability_ceiling: [...agent.capability_ceiling],
       spawn_entry_id: agent.spawn_entry_id,
       recent_messages: structuredClone(agent.recent_messages),
@@ -1038,6 +1503,47 @@ 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);
+      }
+    }
+    for (const [key, messages] of this.pendingParentMessages) {
+      for (const pending of messages) {
+        if (!findCoordinationDelivery(this.deliveryLedger, pending.deliveryId)) {
+          pending.claimed = true;
+          pending.releaseClaim();
+        }
+      }
+      const retained = messages.filter((pending) =>
+        findCoordinationDelivery(this.deliveryLedger, pending.deliveryId),
+      );
+      if (retained.length === 0) this.pendingParentMessages.delete(key);
+      else this.pendingParentMessages.set(key, retained);
+    }
+  }
+
+  private pruneRecentMessageProjectionsForDeletedAgent(agentId: string): void {
+    const belongsToDeletedSubtree = (sourceAgentId: string) =>
+      sourceAgentId === agentId || sourceAgentId.startsWith(`${agentId}.`);
+    for (const agent of this.agents.values()) {
+      agent.recent_messages = agent.recent_messages.filter(
+        (message) => !belongsToDeletedSubtree(message.source_agent_id),
+      );
+    }
+  }
+
   private descendantsOf(agentId: string): PersistedAgent[] {
     const descendants: PersistedAgent[] = [];
     const queue = this.childrenOf(agentId);
@@ -1125,6 +1631,7 @@ export class MinimalSubagentsCoordinator {
       ...structuredClone(agent),
       session_file: undefined,
       session_id: undefined,
+      session_leaf_id: undefined,
       clone_error: cloneError,
       active_turn_id: undefined,
       active_turn_started_at: undefined,
@@ -1135,6 +1642,15 @@ export class MinimalSubagentsCoordinator {
     };
   }
 
+  private rejectAllWaiters(error: Error): void {
+    for (const [key, waiters] of this.waiters) {
+      for (const waiter of waiters) {
+        this.removeWaiter(key, waiter);
+        waiter.reject(error);
+      }
+    }
+  }
+
   private removeWaiter(key: string, waiter: TurnWaiter): void {
     const turnWaiters = this.waiters.get(key);
     turnWaiters?.delete(waiter);
@@ -1145,6 +1661,286 @@ export class MinimalSubagentsCoordinator {
     }
   }
 
+  private resolveWaiterWithMessage(
+    message: CoordinatorMessage,
+    delivery: PersistedCoordinationDelivery,
+  ): boolean {
+    const destinationAgentId = message.details.destination_agent_id;
+    if (!destinationAgentId) return false;
+    const key = agentDeliveryKey(message.details.source_agent_id, message.details.source_turn_id);
+    const turnWaiters = this.waiters.get(key);
+    const waiter = [...(turnWaiters ?? [])].find(
+      (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,
+      "wait",
+    );
+    const currentDelivery = findCoordinationDelivery(this.deliveryLedger, delivery.delivery_id);
+    if (currentDelivery) this.persistCoordinationDeliveryState(currentDelivery);
+    this.waitHandedDeliveryIds.add(delivery.delivery_id);
+    this.removeWaiter(key, waiter);
+    waiter.resolve({
+      event: "message",
+      agent_id: message.details.source_agent_id,
+      turn_id: message.details.source_turn_id,
+      message_id: message.details.message_id,
+      delivery_id: delivery.delivery_id,
+      message: message.content,
+    });
+    return true;
+  }
+
+  private claimPendingParentMessage(
+    callerId: string,
+    sourceAgentId: string,
+    sourceTurnId: string,
+  ): WaitResult | undefined {
+    const key = agentDeliveryKey(sourceAgentId, sourceTurnId);
+    const pendingMessages = this.pendingParentMessages.get(key);
+    const index = pendingMessages?.findIndex(
+      (pending) => pending.destinationAgentId === callerId && !pending.claimed,
+    );
+    if (index === undefined || index < 0 || !pendingMessages) {
+      const retained = this.deliveryLedger.coordinationDeliveries
+        .filter(
+          (delivery) =>
+            delivery.destination_agent_id === callerId &&
+            delivery.message.details.source_agent_id === sourceAgentId &&
+            delivery.message.details.source_turn_id === sourceTurnId &&
+            !this.waitHandedDeliveryIds.has(delivery.delivery_id),
+        )
+        .sort((left, right) => left.sequence - right.sequence)[0];
+      if (!retained) return undefined;
+      this.claimDeliveryTurn(sourceAgentId, sourceTurnId);
+      this.deliveryLedger = setCoordinationDeliveryPath(
+        this.deliveryLedger,
+        retained.delivery_id,
+        "wait",
+      );
+      const currentDelivery = findCoordinationDelivery(this.deliveryLedger, retained.delivery_id);
+      if (currentDelivery) this.persistCoordinationDeliveryState(currentDelivery);
+      this.waitHandedDeliveryIds.add(retained.delivery_id);
+      return {
+        event: "message",
+        agent_id: sourceAgentId,
+        turn_id: sourceTurnId,
+        message_id: retained.message.details.message_id,
+        delivery_id: retained.delivery_id,
+        message: retained.message.content,
+      };
+    }
+    const pending = pendingMessages[index];
+    if (!pending) return undefined;
+    this.claimDeliveryTurn(sourceAgentId, sourceTurnId);
+    const delivery = findCoordinationDelivery(this.deliveryLedger, pending.deliveryId);
+    if (delivery) {
+      this.deliveryLedger = setCoordinationDeliveryPath(
+        this.deliveryLedger,
+        delivery.delivery_id,
+        "wait",
+      );
+      const currentDelivery = findCoordinationDelivery(this.deliveryLedger, delivery.delivery_id);
+      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();
+    pendingMessages.splice(index, 1);
+    if (pendingMessages.length === 0) this.pendingParentMessages.delete(key);
+    return {
+      event: "message",
+      agent_id: sourceAgentId,
+      turn_id: sourceTurnId,
+      message_id: pending.message.details.message_id,
+      delivery_id: pending.deliveryId,
+      message: pending.message.content,
+    };
+  }
+
+  private queuePendingParentMessage(
+    targetId: string,
+    message: CoordinatorMessage,
+    delivery: PersistedCoordinationDelivery,
+  ): void {
+    const key = agentDeliveryKey(message.details.source_agent_id, message.details.source_turn_id);
+    const turnClaimed = () =>
+      isDeliveryLedgerTurnClaimed(
+        this.deliveryLedger,
+        message.details.source_agent_id,
+        message.details.source_turn_id,
+      );
+    const { promise: claimPromise, resolve: releaseClaim } = Promise.withResolvers<void>();
+    const pending: PendingParentMessage = {
+      deliveryId: delivery.delivery_id,
+      message,
+      destinationAgentId: targetId,
+      claimed: false,
+      claimPromise,
+      releaseClaim,
+    };
+    const pendingMessages = this.pendingParentMessages.get(key) ?? [];
+    pendingMessages.push(pending);
+    this.pendingParentMessages.set(key, pendingMessages);
+
+    if (
+      isDeliveryLedgerTurnClaimed(
+        this.deliveryLedger,
+        message.details.source_agent_id,
+        message.details.source_turn_id,
+      )
+    )
+      return;
+
+    const operation = this.enqueueRecipientDelivery(targetId, async () => {
+      if (targetId !== "root") {
+        await this.ensureRuntime(this.requireUsableAgent(targetId, "message"));
+        if (!this.isCoordinationDeliveryCurrent(delivery)) return;
+      }
+      const graceMs = this.deliveryGraceMs();
+      const gracePromise = new Promise<void>((resolve) => {
+        if (graceMs <= 0) {
+          resolve();
+          return;
+        }
+        const timer = setTimeout(resolve, graceMs);
+        pending.cancelGrace = () => {
+          clearTimeout(timer);
+          resolve();
+        };
+      });
+      await Promise.race([pending.claimPromise, gracePromise]);
+      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;
+      }
+      if (!this.acceptingOperations || pending.claimed || turnClaimed()) return;
+      this.removePendingParentMessage(key, pending);
+      this.waitHandedDeliveryIds.add(delivery.delivery_id);
+      await this.deliverToRecipient(
+        targetId,
+        message,
+        () => this.isCoordinationDeliveryCurrent(delivery),
+        true,
+      );
+    });
+    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);
+      this.dependencies.notify?.({
+        type: "failure",
+        agentId: message.details.source_agent_id,
+        message: `Could not queue message ${message.details.message_id}: ${
+          cause instanceof Error ? cause.message : String(cause)
+        }`,
+      });
+    });
+  }
+
+  private removePendingParentMessage(key: string, pending: PendingParentMessage): void {
+    const pendingMessages = this.pendingParentMessages.get(key);
+    if (!pendingMessages) return;
+    const index = pendingMessages.indexOf(pending);
+    if (index >= 0) pendingMessages.splice(index, 1);
+    if (pendingMessages.length === 0) this.pendingParentMessages.delete(key);
+  }
+
+  private claimTerminalDelivery(callerId: string, result: TurnResult): void {
+    if (!findTerminalDelivery(this.deliveryLedger, result.agent_id, result.turn_id)) return;
+    this.claimDeliveryTurn(result.agent_id, result.turn_id);
+    this.setTerminalDeliveryPathToWait(callerId, result);
+  }
+
+  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", {
+        delivery: retained,
+      }),
+    );
+  }
+
+  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;
@@ -1154,6 +1950,7 @@ export class MinimalSubagentsCoordinator {
       const turnId = agent.active_turn_id;
       const runtime = this.runtimes.get(agent.agent_id);
       if (runtime) await runtime.abort();
+      if (this.agents.get(agent.agent_id) !== agent) continue;
       this.settleTurn(agent, turnId, {
         agent_id: agent.agent_id,
         turn_id: turnId,
@@ -1168,6 +1965,7 @@ export class MinimalSubagentsCoordinator {
     const turnId = agent.active_turn_id;
     const runtime = this.runtimes.get(agent.agent_id);
     if (runtime) await runtime.abort();
+    if (this.agents.get(agent.agent_id) !== agent) return undefined;
     this.settleTurn(agent, turnId, {
       agent_id: agent.agent_id,
       turn_id: turnId,
@@ -1230,4 +2028,8 @@ export class MinimalSubagentsCoordinator {
   private now(): Date {
     return this.dependencies.now?.() ?? new Date();
   }
+
+  private deliveryGraceMs(): number {
+    return this.dependencies.automaticDeliveryGraceMs ?? DEFAULT_AUTOMATIC_DELIVERY_GRACE_MS;
+  }
 }