@zq-silk/yui 0.12.0 → 0.12.1

package/dist/lifecycle/exactRunTerminalization.js

@@ -12,6 +12,7 @@ import { createYieldReceipt } from "../run/yieldReceipt.js";
 import { recordExecutionLaneResult } from "../execution/executionGroup.js";
 import { isRuntimeLaunchReservation, runtimeLifecycleTarget } from "../runtime/lifecycleReservation.js";
 import { runOwnsBlockingProviderContinuation } from "../runtime/runtimeContinuationProjection.js";
+import { runHasActiveRuntimeOperations } from "../runtime/runtimeObservation.js";
 import { latestRunDurableProgressAt, RUN_RECOVERY_APPLIED_EVENT, RUN_RECOVERY_REQUESTED_EVENT } from "../scheduler/roleRunStall.js";
 import { markTaskWakeConsumed } from "../scheduler/taskWake.js";
 import { workItemExecutionGroupById, workItemOwnsUnresolvedExecutionLane, updateWorkItemExecutionGroup, updateWorkItemStatus } from "../workItem/workItem.js";
@@ -352,7 +353,7 @@ export function terminalizeExactTaskRun(store, input, now) {
 /**
  * Leader-controlled recovery boundary for one active AgentRun. This primitive
  * validates every durable fence in one transaction and records only a
- * structured request for retry/session replacement. It never writes terminal
+ * structured request for same-Run diagnosis/retry. It never writes terminal
  * bytes, retries a provider input, kills a host, or silently rebinds a native
  * generation. Explicit termination is the sole action that changes Run state.
  */
@@ -420,6 +421,35 @@ function recoverExactAgentRunInTransaction(store, input) {
     if (!matchesRecoverySessionFence(store, input)) {
         return stateChanged("session-or-launch-fence-mismatch");
     }
+    const recoveryBlocker = exactRecoveryExecutionBlocker(store, current);
+    if (recoveryBlocker !== null) {
+        return {
+            disposition: "blocked",
+            action: input.action,
+            run: current,
+            progressAt: progress.progressAt,
+            reason: recoveryBlocker
+        };
+    }
+    if (input.action === "terminate") {
+        const sessions = store.getTaskRoleSessionSet(input.taskId, input.roleName);
+        const session = sessions?.sessions[input.agentId];
+        const providerTurn = sessions?.providerBinding?.turn;
+        const exactTerminalEvidence = session?.status === "stopped"
+            || session?.status === "broken"
+            || providerTurn?.status === "failed"
+            || providerTurn?.status === "cancelled"
+            || providerTurn?.status === "rejected";
+        if (!exactTerminalEvidence) {
+            return {
+                disposition: "blocked",
+                action: input.action,
+                run: current,
+                progressAt: progress.progressAt,
+                reason: "runtime-not-terminal"
+            };
+        }
+    }
     if (input.providerAcceptance === "ambiguous"
         && input.action !== "diagnose") {
         return {
@@ -506,6 +536,42 @@ function recoverExactAgentRunInTransaction(store, input) {
         progressAt: progress.progressAt
     };
 }
+function exactRecoveryExecutionBlocker(store, run) {
+    const sessions = store.getTaskRoleSessionSet(run.taskId, run.roleName);
+    const binding = sessions?.providerBinding;
+    const mailbox = store.getWorkMailbox({
+        kind: "role",
+        taskId: run.taskId,
+        roleName: run.roleName
+    });
+    if (mailbox?.inputDelivery != null)
+        return "provider-input-delivery-unsettled";
+    if (runOwnsBlockingProviderContinuation(store.listEvents(run.taskId), {
+        taskId: run.taskId,
+        roleName: run.roleName,
+        runId: run.id,
+        agentId: run.effective.agentId
+    }))
+        return "provider-continuation-writer-owned";
+    if (runHasActiveRuntimeOperations(store.listEvents(run.taskId), {
+        taskId: run.taskId,
+        roleName: run.roleName,
+        runId: run.id,
+        agentId: run.effective.agentId
+    }))
+        return "provider-operation-active";
+    if (run.deliveredAt !== undefined
+        && (binding === null || binding?.turn === null))
+        return "provider-turn-state-missing";
+    if (binding === null || binding === undefined)
+        return null;
+    if (["submitting", "accepted", "running", "delivery-unknown"].includes(binding.turn?.status ?? ""))
+        return "provider-turn-unsettled";
+    if (binding.authority.owner === "human" || binding.authority.owner === "unknown") {
+        return "provider-writer-authority-unavailable";
+    }
+    return null;
+}
 function matchesRecoverySessionFence(store, input) {
     const sessions = store.getTaskRoleSessionSet(input.taskId, input.roleName);
     // Recovery must never proceed without a durable Session fence.  A missing
@@ -520,8 +586,7 @@ function matchesRecoverySessionFence(store, input) {
         return false;
     if (session.agentId !== input.agentId || session.adapterId !== input.adapterId)
         return false;
-    // A dead Session is precisely when replace-session/terminate recovery is
-    // needed. Preserve its exact identity as the CAS fence; only same-Session
+    // Preserve a dead Session's exact identity as the CAS fence; only same-Session
     // retry is invalid once the native process is stopped or broken.
     if ((session.status === "stopped" || session.status === "broken")
         && input.action === "retry")

package/dist/observability/executionAudit.js

@@ -363,6 +363,7 @@ export function runExecutionAudit(home, options = {}, ports = createProductionEx
             let stopped = 0;
             let other = 0;
             let resets = 0;
+            let conversationSwitches = 0;
             let lifecycleEvents = 0;
             let stopFailures = 0;
             const terminalByRunRelation = {
@@ -393,6 +394,9 @@ export function runExecutionAudit(home, options = {}, ports = createProductionEx
                         continue;
                     if (event.type === "runtime.role-session-reset")
                         resets += 1;
+                    else if (event.type === "runtime.conversation-switch-resolved"
+                        && event.payload.status === "applied")
+                        conversationSwitches += 1;
                     else if (runtimeObservationFromTaskEvent(event)?.kind.startsWith("session.")) {
                         lifecycleEvents += 1;
                     }
@@ -406,6 +410,7 @@ export function runExecutionAudit(home, options = {}, ports = createProductionEx
                 stopped,
                 other,
                 resets,
+                conversationSwitches,
                 lifecycleEvents,
                 stopFailures,
                 terminalByRunRelation

package/dist/release/runtimeRelease.js

@@ -267,6 +267,26 @@ export function isHandoverLockHeld(home) {
         return !isEnoent(error);
     }
 }
+/**
+ * True when a live handover is owned by a process other than `allowedOwnerPid`.
+ *
+ * Foreground maintenance commands acquire the lock and still need to call the
+ * Controller they are draining, while every unrelated CLI/managed Session must
+ * wait rather than starting a second Controller during the replacement window.
+ * An unreadable lock remains a foreign live lock so callers fail closed.
+ */
+export function isForeignHandoverLockHeld(home, allowedOwnerPid = process.pid) {
+    const lockPath = join(resolve(home), "runtime", "handover.lock");
+    try {
+        const owner = JSON.parse(readFileSync(lockPath, "utf8"));
+        if (!isHandoverLockLive(owner))
+            return false;
+        return owner.pid !== allowedOwnerPid;
+    }
+    catch (error) {
+        return !isEnoent(error);
+    }
+}
 export function acquireHandoverLock(home) {
     const lockPath = join(resolve(home), "runtime", "handover.lock");
     mkdirSync(dirname(lockPath), { recursive: true, mode: 0o700 });

package/dist/run/recoveryProjection.js

@@ -1,10 +1,11 @@
 import { createHash } from "node:crypto";
 import { latestRunDurableProgressAt } from "../scheduler/roleRunStall.js";
 import { actionableExecutionLaneRecoveries } from "../execution/executionHealth.js";
+import { runOwnsBlockingProviderContinuation } from "../runtime/runtimeContinuationProjection.js";
+import { runHasActiveRuntimeOperations } from "../runtime/runtimeObservation.js";
 export const RUN_RECOVERY_ACTIONS = [
     "diagnose",
     "retry",
-    "replace-session",
     "terminate"
 ];
 /**
@@ -17,13 +18,32 @@ export function readRunRecoveryFacts(store, taskId, runId) {
         return null;
     const task = store.getTask(taskId);
     const sessionSet = store.getTaskRoleSessionSet(taskId, run.roleName);
+    const events = store.listEvents(taskId);
+    const roleMailbox = store.getWorkMailbox?.({
+        kind: "role",
+        taskId,
+        roleName: run.roleName
+    }) ?? null;
     const progress = latestRunDurableProgressAt(store, taskId, run.roleName, runId);
     return {
         run,
         task: task === null ? null : { id: task.id, status: task.status },
         sessionSet,
+        inputDeliveryUnsettled: roleMailbox?.inputDelivery != null,
+        blockingProviderContinuation: runOwnsBlockingProviderContinuation(events, {
+            taskId,
+            roleName: run.roleName,
+            runId: run.id,
+            agentId: run.effective.agentId
+        }),
+        activeRuntimeOperation: runHasActiveRuntimeOperations(events, {
+            taskId,
+            roleName: run.roleName,
+            runId: run.id,
+            agentId: run.effective.agentId
+        }),
         progress,
-        latestProviderObservation: latestRunProviderObservation(store.listEvents(taskId), runId)
+        latestProviderObservation: latestRunProviderObservation(events, runId)
     };
 }
 /**
@@ -72,9 +92,12 @@ export function projectRunRecovery(facts) {
         ? ["accepted", "ambiguous"]
         : ["rejected", "ambiguous"];
     const blocked = recoveryBlocker(facts, session, canonicalProgressAt);
-    const supportedActions = session?.status === "stopped" || session?.status === "broken"
-        ? RUN_RECOVERY_ACTIONS.filter((action) => action !== "retry")
-        : RUN_RECOVERY_ACTIONS;
+    const sessionTerminal = session?.status === "stopped" || session?.status === "broken";
+    const providerTerminal = sessionSet?.providerBinding?.turn?.status === "failed"
+        || sessionSet?.providerBinding?.turn?.status === "cancelled"
+        || sessionSet?.providerBinding?.turn?.status === "rejected";
+    const supportedActions = RUN_RECOVERY_ACTIONS.filter((action) => ((action !== "retry" || !sessionTerminal)
+        && (action !== "terminate" || sessionTerminal || providerTerminal)));
     const actions = blocked === null
         ? supportedActions.map((action) => buildActionPlan(facts, action, session, canonicalProgressAt))
         : [];
@@ -139,6 +162,23 @@ function recoveryBlocker(facts, session, canonicalProgressAt) {
         return "progress-unavailable";
     if (session === null)
         return "session-missing";
+    if (facts.inputDeliveryUnsettled)
+        return "provider-input-delivery-unsettled";
+    if (facts.blockingProviderContinuation)
+        return "provider-continuation-writer-owned";
+    if (facts.activeRuntimeOperation)
+        return "provider-operation-active";
+    const binding = facts.sessionSet?.providerBinding;
+    if (run.deliveredAt !== undefined
+        && (binding === null || binding?.turn === null))
+        return "provider-turn-state-missing";
+    if (binding !== null && binding !== undefined) {
+        if (["submitting", "accepted", "running", "delivery-unknown"].includes(binding.turn?.status ?? ""))
+            return "provider-turn-unsettled";
+        if (binding.authority.owner === "human" || binding.authority.owner === "unknown") {
+            return "provider-writer-authority-unavailable";
+        }
+    }
     return null;
 }
 function buildActionPlan(facts, action, session, canonicalProgressAt) {
@@ -208,6 +248,5 @@ function actionAcceptance(facts, action) {
 const ACTION_REASONS = {
     diagnose: "Collect bounded diagnostics before any state-changing recovery.",
     retry: "Request another provider turn on the same native Session when the failure is transient.",
-    "replace-session": "Request a fresh native Session when the current one is unusable.",
     terminate: "Fail the Run explicitly when recovery is not viable."
 };

package/dist/runtime/agentHost.js

@@ -1,18 +1,20 @@
 import { createHash, randomUUID } from "node:crypto";
-import { appendFileSync, chmodSync, closeSync, fsyncSync, mkdirSync, openSync, rmSync } from "node:fs";
-import { readdir, readFile, rename, unlink } from "node:fs/promises";
+import { chmodSync, mkdirSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { createConnection, createServer } from "node:net";
 import { createInterface } from "node:readline";
-import { callController, ControllerClientError } from "../core/controllerClient.js";
+import { callController, controllerCallMayHaveApplied, ControllerClientError } from "../core/controllerClient.js";
 import { readHomeFilesystemId } from "../core/homeFilesystemIdentity.js";
+import { callFileTaskController } from "../controller/clientRuntime.js";
+import { isForeignHandoverLockHeld } from "../release/runtimeRelease.js";
 import { publishStructuredProviderAccepted, publishStructuredProviderActivationTerminal, publishStructuredConversationRecoverability, publishStructuredProviderOpened, publishStructuredProviderTerminal } from "../controller/structuredProviderObservation.js";
 import { validateAgentHostLaunchPayload } from "./launchBroker.js";
 import { ProviderDeliveryUnknownError, ProviderConversationMissingError, ProviderTurnRejectedError, startStructuredProviderSession } from "./structuredProviderHost.js";
 import { sameProviderAuthorityFence, validateProviderAuthorityFence } from "./providerAuthorityFence.js";
 import { validateRuntimeProcessExitObservation } from "./processExitObservation.js";
-import { readRuntimeStopReceipt, removeRuntimeStopReceipt } from "./runtimeStopReceipt.js";
+import { persistRuntimeProcessExitObservation, replayRuntimeProcessExitOutbox } from "./processExitOutbox.js";
+import { readRuntimeStopReceipt, removeRuntimeStopReceipt, writeRuntimeStopReceipt } from "./runtimeStopReceipt.js";
 import { AGENT_HOST_CONTROL_TIMEOUT_MS, AGENT_HOST_READY_TIMEOUT_MS } from "./runtimeDeadlines.js";
 export const AGENT_HOST_CONTROL_PROTOCOL = "yui-agent-host/v2";
 const HOST_CONTROL_MAX_BYTES = 32 * 1024;
@@ -26,6 +28,7 @@ export async function runAgentHost(input) {
     let session;
     let sessionPayload;
     let activeTurnPayload;
+    const switchDetachedSessions = new WeakSet();
     let activationId;
     let conversationRecoverability = "unknown";
     let authority;
@@ -116,19 +119,21 @@ export async function runAgentHost(input) {
             const stopReceipt = readRuntimeStopReceipt(input.home, currentPayload.launchId);
             const observedAt = new Date().toISOString();
             const failures = [];
-            try {
-                await publishStructuredProviderActivationTerminal({
-                    home: input.home,
-                    environment: currentPayload.environment,
-                    conversationId: providerSession.conversationId,
-                    nativeSessionId: providerSession.nativeSessionId,
-                    activationId: currentActivationId,
-                    status: stopReceipt !== null || hostStopRequested ? "ended" : "failed",
-                    observedAt
-                });
-            }
-            catch (error) {
-                failures.push(`activation terminal: ${errorText(error)}`);
+            if (!switchDetachedSessions.has(providerSession)) {
+                try {
+                    await publishStructuredProviderActivationTerminal({
+                        home: input.home,
+                        environment: currentPayload.environment,
+                        conversationId: providerSession.conversationId,
+                        nativeSessionId: providerSession.nativeSessionId,
+                        activationId: currentActivationId,
+                        status: stopReceipt !== null || hostStopRequested ? "ended" : "failed",
+                        observedAt
+                    });
+                }
+                catch (error) {
+                    failures.push(`activation terminal: ${errorText(error)}`);
+                }
             }
             let exitPersisted = false;
             try {
@@ -163,7 +168,7 @@ export async function runAgentHost(input) {
             if (stopReceipt !== null && exitPersisted) {
                 removeRuntimeStopReceipt(input.home, currentPayload.launchId);
             }
-            if (hostStopRequested)
+            if (hostStopRequested || !ownsCurrentSession)
                 return;
             updateSnapshot(hostSnapshot(failures.length === 0 ? "exited" : "failed", {
                 launchId: currentPayload.launchId,
@@ -196,9 +201,12 @@ export async function runAgentHost(input) {
             throw new Error("Agent Host still owns an unsettled Provider Turn.");
         }
         const requestedAuthority = validateProviderAuthorityFence(providerControl.authority);
-        if (authority === undefined)
+        const replacesCurrentConversation = session !== undefined && providerControl.kind === "new";
+        if (!replacesCurrentConversation && authority === undefined)
             authority = requestedAuthority;
-        else if (!sameProviderAuthorityFence(authority, requestedAuthority)) {
+        else if (!replacesCurrentConversation
+            && authority !== undefined
+            && !sameProviderAuthorityFence(authority, requestedAuthority)) {
             throw new Error("Agent Host launch carries a stale Provider authority fence.");
         }
         updateSnapshot(hostSnapshot("starting", {
@@ -217,6 +225,43 @@ export async function runAgentHost(input) {
         let providerAcceptedAttemptId;
         let durableInitialTurn;
         try {
+            if (replacesCurrentConversation) {
+                const previousSession = session;
+                const previousPayload = sessionPayload;
+                const previousActivationId = activationId ?? previousPayload?.launchId;
+                if (previousPayload === undefined || previousActivationId === undefined
+                    || authority?.owner !== "controller") {
+                    throw new Error("Agent Host cannot detach an inexact Provider Activation.");
+                }
+                await detachDurableProviderForConversationSwitch(input.home, {
+                    taskId: requiredEnvironment(next.environment.YUI_TASK_ID, "Task id"),
+                    roleName: requiredEnvironment(next.environment.YUI_ROLE, "Role name"),
+                    runId: requiredEnvironment(next.environment.YUI_RUN_ID, "Run id"),
+                    agentId: requiredEnvironment(next.environment.YUI_AGENT_ID, "Agent id"),
+                    launchId: next.launchId,
+                    previousConversationId: previousSession.conversationId,
+                    previousNativeSessionId: previousSession.nativeSessionId,
+                    previousActivationId,
+                    nextAuthorityEpoch: requestedAuthority.epoch,
+                    nextAuthorityHolderId: requestedAuthority.holderId,
+                    observedAt: new Date().toISOString()
+                });
+                switchDetachedSessions.add(previousSession);
+                // The persistent Provider child belongs to the Activation that first
+                // created it, not to the most recent resume Run payload. The exit
+                // observer carries that Activation launch id, so the stop receipt must
+                // use the same identity or the expected switch detach is misclassified
+                // as an abnormal child exit and generic cleanup can kill the Host.
+                writeRuntimeStopReceipt(input.home, previousActivationId, new Date());
+                authority = undefined;
+                await terminateProviderSessionForConversationSwitch(previousSession);
+                if (session === previousSession)
+                    session = undefined;
+                sessionPayload = undefined;
+                activationId = undefined;
+                conversationRecoverability = "unknown";
+                authority = requestedAuthority;
+            }
             if (session !== undefined) {
                 if (session.adapterId !== providerControl.adapterId
                     || providerControl.mode !== "resume"
@@ -493,30 +538,12 @@ export async function runAgentHost(input) {
                 }
             };
             const durableTurn = hostTurnControlParams(currentPayload, currentSession.nativeSessionId, currentAuthority, attemptId);
-            try {
-                await beginDurableProviderTurn(input.home, durableTurn);
-            }
-            catch (error) {
-                await callController(input.home, "runtime.provider-turn-submission-resolve", {
-                    ...durableTurn,
-                    status: "rejected",
-                    reason: `Human Turn intent acknowledgement failed before Provider write: ${errorText(error)}`,
-                    observedAt: new Date().toISOString()
-                }).catch(() => { });
-                throw error;
-            }
+            await beginDurableProviderTurn(input.home, durableTurn);
             try {
                 await submitTurn(turnControl);
             }
             catch (error) {
-                await callController(input.home, "runtime.provider-turn-submission-resolve", {
-                    ...durableTurn,
-                    status: error instanceof ProviderDeliveryUnknownError
-                        ? "delivery-unknown"
-                        : "rejected",
-                    reason: errorText(error),
-                    observedAt: new Date().toISOString()
-                }).catch(() => { });
+                await resolveProviderTurnSubmission(input.home, durableTurn, error);
                 throw error;
             }
             process.stdout.write("Provider accepted the human Turn; waiting for its terminal boundary.\n");
@@ -670,50 +697,19 @@ async function redeem(home, launchId, ticket) {
     return validateAgentHostLaunchPayload(result);
 }
 async function persistAndSubmitExit(home, observation) {
-    const directory = resolve(join(home, "runtime", "agent-host-outbox"));
-    mkdirSync(directory, { recursive: true, mode: 0o700 });
-    const path = join(directory, `${observation.hostInstanceId}.jsonl`);
-    const descriptor = openSync(path, "a", 0o600);
     try {
-        appendFileSync(descriptor, `${JSON.stringify(observation)}\n`, "utf8");
-        fsyncSync(descriptor);
-    }
-    finally {
-        closeSync(descriptor);
-    }
-    chmodSync(path, 0o600);
-    await callController(home, "runtime.process-exit-observe", observation);
-    rmSync(path, { force: true });
-}
-async function replayExitOutbox(home) {
-    const directory = resolve(join(home, "runtime", "agent-host-outbox"));
-    let entries;
-    try {
-        entries = await readdir(directory);
+        await persistRuntimeProcessExitObservation(home, observation, (value) => callController(home, "runtime.process-exit-observe", value).then(() => undefined));
     }
     catch (error) {
-        if (error.code === "ENOENT")
+        // The durable outbox is the acknowledgement during a planned Controller
+        // gap. The replacement Controller drains it before accepting new work.
+        if (isForeignHandoverLockHeld(home))
             return;
         throw error;
     }
-    for (const name of entries.filter((value) => value.includes(".jsonl")).sort()) {
-        const path = join(directory, name);
-        const claimed = `${path}.claim-${process.pid}-${randomUUID()}`;
-        try {
-            await rename(path, claimed);
-        }
-        catch (error) {
-            if (error.code === "ENOENT")
-                continue;
-            throw error;
-        }
-        const lines = (await readFile(claimed, "utf8")).split("\n").filter(Boolean);
-        for (const line of lines) {
-            const observation = validateRuntimeProcessExitObservation(JSON.parse(line));
-            await callController(home, "runtime.process-exit-observe", observation);
-        }
-        await unlink(claimed);
-    }
+}
+async function replayExitOutbox(home) {
+    await replayRuntimeProcessExitOutbox(home, (observation) => callController(home, "runtime.process-exit-observe", observation).then(() => undefined));
 }
 /** Internal socket boundary exported for transport-level verification. */
 export async function openAgentHostControl(home, payload, snapshot, dispatch) {
@@ -906,26 +902,104 @@ function hostTurnControlParams(payload, nativeSessionId, authority, attemptId) {
 }
 async function beginDurableProviderTurn(home, durableTurn) {
     try {
-        await callController(home, "runtime.provider-turn-begin", durableTurn);
+        await callControllerIdempotently(home, "runtime.provider-turn-begin", durableTurn);
+    }
+    catch (error) {
+        if (!(error instanceof ControllerAcknowledgementUnknownError))
+            throw error;
+        await resolveProviderTurnSubmission(home, durableTurn, new Error(`Provider Turn intent acknowledgement failed before Provider write: ${errorText(error)}`));
+        throw error;
+    }
+}
+async function detachDurableProviderForConversationSwitch(home, request) {
+    await callControllerIdempotently(home, "runtime.conversation-switch-detach", request);
+}
+async function callControllerIdempotently(home, method, request) {
+    try {
+        await callAgentController(home, method, request);
     }
     catch (error) {
-        if (!(error instanceof ControllerClientError) || error.code !== "INTERNAL_ERROR") {
+        if (!(error instanceof ControllerClientError)
+            || (error.code !== "INTERNAL_ERROR" && !controllerCallMayHaveApplied(error))) {
             throw error;
         }
-        // The exact attempt is idempotent, so one lost acknowledgement can be
-        // retried without creating a second Provider write.
-        await callController(home, "runtime.provider-turn-begin", durableTurn);
+        const firstCallMayHaveApplied = controllerCallMayHaveApplied(error);
+        // These methods carry exact attempt, launch, and authority fences. A
+        // bounded replay confirms a commit whose acknowledgement may have been lost.
+        try {
+            await callAgentController(home, method, request);
+        }
+        catch (replayError) {
+            if (firstCallMayHaveApplied || controllerCallMayHaveApplied(replayError)) {
+                throw new ControllerAcknowledgementUnknownError(`${method} may have been committed, but its acknowledgement could not be confirmed: ${errorText(replayError)}`);
+            }
+            throw replayError;
+        }
+    }
+}
+class ControllerAcknowledgementUnknownError extends Error {
+    name = "ControllerAcknowledgementUnknownError";
+}
+async function terminateProviderSessionForConversationSwitch(providerSession) {
+    providerSession.terminate("SIGTERM");
+    const forceKill = setTimeout(() => providerSession.terminate("SIGKILL"), 3_000);
+    forceKill.unref();
+    let hardTimeout;
+    const timeout = new Promise((_resolve, reject) => {
+        hardTimeout = setTimeout(() => reject(new Error("Old Provider Activation did not exit after its switch authority was revoked.")), 8_000);
+        hardTimeout.unref();
+    });
+    try {
+        await Promise.race([providerSession.waitForExit(), timeout]);
+    }
+    finally {
+        clearTimeout(forceKill);
+        if (hardTimeout !== undefined)
+            clearTimeout(hardTimeout);
     }
 }
 async function resolveProviderTurnSubmission(home, durableTurn, error) {
-    await callController(home, "runtime.provider-turn-submission-resolve", {
+    const attemptId = durableTurn.attemptId;
+    if (typeof attemptId !== "string") {
+        throw new Error("Provider Turn resolution has no attempt id.");
+    }
+    const request = {
         ...durableTurn,
         status: error instanceof ProviderDeliveryUnknownError
             ? "delivery-unknown"
             : "rejected",
         reason: errorText(error),
         observedAt: new Date().toISOString()
-    }).catch(() => { });
+    };
+    try {
+        await callControllerIdempotently(home, "runtime.provider-turn-submission-resolve", request);
+    }
+    catch (resolutionError) {
+        throw new ProviderDeliveryUnknownError(`Provider submission outcome could not be durably resolved: ${errorText(resolutionError)}. Original outcome: ${errorText(error)}`, attemptId);
+    }
+}
+/**
+ * Existing in-flight launches keep using the old Controller while it drains.
+ * If the socket is already gone under an explicit handover fence, wait for
+ * the replacement and retry the domain-idempotent Agent Host operation.
+ */
+async function callAgentController(home, method, params) {
+    try {
+        await callController(home, method, params);
+        return;
+    }
+    catch (error) {
+        if (!isControllerUnavailable(error) || !isForeignHandoverLockHeld(home)) {
+            throw error;
+        }
+    }
+    await callFileTaskController(home, method, params);
+}
+function isControllerUnavailable(error) {
+    return error instanceof ControllerClientError
+        && (error.code === "CONTROLLER_NOT_RUNNING"
+            || error.code === "CONTROLLER_UNAVAILABLE"
+            || error.code === "CONTROLLER_DRAINING");
 }
 function requiredEnvironment(value, label) {
     if (typeof value !== "string" || value.trim().length === 0 || value.includes("\0")) {