@zq-silk/yui 0.12.0 → 0.12.2

package/dist/controller/runtime.js

@@ -36,6 +36,7 @@ import { createRuntimeResourceActivityTracker } from "./resourceInventory.js";
 import { SessionOwnerReconciliation } from "./sessionOwnerReconciliation.js";
 import { launchBrokerForHome } from "../runtime/launchBroker.js";
 import { classifyRuntimeProcessExit, validateRuntimeProcessExitObservation } from "../runtime/processExitObservation.js";
+import { replayRuntimeProcessExitOutbox } from "../runtime/processExitOutbox.js";
 import { appendGlobalProcessExitObservation } from "../runtime/globalProcessExitStore.js";
 import { builtinAgentDriverRegistry } from "../runtime/builtinAgentDrivers.js";
 import { createRuntimeObservation, runtimeObservationFromTaskEvent } from "../runtime/runtimeObservation.js";
@@ -385,6 +386,12 @@ export async function startFileTaskControllerRuntime(home, options = {}) {
             environment: options.environment
         });
     const lifecycleDispatcher = createRuntimeLifecycleDispatcher(store, schedulerStore, sessionHost, options.dispatcher, signalRuntimeCleanup, launchCoordinator, planner);
+    // Process-exit observations are persisted by the Agent Host before socket
+    // delivery. Drain them while this Controller is still the only storage
+    // writer and before it begins accepting new work after a handover.
+    await replayRuntimeProcessExitOutbox(home, async (observation) => {
+        await lifecycleDispatcher("runtime.process-exit-observe", observation);
+    });
     // f7/rr5: This same inbox feeds the supervisor's terminal channel and the
     // runtime event processor. When a Job reaches a terminal state, the
     // supervisor enqueues a durable-job-terminal event; the processor drains it
@@ -577,6 +584,11 @@ export function createRuntimeLifecycleDispatcher(store, schedulerStore, sessionH
             }
             return { recorded: true };
         }
+        if (method === "runtime.conversation-switch-detach") {
+            const value = conversationSwitchDetachParams(params);
+            const outcome = schedulerStore.detachAgentHostProviderForConversationSwitch(value);
+            return { recorded: outcome === "detached", outcome };
+        }
         if (method === "runtime.provider-turn-submission-resolve") {
             const value = providerTurnControlParams(params);
             const status = params.status;
@@ -671,6 +683,8 @@ export function createRuntimeLifecycleDispatcher(store, schedulerStore, sessionH
                 || !Number.isSafeInteger(hostPid) || hostPid <= 0) {
                 throw applicationError("INVALID_PARAMS", "Launch redemption identity is invalid.");
             }
+            // The launch payload is validated at reservation time and every member
+            // of its discriminated Provider-control union is JSON serializable.
             return launchBrokerForHome(store.rootDirectory()).redeem(launchId, ticket);
         }
         if (method === "runtime.replace-agent-environment") {
@@ -735,6 +749,9 @@ export function createRuntimeLifecycleDispatcher(store, schedulerStore, sessionH
             const activeRun = request.scope === "task"
                 ? store.getActiveAgentRun(request.taskId, request.roleName)
                 : null;
+            if (request.scope === "task" && activeRun === null) {
+                throw applicationError("INVALID_PARAMS", "Task Role runtime attachment requires an admitted active Run; it cannot create an empty Provider Conversation.");
+            }
             const managedWorkspace = request.scope === "task"
                 ? activeRun?.workspace
                     ?? currentDesiredManagedWorkspace(store, request.taskId, request.roleName)
@@ -754,8 +771,21 @@ export function createRuntimeLifecycleDispatcher(store, schedulerStore, sessionH
                 throw applicationError("INVALID_PARAMS", `Configured Agent does not match Role: ${effective.agentId}.`);
             }
             validateLifecycleEnvironment(request.environment, agent);
-            const mode = roleAgentSessionResumeMode(sessions, effective.agentId, effective);
             const session = sessions?.sessions[effective.agentId];
+            const managedTurnDispatch = activeRun !== null && (activeRun.pushedAt === undefined
+                || activeRun.providerRetry?.state === "dispatching"
+                || activeRun.controlRequest?.state === "dispatching");
+            // An ensure call may reattach the already-admitted Run to its existing
+            // Conversation, but it may not manufacture a fresh Conversation without a
+            // pending managed Turn. Fresh replacement remains owned by Run dispatch.
+            const mode = activeRun === null
+                ? roleAgentSessionResumeMode(sessions, effective.agentId, effective)
+                : managedTurnDispatch ? activeRun.mode : "resume";
+            if (request.scope === "task" && mode === "resume"
+                && (session?.nativeSessionId === undefined
+                    || session.nativeSessionId.trim().length === 0)) {
+                throw applicationError("INVALID_PARAMS", "Task Role runtime attachment cannot resume because its Provider Conversation identity is missing.");
+            }
             const owner = request.scope === "task"
                 ? { scope: "task", taskId: request.taskId, roleName: request.roleName }
                 : { scope: "global", roleName: request.roleName };
@@ -1105,6 +1135,31 @@ function providerTurnControlParams(params) {
         now: new Date(observedAt)
     };
 }
+function conversationSwitchDetachParams(params) {
+    if (typeof params !== "object" || params === null || Array.isArray(params)) {
+        throw applicationError("INVALID_PARAMS", "Provider Conversation detachment params are invalid.");
+    }
+    const value = params;
+    const nextAuthorityEpoch = value.nextAuthorityEpoch;
+    const observedAt = requiredParam(value.observedAt);
+    if (!Number.isSafeInteger(nextAuthorityEpoch) || nextAuthorityEpoch < 1
+        || !Number.isFinite(Date.parse(observedAt))) {
+        throw applicationError("INVALID_PARAMS", "Provider Conversation detachment fence is invalid.");
+    }
+    return {
+        taskId: requiredParam(value.taskId),
+        roleName: requiredParam(value.roleName),
+        runId: requiredParam(value.runId),
+        agentId: requiredParam(value.agentId),
+        launchId: requiredParam(value.launchId),
+        previousConversationId: requiredParam(value.previousConversationId),
+        previousNativeSessionId: requiredParam(value.previousNativeSessionId),
+        previousActivationId: requiredParam(value.previousActivationId),
+        nextAuthorityEpoch: nextAuthorityEpoch,
+        nextAuthorityHolderId: requiredParam(value.nextAuthorityHolderId),
+        now: new Date(observedAt)
+    };
+}
 function abortableDelay(milliseconds, signal) {
     return new Promise((resolve, reject) => {
         const timer = setTimeout(() => {

package/dist/controller/runtimeHookRunFence.js

@@ -4,6 +4,7 @@ import { nativeSessionIdForLaunch } from "../runtime/preallocatedNativeSession.j
 import { runtimeObservationFromTaskEvent } from "../runtime/runtimeObservation.js";
 import { YUI_CONTROL_PLANE_DESCRIPTOR, YUI_TASK_RUNTIME_DESCRIPTOR, assertExactTaskRuntimeEnvironment, exactControlPlaneDigest, parseExactControlPlaneDescriptor, refreshReusedTaskRuntimeDescriptorSource } from "../runtime/exactControlPlane.js";
 import { agentRunDeliveryReceiptId } from "../run/agentRun.js";
+import { conversationReplacementBasis } from "../runtime/conversationSwitch.js";
 /**
  * Resolves turn identity from the current durable in-flight fence. The one
  * exception is a Driver-declared startup Session Hook, which can arrive before
@@ -101,14 +102,27 @@ export function resolveRuntimeHookRunFence(environment, adapterId, payloadNative
     const startupRun = startupRunId === undefined
         ? null
         : store.getAgentRun(taskId, startupRunId);
+    const replacementStartup = options.startupSession !== undefined
+        && session !== undefined
+        && sessions !== null
+        && startupReservation
+        && startupRun?.mode === "new"
+        && conversationReplacementBasis({
+            sessions,
+            events: store.listEvents(taskId),
+            mailbox: roleMailbox,
+            roleName,
+            runId: startupRun.id,
+            runMode: startupRun.mode
+        }) !== null;
     const preallocatedStartup = options.startupSession === "preallocated"
         && expectedNativeSessionId !== undefined
-        && session === undefined
+        && (session === undefined || replacementStartup)
         && startupReservation
         && nativeSessionId === nativeSessionIdForLaunch(home, launchId, agentId, adapterId);
     const discoveredStartup = options.startupSession === "discovered"
         && expectedNativeSessionId === undefined
-        && session === undefined
+        && (session === undefined || replacementStartup)
         && startupReservation;
     const terminalRunId = options.terminal === true && acceptedBinding === null
         ? requireIdentity(environment.YUI_RUN_ID ?? runtime?.runId, "Run id")
@@ -154,6 +168,7 @@ export function resolveRuntimeHookRunFence(environment, adapterId, payloadNative
     if (acceptedBinding === null
         && runtime !== undefined
         && session !== undefined
+        && !replacementStartup
         && sessionLaunchId !== undefined
         && typeof runtimeSource === "string"
         && !runtimeSource.trimStart().startsWith("{")
@@ -187,7 +202,7 @@ export function resolveRuntimeHookRunFence(environment, adapterId, payloadNative
     if (run.effective.workspace.root !== workspace) {
         throw new Error("Runtime observation Hook workspace does not match the durable Run snapshot.");
     }
-    if (session !== undefined && acceptedBinding === null) {
+    if (session !== undefined && acceptedBinding === null && !replacementStartup) {
         if (session.adapterId !== adapterId
             || session.launchId !== effectiveLaunchId
             || session.nativeSessionId !== nativeSessionId
@@ -195,7 +210,7 @@ export function resolveRuntimeHookRunFence(environment, adapterId, payloadNative
             throw new Error("Runtime observation Hook Session does not match its durable generation.");
         }
     }
-    else if (session === undefined && acceptedBinding === null) {
+    else if (acceptedBinding === null && (session === undefined || replacementStartup)) {
         if (!discoveredStartup && !preallocatedStartup) {
             throw new Error("Runtime observation Hook launch is not durably reserved.");
         }

package/dist/controller/structuredProviderObservation.js

@@ -3,6 +3,7 @@ import { callController } from "../core/controllerClient.js";
 import { builtinAgentDriverRegistry } from "../runtime/builtinAgentDrivers.js";
 import { createRuntimeObservation, runtimeObservationSemanticKey } from "../runtime/runtimeObservation.js";
 import { runtimeLifecycleSignalKey } from "../runtime/lifecycleReservation.js";
+import { isForeignHandoverLockHeld } from "../release/runtimeRelease.js";
 import { FileRuntimeEventInbox } from "./runtimeEventInbox.js";
 import { resolveRuntimeHookRunFence } from "./runtimeHookRunFence.js";
 let structuredSequence = 0;
@@ -256,10 +257,26 @@ async function persistAndApply(home, observations, taskId, roleName) {
     const inbox = new FileRuntimeEventInbox(home);
     for (const entry of observations)
         inbox.enqueueObservation(entry);
+    // The immutable inbox is authoritative. During a release/update handover the
+    // old Controller is draining and the replacement is not ready yet; leave the
+    // entries for normal inbox replay instead of turning a healthy Provider Turn
+    // into a transport failure.
+    if (isForeignHandoverLockHeld(home))
+        return;
     for (const entry of observations) {
-        const result = await callController(home, "runtime.observation-apply", entry, {
-            timeoutMs: 10_000
-        });
+        let result;
+        try {
+            result = await callController(home, "runtime.observation-apply", entry, {
+                timeoutMs: 10_000
+            });
+        }
+        catch (error) {
+            // Close the race where the handover begins after the first check but
+            // before this socket call. The durable entry remains pending for replay.
+            if (isForeignHandoverLockHeld(home))
+                return;
+            throw error;
+        }
         // A fast Provider can accept the initial Turn before the scheduler call
         // that launched this Host has returned and committed `run.pushed`. The
         // immutable inbox entry already makes that exact fenced fact durable;

package/dist/core/controllerClient.js

@@ -14,6 +14,15 @@ export class ControllerClientError extends Error {
         this.name = "ControllerClientError";
     }
 }
+/** The Controller may have committed the request before this client lost its acknowledgement. */
+export function controllerCallMayHaveApplied(error) {
+    return error instanceof ControllerClientError
+        && [
+            "CONTROLLER_TIMEOUT",
+            "CONTROLLER_UNAVAILABLE",
+            "INVALID_RESPONSE"
+        ].includes(error.code);
+}
 export async function readControllerDiscovery(home) {
     const discoveryPath = join(home, CONTROLLER_DISCOVERY_PATH);
     try {
@@ -210,6 +219,7 @@ function exchange(socketPath, requestLine, expectedId, timeoutMs) {
         const socket = createConnection(socketPath);
         let buffer = Buffer.alloc(0);
         let settled = false;
+        let deliveryStarted = false;
         const timer = setTimeout(() => {
             fail(new ControllerClientError("CONTROLLER_TIMEOUT", "Controller request timed out."));
         }, timeoutMs);
@@ -229,7 +239,13 @@ function exchange(socketPath, requestLine, expectedId, timeoutMs) {
             socket.destroy();
             reject(error);
         };
-        socket.on("connect", () => socket.write(requestLine));
+        socket.on("connect", () => {
+            // Once write begins, a missing response cannot prove that the Controller
+            // did not commit the request. Callers must use their domain identity to
+            // decide whether an explicit retry is safe.
+            deliveryStarted = true;
+            socket.write(requestLine);
+        });
         socket.on("data", (chunk) => {
             if (settled)
                 return;
@@ -260,7 +276,9 @@ function exchange(socketPath, requestLine, expectedId, timeoutMs) {
                 fail(invalidResponse());
         });
         socket.on("error", () => {
-            fail(new ControllerClientError("CONTROLLER_UNAVAILABLE", "Controller is unavailable."));
+            fail(deliveryStarted
+                ? new ControllerClientError("CONTROLLER_DELIVERY_UNKNOWN", "Controller request delivery is unknown.")
+                : new ControllerClientError("CONTROLLER_UNAVAILABLE", "Controller is unavailable."));
         });
     });
 }

package/dist/core/controllerServer.js

@@ -833,6 +833,7 @@ function safeApplicationErrorCode(code) {
         case "METHOD_NOT_FOUND":
         case "NOT_FOUND":
         case "UNAUTHORIZED":
+        case "CONTROLLER_DRAINING":
             return code;
         default:
             return undefined;

package/dist/executor/agentExecutor.js

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import { hasRecentTurnId, rememberRecentTurnId, validatePendingTurnCompletion, validateRecentTurnIds } from "./turnCompletion.js";
 import { effectiveLaunchSnapshotsCompatible, effectiveLaunchSnapshotsCompatibleForTaskSession, validateEffectiveLaunchSnapshot } from "./effectiveLaunch.js";
-import { rebindProviderRuntimeRun, validateProviderRuntimeBinding } from "../runtime/providerRuntimeIdentity.js";
+import { currentProviderActivation, endProviderActivation, rebindProviderRuntimeRun, validateProviderRuntimeBinding } from "../runtime/providerRuntimeIdentity.js";
 import { builtinDriverIdForAdapter } from "../runtime/builtinAgentDrivers.js";
 export function createRoleSessionSet(owner, activeAgentId, now) {
     const base = {
@@ -120,6 +120,20 @@ export function recordRoleAgentSession(set, input, now) {
     validateRoleSessionSet(updated);
     return updated;
 }
+/**
+ * Atomically archives the quiescent old native Session and binds the Provider
+ * Conversation selected by an already-authorized switch. Authorization is
+ * deliberately owned by the Controller caller, not inferred here.
+ */
+export function replaceTaskRoleAgentSessionForConversationSwitch(set, input, now) {
+    validateRoleSessionSet(set);
+    const existing = set.sessions[input.agentId];
+    if (existing === undefined || existing.nativeSessionId === input.nativeSessionId) {
+        return recordRoleAgentSession(set, input, now);
+    }
+    const terminalized = updateRoleAgentSessionStatus(set, input.agentId, "stopped", now);
+    return recordRoleAgentSession(terminalized, input, now);
+}
 /**
  * Session titles and previews can originate in native Agent output. Keep them
  * single-line and inert before they are persisted or rendered in a terminal.
@@ -179,25 +193,6 @@ export function retireTaskRoleSessionsForWorkspace(set, now) {
         updatedAt: timestamp
     });
 }
-/**
- * Clears the Provider transport identity after its physical runtime is proven
- * stopped, without retiring workspace-bound Session records. Workspace
- * retirement remains a separate, stricter transaction after every supported
- * placeholder has been terminalized.
- */
-export function clearTaskRoleProviderRuntimeForCleanup(set, now) {
-    validateRoleSessionSet(set);
-    if (set.inFlight !== null) {
-        throw new Error("Cannot clear a Task Role Provider runtime with unsettled Run state.");
-    }
-    if (set.providerBinding === null)
-        return set;
-    return validateRoleSessionSet({
-        ...set,
-        providerBinding: null,
-        updatedAt: requireDate(now, "Provider Runtime cleanup timestamp")
-    });
-}
 /**
  * Terminalizes only the aggregate-16 Claude placeholder shape after the
  * caller has fenced the Task store and proved that the exact Role has no live
@@ -307,7 +302,10 @@ export function bindTaskRoleRun(set, fence, preparedAt, mode) {
         throw new Error("Task Role session set already has an in-flight Run.");
     }
     const timestamp = requireDate(preparedAt, "Task Role Run preparedAt");
-    const providerBinding = mode === "resume" && set.providerBinding !== null
+    // A fresh Conversation is a two-phase replacement: keep the old binding as
+    // current evidence until the new Provider session is observed and atomically
+    // superseded. Homes with no prior Conversation still start from null.
+    const providerBinding = set.providerBinding !== null
         ? rebindProviderRuntimeRun(set.providerBinding, normalized.runId)
         : null;
     const updated = {
@@ -372,6 +370,35 @@ export function updateTaskRoleProviderRuntime(set, binding, updatedAt) {
         updatedAt: requireDate(updatedAt, "Provider Runtime Binding timestamp")
     });
 }
+/**
+ * Records an exact local Host exit without forgetting the Provider
+ * Conversation. The ended Activation releases writer authority, while the
+ * current Conversation and any unsettled Turn remain durable recovery fences.
+ */
+export function stopTaskRoleRuntimeAfterPhysicalExit(set, now) {
+    validateRoleSessionSet(set);
+    const active = set.sessions[set.activeAgentId];
+    if (active === undefined)
+        return set;
+    const activation = set.providerBinding === null
+        ? null
+        : currentProviderActivation(set.providerBinding);
+    if (active.status === "stopped") {
+        if (activation !== null) {
+            throw new Error("Stopped Task Role Session cannot retain a live Provider Activation.");
+        }
+        return set;
+    }
+    let updated = updateRoleAgentSessionStatus(set, set.activeAgentId, "stopped", now);
+    if (activation !== null) {
+        updated = updateTaskRoleProviderRuntime(updated, endProviderActivation(updated.providerBinding, activation.activationId, {
+            status: "ended",
+            endedAt: now.toISOString(),
+            reason: "runtime-physical-exit"
+        }), now);
+    }
+    return updated;
+}
 export function markTaskRoleRunPushed(set, fence, pushedAt) {
     validateRoleSessionSet(set);
     assertTaskRoleSessionSet(set);
@@ -515,31 +542,6 @@ export function terminalizeTaskRoleRunSession(set, fence, terminalAt) {
     }
     return updated;
 }
-/**
- * Resets the current native generation after its active Run is terminal.
- * The Controller separately owns verified process cleanup.
- */
-export function resetTaskRoleSession(set, now) {
-    validateRoleSessionSet(set);
-    const timestamp = requireDate(now, "Task Role Session reset timestamp");
-    const current = set.sessions[set.activeAgentId];
-    const sessions = { ...set.sessions };
-    delete sessions[set.activeAgentId];
-    const history = current === undefined
-        ? set.history
-        : [
-            ...(set.history ?? []),
-            { ...current, status: "broken", updatedAt: timestamp }
-        ];
-    return validateRoleSessionSet({
-        ...set,
-        sessions,
-        ...(history === undefined ? {} : { history }),
-        inFlight: null,
-        providerBinding: null,
-        updatedAt: timestamp
-    });
-}
 export function settleTaskRoleCompletion(set, expected, settledAt) {
     validateRoleSessionSet(set);
     assertTaskRoleSessionSet(set);

package/dist/executor/fileRoleLaunchPlanner.js

@@ -12,7 +12,9 @@ import { compileRoleSessionContext, roleSessionKind } from "../context/roleSessi
 import { materializeSessionBootstrap } from "../context/sessionBootstrapManifest.js";
 import { serializeRunBootstrapEnvelope, serializeRunHostRecoveryEnvelope } from "../context/runContextContract.js";
 import { serializeProviderRetryEnvelope } from "../run/providerRetry.js";
+import { serializeWorkflowOutcomeRequestEnvelope } from "../run/runControlRequest.js";
 import { prefixYuiTitleInput } from "../run/runIdentity.js";
+import { agentRunDeliveryReceiptId } from "../run/agentRun.js";
 import { resolveAgentAdapter } from "./agentAdapter.js";
 import { resolveTaskRoleSessionTitle } from "../runtime/sessionTitle.js";
 import { nativeSessionIdForLaunch } from "../runtime/preallocatedNativeSession.js";
@@ -25,7 +27,8 @@ import { parseTaskRuntimeIsolationDescriptor, taskRuntimeIsolationEnvironment }
 import { ResourceRegistrar } from "../resources/resourceRegistrar.js";
 import { builtinAgentDriverRegistry, builtinDriverIdForAdapter } from "../runtime/builtinAgentDrivers.js";
 import { managedRuntimeAdmission } from "../runtime/agentDriver.js";
-import { formatAgentRunReceiptId } from "../task/taskRecordReference.js";
+import { freshConversationLaunchAllowed } from "../runtime/conversationSwitch.js";
+import { currentProviderActivation } from "../runtime/providerRuntimeIdentity.js";
 import { assertCodexLaunchOverridesAvailable, inspectCodexLaunchConfig } from "./codexConfigConflict.js";
 /** Builds managed native Agent launches from the authoritative Task records. */
 export class FileRoleLaunchPlanner {
@@ -224,6 +227,20 @@ export class FileRoleLaunchPlanner {
         if (input.mode === "resume" && !compatibleExisting) {
             throw new Error(`Task Role resume effective snapshot drifted: ${task.id}/${role.name}.`);
         }
+        if (input.mode === "new" && sessionSet !== null
+            && !freshConversationLaunchAllowed({
+                sessions: sessionSet,
+                events: this.store.listEvents(task.id),
+                mailbox: this.store.getWorkMailbox({
+                    kind: "role",
+                    taskId: task.id,
+                    roleName: role.name
+                }),
+                roleName: role.name,
+                ...(input.runId === undefined ? {} : { candidateRunId: input.runId })
+            })) {
+            throw new Error(`Fresh Provider Conversation is not authorized: ${task.id}/${role.name}.`);
+        }
         return this.#compile(role, input, { scope: "task", taskId: task.id }, resolveTaskRoleSessionTitle(input.mode === "resume" ? existing?.title : undefined, task, role.name), input.mode === "resume" && compatibleExisting ? existing.nativeSessionId : undefined, runWorkspace, effective, {
             purpose: activeRun?.purpose ?? "execution"
         });
@@ -464,10 +481,10 @@ export class FileRoleLaunchPlanner {
         if (runtimeDescriptor !== undefined && runtimeDescriptorSource !== undefined) {
             this.#writeExactTaskRuntimeDescriptor(runtimeDescriptor, runtimeDescriptorSource);
         }
-        // rr13/rr26: Generate a per-Session DurableJob caller key for every
-        // task-scope launch, including resume.  Resume/ensure may reuse a live
-        // host, so its candidate hash is committed by TmuxSessionHost only when
-        // hostCreated=true; otherwise the live process keeps its existing key.
+        // Generate a candidate per-Provider-process DurableJob caller key for
+        // every task-scope launch. A reused live Conversation keeps the key that
+        // its process inherited; a new Host or a Conversation replacement commits
+        // the fresh candidate only after Provider dispatch is observed.
         let jobCallerKey;
         if (owner.scope === "task" && (input.mode === "new" || input.mode === "resume")) {
             jobCallerKey = randomBytes(32).toString("hex");
@@ -476,35 +493,62 @@ export class FileRoleLaunchPlanner {
         // write, whether it creates or resumes the native Conversation. Keeping
         // resume on the same launch handshake prevents a durable AgentRun from
         // existing without a corresponding Provider Turn.
-        const carriesInitialTurn = managedControl
-            && managedRun?.pushedAt === undefined;
+        if (managedControl && (managedRun === null || managedRun.status !== "active")) {
+            throw new Error(`Managed Run is no longer active: ${input.runId}.`);
+        }
+        const carriesInitialTurn = managedControl && (managedRun.pushedAt === undefined
+            || managedRun.providerRetry?.state === "dispatching"
+            || managedRun.controlRequest?.state === "dispatching");
         const providerAuthority = managedControl
-            ? this.#providerAuthorityForLaunch(owner.taskId, role.name, input.launchId)
+            ? this.#providerAuthorityForLaunch(owner.taskId, role.name, input.launchId, input.mode)
             : undefined;
         const providerNativeSessionId = binding.adapterId === "claude"
             ? preallocatedNativeSessionId
             : resumeNativeSessionId;
-        const providerControl = managedControl
+        const initialTurn = carriesInitialTurn
             ? {
-                schemaVersion: 1,
-                adapterId: binding.adapterId,
-                transport: managedCompiled.transport,
-                mode: resumeNativeSessionId === undefined ? "new" : "resume",
-                ...(providerNativeSessionId === undefined
-                    ? {}
-                    : { nativeSessionId: providerNativeSessionId }),
-                ...(sessionTitle === undefined ? {} : { sessionTitle }),
-                authority: providerAuthority,
-                ...(carriesInitialTurn
-                    ? {
-                        initialTurn: {
-                            attemptId: formatAgentRunReceiptId(owner.taskId, input.runId),
-                            boundedText: managedRunLaunchEnvelope(managedRun, input.mode, sessionTitle)
-                        }
-                    }
-                    : {})
+                attemptId: agentRunDeliveryReceiptId(managedRun),
+                boundedText: managedRunLaunchEnvelope(managedRun, input.mode, sessionTitle)
             }
             : undefined;
+        const providerControl = !managedControl
+            ? undefined
+            : initialTurn === undefined
+                ? {
+                    schemaVersion: 1,
+                    adapterId: binding.adapterId,
+                    transport: managedCompiled.transport,
+                    kind: "ensure",
+                    mode: "resume",
+                    nativeSessionId: requireText(providerNativeSessionId, "Managed Provider ensure native session id"),
+                    ...(sessionTitle === undefined ? {} : { sessionTitle }),
+                    authority: providerAuthority
+                }
+                : resumeNativeSessionId === undefined
+                    ? {
+                        schemaVersion: 1,
+                        adapterId: binding.adapterId,
+                        transport: managedCompiled.transport,
+                        kind: "new",
+                        mode: "new",
+                        ...(providerNativeSessionId === undefined
+                            ? {}
+                            : { nativeSessionId: providerNativeSessionId }),
+                        ...(sessionTitle === undefined ? {} : { sessionTitle }),
+                        authority: providerAuthority,
+                        initialTurn
+                    }
+                    : {
+                        schemaVersion: 1,
+                        adapterId: binding.adapterId,
+                        transport: managedCompiled.transport,
+                        kind: "resume",
+                        mode: "resume",
+                        nativeSessionId: requireText(providerNativeSessionId, "Managed Provider resume native session id"),
+                        ...(sessionTitle === undefined ? {} : { sessionTitle }),
+                        authority: providerAuthority,
+                        initialTurn
+                    };
         const launch = {
             command,
             args,
@@ -572,13 +616,26 @@ export class FileRoleLaunchPlanner {
                 : {})
         };
     }
-    #providerAuthorityForLaunch(taskId, roleName, launchId) {
+    #providerAuthorityForLaunch(taskId, roleName, launchId, mode) {
         const activationId = requireText(launchId, "Managed Provider Activation id");
         const binding = this.store.getTaskRoleSessionSet(taskId, roleName)?.providerBinding;
         if (binding === null || binding === undefined) {
             return { epoch: 1, owner: "controller", holderId: activationId };
         }
         if (binding.authority.owner === "controller") {
+            if (mode === "new") {
+                const activation = currentProviderActivation(binding);
+                if (activation === null || binding.authority.holderId !== activation.activationId) {
+                    throw new Error(`Provider Activation is not exact: ${taskId}/${roleName}.`);
+                }
+                // An actor-requested switch first ends the idle old Activation (+1)
+                // and then binds the replacement Activation (+1).
+                return {
+                    epoch: binding.authority.epoch + 2,
+                    owner: "controller",
+                    holderId: activationId
+                };
+            }
             return {
                 epoch: binding.authority.epoch,
                 owner: "controller",
@@ -642,9 +699,16 @@ function managedRunLaunchEnvelope(run, mode, title) {
             roleName: run.roleName,
             retry: run.providerRetry
         })
-        : mode === "resume" && run.pushedAt !== undefined
-            ? serializeRunHostRecoveryEnvelope(run.bootstrapEnvelope)
-            : serializeRunBootstrapEnvelope(run.bootstrapEnvelope);
+        : run.controlRequest?.state === "dispatching"
+            ? serializeWorkflowOutcomeRequestEnvelope({
+                taskId: run.taskId,
+                runId: run.id,
+                roleName: run.roleName,
+                request: run.controlRequest
+            })
+            : mode === "resume" && run.pushedAt !== undefined
+                ? serializeRunHostRecoveryEnvelope(run.bootstrapEnvelope)
+                : serializeRunBootstrapEnvelope(run.bootstrapEnvelope);
     return title === undefined
         ? body
         : prefixYuiTitleInput(body, title);