maka-agent 0.2.0-dev.23.20260906 → 0.2.0-dev.24.20260907

package/node_modules/@maka/runtime-host/dist/server/root-turn-coordinator.js

@@ -18,6 +18,8 @@
  */
 import { createHash, randomUUID } from 'node:crypto';
 import { isDeepStrictEqual } from 'node:util';
+import { readLogicalRuntimeExecution, readLogicalRuntimeExecutionForRun, } from '@maka/core/runtime-logical-execution';
+import { runtimeHandoffPause } from '@maka/core/runtime-handoff';
 import { INLINE_REFERENCE_MAX_COUNT, messageContentDigest, messageContentsEqual, normalizeMessageContent, } from '@maka/core/events';
 import { isWorkHubCoordinationSessionId } from '@maka/core/session';
 import { resolveEffectiveOrchestration } from '@maka/core/orchestration';
@@ -58,6 +60,8 @@ export class RootTurnCoordinator {
     };
     #executions = new HostedExecutionRegistry();
     #admissions;
+    #handoffHold;
+    #cancelHandoff;
     #recoveryPlansBySession = new Map();
     stores;
     executionProjection;
@@ -117,6 +121,8 @@ export class RootTurnCoordinator {
                     }
                 }
                 else {
+                    if (plan.rootReplayAdmission === admission)
+                        continue;
                     if (admission.execution.kind !== 'safe_boundary_continuation') {
                         throw new Error(`Startup recovery left Turn ${admission.turnId} non-terminal`);
                     }
@@ -127,7 +133,11 @@ export class RootTurnCoordinator {
             if (!admission)
                 continue;
             // Session recovery may have materialized this Run after the replay plan was prepared.
-            if (await this.readRunIfPresent(sessionId, admission.runId))
+            const existingRun = await this.readRunIfPresent(sessionId, admission.runId);
+            const pendingHandoff = existingRun &&
+                (await readLogicalRuntimeExecution(this.stores.runtimeEventStore, admission, existingRun))
+                    ?.pendingHandoff;
+            if (existingRun && !pendingHandoff)
                 continue;
             const input = activationInputForAdmission(admission);
             const disposition = await this.sessionAdmission.run(sessionId, async (lease) => {
@@ -138,7 +148,7 @@ export class RootTurnCoordinator {
                         return undefined;
                     }
                 }
-                const continuation = admission.execution.kind === 'safe_boundary_continuation'
+                const continuation = admission.execution.kind === 'safe_boundary_continuation' && !pendingHandoff
                     ? await this.reconstructAdmittedContinuation(admission)
                     : undefined;
                 if (continuation?.disposition === 'parked') {
@@ -169,6 +179,7 @@ export class RootTurnCoordinator {
         this.#recoveryPlansBySession.clear();
     }
     async close() {
+        this.#cancelHandoff?.();
         this.beginDrain();
         await this.#admissions.waitForSettledAdmissions();
         const errors = [];
@@ -221,7 +232,9 @@ export class RootTurnCoordinator {
                 runId: active.runId,
             };
         }
-        return this.#admissions.has(sessionId) ? { kind: 'reserved' } : { kind: 'idle' };
+        return this.#handoffHold || this.#admissions.has(sessionId)
+            ? { kind: 'reserved' }
+            : { kind: 'idle' };
     }
     /** Returns the newest Host-admitted continuation descended from one root execution. */
     async readLatestRootTurnLineage(identity) {
@@ -231,7 +244,11 @@ export class RootTurnCoordinator {
         }
         let latest = origin;
         while (true) {
-            const continuation = await this.stores.agentRunStore.readRootTurnContinuationAdmission(identity.sessionId, latest.turnId, latest.runId);
+            const run = await this.readRunIfPresent(latest.sessionId, latest.runId);
+            const physical = run?.terminalEvent && runtimeHandoffPause(run.terminalEvent)
+                ? (await readLogicalRuntimeExecution(this.stores.runtimeEventStore, latest, run))?.tip
+                : run;
+            const continuation = await this.stores.agentRunStore.readRootTurnContinuationAdmission(identity.sessionId, latest.turnId, physical?.runId ?? latest.runId);
             if (!continuation)
                 break;
             latest = continuation;
@@ -249,12 +266,16 @@ export class RootTurnCoordinator {
         }, context);
     }
     reserveRootTurn(sessionId) {
+        if (this.#handoffHold)
+            return undefined;
         return this.#admissions.reserve(sessionId);
     }
     parkContinuationAdmission(admission) {
         this.#admissions.park(admission);
     }
     takeParkedContinuationReservation(admission) {
+        if (this.#handoffHold)
+            return undefined;
         return this.#admissions.takeParked(admission);
     }
     clearParkedContinuationAdmission(admission) {
@@ -272,6 +293,163 @@ export class RootTurnCoordinator {
     beginDrain() {
         this.#admissions.beginDrain();
     }
+    async prepareHandoff(hostEpoch, signal) {
+        if (this.#handoffHold || this.#admissions.isDraining || signal.aborted)
+            return undefined;
+        const hold = deferred();
+        this.#handoffHold = hold;
+        const held = new Map();
+        let sealed = false;
+        let detached = false;
+        const releaseHold = () => {
+            if (this.#handoffHold === hold) {
+                this.#handoffHold = undefined;
+                this.#cancelHandoff = undefined;
+            }
+            hold.resolve();
+            signal.removeEventListener('abort', cancel);
+        };
+        const cancel = () => {
+            if (detached)
+                return;
+            sealed = false;
+            for (const [active, { request, attachment }] of held) {
+                request.cancel();
+                attachment.arrived.resolve();
+                attachment.decision.resolve('resume');
+                if (active.handoff === attachment)
+                    active.handoff = undefined;
+            }
+            releaseHold();
+        };
+        this.#cancelHandoff = cancel;
+        signal.addEventListener('abort', cancel, { once: true });
+        try {
+            await waitForHostedExecutionIdleOrAbort(this.#admissions.waitForSettledAdmissions(), signal);
+            // Natural completion can hand a queued follow-up to a fresh root while
+            // gates converge. Bound that convergence; never chase an endless queue.
+            for (let pass = 0; pass < 3; pass += 1) {
+                for (const [, active] of this.#executions.entries()) {
+                    if (held.has(active))
+                        continue;
+                    await waitForHostedExecutionIdleOrAbort(active.startSettled.promise, signal);
+                    if (this.#executions.get(active.sessionId) !== active)
+                        continue;
+                    const request = this.manager.requestRunHandoff(active.sessionId, active.continuation?.runId ?? active.runId, {
+                        protocol: 'runtime_handoff_pause_v1',
+                        hostEpoch,
+                        handoffId: randomUUID(),
+                        rootRunId: active.runId,
+                        successorRunId: randomUUID(),
+                        successorInvocationId: randomUUID(),
+                        claimId: randomUUID(),
+                    }, signal);
+                    if (!request) {
+                        cancel();
+                        return undefined;
+                    }
+                    const attachment = {
+                        decision: valueDeferred(),
+                        arrived: deferred(),
+                    };
+                    active.handoff = attachment;
+                    held.set(active, { request, attachment });
+                }
+                for (const [active, item] of held) {
+                    if (await waitForAbortableValue(item.request.ready, signal))
+                        continue;
+                    const snapshot = await this.readCanonicalSnapshot(active.sessionId, active.turnId, active.runId);
+                    if (!isTerminalSnapshot(snapshot)) {
+                        cancel();
+                        return undefined;
+                    }
+                    item.attachment.decision.resolve('resume');
+                    if (active.handoff === item.attachment)
+                        active.handoff = undefined;
+                    await waitForHostedExecutionIdleOrAbort(active.done, signal);
+                    held.delete(active);
+                }
+                if ([...this.#executions.entries()].every(([, active]) => held.has(active)))
+                    break;
+            }
+            if (signal.aborted ||
+                [...this.#executions.entries()].some(([, active]) => !held.has(active))) {
+                cancel();
+                return undefined;
+            }
+            return {
+                executions: [...held.keys()].map(({ sessionId, turnId, runId }) => ({
+                    sessionId,
+                    turnId,
+                    runId,
+                })),
+                seal: async () => {
+                    if (signal.aborted || this.#handoffHold !== hold || detached)
+                        return false;
+                    if (sealed)
+                        return true;
+                    for (const [active, { request }] of held) {
+                        if (this.#executions.get(active.sessionId) !== active || !request.commit()) {
+                            cancel();
+                            return false;
+                        }
+                    }
+                    try {
+                        const results = await Promise.all([...held.values()].map(({ request }) => request.sealed));
+                        sealed = !signal.aborted && this.#handoffHold === hold && results.every(Boolean);
+                        if (sealed) {
+                            await Promise.all([...held].map(([active, { attachment }]) => Promise.race([
+                                attachment.arrived.promise,
+                                active.done.then(() => {
+                                    throw new Error('Sealed execution ended before its attachment handoff');
+                                }),
+                            ])));
+                        }
+                    }
+                    catch (error) {
+                        cancel();
+                        throw error;
+                    }
+                    if (!sealed)
+                        cancel();
+                    return sealed;
+                },
+                residencies: async () => {
+                    if (!sealed || signal.aborted || this.#handoffHold !== hold || detached)
+                        return undefined;
+                    const residencies = [];
+                    for (const [active, { attachment }] of held) {
+                        if (this.#executions.get(active.sessionId) !== active ||
+                            active.handoff !== attachment ||
+                            active.stopRequested)
+                            return undefined;
+                        const messages = await this.sessionAdmission.run(active.sessionId, (lease) => this.messages.handoffResidencies(active, lease));
+                        if (!messages)
+                            return undefined;
+                        residencies.push(active.residency, ...messages);
+                    }
+                    return residencies;
+                },
+                detach: async () => {
+                    if (!sealed || signal.aborted || this.#handoffHold !== hold || detached) {
+                        throw new Error('Cannot detach a handoff without all durable seals');
+                    }
+                    detached = true;
+                    for (const { attachment } of held.values())
+                        attachment.decision.resolve('detach');
+                    await Promise.all([...held.keys()].map((active) => active.done));
+                    releaseHold();
+                },
+                cancel,
+            };
+        }
+        catch (error) {
+            cancel();
+            if (signal.aborted)
+                return undefined;
+            throw error;
+        }
+    }
     async runExclusiveSessionOperation(input, operation) {
         const { sessionId, abortSignal } = input;
         let reservation;
@@ -287,7 +465,7 @@ export class RootTurnCoordinator {
             }
             const active = this.#executions.get(sessionId);
             const pending = this.#admissions.get(sessionId);
-            const whenIdle = active?.done ?? pending?.whenIdle.promise;
+            const whenIdle = active?.done ?? pending?.whenIdle.promise ?? this.#handoffHold?.promise;
             if (whenIdle) {
                 await waitForHostedExecutionIdleOrAbort(whenIdle, abortSignal);
             }
@@ -336,6 +514,8 @@ export class RootTurnCoordinator {
                 reason: 'Runtime Host execution authority is draining.',
             };
         }
+        if (this.#handoffHold)
+            return { kind: 'busy', whenIdle: this.#handoffHold.promise };
         const active = this.#executions.get(sessionId);
         if (active) {
             return {
@@ -528,7 +708,9 @@ export class RootTurnCoordinator {
         return this.#executions.subscribe(listener);
     }
     whenIdle(sessionId) {
-        return (this.#executions.get(sessionId)?.done ?? this.#admissions.get(sessionId)?.whenIdle.promise);
+        return (this.#executions.get(sessionId)?.done ??
+            this.#admissions.get(sessionId)?.whenIdle.promise ??
+            this.#handoffHold?.promise);
     }
     stopRoot(identity, input = {}) {
         normalizeStopSessionSource(input.source, input.workHubActionId);
@@ -1330,9 +1512,19 @@ export class RootTurnCoordinator {
         });
     }
     async planTurnResume(input) {
-        const plan = input.sourceRunId
+        let sourceRunId = input.sourceRunId;
+        if (sourceRunId) {
+            const run = await this.readRunIfPresent(input.sessionId, sourceRunId);
+            if (run?.terminalEvent && runtimeHandoffPause(run.terminalEvent)) {
+                const logical = await readLogicalRuntimeExecutionForRun(this.stores.runtimeEventStore, run);
+                // Queries may name the stable public root. The returned plan and the
+                // subsequent start must still bind the exact physical source/high-water.
+                sourceRunId = logical?.tip.runId ?? sourceRunId;
+            }
+        }
+        const plan = sourceRunId
             ? await this.manager.planAuthoritativeSafeBoundaryContinuation(input.sessionId, {
-                sourceRunId: input.sourceRunId,
+                sourceRunId,
                 ...(input.expectedRuntimeEventHighWater !== undefined
                     ? {
                         expectedRuntimeEventHighWater: input.expectedRuntimeEventHighWater,
@@ -1391,9 +1583,9 @@ export class RootTurnCoordinator {
         }
         const fence = commitQueueFence();
         await this.messages.cancelMessages(input.sessionId, fence.retracted.map((message) => message.messageId));
-        await this.interactions.claimRunClosure(input, 'turn_stopped', admission);
+        await this.interactions.claimRunClosure({ ...input, runId: active.continuation?.runId ?? active.runId }, 'turn_stopped', admission);
         const shouldDeliverStop = !active.stopRequested;
-        active.stopRequested = true;
+        active.stopRequested = stopInput;
         return {
             active,
             deliverStop: () => shouldDeliverStop
@@ -1418,7 +1610,7 @@ export class RootTurnCoordinator {
             if (active?.turnId === input.turnId && active.runId === input.runId) {
                 const fence = commitQueueFence();
                 await this.messages.cancelMessages(input.sessionId, fence.retracted.map((message) => message.messageId));
-                active.stopRequested = true;
+                active.stopRequested ??= { source: 'stop_button' };
                 return { kind: 'await_terminal', active };
             }
             return { kind: 'complete', outcome: { ok: true, result: snapshot } };
@@ -1441,9 +1633,9 @@ export class RootTurnCoordinator {
         }
         const fence = commitQueueFence();
         await this.messages.cancelMessages(input.sessionId, fence.retracted.map((message) => message.messageId));
-        await this.interactions.claimRunClosure(input, 'turn_stopped', admissionLease);
+        await this.interactions.claimRunClosure({ ...input, runId: active.continuation?.runId ?? active.runId }, 'turn_stopped', admissionLease);
         const shouldRequestStop = !active.stopRequested;
-        active.stopRequested = true;
+        active.stopRequested ??= { source: 'stop_button' };
         return shouldRequestStop
             ? { kind: 'request_stop', active }
             : { kind: 'await_terminal', active };
@@ -1484,7 +1676,19 @@ export class RootTurnCoordinator {
             }
             if (active)
                 return completedStart(sessionBusy('Session already has an active root Turn'));
-            throw new Error('Admitted non-terminal Turn has no active Runtime Host execution');
+            const logical = await readLogicalRuntimeExecution(this.stores.runtimeEventStore, admission, existingRun);
+            if (!logical?.pendingHandoff) {
+                throw new Error('Admitted non-terminal Turn has no active Runtime Host execution');
+            }
+            const plan = await this.manager.planAuthoritativeSafeBoundaryContinuation(input.sessionId, {
+                sourceRunId: logical.tip.runId,
+                purpose: 'handoff',
+            });
+            if (!plan.continuation) {
+                this.parkContinuationAdmission(admission);
+                return completedStart(operationUnavailable(`Sealed handoff cannot resume: ${plan.rejectionReasons.join(', ')}`));
+            }
+            continuation = plan.continuation;
         }
         const active = this.#executions.get(input.sessionId);
         const currentReservation = this.#admissions.get(input.sessionId);
@@ -1517,6 +1721,9 @@ export class RootTurnCoordinator {
         try {
             this.messages.reserveRootTurn(messageIdentity);
             messageReserved = true;
+            if (continuation?.handoffRootRunId !== undefined) {
+                await this.messages.advanceHandoffRun(messageIdentity, continuation.runId, admissionLease);
+            }
             await this.continuity.holdTerminalPublication(input.sessionId, input.turnId, runId, admissionLease);
         }
         catch (error) {
@@ -1547,7 +1754,7 @@ export class RootTurnCoordinator {
             startSettled,
             done: Promise.resolve(),
             residency,
-            stopRequested: false,
+            stopRequested: undefined,
             messageTransitionCommitted: false,
         };
         if (replacing && this.#executions.get(input.sessionId) !== replacing) {
@@ -1613,6 +1820,7 @@ export class RootTurnCoordinator {
     }
     async drainTurn(input, active, startSettled) {
         let terminalTransitionStarted = false;
+        let detached = false;
         try {
             const messageOrigin = hostedExecutionMessageOrigin(active.descriptor);
             const onRunStarted = async () => {
@@ -1620,46 +1828,80 @@ export class RootTurnCoordinator {
                 await this.continuity.refreshCanonical(input.sessionId);
                 startSettled.resolve();
             };
-            const stream = active.execution
-                ? active.execution.start({
-                    runId: active.runId,
-                    userMessageId: active.userMessageId,
-                    onRunStarted: async () => {
-                        await onRunStarted();
-                        await active.execution?.onReady?.();
-                    },
+            let stream = active.continuation
+                ? this.manager.resumeSafeBoundaryContinuation(active.continuation, {
+                    onRunStarted,
+                    stopBeforeDispatch: () => active.stopRequested,
                 })
-                : active.descriptor.kind === 'context_compact'
-                    ? this.manager.compactSession(input.sessionId, {
-                        turnId: input.turnId,
-                        hostedRoot: {
-                            runId: active.runId,
-                            onRunStarted,
+                : active.execution
+                    ? active.execution.start({
+                        runId: active.runId,
+                        userMessageId: active.userMessageId,
+                        onRunStarted: async () => {
+                            await onRunStarted();
+                            await active.execution?.onReady?.();
                         },
                     })
-                    : active.continuation
-                        ? this.manager.resumeSafeBoundaryContinuation(active.continuation, {
-                            onRunStarted,
+                    : active.descriptor.kind === 'context_compact'
+                        ? this.manager.compactSession(input.sessionId, {
+                            turnId: input.turnId,
+                            hostedRoot: {
+                                runId: active.runId,
+                                onRunStarted,
+                            },
                         })
-                        : this.startRootMessageTurn(input, active, normalizeMessageContent(requireRootMessageContent(input)), messageOrigin, onRunStarted);
-            for await (const event of stream) {
-                if (active.execution?.onEvent) {
-                    try {
-                        active.execution.onEvent(event);
+                        : active.continuation
+                            ? this.manager.resumeSafeBoundaryContinuation(active.continuation, {
+                                onRunStarted,
+                            })
+                            : this.startRootMessageTurn(input, active, normalizeMessageContent(requireRootMessageContent(input)), messageOrigin, onRunStarted);
+            for (;;) {
+                for await (const event of stream) {
+                    if (active.execution?.onEvent) {
+                        try {
+                            active.execution.onEvent(event);
+                        }
+                        catch {
+                            // Presentation observers do not participate in execution authority.
+                        }
                     }
-                    catch {
-                        // Presentation observers do not participate in execution authority.
+                    if (isRuntimeSessionForwardedEvent(event)) {
+                        await this.continuity.acceptRuntimeEvent(input.sessionId, active.runId, event);
+                    }
+                    else if (isInteractionAnswerAck(event)) {
+                        await this.continuity.refreshCanonical(input.sessionId);
+                    }
+                    else if (event.type === 'user_question_request' || event.type === 'form_request') {
+                        this.continuity.enqueueCanonicalRefresh(input.sessionId);
                     }
                 }
-                if (isRuntimeSessionForwardedEvent(event)) {
-                    await this.continuity.acceptRuntimeEvent(input.sessionId, active.runId, event);
-                }
-                else if (isInteractionAnswerAck(event)) {
-                    await this.continuity.refreshCanonical(input.sessionId);
-                }
-                else if (event.type === 'user_question_request' || event.type === 'form_request') {
-                    this.continuity.enqueueCanonicalRefresh(input.sessionId);
-                }
+                const logical = await readLogicalRuntimeExecution(this.stores.runtimeEventStore, active);
+                if (!logical?.pendingHandoff)
+                    break;
+                const handoff = active.handoff;
+                handoff?.arrived.resolve();
+                if (handoff && (await handoff.decision.promise) === 'detach') {
+                    await this.sessionAdmission.run(input.sessionId, (lease) => this.messages.detachHandoffRoot(active, lease));
+                    detached = true;
+                    return;
+                }
+                await this.sessionAdmission.run(input.sessionId, async (lease) => {
+                    if (this.#executions.get(input.sessionId) !== active) {
+                        throw new RuntimeMessageAuthorityInvariantError('Sealed handoff lost its original root owner');
+                    }
+                    const plan = await this.manager.planAuthoritativeSafeBoundaryContinuation(input.sessionId, {
+                        sourceRunId: logical.tip.runId,
+                        purpose: 'handoff',
+                    });
+                    if (!plan.continuation)
+                        throw new Error(`Sealed handoff cannot resume: ${plan.rejectionReasons.join(', ')}`);
+                    await this.messages.advanceHandoffRun(active, plan.continuation.runId, lease);
+                    active.continuation = plan.continuation;
+                });
+                stream = this.manager.resumeSafeBoundaryContinuation(active.continuation, {
+                    onRunStarted,
+                    stopBeforeDispatch: () => active.stopRequested,
+                });
             }
             const snapshot = await this.readCanonicalSnapshot(input.sessionId, input.turnId, active.runId);
             await this.assertCompletedExecutionIdentity(input, active);
@@ -1702,7 +1944,7 @@ export class RootTurnCoordinator {
                                 ((!active.stopRequested &&
                                     snapshot.status === 'failed' &&
                                     isContainableRunFailure(error)) ||
-                                    (active.stopRequested &&
+                                    (Boolean(active.stopRequested) &&
                                         snapshot.status === 'cancelled' &&
                                         isStoppedInteractionAdmission(error)));
                     }
@@ -1725,32 +1967,38 @@ export class RootTurnCoordinator {
             throw commandFailure;
         }
         finally {
-            this.observeExecutionCompletion(active, {
-                kind: 'authority_error',
-                execution: active,
-                reason: 'Runtime root Turn ended without a canonical completion.',
-            });
-            await active.observationSettled?.catch(() => this.requestHostDrain());
-            let releaseRootOwnership = active.messageTransitionCommitted;
-            if (!active.messageTransitionCommitted) {
-                try {
-                    this.messages.abandonRootReservation({
-                        sessionId: input.sessionId,
-                        turnId: active.turnId,
-                        runId: active.runId,
-                    });
-                    releaseRootOwnership = true;
-                }
-                catch {
-                    this.requestHostDrain();
-                }
-            }
-            if (releaseRootOwnership) {
+            if (detached) {
                 this.#executions.release(active);
                 active.residency.release();
             }
-            active.completion.resolve(active.observedCompletion);
-            this.#executions.publish(active);
+            else {
+                this.observeExecutionCompletion(active, {
+                    kind: 'authority_error',
+                    execution: active,
+                    reason: 'Runtime root Turn ended without a canonical completion.',
+                });
+                await active.observationSettled?.catch(() => this.requestHostDrain());
+                let releaseRootOwnership = active.messageTransitionCommitted;
+                if (!active.messageTransitionCommitted) {
+                    try {
+                        this.messages.abandonRootReservation({
+                            sessionId: input.sessionId,
+                            turnId: active.turnId,
+                            runId: active.runId,
+                        });
+                        releaseRootOwnership = true;
+                    }
+                    catch {
+                        this.requestHostDrain();
+                    }
+                }
+                if (releaseRootOwnership) {
+                    this.#executions.release(active);
+                    active.residency.release();
+                }
+                active.completion.resolve(active.observedCompletion);
+                this.#executions.publish(active);
+            }
         }
     }
     async materializeAdmittedMessageSources(active) {
@@ -1789,7 +2037,7 @@ export class RootTurnCoordinator {
                 turnId: active.turnId,
                 runId: active.runId,
             };
-            await this.interactions.assertTerminalFence(identity, lease);
+            await this.interactions.assertTerminalFence({ ...identity, runId: active.continuation?.runId ?? active.runId }, lease);
             const batch = this.messages.beginTerminalTransition(identity);
             await this.continuity.publishTerminalProjection(sessionId, active.turnId, active.runId, lease);
             if (batch.sources.length === 0) {
@@ -1914,6 +2162,10 @@ export class RootTurnCoordinator {
         }
     }
 }
+async function waitForAbortableValue(value, signal) {
+    await waitForHostedExecutionIdleOrAbort(value.then(() => undefined), signal);
+    return value;
+}
 class HostedRootAdmissionGateError extends Error {
     cause;
     name = 'HostedRootAdmissionGateError';

package/node_modules/@maka/runtime-host/dist/server/scheduled-task-coordinator.js

@@ -71,6 +71,7 @@ export class HostScheduledTaskCoordinator {
     #prepared = false;
     #started = false;
     #draining = false;
+    #handoffHeld = false;
     #closed = false;
     #retiringSessions = new Set();
     constructor(input) {
@@ -156,6 +157,34 @@ export class HostScheduledTaskCoordinator {
         this.#started = true;
         void this.#refresh().catch((error) => this.#fatal(error));
     }
+    holdForHandoff() {
+        if (this.#draining || this.#handoffHeld)
+            return undefined;
+        this.#handoffHeld = true;
+        this.#stopTimer();
+        let released = false;
+        return {
+            settled: async () => {
+                // An admitted native effect or Agent fire finishes normally. No new
+                // fire may start while the handoff waits for this lane.
+                for (;;) {
+                    const lane = this.#lane;
+                    await lane;
+                    if (lane === this.#lane)
+                        return;
+                }
+            },
+            residencies: () => (this.#residency ? [this.#residency] : []),
+            release: () => {
+                if (released)
+                    return;
+                released = true;
+                this.#handoffHeld = false;
+                if (!this.#draining)
+                    void this.#refresh().catch((error) => this.#fatal(error));
+            },
+        };
+    }
     beginDrain() {
         if (this.#draining)
             return;
@@ -390,12 +419,16 @@ export class HostScheduledTaskCoordinator {
     }
     async #refresh() {
         await this.#exclusive(async () => {
+            if (this.#handoffHeld || this.#draining)
+                return;
             for (const claim of await this.#store.listPendingFires()) {
+                if (this.#handoffHeld || this.#draining)
+                    break;
                 if (claim.nativeState === 'waiting_for_provider') {
                     await this.#fulfill(claim, true);
                 }
             }
-            while (!this.#draining) {
+            while (!this.#draining && !this.#handoffHeld) {
                 const scan = await this.#store.claimNextDue(this.#now());
                 for (const expired of scan.expired)
                     this.#publish('updated', expired.id);
@@ -616,7 +649,7 @@ export class HostScheduledTaskCoordinator {
     async #refreshSchedule() {
         this.#stopTimer();
         await this.#refreshResidency();
-        if (!this.#started || this.#draining)
+        if (!this.#started || this.#draining || this.#handoffHeld)
             return;
         const [tasks, claims] = await Promise.all([this.#store.list(), this.#store.listPendingFires()]);
         const next = tasks
@@ -626,6 +659,8 @@ export class HostScheduledTaskCoordinator {
             return earliest === null || deadline < earliest ? deadline : earliest;
         }, null);
         const waitingForProvider = claims.some((claim) => claim.nativeState === 'waiting_for_provider');
+        if (this.#draining || this.#handoffHeld)
+            return;
         if (next === null && !waitingForProvider)
             return;
         const nextTaskDelay = next === null