@caupulican/pi-adaptative 0.86.2 → 0.86.5

package/dist/core/delegation/worker-agent-control-coordinator.js

@@ -1,5 +1,11 @@
-import { WorkerAgentMailbox, } from "./worker-agent-control.js";
-import { WorkerConversationStore } from "./worker-conversation-store.js";
+import { latestAgentAttemptsByDurableOrder } from "../orchestration/attempt-ordering.js";
+import { MAX_ORCHESTRATION_COLLECTION_LENGTH, MAX_ORCHESTRATION_IDENTIFIER_LENGTH, } from "../orchestration/contracts.js";
+import { SessionRootMailbox, sessionRootAddress, sessionRootReplyMessageId, } from "./session-root-mailbox.js";
+import { normalizeWorkerAgentDependencyTaskIds, WorkerAgentMailbox, workerAgentBroadcastTargetIdempotencyKey, workerAgentMessageId, } from "./worker-agent-control.js";
+import { MAX_WORKER_TRANSCRIPT_PAGE_MESSAGES, WorkerConversationStore, } from "./worker-conversation-store.js";
+import { evaluateReusableWorkerTaskAdmission } from "./worker-fleet-limits.js";
+import { projectWorkerTaskSessionView } from "./worker-task-view.js";
+const MAX_BROADCAST_ERROR_CHARS = 512;
 /**
  * Sole owner of model-facing logical-agent controls and their durable inboxes.
  *
@@ -10,88 +16,755 @@ export class WorkerAgentControlCoordinator {
     constructor(options) {
         this.mailboxes = new Map();
         this.stateListeners = new Set();
-        this.conversations = new WorkerConversationStore();
+        this.reconcilingTaskBearingAgentIds = new Set();
+        this.taskBearingContinuationAgentIds = new Set();
+        this.sessionRootReconciliationFailures = new Map();
+        this.workerReplyReconciliationFailures = new Map();
         this.options = options;
+        this.conversations = options.conversationStore ?? new WorkerConversationStore();
+        this.sessionRootAddress = sessionRootAddress(options.parentSessionId);
+        this.sessionRootMailbox = new SessionRootMailbox({
+            agentDir: options.agentDir,
+            parentSessionId: options.parentSessionId,
+        });
     }
     getProcessOwnerId() {
         return this.options.processOwnerId;
     }
     listWorkerAgents(scope = {}) {
         this.requireControl();
-        const agents = Object.values(this.options.getLifecycle().getTaskRuntimeSnapshot().agents);
-        const caller = scope.callerAgentId ? this.requireKnownAgent(scope.callerAgentId) : undefined;
+        const snapshot = this.options.getLifecycle().getTaskRuntimeSnapshot();
+        if (scope.callerAgentId) {
+            const callerAgentId = scope.callerAgentId.trim();
+            if (!callerAgentId || !snapshot.agents[callerAgentId]) {
+                throw new Error(`Unknown logical worker agent '${callerAgentId}'.`);
+            }
+        }
+        const latestAttempts = this.latestAttemptsByAgent(snapshot);
+        const agents = Object.values(snapshot.agents);
         return agents
-            .filter((agent) => !caller || agent.rootAgentId === caller.rootAgentId)
-            .sort((left, right) => left.depth - right.depth || left.createdAt.localeCompare(right.createdAt));
+            .sort((left, right) => left.depth - right.depth || left.createdAt.localeCompare(right.createdAt))
+            .map((agent) => this.workerAgentView(agent, this.projectAgentActivity(agent, latestAttempts.get(agent.agentId))));
+    }
+    getWorkerTaskSessionView() {
+        this.requireControl();
+        return projectWorkerTaskSessionView(this.options.getLifecycle().getTaskRuntimeSnapshot());
+    }
+    /** Snapshot-only activity projection. Unlike waitForWorkerAgent, this never yields scheduler capacity. */
+    getWorkerAgentActivity(agentId, scope = {}) {
+        this.requireControl();
+        const canonicalAgentId = agentId.trim();
+        if (!canonicalAgentId)
+            throw new Error("Logical worker agent id is required.");
+        const agent = this.options.getLifecycle().getAgent(canonicalAgentId);
+        if (!agent)
+            return "unknown";
+        this.requireSessionPeer(canonicalAgentId, scope);
+        return this.activityForAgent(agent);
     }
     readWorkerAgentTranscript(agentId, options = {}) {
         this.requireControl();
-        const agent = this.requireVisibleAgent(agentId, options);
+        const agent = this.requireControllableAgent(agentId, options);
         const cursor = options.cursor ?? 0;
         const maxMessages = options.maxMessages ?? 16;
         if (!Number.isSafeInteger(cursor) || cursor < 0)
             throw new TypeError("Worker transcript cursor is invalid.");
-        if (!Number.isSafeInteger(maxMessages) || maxMessages < 1 || maxMessages > 64) {
-            throw new TypeError("Worker transcript page size must be from 1 through 64 messages.");
+        if (!Number.isSafeInteger(maxMessages) || maxMessages < 1 || maxMessages > MAX_WORKER_TRANSCRIPT_PAGE_MESSAGES) {
+            throw new TypeError(`Worker transcript page size must be from 1 through ${MAX_WORKER_TRANSCRIPT_PAGE_MESSAGES} messages.`);
         }
-        const transcript = this.conversations
+        const page = this.conversations
             .open({
             agentDir: this.options.agentDir,
             resumeContext: agent.resumeContext,
             expectedLogicalAgentId: agent.agentId,
         })
-            .getRawTranscript();
-        if (cursor > transcript.length)
-            throw new TypeError("Worker transcript cursor exceeds the transcript length.");
-        const messages = transcript.slice(cursor, cursor + maxMessages);
-        const nextCursor = cursor + messages.length;
+            .getRawTranscriptPage({
+            cursor,
+            maxMessages,
+            ...(options.maxBytes !== undefined ? { maxBytes: options.maxBytes } : {}),
+        });
         return {
             agentId: agent.agentId,
-            cursor,
-            totalMessages: transcript.length,
-            messages,
-            ...(nextCursor < transcript.length ? { nextCursor } : {}),
+            ...page,
         };
     }
     sendWorkerAgentMessage(agentId, message, options = {}) {
         this.requireControl();
-        const agent = this.requireVisibleAgent(agentId, { callerAgentId: options.senderAgentId });
+        this.rejectGenericReplyOptions(options);
+        const agent = this.requireSessionPeer(agentId, { callerAgentId: options.senderAgentId });
+        this.assertAgentAcceptsNewMessages(agent, options.idempotencyKey);
         const queued = this.enqueuePeerMessage(agent, "follow_up", message, options);
-        this.signalStateChanged();
+        this.notifyStateChangedBestEffort();
         return { messageId: queued.messageId, queued: true };
     }
+    broadcastWorkerAgentMessage(agentIds, message, options) {
+        this.requireControl();
+        const canonicalAgentIds = this.canonicalAgentIdSet(agentIds, "Worker broadcast");
+        const recipients = canonicalAgentIds.map((agentId) => ({
+            agentId,
+            idempotencyKey: workerAgentBroadcastTargetIdempotencyKey(options.idempotencyKey, agentId),
+        }));
+        const senderAgentId = options.senderAgentId ? this.requireKnownAgent(options.senderAgentId).agentId : undefined;
+        let created = false;
+        const results = recipients.map(({ agentId, idempotencyKey }) => {
+            try {
+                const target = this.requireSessionPeer(agentId, { callerAgentId: senderAgentId });
+                this.assertAgentAcceptsNewMessages(target, idempotencyKey);
+                const messageOptions = senderAgentId
+                    ? {
+                        senderAgentId,
+                        ...(options.threadId !== undefined ? { threadId: options.threadId } : {}),
+                        ...(options.expectReply === true ? { expectReply: true } : {}),
+                        idempotencyKey,
+                    }
+                    : this.sessionRootMessageOptions({
+                        ...(options.threadId !== undefined ? { threadId: options.threadId } : {}),
+                        ...(options.expectReply === true ? { expectReply: true } : {}),
+                        idempotencyKey,
+                    });
+                const queued = this.enqueuePeerMessage(target, "follow_up", message, messageOptions);
+                created ||= queued.status === "retained" && queued.created;
+                return {
+                    agentId,
+                    accepted: true,
+                    queued: true,
+                    replayed: queued.status === "completed_replay" || !queued.created,
+                    messageId: queued.messageId,
+                };
+            }
+            catch (error) {
+                return {
+                    agentId,
+                    accepted: false,
+                    error: (error instanceof Error ? error.message : String(error)).slice(0, MAX_BROADCAST_ERROR_CHARS),
+                };
+            }
+        });
+        if (created)
+            this.notifyStateChangedBestEffort();
+        return { results };
+    }
     followUpWorkerAgent(agentId, message, options = {}) {
         this.requireControl();
-        const agent = this.requireVisibleAgent(agentId, { callerAgentId: options.senderAgentId });
-        const canonicalAgentId = agent.agentId;
-        const active = this.latestAgentAttempt(agent);
-        if (active?.status === "queued" || active?.status === "running" || active?.status === "leased") {
-            const queued = this.enqueuePeerMessage(agent, "steer", message, options);
-            this.signalStateChanged();
+        const agent = this.requireControllableAgent(agentId, { callerAgentId: options.senderAgentId });
+        return this.followUpAcceptedAgent(agent, message, options);
+    }
+    sendSessionRootWorkerAgentMessage(agentId, message, options = {}) {
+        this.requireControl();
+        const agent = this.requireKnownAgent(agentId);
+        this.assertAgentAcceptsNewMessages(agent, options.idempotencyKey);
+        const queued = this.enqueuePeerMessage(agent, "follow_up", message, this.sessionRootMessageOptions(options));
+        this.notifyStateChangedBestEffort();
+        return { messageId: queued.messageId, queued: true };
+    }
+    followUpSessionRootWorkerAgent(agentId, message, options = {}) {
+        this.requireControl();
+        return this.followUpAcceptedAgent(this.requireKnownAgent(agentId), message, this.sessionRootMessageOptions(options));
+    }
+    replyToWorkerAgentMessage(sourceAgentId, message, replyToMessageId) {
+        this.requireControl();
+        const source = this.requireKnownAgent(sourceAgentId);
+        const sourceMailbox = this.getMailbox(source.agentId);
+        const completedReply = sourceMailbox.resolveCompletedReply(replyToMessageId, message);
+        const activeAcknowledgementId = sourceMailbox.getReplyAcknowledgementId(replyToMessageId);
+        if (completedReply &&
+            activeAcknowledgementId !== undefined &&
+            activeAcknowledgementId !== completedReply.replyMessageId) {
+            throw new Error("Worker reply acknowledgement identity conflicts with its durable source receipt.");
+        }
+        if (completedReply && activeAcknowledgementId === undefined) {
+            if (completedReply.requestSenderId === this.sessionRootAddress) {
+                return { destination: "session_root", messageId: completedReply.replyMessageId };
+            }
+            const completedTarget = this.requireKnownAgent(completedReply.requestSenderId);
+            this.reconcileCompletedWorkerReplyAcknowledgement(sourceMailbox, replyToMessageId, completedTarget.agentId, completedReply.replyMessageId);
+            return {
+                destination: "worker",
+                messageId: completedReply.replyMessageId,
+                started: false,
+                steering: false,
+                skipReason: "worker_reply_already_accepted",
+            };
+        }
+        const request = sourceMailbox.getMessage(replyToMessageId);
+        if (!request || request.deliveredAt === undefined || request.expectReply !== true) {
+            throw new Error("Worker reply does not reference a delivered reply-expected message.");
+        }
+        if (!request.senderAgentId)
+            throw new Error("Worker reply request has no routable requester.");
+        if (request.senderAgentId === this.sessionRootAddress) {
+            return this.routeWorkerReplyToSessionRoot(source, sourceMailbox, request, message);
+        }
+        const target = this.requireKnownAgent(request.senderAgentId);
+        if (target.status === "retired" && activeAcknowledgementId === undefined) {
+            throw new Error(`Logical worker agent '${target.agentId}' is retired.`);
+        }
+        return this.routeWorkerReplyToAgent(target, source.agentId, request, message);
+    }
+    listSessionRootReplies(query = {}) {
+        this.requireControl();
+        this.reconcileSessionRootSurface();
+        return this.sessionRootMailbox.pendingReplies(query);
+    }
+    waitForSessionRootReplies(options = {}) {
+        this.requireControl();
+        this.reconcileSessionRootSurface();
+        return this.sessionRootMailbox.waitForReplies(options);
+    }
+    acknowledgeSessionRootReply(messageId, ackToken) {
+        this.requireControl();
+        this.reconcileSessionRootSurface();
+        const acknowledged = this.sessionRootMailbox.acknowledge(messageId, ackToken);
+        if (acknowledged) {
+            this.reconcileWorkerReplyOutboxesBestEffort();
+            this.notifyStateChangedBestEffort();
+        }
+        return acknowledged;
+    }
+    reconcileSessionRootSurface() {
+        this.reconcileSessionRootReplies();
+        this.reconcileWorkerReplyOutboxesBestEffort();
+    }
+    followUpAcceptedAgent(agent, message, options) {
+        this.rejectGenericReplyOptions(options);
+        if (this.activityForAgent(agent) === "active") {
+            const queued = this.enqueuePeerMessage(agent, "steer", message, options, { kind: "agent_turn" });
+            this.notifyStateChangedBestEffort();
+            if (queued.status === "completed_replay" ||
+                queued.message.deliveredAt !== undefined ||
+                queued.message.failedAt !== undefined) {
+                return {
+                    started: false,
+                    steering: false,
+                    messageId: queued.messageId,
+                    skipReason: "worker_message_already_finalized",
+                };
+            }
             return { started: false, steering: true, messageId: queued.messageId };
         }
         if (agent.status !== "registered") {
             return { started: false, steering: false, messageId: "", skipReason: `agent_${agent.status}` };
         }
-        const queued = this.enqueuePeerMessage(agent, "follow_up", message, options);
+        return this.startIdleAgentTask(agent, message, options);
+    }
+    /**
+     * Atomically transition one idle persistent agent to a fresh task. There is no await between the
+     * activity check and durable prepare, so competing model calls cannot turn the loser into steering.
+     */
+    startWorkerAgentTask(agentId, message, options = {}) {
+        this.requireControl();
+        const canonicalAgentId = agentId.trim();
+        if (!canonicalAgentId)
+            throw new Error("Logical worker agent id is required.");
+        const candidate = this.options.getLifecycle().getAgent(canonicalAgentId);
+        if (!candidate)
+            return { started: false, steering: false, messageId: "", skipReason: "unknown_agent" };
+        const agent = this.requireControllableAgent(canonicalAgentId, options);
+        const dependsOnTaskIds = normalizeWorkerAgentDependencyTaskIds(options.dependsOnTaskIds);
+        if (options.idempotencyKey !== undefined) {
+            const replay = this.replayWorkerAgentTask(agent, message, options.idempotencyKey, dependsOnTaskIds);
+            if (replay)
+                return replay;
+        }
+        const activity = this.activityForAgent(agent);
+        if (activity !== "idle") {
+            return { started: false, steering: false, messageId: "", skipReason: `worker_${activity}` };
+        }
+        if (agent.status !== "registered") {
+            return { started: false, steering: false, messageId: "", skipReason: `agent_${agent.status}` };
+        }
+        return this.startIdleAgentTask(agent, message, options.idempotencyKey === undefined ? {} : { idempotencyKey: options.idempotencyKey }, dependsOnTaskIds);
+    }
+    replayWorkerAgentTask(agent, message, idempotencyKey, dependsOnTaskIds) {
+        this.assertIdempotencyTarget(agent.agentId, idempotencyKey);
+        const messageId = workerAgentMessageId(this.options.parentSessionId, idempotencyKey);
+        const mailbox = this.getMailbox(agent.agentId);
+        const correlatedAttempt = this.controlMessageAttemptById(agent.agentId, messageId);
+        if (correlatedAttempt) {
+            if (correlatedAttempt.dispatch.instructions !== message.trim()) {
+                throw new Error("Worker control idempotency identity conflicts with its durable dispatch.");
+            }
+            this.assertAttemptDependencyIdentity(correlatedAttempt, dependsOnTaskIds);
+            const record = this.options.getLifecycle().getRecord(correlatedAttempt.taskId);
+            if (!record) {
+                return {
+                    started: false,
+                    steering: false,
+                    messageId,
+                    skipReason: "orchestration_projection_missing",
+                };
+            }
+            return { started: true, steering: false, messageId, record };
+        }
+        if (!mailbox.getMessage(messageId)) {
+            return mailbox.hasControlReplayReceipt(messageId)
+                ? {
+                    started: false,
+                    steering: false,
+                    messageId,
+                    skipReason: "worker_task_receipt_without_attempt",
+                }
+                : undefined;
+        }
+        const acceptance = mailbox.enqueueWithReceipt({
+            kind: "follow_up",
+            content: message,
+            idempotencyKey,
+            task: {
+                kind: "agent_turn",
+                ...(dependsOnTaskIds.length > 0 ? { dependsOnTaskIds } : {}),
+            },
+        });
+        if (acceptance.status === "completed_replay") {
+            return {
+                started: false,
+                steering: false,
+                messageId,
+                skipReason: "worker_task_receipt_without_attempt",
+            };
+        }
+        const accepted = acceptance.message;
+        const attempt = this.controlMessageAttempt(agent.agentId, accepted);
+        if (attempt) {
+            const record = this.options.getLifecycle().getRecord(attempt.taskId);
+            if (!record) {
+                return {
+                    started: false,
+                    steering: false,
+                    messageId,
+                    skipReason: "orchestration_projection_missing",
+                };
+            }
+            // Idempotent API replay returns the original accepted start even after that attempt became
+            // terminal. The record carries its current projection; no second task or scheduler entry is made.
+            return { started: true, steering: false, messageId, record };
+        }
+        if (accepted.deliveredAt !== undefined) {
+            return {
+                started: false,
+                steering: false,
+                messageId,
+                skipReason: "worker_task_delivered_without_attempt",
+            };
+        }
+        const reconciliation = this.reconcileTaskBearingMailbox(agent.agentId, messageId);
+        this.notifyStateChangedBestEffort();
+        return {
+            started: reconciliation.started,
+            steering: false,
+            messageId,
+            ...(reconciliation.record ? { record: reconciliation.record } : {}),
+            ...(reconciliation.skipReason ? { skipReason: reconciliation.skipReason } : {}),
+        };
+    }
+    startIdleAgentTask(agent, message, options, dependsOnTaskIds = []) {
+        if (!this.isAcceptedControlReplay(agent.agentId, options.idempotencyKey)) {
+            const headroomSkipReason = this.options.taskStartHeadroomSkipReason?.(agent);
+            if (headroomSkipReason)
+                return { started: false, steering: false, messageId: "", skipReason: headroomSkipReason };
+            const skipReason = this.reusableTaskAdmissionSkipReason(agent.agentId);
+            if (skipReason)
+                return { started: false, steering: false, messageId: "", skipReason };
+        }
+        const queued = this.enqueuePeerMessage(agent, "follow_up", message, options, {
+            kind: "agent_turn",
+            ...(dependsOnTaskIds.length > 0 ? { dependsOnTaskIds } : {}),
+        });
+        if (queued.status === "completed_replay") {
+            return {
+                started: false,
+                steering: false,
+                messageId: queued.messageId,
+                skipReason: "worker_message_already_finalized",
+            };
+        }
+        const reconciliation = this.reconcileTaskBearingMailbox(agent.agentId, queued.messageId);
+        this.notifyStateChangedBestEffort();
+        return {
+            started: reconciliation.started,
+            steering: false,
+            messageId: queued.messageId,
+            ...(reconciliation.record ? { record: reconciliation.record } : {}),
+            ...(reconciliation.skipReason ? { skipReason: reconciliation.skipReason } : {}),
+        };
+    }
+    assertAttemptDependencyIdentity(attempt, dependsOnTaskIds) {
+        const snapshot = this.options.getLifecycle().getTaskRuntimeSnapshot();
+        const durableDependencies = snapshot.tasks?.[attempt.taskId]?.task.dependsOn;
+        if (!durableDependencies) {
+            if (dependsOnTaskIds.length > 0) {
+                throw new Error("Worker control idempotency dependency projection is missing.");
+            }
+            return;
+        }
+        if (durableDependencies.length !== dependsOnTaskIds.length ||
+            durableDependencies.some((dependencyId, index) => dependencyId !== dependsOnTaskIds[index])) {
+            throw new Error("Worker control idempotency identity conflicts with its durable task dependencies.");
+        }
+    }
+    sessionRootMessageOptions(options) {
+        return {
+            senderAgentId: this.sessionRootAddress,
+            ...(options.threadId !== undefined ? { threadId: options.threadId } : {}),
+            ...(options.expectReply === true ? { expectReply: true } : {}),
+            ...(options.idempotencyKey !== undefined ? { idempotencyKey: options.idempotencyKey } : {}),
+        };
+    }
+    rejectGenericReplyOptions(options) {
+        if ("replyToMessageId" in options) {
+            throw new Error("Worker replies must use the dedicated inferred-destination reply control.");
+        }
+    }
+    assertAgentAcceptsNewMessages(agent, idempotencyKey) {
+        if (agent.status !== "retired")
+            return;
+        if (idempotencyKey !== undefined) {
+            const messageId = workerAgentMessageId(this.options.parentSessionId, idempotencyKey);
+            const mailbox = this.getMailbox(agent.agentId);
+            if (mailbox.getMessage(messageId) || mailbox.hasControlReplayReceipt(messageId))
+                return;
+        }
+        throw new Error(`Logical worker agent '${agent.agentId}' is retired.`);
+    }
+    routeWorkerReplyToAgent(target, sourceAgentId, request, message) {
+        const activity = this.activityForAgent(target);
+        const idempotencyKey = `peer-reply:${sourceAgentId}:${request.messageId}`;
+        this.assertIdempotencyTarget(target.agentId, idempotencyKey);
+        const replyMessageId = workerAgentMessageId(this.options.parentSessionId, idempotencyKey);
+        const sourceMailbox = this.getMailbox(sourceAgentId);
+        const reservationAlreadyActive = sourceMailbox.getReplyAcknowledgementId(request.messageId) === replyMessageId;
+        if (!sourceMailbox.beginReplyAcknowledgement(request.messageId, replyMessageId, message)) {
+            throw new Error("Worker reply source acknowledgement could not be acquired.");
+        }
+        const transcriptInput = {
+            idempotencyKey,
+            content: message,
+            senderAgentId: sourceAgentId,
+            replyToMessageId: request.messageId,
+            ...(request.threadId ? { threadId: request.threadId } : {}),
+            task: { kind: "agent_turn" },
+        };
+        const transcriptReplay = this.reconcileMandatoryControlTranscript(target, transcriptInput, false);
+        if (transcriptReplay.delivered) {
+            if (!sourceMailbox.commitReplyAcknowledgement(request.messageId, replyMessageId) &&
+                sourceMailbox.getReplyAcknowledgementId(request.messageId) !== undefined) {
+                throw new Error("Worker reply source acknowledgement did not commit after transcript replay.");
+            }
+            this.notifyStateChangedBestEffort();
+            return {
+                destination: "worker",
+                messageId: replyMessageId,
+                started: false,
+                steering: false,
+                skipReason: "worker_reply_already_accepted",
+            };
+        }
+        if (target.status === "retired") {
+            this.deliverMandatoryControlToRetiredTranscript(target, transcriptInput);
+            if (!sourceMailbox.commitReplyAcknowledgement(request.messageId, replyMessageId) &&
+                sourceMailbox.getReplyAcknowledgementId(request.messageId) !== undefined) {
+                throw new Error("Worker reply source acknowledgement did not commit after retired-target delivery.");
+            }
+            this.notifyStateChangedBestEffort();
+            return {
+                destination: "worker",
+                messageId: replyMessageId,
+                started: false,
+                steering: false,
+                skipReason: "worker_reply_retired_target_transcript_delivery",
+            };
+        }
+        const targetMailbox = this.getMailbox(target.agentId);
+        let queued;
         try {
-            const prepared = this.options
-                .getLifecycle()
-                .prepareAgentTurn({ agentId: canonicalAgentId, instructions: message });
-            this.options.scheduler.enqueue(prepared.record, this.options.recoveredRequest(prepared.attempt));
-            this.options.statusChanged();
-            this.options.scheduler.drain();
-            this.signalStateChanged();
-            return { started: true, steering: false, messageId: queued.messageId, record: prepared.record };
+            queued = targetMailbox.enqueueWithReceipt({
+                kind: activity === "active" ? "steer" : "follow_up",
+                content: message,
+                senderAgentId: sourceAgentId,
+                replyToMessageId: request.messageId,
+                ...(request.threadId ? { threadId: request.threadId } : {}),
+                idempotencyKey,
+                task: { kind: "agent_turn" },
+            });
         }
         catch (error) {
+            if (!reservationAlreadyActive) {
+                this.rollbackReplyReservationAfterTargetRejection(sourceMailbox, request.messageId, replyMessageId, error);
+            }
+            throw error;
+        }
+        if (queued.messageId !== replyMessageId) {
+            throw new Error("Worker reply target returned a divergent deterministic message identity.");
+        }
+        if (queued.status === "completed_replay") {
+            if (!targetMailbox.hasDeliveredControlReceipt(queued.messageId)) {
+                throw new Error("Worker reply target replay has no durable delivery evidence.");
+            }
+            if (!sourceMailbox.commitReplyAcknowledgement(request.messageId, queued.messageId) &&
+                sourceMailbox.getReplyAcknowledgementId(request.messageId) !== undefined) {
+                throw new Error("Worker reply source acknowledgement did not commit after target replay.");
+            }
+            this.notifyStateChangedBestEffort();
+            return {
+                destination: "worker",
+                messageId: queued.messageId,
+                started: false,
+                steering: false,
+                skipReason: "worker_reply_already_accepted",
+            };
+        }
+        this.beginWorkerReplyAcknowledgement(target, queued.message);
+        if (queued.message.deliveredAt !== undefined) {
+            if (!this.reconcileCompletedWorkerReplyAcknowledgement(sourceMailbox, request.messageId, target.agentId, queued.messageId) &&
+                sourceMailbox.getReplyAcknowledgementId(request.messageId) !== undefined) {
+                throw new Error("Worker reply source acknowledgement did not commit after target delivery.");
+            }
+            this.notifyStateChangedBestEffort();
             return {
+                destination: "worker",
+                messageId: queued.messageId,
                 started: false,
                 steering: false,
+                skipReason: "worker_reply_already_accepted",
+            };
+        }
+        if (activity === "active") {
+            this.notifyStateChangedBestEffort();
+            if (!queued.created) {
+                return {
+                    destination: "worker",
+                    messageId: queued.messageId,
+                    started: false,
+                    steering: false,
+                    skipReason: "worker_reply_already_accepted",
+                };
+            }
+            return {
+                destination: "worker",
                 messageId: queued.messageId,
-                skipReason: error instanceof Error ? error.message : String(error),
+                started: false,
+                steering: true,
             };
         }
+        const reconciliation = this.reconcileTaskBearingMailbox(target.agentId, queued.messageId);
+        this.notifyStateChangedBestEffort();
+        return {
+            destination: "worker",
+            messageId: queued.messageId,
+            started: reconciliation.started,
+            steering: false,
+            ...(reconciliation.record ? { record: reconciliation.record } : {}),
+            ...(reconciliation.skipReason ? { skipReason: reconciliation.skipReason } : {}),
+        };
+    }
+    routeWorkerReplyToSessionRoot(source, sourceMailbox, request, message) {
+        const replyMessageId = sessionRootReplyMessageId(this.options.parentSessionId, source.agentId, request.messageId);
+        const reservationAlreadyActive = sourceMailbox.getReplyAcknowledgementId(request.messageId) === replyMessageId;
+        const replyInput = {
+            sourceAgentId: source.agentId,
+            requestMessageId: request.messageId,
+            ...(request.threadId ? { threadId: request.threadId } : {}),
+            content: message,
+        };
+        try {
+            this.sessionRootMailbox.assertReplyInput(replyInput);
+        }
+        catch (error) {
+            if (reservationAlreadyActive) {
+                this.rollbackReplyReservationAfterTargetRejection(sourceMailbox, request.messageId, replyMessageId, error);
+            }
+            throw error;
+        }
+        if (!sourceMailbox.beginReplyAcknowledgement(request.messageId, replyMessageId, message)) {
+            throw new Error("Session root reply source acknowledgement could not be acquired.");
+        }
+        let accepted;
+        try {
+            accepted = this.sessionRootMailbox.enqueueSourceOwnedReply(replyInput);
+        }
+        catch (error) {
+            if (!reservationAlreadyActive) {
+                this.rollbackReplyReservationAfterTargetRejection(sourceMailbox, request.messageId, replyMessageId, error);
+            }
+            throw error;
+        }
+        if (accepted.messageId !== replyMessageId) {
+            throw new Error("Session root reply target returned a divergent deterministic message identity.");
+        }
+        if (accepted.status === "completed_replay") {
+            if (!sourceMailbox.commitReplyAcknowledgement(request.messageId, accepted.messageId) &&
+                sourceMailbox.getReplyAcknowledgementId(request.messageId) !== undefined) {
+                throw new Error("Session root reply source acknowledgement did not commit after target replay.");
+            }
+            this.releaseSessionRootSourceReceiptBestEffort(accepted.messageId);
+        }
+        else {
+            this.reconcileSessionRootReply(accepted.reply);
+        }
+        this.notifyStateChangedBestEffort();
+        return { destination: "session_root", messageId: accepted.messageId };
+    }
+    rollbackReplyReservationAfterTargetRejection(sourceMailbox, requestMessageId, replyMessageId, targetError) {
+        try {
+            if (!sourceMailbox.rollbackReplyAcknowledgement(requestMessageId, replyMessageId) &&
+                sourceMailbox.getReplyAcknowledgementId(requestMessageId) === replyMessageId) {
+                throw new Error("Worker reply source reservation did not roll back after target rejection.");
+            }
+        }
+        catch (rollbackError) {
+            throw new AggregateError([targetError, rollbackError], "Worker reply target rejected after its source reservation could not be rolled back.");
+        }
+        throw targetError;
+    }
+    deliverMandatoryControlToRetiredTranscript(target, input) {
+        if (target.status !== "retired" || this.activityForAgent(target) === "active") {
+            throw new Error("Mandatory transcript fallback requires a terminal logical worker target.");
+        }
+        const delivery = this.reconcileMandatoryControlTranscript(target, input, true);
+        return delivery.messageId;
+    }
+    reconcileMandatoryControlTranscript(target, input, appendIfMissing) {
+        const messageId = workerAgentMessageId(this.options.parentSessionId, input.idempotencyKey);
+        return this.reconcileControlTranscript(target, {
+            messageId,
+            kind: "follow_up",
+            content: input.content,
+            senderAgentId: input.senderAgentId,
+            ...(input.threadId ? { threadId: input.threadId } : {}),
+            ...(input.replyToMessageId ? { replyToMessageId: input.replyToMessageId } : {}),
+            task: input.task,
+            createdAt: new Date().toISOString(),
+        }, appendIfMissing);
+    }
+    reconcileControlTranscript(target, message, appendIfMissing) {
+        const messageId = message.messageId;
+        if (!target.resumeContext.sessionFile) {
+            if (appendIfMissing) {
+                throw new Error("Mandatory transcript fallback target has no durable session transcript.");
+            }
+            return { messageId, delivered: false };
+        }
+        const projected = this.mailboxMessage(message);
+        const conversation = this.conversations.open({
+            agentDir: this.options.agentDir,
+            resumeContext: target.resumeContext,
+            expectedLogicalAgentId: target.agentId,
+        });
+        if (typeof projected.content !== "string") {
+            throw new Error("Worker control transcript projection is not textual.");
+        }
+        const reconciliation = conversation.reconcileWorkerControlMessage({ messageId, content: projected.content }, projected, appendIfMissing);
+        return { messageId, delivered: reconciliation.delivered };
+    }
+    reconcileSessionRootReplies() {
+        let replies;
+        try {
+            replies = this.sessionRootMailbox.retainedReplies();
+            this.sessionRootReconciliationFailures.delete("session-root-mailbox");
+        }
+        catch (error) {
+            this.recordSessionRootReconciliationFailure("session-root-mailbox", error instanceof Error ? error.message : String(error));
+            return;
+        }
+        for (const reply of replies)
+            this.reconcileSessionRootReply(reply);
+    }
+    reconcileSessionRootReply(reply) {
+        try {
+            const source = this.options.getLifecycle().getAgent(reply.sourceAgentId);
+            if (!source) {
+                if (reply.sourceReconciledAt) {
+                    this.sessionRootReconciliationFailures.delete(reply.messageId);
+                    return;
+                }
+                throw new Error(`Unknown logical worker agent '${reply.sourceAgentId}'.`);
+            }
+            const sourceMailbox = this.getMailbox(source.agentId);
+            const request = sourceMailbox.getMessage(reply.requestMessageId);
+            if (!request) {
+                if (reply.sourceReconciledAt) {
+                    this.releaseSessionRootSourceReceiptBestEffort(reply.messageId);
+                    this.sessionRootReconciliationFailures.delete(reply.messageId);
+                    return;
+                }
+                throw new Error("Session root reply source request is missing before reconciliation.");
+            }
+            if (request.deliveredAt === undefined ||
+                request.expectReply !== true ||
+                request.senderAgentId !== this.sessionRootAddress ||
+                request.threadId !== reply.threadId) {
+                throw new Error("Session root reply source request conflicts with its durable target.");
+            }
+            let acknowledgementId = sourceMailbox.getReplyAcknowledgementId(request.messageId);
+            if (acknowledgementId && acknowledgementId !== reply.messageId) {
+                throw new Error("Session root reply source request has a divergent acknowledgement marker.");
+            }
+            if (request.repliedAt !== undefined && acknowledgementId === undefined) {
+                if (!reply.sourceReconciledAt) {
+                    throw new Error("Session root reply source was marked replied without its exact acknowledgement marker.");
+                }
+                this.releaseSessionRootSourceReceiptBestEffort(reply.messageId);
+                this.sessionRootReconciliationFailures.delete(reply.messageId);
+                return;
+            }
+            if (request.repliedAt === undefined) {
+                if (!sourceMailbox.beginReplyAcknowledgement(request.messageId, reply.messageId, reply.content)) {
+                    throw new Error("Session root reply source acknowledgement could not be acquired.");
+                }
+                acknowledgementId = reply.messageId;
+            }
+            if (!this.sessionRootMailbox.markSourceReconciled(reply.messageId)) {
+                throw new Error("Session root reply disappeared during source reconciliation.");
+            }
+            if (acknowledgementId === reply.messageId) {
+                if (!sourceMailbox.commitReplyAcknowledgement(request.messageId, reply.messageId)) {
+                    const remaining = sourceMailbox.getReplyAcknowledgementId(request.messageId);
+                    if (remaining !== undefined) {
+                        throw new Error("Session root reply source acknowledgement did not commit.");
+                    }
+                }
+            }
+            this.releaseSessionRootSourceReceiptBestEffort(reply.messageId);
+            this.sessionRootReconciliationFailures.delete(reply.messageId);
+        }
+        catch (error) {
+            this.recordSessionRootReconciliationFailure(reply.messageId, error instanceof Error ? error.message : String(error));
+        }
+    }
+    recordSessionRootReconciliationFailure(messageId, reason) {
+        if (this.sessionRootReconciliationFailures.get(messageId) === reason)
+            return;
+        if (!this.sessionRootReconciliationFailures.has(messageId) &&
+            this.sessionRootReconciliationFailures.size >= 128) {
+            const oldest = this.sessionRootReconciliationFailures.keys().next().value;
+            if (oldest)
+                this.sessionRootReconciliationFailures.delete(oldest);
+        }
+        this.sessionRootReconciliationFailures.set(messageId, reason);
+        try {
+            this.options.warn?.(`Session root reply reconciliation failed for ${messageId}: ${reason}`);
+        }
+        catch {
+            // Diagnostics are bounded observers; durable mailboxes remain authoritative.
+        }
+    }
+    releaseSessionRootSourceReceiptBestEffort(messageId) {
+        try {
+            this.sessionRootMailbox.releaseSourceReplayReceipt(messageId);
+            this.sessionRootReconciliationFailures.delete(`receipt:${messageId}`);
+        }
+        catch (error) {
+            this.recordSessionRootReconciliationFailure(`receipt:${messageId}`, error instanceof Error ? error.message : String(error));
+        }
+    }
+    notifyStateChangedBestEffort() {
+        try {
+            this.options.statusChanged();
+        }
+        catch {
+            // Notification observers cannot redefine durable task acceptance.
+        }
+        this.notifyStateListeners();
     }
     interruptWorkerAgent(agentId, scope = {}) {
         const { agent, attempt } = this.controlledAgentAttempt(agentId, scope);
@@ -115,8 +788,27 @@ export class WorkerAgentControlCoordinator {
         const record = this.options.getLifecycle().getRecord(attempt.taskId);
         if (!record)
             return { started: false, skipReason: "orchestration_projection_missing" };
-        const promise = this.options.run(this.options.recoveredRequest(attempt), record);
-        this.options.scheduler.track(record.laneId, promise);
+        try {
+            const request = this.options.recoveredRequest(attempt);
+            this.options.scheduler.enqueue(record, request, true, request.verificationOfTaskId !== undefined);
+        }
+        catch (error) {
+            return {
+                started: false,
+                record,
+                skipReason: error instanceof Error ? error.message : String(error),
+            };
+        }
+        try {
+            this.options.scheduler.drain();
+        }
+        catch (error) {
+            return {
+                started: true,
+                record,
+                skipReason: `worker_resume_recovery_pending:${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
         this.signalStateChanged();
         return { started: true, record };
     }
@@ -129,72 +821,141 @@ export class WorkerAgentControlCoordinator {
         this.signalStateChanged();
         return record;
     }
-    /** Event-driven wait: durable projection plus state/mailbox notifications, never output polling. */
+    retireWorkerAgent(agentId, scope = {}) {
+        this.requireControl();
+        let target = this.requireControllableAgent(agentId, scope);
+        if (target.status === "retired") {
+            return { agent: this.workerAgentView(target), retired: true, replayed: true };
+        }
+        const activity = this.activityForAgent(target);
+        if (activity !== "idle") {
+            throw new Error(`Logical worker agent '${target.agentId}' cannot retire while ${activity}.`);
+        }
+        const mailbox = this.getMailbox(target.agentId);
+        if (mailbox.pendingTaskBearing().length > 0) {
+            this.reconcileTaskBearingMailbox(target.agentId);
+            target = this.requireControllableAgent(target.agentId, scope);
+        }
+        this.reconcileWorkerReplyOutboxesBestEffort();
+        const pendingMessages = mailbox.pending();
+        if (pendingMessages.length > 0) {
+            throw new Error(`Logical worker agent '${target.agentId}' has ${pendingMessages.length} pending control message${pendingMessages.length === 1 ? "" : "s"}.`);
+        }
+        const unresolvedReplyCount = mailbox.awaitingReplies().length + mailbox.listReplyAcknowledgements().length;
+        if (unresolvedReplyCount > 0) {
+            throw new Error(`Logical worker agent '${target.agentId}' has ${unresolvedReplyCount} unresolved reply obligation${unresolvedReplyCount === 1 ? "" : "s"}.`);
+        }
+        const retired = this.options.getLifecycle().retireAgent(target.agentId);
+        this.notifyStateChangedBestEffort();
+        return { agent: this.workerAgentView(retired), retired: true, replayed: false };
+    }
+    /** Event-driven wait: durable projection plus one shared state notification, never output polling. */
     waitForWorkerAgent(agentId, timeoutMs = 30_000, scope = {}) {
+        return this.waitForWorkerAgents([agentId], "all", timeoutMs, scope).then((result) => ({
+            status: result.statuses[0]?.status ?? "unknown",
+        }));
+    }
+    /** One event-driven wait set with one shared caller-capacity lease; never per-agent promise polling. */
+    waitForWorkerAgents(agentIds, mode, timeoutMs = 30_000, scope = {}) {
         this.requireControl();
-        const canonicalAgentId = agentId.trim();
-        if (!canonicalAgentId)
-            throw new Error("Logical worker agent id is required.");
-        const target = this.options.getLifecycle().getAgent(canonicalAgentId);
-        if (target)
-            this.requireVisibleAgent(canonicalAgentId, scope);
+        if (mode !== "any" && mode !== "all")
+            throw new TypeError("Worker wait mode must be 'any' or 'all'.");
+        const canonicalAgentIds = this.canonicalAgentIdSet(agentIds, "Worker wait");
+        const baselineSnapshot = this.options.getLifecycle().getTaskRuntimeSnapshot();
+        if (scope.callerAgentId) {
+            const callerAgentId = scope.callerAgentId.trim();
+            if (!callerAgentId || !baselineSnapshot.agents[callerAgentId]) {
+                throw new Error(`Unknown logical worker agent '${callerAgentId}'.`);
+            }
+        }
         const boundedTimeoutMs = Number.isFinite(timeoutMs)
             ? Math.max(1, Math.min(Math.floor(timeoutMs), 300_000))
             : 30_000;
-        const currentStatus = () => {
-            const agent = this.options.getLifecycle().getAgent(canonicalAgentId);
-            if (!agent)
-                return "unknown";
-            const attempt = this.latestAgentAttempt(agent);
-            if (attempt?.status === "suspended" || agent.status === "suspended")
-                return "suspended";
-            if (attempt?.status === "queued" || attempt?.status === "leased" || attempt?.status === "running") {
-                return "active";
-            }
-            return "idle";
+        const statusesFromSnapshot = (snapshot) => {
+            const latestAttempts = this.latestAttemptsByAgent(snapshot);
+            return canonicalAgentIds.map((agentId) => {
+                const agent = snapshot.agents[agentId];
+                return {
+                    agentId,
+                    status: agent
+                        ? this.projectAgentActivity(agent, latestAttempts.get(agent.agentId))
+                        : "unknown",
+                };
+            });
+        };
+        const currentStatuses = () => statusesFromSnapshot(this.options.getLifecycle().getTaskRuntimeSnapshot());
+        const baselineStatuses = statusesFromSnapshot(baselineSnapshot);
+        const baselineByAgentId = new Map(baselineStatuses.map(({ agentId, status }) => [agentId, status]));
+        const updatedAgentIds = new Set();
+        const recordUpdates = (statuses) => {
+            for (const { agentId, status } of statuses) {
+                if (baselineByAgentId.get(agentId) !== status)
+                    updatedAgentIds.add(agentId);
+            }
+        };
+        const waitSatisfied = (statuses) => {
+            return mode === "any"
+                ? statuses.some(({ status }) => status !== "active")
+                : statuses.every(({ status }) => status !== "active");
         };
-        const immediate = currentStatus();
-        if (immediate !== "active")
-            return Promise.resolve({ status: immediate });
+        const result = (statuses, timedOut) => ({
+            statuses,
+            updatedAgentIds: canonicalAgentIds.filter((agentId) => updatedAgentIds.has(agentId)),
+            timedOut,
+        });
+        if (waitSatisfied(baselineStatuses))
+            return Promise.resolve(result(baselineStatuses, false));
         return new Promise((resolve) => {
             let settled = false;
-            let releaseYield = () => undefined;
-            let unsubscribeMailbox = () => undefined;
+            let releaseYield;
             let unsubscribeState = () => undefined;
             let timeout;
+            const cleanup = () => {
+                unsubscribeState();
+                if (timeout)
+                    clearTimeout(timeout);
+                const release = releaseYield;
+                releaseYield = undefined;
+                release?.();
+            };
             const settle = () => {
                 if (settled)
                     return;
-                const next = currentStatus();
-                if (next === "active")
+                const statuses = currentStatuses();
+                recordUpdates(statuses);
+                if (!waitSatisfied(statuses))
                     return;
                 settled = true;
-                unsubscribeMailbox();
-                unsubscribeState();
-                if (timeout)
-                    clearTimeout(timeout);
-                releaseYield();
-                resolve({ status: next });
+                cleanup();
+                resolve(result(statuses, false));
             };
-            unsubscribeMailbox = this.getMailbox(canonicalAgentId).subscribe(settle);
             unsubscribeState = this.subscribeStateChanges(settle);
             timeout = setTimeout(() => {
                 if (settled)
                     return;
                 settled = true;
-                unsubscribeMailbox();
-                unsubscribeState();
-                releaseYield();
-                resolve({ status: currentStatus() });
+                const statuses = currentStatuses();
+                recordUpdates(statuses);
+                cleanup();
+                resolve(result(statuses, true));
             }, boundedTimeoutMs);
             if (typeof timeout === "object" && "unref" in timeout)
                 timeout.unref();
             if (scope.callerAgentId && this.options.yieldCapacity) {
-                const yielded = this.options.yieldCapacity(scope.callerAgentId, canonicalAgentId);
-                if (settled)
-                    yielded();
-                else
-                    releaseYield = yielded;
+                // Capacity belongs to the waiting caller. Passing that identity through both slots keeps
+                // legacy controller adapters from treating an independent peer as the capacity owner.
+                try {
+                    const yielded = this.options.yieldCapacity(scope.callerAgentId, scope.callerAgentId);
+                    if (settled)
+                        yielded();
+                    else
+                        releaseYield = yielded;
+                }
+                catch (error) {
+                    settled = true;
+                    cleanup();
+                    throw error;
+                }
             }
             settle();
         });
@@ -205,9 +966,15 @@ export class WorkerAgentControlCoordinator {
         const pending = mailbox.pending();
         if (pending.length === 0)
             return [];
-        const delivered = conversation.findDeliveredWorkerControlMessageIds(pending.map((message) => message.messageId));
+        const delivered = conversation.findDeliveredWorkerControlMessageIds(pending.map((message) => {
+            const projected = this.mailboxMessage(message);
+            if (typeof projected.content !== "string") {
+                throw new Error("Worker control transcript projection is not textual.");
+            }
+            return { messageId: message.messageId, content: projected.content };
+        }));
         for (const messageId of delivered)
-            mailbox.acknowledgeDelivered(messageId);
+            this.acknowledgeDeliveredMailboxMessage(agentId, messageId);
         return mailbox
             .pending()
             .filter((message) => message.kind === "steer" || includeFollowUp)
@@ -219,12 +986,101 @@ export class WorkerAgentControlCoordinator {
             return;
         const messageId = /^\[Worker control (worker-message-[^\]\s]+)(?: [^\]]+)?\]\n/.exec(message.content)?.[1];
         if (messageId)
-            this.getMailbox(agentId).acknowledgeDelivered(messageId);
+            this.acknowledgeDeliveredMailboxMessage(agentId, messageId);
     }
     /** Called by controller-owned execution transitions after lifecycle state changed. */
     signalStateChanged() {
-        for (const listener of this.stateListeners)
-            listener();
+        this.reconcileTaskBearingMailboxTurns();
+        this.notifyStateListeners();
+    }
+    /** Restart/idle boundary: adopt or schedule every oldest pending executable mailbox intent. */
+    reconcileTaskBearingMailboxTurns() {
+        const agents = this.replyReconciliationAgents();
+        this.reconcileWorkerReplyOutboxes(agents);
+        for (const agent of agents)
+            this.reconcileTaskBearingMailbox(agent.agentId);
+    }
+    replyReconciliationAgents() {
+        return Object.values(this.options.getLifecycle().getTaskRuntimeSnapshot().agents).sort((left, right) => left.createdAt.localeCompare(right.createdAt) || left.agentId.localeCompare(right.agentId));
+    }
+    reconcileWorkerReplyOutboxes(agents) {
+        for (const agent of agents)
+            this.reconcileWorkerReplyAcknowledgements(agent);
+    }
+    reconcileWorkerReplyOutboxesBestEffort() {
+        try {
+            this.reconcileWorkerReplyOutboxes(this.replyReconciliationAgents());
+            this.workerReplyReconciliationFailures.delete("worker-reply-outbox-snapshot");
+        }
+        catch (error) {
+            this.recordWorkerReplyReconciliationFailure("worker-reply-outbox-snapshot", error instanceof Error ? error.message : String(error));
+        }
+    }
+    reconcileWorkerReplyAcknowledgements(source) {
+        const sourceMailbox = this.getMailbox(source.agentId);
+        let acknowledgements;
+        try {
+            acknowledgements = sourceMailbox.listReplyAcknowledgements();
+            this.workerReplyReconciliationFailures.delete(`source:${source.agentId}`);
+        }
+        catch (error) {
+            this.recordWorkerReplyReconciliationFailure(`source:${source.agentId}`, error instanceof Error ? error.message : String(error));
+            return;
+        }
+        for (const acknowledgement of acknowledgements) {
+            const failureKey = `reply:${source.agentId}:${acknowledgement.messageId}`;
+            try {
+                const request = sourceMailbox.getMessage(acknowledgement.messageId);
+                if (!request?.senderAgentId) {
+                    throw new Error("Worker reply acknowledgement source request is missing routing metadata.");
+                }
+                if (request.senderAgentId === this.sessionRootAddress) {
+                    this.routeWorkerReplyToSessionRoot(source, sourceMailbox, request, acknowledgement.replyContent);
+                    this.workerReplyReconciliationFailures.delete(failureKey);
+                    continue;
+                }
+                const target = this.requireKnownAgent(request.senderAgentId);
+                this.routeWorkerReplyToAgent(target, source.agentId, request, acknowledgement.replyContent);
+                this.workerReplyReconciliationFailures.delete(failureKey);
+            }
+            catch (error) {
+                this.recordWorkerReplyReconciliationFailure(failureKey, error instanceof Error ? error.message : String(error));
+            }
+        }
+    }
+    recordWorkerReplyReconciliationFailure(failureKey, reason) {
+        if (this.workerReplyReconciliationFailures.get(failureKey) === reason)
+            return;
+        if (!this.workerReplyReconciliationFailures.has(failureKey) &&
+            this.workerReplyReconciliationFailures.size >= 128) {
+            const oldest = this.workerReplyReconciliationFailures.keys().next().value;
+            if (oldest)
+                this.workerReplyReconciliationFailures.delete(oldest);
+        }
+        this.workerReplyReconciliationFailures.set(failureKey, reason);
+        try {
+            this.options.warn?.(`Worker reply acknowledgement recovery failed for ${failureKey}: ${reason}`);
+        }
+        catch {
+            // Diagnostics are bounded observers; durable acknowledgement evidence remains authoritative.
+        }
+    }
+    reconcileCompletedWorkerReplyAcknowledgement(sourceMailbox, requestMessageId, targetAgentId, replyMessageId) {
+        if (sourceMailbox.getReplyAcknowledgementId(requestMessageId) !== replyMessageId)
+            return false;
+        if (!this.getMailbox(targetAgentId).hasDeliveredControlReceipt(replyMessageId))
+            return false;
+        return sourceMailbox.commitReplyAcknowledgement(requestMessageId, replyMessageId);
+    }
+    notifyStateListeners() {
+        for (const listener of this.stateListeners) {
+            try {
+                listener();
+            }
+            catch {
+                // State listeners are advisory; one observer cannot redefine or hide a durable mutation.
+            }
+        }
     }
     /** Route a terminal child edge to its owning parent without injecting into an active model turn. */
     deliverWorkerTerminalHandoff(args) {
@@ -237,33 +1093,285 @@ export class WorkerAgentControlCoordinator {
             `laneId=${args.record.laneId}`,
             `status=${args.record.status}`,
             ...(args.record.reasonCode ? [`reasonCode=${args.record.reasonCode}`] : []),
-            `Read the exact child evidence with delegate action="transcript" agentId="${args.childAgentId}".`,
+            `Read bounded raw transcript pages with delegate action="transcript" agentId="${args.childAgentId}". Messages present in each page are complete durable entries; omittedMessages discloses whole-message omissions, and an empty page may still continue via nextCursor.`,
         ].join("\n");
-        const queued = this.getMailbox(parent.agentId).enqueue({
+        const idempotencyKey = `terminal-handoff:${args.terminalAttemptId}`;
+        const transcriptInput = {
+            idempotencyKey,
+            content,
+            senderAgentId: args.childAgentId,
+            task: { kind: "terminal_handoff", sourceAttemptId: args.terminalAttemptId },
+        };
+        this.assertIdempotencyTarget(parent.agentId, idempotencyKey);
+        const transcriptReplay = this.reconcileMandatoryControlTranscript(parent, transcriptInput, false);
+        if (transcriptReplay.delivered) {
+            this.notifyStateChangedBestEffort();
+            return { messageId: transcriptReplay.messageId, started: false, accepted: true };
+        }
+        if (parent.status === "retired") {
+            const messageId = this.deliverMandatoryControlToRetiredTranscript(parent, transcriptInput);
+            this.notifyStateChangedBestEffort();
+            return {
+                messageId,
+                started: false,
+                accepted: true,
+                skipReason: "terminal_handoff_retired_target_transcript_delivery",
+            };
+        }
+        const queued = this.getMailbox(parent.agentId).enqueueWithReceipt({
             kind: active ? "steer" : "follow_up",
             content,
             senderAgentId: args.childAgentId,
-            idempotencyKey: `terminal-handoff:${args.terminalAttemptId}`,
+            idempotencyKey,
+            task: { kind: "terminal_handoff", sourceAttemptId: args.terminalAttemptId },
         });
-        let started = false;
-        if (!active && parent.status === "registered") {
-            const prepared = this.options.getLifecycle().prepareAgentTurn({
-                agentId: parent.agentId,
-                instructions: content,
-            });
-            this.options.scheduler.enqueue(prepared.record, this.options.recoveredRequest(prepared.attempt));
-            this.options.statusChanged();
+        if (queued.status === "completed_replay") {
+            this.notifyStateChangedBestEffort();
+            return { messageId: queued.messageId, started: false, accepted: true };
+        }
+        if (queued.message.deliveredAt !== undefined) {
+            this.notifyStateChangedBestEffort();
+            return { messageId: queued.messageId, started: false, accepted: true };
+        }
+        const reconciliation = this.reconcileTaskBearingMailbox(parent.agentId, queued.messageId);
+        this.notifyStateChangedBestEffort();
+        return {
+            messageId: queued.messageId,
+            started: reconciliation.started,
+            accepted: true,
+            ...(reconciliation.skipReason ? { skipReason: reconciliation.skipReason } : {}),
+        };
+    }
+    reconcileTaskBearingMailbox(agentId, expectedMessageId) {
+        if (this.reconcilingTaskBearingAgentIds.has(agentId)) {
+            return { started: false, skipReason: "worker_task_reconciliation_in_progress" };
+        }
+        this.reconcilingTaskBearingAgentIds.add(agentId);
+        try {
+            const agent = this.options.getLifecycle().getAgent(agentId);
+            if (!agent)
+                return { started: false, skipReason: "unknown_agent" };
+            const mailbox = this.getMailbox(agentId);
+            for (let settlement = 0; settlement < 64; settlement++) {
+                const message = mailbox.pendingTaskBearing()[0];
+                if (!message)
+                    return { started: false };
+                if (this.reconcileTaskBearingTranscriptDelivery(agent, message)) {
+                    if (expectedMessageId === message.messageId) {
+                        return { started: false, skipReason: "worker_control_transcript_delivery_reconciled" };
+                    }
+                    continue;
+                }
+                this.beginWorkerReplyAcknowledgement(agent, message);
+                const correlated = this.controlMessageAttempt(agent.agentId, message);
+                if (correlated) {
+                    const scheduled = this.scheduleCorrelatedTaskBearingAttempt(correlated);
+                    if (scheduled.skipReason?.startsWith("worker_task_terminal_")) {
+                        const settled = this.settleTerminalTaskBearingMessage(agent, mailbox, message, scheduled, expectedMessageId);
+                        if (settled)
+                            return settled;
+                        continue;
+                    }
+                    if (expectedMessageId && message.messageId !== expectedMessageId) {
+                        return { started: false, skipReason: "worker_task_waiting_for_older_message" };
+                    }
+                    return scheduled;
+                }
+                if (expectedMessageId && message.messageId !== expectedMessageId) {
+                    return { started: false, skipReason: "worker_task_waiting_for_older_message" };
+                }
+                const activity = this.activityForAgent(agent);
+                if (activity !== "idle")
+                    return { started: false, skipReason: `worker_${activity}` };
+                if (agent.status !== "registered") {
+                    const settled = this.settleTerminalTaskBearingMessage(agent, mailbox, message, { started: false, skipReason: `agent_${agent.status}` }, expectedMessageId);
+                    if (settled)
+                        return settled;
+                    continue;
+                }
+                const reuseSkipReason = this.reusableTaskAdmissionSkipReason(agent.agentId);
+                if (reuseSkipReason) {
+                    this.reconcileControlTranscript(agent, message, true);
+                    this.acknowledgeDeliveredMailboxMessage(agent.agentId, message.messageId);
+                    const settlement = {
+                        started: false,
+                        skipReason: `${reuseSkipReason}:transcript_fallback_delivered`,
+                    };
+                    if (expectedMessageId === message.messageId)
+                        return settlement;
+                    continue;
+                }
+                try {
+                    this.enableAttemptAccountingForNextTask(agent);
+                    const prepared = this.options.getLifecycle().prepareAgentTurn({
+                        agentId: agent.agentId,
+                        instructions: message.content,
+                        controlMessageId: message.messageId,
+                        ...(message.task?.kind === "agent_turn" && message.task.dependsOnTaskIds
+                            ? { dependsOnTaskIds: message.task.dependsOnTaskIds }
+                            : {}),
+                    });
+                    return this.scheduleTaskBearingAttempt(prepared.record, prepared.attempt);
+                }
+                catch (error) {
+                    const recovered = this.controlMessageAttempt(agent.agentId, message);
+                    if (recovered) {
+                        const scheduled = this.scheduleCorrelatedTaskBearingAttempt(recovered);
+                        if (scheduled.skipReason?.startsWith("worker_task_terminal_")) {
+                            const settled = this.settleTerminalTaskBearingMessage(agent, mailbox, message, scheduled, expectedMessageId);
+                            if (settled)
+                                return settled;
+                            continue;
+                        }
+                        return {
+                            ...scheduled,
+                            ...(scheduled.skipReason
+                                ? {}
+                                : { skipReason: "worker_task_recovered_after_prepare_interruption" }),
+                        };
+                    }
+                    return { started: false, skipReason: error instanceof Error ? error.message : String(error) };
+                }
+            }
+            this.scheduleTaskBearingReconciliationContinuation(agentId);
+            return { started: false, skipReason: "worker_task_reconciliation_bound_reached" };
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            try {
+                this.options.warn?.(`Worker task-bearing mailbox reconciliation failed for ${agentId}: ${reason}`);
+            }
+            catch {
+                // Diagnostics are observers; the pending mailbox remains the recovery source of truth.
+            }
+            return { started: false, skipReason: reason };
+        }
+        finally {
+            this.reconcilingTaskBearingAgentIds.delete(agentId);
+        }
+    }
+    scheduleTaskBearingReconciliationContinuation(agentId) {
+        if (this.taskBearingContinuationAgentIds.has(agentId))
+            return;
+        this.taskBearingContinuationAgentIds.add(agentId);
+        queueMicrotask(() => {
+            this.taskBearingContinuationAgentIds.delete(agentId);
+            this.reconcileTaskBearingMailbox(agentId);
+        });
+    }
+    reconcileTaskBearingTranscriptDelivery(target, message) {
+        if (!this.reconcileControlTranscript(target, message, false).delivered)
+            return false;
+        this.acknowledgeDeliveredMailboxMessage(target.agentId, message.messageId);
+        return true;
+    }
+    settleTerminalTaskBearingMessage(agent, mailbox, message, scheduled, expectedMessageId) {
+        const returnSettlement = expectedMessageId === message.messageId;
+        if (scheduled.skipReason && mailbox.deadLetterOrdinaryTask(message.messageId, scheduled.skipReason)) {
+            return returnSettlement ? scheduled : undefined;
+        }
+        const retained = mailbox.getMessage(message.messageId);
+        if (!retained || retained.deliveredAt !== undefined || retained.failedAt !== undefined) {
+            return returnSettlement ? scheduled : undefined;
+        }
+        const activity = this.activityForAgent(agent);
+        if (activity !== "idle") {
+            return { ...scheduled, skipReason: `worker_${activity}:transcript_fallback_waiting` };
+        }
+        this.reconcileControlTranscript(agent, retained, true);
+        this.acknowledgeDeliveredMailboxMessage(agent.agentId, retained.messageId);
+        const settlement = {
+            ...scheduled,
+            skipReason: `${scheduled.skipReason ?? "worker_task_terminal"}:transcript_fallback_delivered`,
+        };
+        return returnSettlement ? settlement : undefined;
+    }
+    controlMessageAttempt(agentId, message) {
+        const attempt = this.controlMessageAttemptById(agentId, message.messageId);
+        if (attempt && attempt.dispatch.instructions !== message.content) {
+            throw new Error(`Worker control message '${message.messageId}' conflicts with its durable dispatch.`);
+        }
+        return attempt;
+    }
+    controlMessageAttemptById(agentId, messageId) {
+        const matches = Object.values(this.options.getLifecycle().getTaskRuntimeSnapshot().attempts).filter((attempt) => attempt.dispatch.logicalLaneId === agentId && attempt.dispatch.controlMessageId === messageId);
+        if (matches.length > 1) {
+            throw new Error(`Worker control message '${messageId}' owns multiple durable attempts.`);
+        }
+        return matches[0];
+    }
+    scheduleCorrelatedTaskBearingAttempt(attempt) {
+        const record = this.options.getLifecycle().getRecord(attempt.taskId);
+        if (!record)
+            return { started: false, skipReason: "orchestration_projection_missing" };
+        if (attempt.status === "queued")
+            return this.scheduleTaskBearingAttempt(record, attempt);
+        if (attempt.status === "leased" || attempt.status === "running" || attempt.status === "suspended") {
+            return { started: true, record };
+        }
+        return { started: false, record, skipReason: `worker_task_terminal_${attempt.status}` };
+    }
+    scheduleTaskBearingAttempt(record, attempt) {
+        try {
+            this.options.scheduler.enqueue(record, this.options.recoveredRequest(attempt));
+        }
+        catch (error) {
+            return {
+                started: false,
+                record,
+                skipReason: error instanceof Error ? error.message : String(error),
+            };
+        }
+        try {
             this.options.scheduler.drain();
-            started = true;
+            return { started: true, record };
         }
-        this.signalStateChanged();
-        return { messageId: queued.messageId, started };
+        catch (error) {
+            return {
+                started: true,
+                record,
+                skipReason: `worker_task_recovery_pending:${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    enableAttemptAccountingForNextTask(agent) {
+        if (!agent.resumeContext.sessionFile)
+            return;
+        this.conversations
+            .open({
+            agentDir: this.options.agentDir,
+            resumeContext: agent.resumeContext,
+            expectedLogicalAgentId: agent.agentId,
+        })
+            .enableAttemptUsageBoundaries();
     }
     requireControl() {
         if (!this.options.isControlAvailable()) {
             throw new Error("Worker delegation control is unavailable in this UAC surface.");
         }
     }
+    canonicalAgentIdSet(agentIds, label) {
+        if (!Array.isArray(agentIds) || agentIds.length < 1 || agentIds.length > MAX_ORCHESTRATION_COLLECTION_LENGTH) {
+            throw new TypeError(`${label} agent ids must contain from 1 through ${MAX_ORCHESTRATION_COLLECTION_LENGTH} entries.`);
+        }
+        const canonicalAgentIds = [];
+        const seenAgentIds = new Set();
+        for (const agentId of agentIds) {
+            if (typeof agentId !== "string")
+                throw new TypeError("Logical worker agent id is required.");
+            const canonicalAgentId = agentId.trim();
+            if (!canonicalAgentId)
+                throw new TypeError("Logical worker agent id is required.");
+            if (canonicalAgentId.length > MAX_ORCHESTRATION_IDENTIFIER_LENGTH) {
+                throw new TypeError(`Logical worker agent id exceeds ${MAX_ORCHESTRATION_IDENTIFIER_LENGTH} characters.`);
+            }
+            if (seenAgentIds.has(canonicalAgentId))
+                continue;
+            seenAgentIds.add(canonicalAgentId);
+            canonicalAgentIds.push(canonicalAgentId);
+        }
+        return canonicalAgentIds;
+    }
     requireKnownAgent(agentId) {
         const normalized = agentId.trim();
         if (!normalized)
@@ -273,18 +1381,14 @@ export class WorkerAgentControlCoordinator {
             throw new Error(`Unknown logical worker agent '${normalized}'.`);
         return agent;
     }
-    requireVisibleAgent(agentId, scope) {
+    requireSessionPeer(agentId, scope) {
         const target = this.requireKnownAgent(agentId);
-        if (!scope.callerAgentId)
-            return target;
-        const caller = this.requireKnownAgent(scope.callerAgentId);
-        if (caller.rootAgentId !== target.rootAgentId) {
-            throw new Error(`Logical worker agent '${target.agentId}' is outside the caller's agent tree.`);
-        }
+        if (scope.callerAgentId)
+            this.requireKnownAgent(scope.callerAgentId);
         return target;
     }
     requireControllableAgent(agentId, scope) {
-        const target = this.requireVisibleAgent(agentId, scope);
+        const target = this.requireSessionPeer(agentId, scope);
         if (!scope.callerAgentId)
             return target;
         const caller = this.requireKnownAgent(scope.callerAgentId);
@@ -305,6 +1409,20 @@ export class WorkerAgentControlCoordinator {
             return latest;
         return agent.activeAttemptId ? lifecycle.getTaskRuntimeSnapshot().attempts[agent.activeAttemptId] : undefined;
     }
+    latestAttemptsByAgent(snapshot) {
+        return latestAgentAttemptsByDurableOrder(snapshot);
+    }
+    activityForAgent(agent) {
+        return this.projectAgentActivity(agent, this.latestAgentAttempt(agent));
+    }
+    projectAgentActivity(agent, attempt) {
+        if (attempt?.status === "suspended" || agent.status === "suspended")
+            return "suspended";
+        if (attempt?.status === "queued" || attempt?.status === "leased" || attempt?.status === "running") {
+            return "active";
+        }
+        return "idle";
+    }
     controlledAgentAttempt(agentId, scope) {
         this.requireControl();
         const agent = this.requireControllableAgent(agentId, scope);
@@ -323,39 +1441,103 @@ export class WorkerAgentControlCoordinator {
         }
         return mailbox;
     }
+    isAcceptedControlReplay(agentId, idempotencyKey) {
+        if (idempotencyKey === undefined)
+            return false;
+        const messageId = workerAgentMessageId(this.options.parentSessionId, idempotencyKey);
+        const mailbox = this.getMailbox(agentId);
+        return mailbox.getMessage(messageId) !== undefined || mailbox.hasControlReplayReceipt(messageId);
+    }
+    reusableTaskAdmissionSkipReason(agentId) {
+        const admission = evaluateReusableWorkerTaskAdmission(this.options.getLifecycle().getTaskRuntimeSnapshot(), agentId);
+        return admission.ok ? undefined : admission.reasonCode;
+    }
     subscribeStateChanges(listener) {
         this.stateListeners.add(listener);
         return () => this.stateListeners.delete(listener);
     }
-    enqueuePeerMessage(target, kind, content, options) {
-        if (!options.replyToMessageId) {
-            return this.getMailbox(target.agentId).enqueue({ kind, content, ...options });
-        }
-        if (!options.senderAgentId)
-            throw new Error("A worker reply requires its sender agent identity.");
-        const sender = this.requireKnownAgent(options.senderAgentId);
-        if (sender.rootAgentId !== target.rootAgentId)
-            throw new Error("A worker reply target is outside its agent tree.");
-        const senderMailbox = this.getMailbox(sender.agentId);
-        const request = senderMailbox.getMessage(options.replyToMessageId);
+    acknowledgeDeliveredMailboxMessage(agentId, messageId) {
+        const mailbox = this.getMailbox(agentId);
+        const controlMessage = mailbox.getMessage(messageId);
+        if (controlMessage) {
+            const target = this.requireKnownAgent(agentId);
+            const sourceMailbox = this.beginWorkerReplyAcknowledgement(target, controlMessage, true);
+            mailbox.acknowledgeDelivered(messageId);
+            if (sourceMailbox &&
+                controlMessage.replyToMessageId &&
+                !sourceMailbox.commitReplyAcknowledgement(controlMessage.replyToMessageId, controlMessage.messageId) &&
+                sourceMailbox.getReplyAcknowledgementId(controlMessage.replyToMessageId) !== undefined) {
+                throw new Error("Worker reply source acknowledgement did not commit.");
+            }
+            return;
+        }
+        mailbox.acknowledgeDelivered(messageId);
+    }
+    beginWorkerReplyAcknowledgement(target, reply, allowCommittedSource = false) {
+        if (reply.replyToMessageId === undefined)
+            return undefined;
+        if (!reply.senderAgentId)
+            throw new Error("Worker reply routing metadata is incomplete.");
+        const source = this.requireKnownAgent(reply.senderAgentId);
+        const sourceMailbox = this.getMailbox(source.agentId);
+        const request = sourceMailbox.getMessage(reply.replyToMessageId);
         if (!request || request.expectReply !== true || request.deliveredAt === undefined) {
             throw new Error("Worker reply does not reference a delivered reply-expected message.");
         }
         if (request.senderAgentId !== target.agentId) {
             throw new Error("Worker reply target does not match the original requester.");
         }
-        if (request.threadId && options.threadId && request.threadId !== options.threadId) {
+        if (request.threadId !== reply.threadId) {
             throw new Error("Worker reply thread conflicts with the original request.");
         }
-        const queued = this.getMailbox(target.agentId).enqueue({
+        const activeAcknowledgementId = sourceMailbox.getReplyAcknowledgementId(request.messageId);
+        if (activeAcknowledgementId && activeAcknowledgementId !== reply.messageId) {
+            throw new Error("Worker reply acknowledgement identity conflicts with an active transaction.");
+        }
+        if (request.repliedAt !== undefined && activeAcknowledgementId === undefined) {
+            if (allowCommittedSource || reply.deliveredAt !== undefined)
+                return sourceMailbox;
+            throw new Error("Worker reply source was marked replied without its exact acknowledgement marker.");
+        }
+        if (!sourceMailbox.beginReplyAcknowledgement(request.messageId, reply.messageId, reply.content)) {
+            throw new Error("Worker reply source acknowledgement could not be acquired.");
+        }
+        return sourceMailbox;
+    }
+    enqueuePeerMessage(target, kind, content, options, task) {
+        if (options.idempotencyKey !== undefined) {
+            this.assertIdempotencyTarget(target.agentId, options.idempotencyKey);
+        }
+        return this.getMailbox(target.agentId).enqueueWithReceipt({
             kind,
             content,
             ...options,
-            ...(request.threadId && !options.threadId ? { threadId: request.threadId } : {}),
-            idempotencyKey: `peer-reply:${sender.agentId}:${request.messageId}`,
+            ...(task ? { task } : {}),
         });
-        senderMailbox.markReplied(request.messageId);
-        return queued;
+    }
+    workerAgentView(agent, activity = this.activityForAgent(agent)) {
+        return {
+            agentId: agent.agentId,
+            ...(agent.parentAgentId ? { parentAgentId: agent.parentAgentId } : {}),
+            rootAgentId: agent.rootAgentId,
+            depth: agent.depth,
+            role: agent.role,
+            status: agent.status,
+            activity,
+            createdAt: agent.createdAt,
+            updatedAt: agent.updatedAt,
+        };
+    }
+    assertIdempotencyTarget(targetAgentId, idempotencyKey) {
+        const messageId = workerAgentMessageId(this.options.parentSessionId, idempotencyKey);
+        for (const agent of Object.values(this.options.getLifecycle().getTaskRuntimeSnapshot().agents)) {
+            if (agent.agentId === targetAgentId)
+                continue;
+            const mailbox = this.getMailbox(agent.agentId);
+            if (mailbox.getMessage(messageId) || mailbox.hasControlReplayReceipt(messageId)) {
+                throw new Error(`Worker control idempotency identity is already accepted by logical worker '${agent.agentId}'.`);
+            }
+        }
     }
     mailboxMessage(message) {
         const metadata = [