@zq-silk/yui 0.12.0 → 0.12.1

package/dist/controller/fileSchedulerStoreAdapter.js

@@ -1,7 +1,8 @@
 import { createHash } from "node:crypto";
 import { isDeepStrictEqual } from "node:util";
-import { activeLiveRoleAgentSession, bindTaskRoleProviderRuntime, bindTaskRoleRun, clearTaskRoleProviderRuntimeForCleanup, clearTaskRoleRun, createRoleSessionSet, markTaskRoleRunDelivered, markTaskRoleRunPushed, prepareTaskRoleRunRedispatch, recordRoleAgentSession, recordTaskRoleTurnBoundary, rememberRoleAgentCompletedTurn, updateRoleAgentSessionStatus, updateTaskRoleProviderRuntime } from "../executor/agentExecutor.js";
-import { acceptProviderTurn, beginProviderTurn, createProviderRuntimeBinding, endProviderActivation, currentProviderActivation, currentProviderConversation, markProviderTurnDeliveryUnknown, rejectProviderTurn, settleProviderTurn, startProviderActivation, supersedeProviderConversation, updateProviderConversationRecoverability } from "../runtime/providerRuntimeIdentity.js";
+import { activeLiveRoleAgentSession, bindTaskRoleProviderRuntime, bindTaskRoleRun, clearTaskRoleRun, createRoleSessionSet, markTaskRoleRunDelivered, markTaskRoleRunPushed, prepareTaskRoleRunRedispatch, recordRoleAgentSession, replaceTaskRoleAgentSessionForConversationSwitch, recordTaskRoleTurnBoundary, rememberRoleAgentCompletedTurn, stopTaskRoleRuntimeAfterPhysicalExit, updateRoleAgentSessionStatus, updateTaskRoleProviderRuntime } from "../executor/agentExecutor.js";
+import { acceptProviderTurn, beginProviderTurn, createProviderRuntimeBinding, endProviderActivation, currentProviderActivation, currentProviderConversation, markProviderTurnDeliveryUnknown, rejectProviderTurn, settleProviderTurnSubmission, settleProviderTurn, startProviderActivation, supersedeProviderConversation, updateProviderConversationRecoverability } from "../runtime/providerRuntimeIdentity.js";
+import { CONVERSATION_SWITCH_DETACHED_EVENT, CONVERSATION_SWITCH_RESOLVED_EVENT, conversationDetachmentBasis, conversationReplacementBasis, pendingConversationSwitch, roleSessionDispatchModeWithConversationSwitch } from "../runtime/conversationSwitch.js";
 import { decideProviderRecovery } from "../runtime/providerRecoveryDecision.js";
 import { hasRecentTurnId } from "../executor/turnCompletion.js";
 import { createTaskEvent } from "../event/taskEvent.js";
@@ -21,11 +22,11 @@ import { classifyRuntimeProcessExit, validateRuntimeProcessExitObservation } fro
 import { terminalizeExactTaskRun } from "../lifecycle/exactRunTerminalization.js";
 import { createCanonicalLifecycleEvent, foldCanonicalLifecycleEvent } from "../lifecycle/canonicalLifecycleEvent.js";
 import { recordLeaderFailure } from "../scheduler/leaderFailure.js";
-import { enqueueOperatorEvent, recordLeaderAttentionRequired, routeRoleEvent } from "../scheduler/operatorEvent.js";
+import { recordLeaderAttentionRequired, routeRoleEvent } from "../scheduler/operatorEvent.js";
 import { pendingWakeupsMatch } from "../scheduler/pendingWakeup.js";
 import { queueLeaderWakeup } from "../scheduler/wakeupQueue.js";
 import { wakeReason } from "../scheduler/wakeReason.js";
-import { foldRunProgressFacts, latestRunDurableProgressAt, latestRunEventTime, latestStallEvidenceKey, RUN_PROGRESS_EVENT, RUN_RECOVERED_EVENT, RUN_STALLED_EVENT } from "../scheduler/roleRunStall.js";
+import { foldRunProgressFacts, latestRunDurableProgressAt, latestRunEventTime, latestStallEvidenceKey, isRoleRunStalled, RUN_PROGRESS_EVENT, RUN_DIAGNOSTIC_FINISHED_EVENT, RUN_RECOVERED_EVENT, RUN_STALLED_EVENT } from "../scheduler/roleRunStall.js";
 import { projectProviderContinuations } from "../runtime/runtimeContinuationProjection.js";
 import { providerContinuationKey } from "../runtime/providerContinuation.js";
 import { currentWorkItemExecutionGroup, updateWorkItemExecutionGroup, updateWorkItemStatus, workItemOwnsUnresolvedExecutionLane } from "../workItem/workItem.js";
@@ -36,7 +37,7 @@ import { enqueueWork } from "../coordination/workMailboxQueue.js";
 import { RUNTIME_CLEANUP_REQUIRED_REASON, RUNTIME_LAUNCH_RESERVED_REASON, RUNTIME_LIFECYCLE_OWNER, RuntimeLifecycleBusyError, hasRuntimeCleanupObligation, hasRuntimeLifecycleWork, isRuntimeLaunchReservation, runtimeLifecycleTarget } from "../runtime/lifecycleReservation.js";
 import { nativeSessionIdForLaunch } from "../runtime/preallocatedNativeSession.js";
 import { builtinAgentDriverRegistry } from "../runtime/builtinAgentDrivers.js";
-import { RUNTIME_OBSERVATION_TASK_EVENT, createRuntimeObservation, isRuntimeTokenEvidence, runtimeObservationFenceMatches, runtimeObservationFromTaskEvent, runtimeObservationRunFenceMatches, runtimeObservationTaskEventPayload } from "../runtime/runtimeObservation.js";
+import { RUNTIME_OBSERVATION_TASK_EVENT, createRuntimeObservation, isRuntimeTokenEvidence, runtimeObservationFenceMatches, runtimeObservationFromTaskEvent, runtimeObservationRunFenceMatches, runtimeObservationTaskEventPayload, runHasActiveRuntimeOperations } from "../runtime/runtimeObservation.js";
 import { projectRuntimeTaskEvents } from "../runtime/runtimeProjection.js";
 import { contextSnapshotRef } from "../context/contextSnapshot.js";
 import { contextSnapshotDeltaRefIds, freezeRunContextSnapshot } from "../context/runContextPack.js";
@@ -386,7 +387,7 @@ export class FileSchedulerStoreAdapter {
                     const message = [
                         `Leader native Session became unavailable while Run ${active.id} remains active.`,
                         "Yui preserved the Run because Session/host termination is not a workflow outcome.",
-                        "Inspect native-child and mailbox facts, then explicitly continue, reset, or request user input."
+                        "Inspect native-child and mailbox facts, then explicitly diagnose, recover the Run, request a Conversation switch, or request user input."
                     ].join(" ");
                     recordLeaderAttentionRequired(store, {
                         taskId: input.fence.taskId,
@@ -718,6 +719,27 @@ export class FileSchedulerStoreAdapter {
         // the fold as present and skips the per-candidate fallback scans.
         return latestRunDurableProgressAt(view, taskId, roleName, runId, projected.runFacts.get(runId) ?? {});
     }
+    recordRoleRunDiagnostic(input) {
+        return this.store.transaction((store) => {
+            const task = store.getTask(input.taskId);
+            const run = store.getActiveAgentRun(input.taskId, input.roleName);
+            if (task === null || task.status !== "active"
+                || run === null || run.id !== input.runId || run.status !== "active") {
+                return "state-changed";
+            }
+            const latest = latestRunEventTime(store.listEvents(input.taskId), RUN_DIAGNOSTIC_FINISHED_EVENT, input.runId);
+            if (latest !== undefined && Date.parse(latest) >= Date.parse(input.startedAt)) {
+                return "already-recorded";
+            }
+            store.saveEvent(input.taskId, createTaskEvent(store.nextEventId(input.taskId), input.taskId, RUN_DIAGNOSTIC_FINISHED_EVENT, {
+                runId: input.runId,
+                roleName: input.roleName,
+                outcome: input.outcome,
+                startedAt: input.startedAt
+            }, input.now));
+            return "recorded";
+        });
+    }
     recordRoleRunStall(input) {
         return this.store.transaction((store) => {
             const task = store.getTask(input.taskId);
@@ -749,15 +771,9 @@ export class FileSchedulerStoreAdapter {
                 progressAt: input.progressAt,
                 idleMs: String(Math.max(0, Math.floor(input.idleMs))),
                 evidenceKey: input.evidenceKey,
-                status: "needs-attention"
+                status: "diagnostic-only"
             }, input.now);
             store.saveEvent(task.id, event);
-            if (role.name === "leader") {
-                enqueueOperatorEvent(store, event, "leader-run-stalled", input.now);
-            }
-            else {
-                queueLeaderWakeup(store, task.id, wakeReason("role-run-stalled"), input.now);
-            }
             return "raised";
         });
     }
@@ -785,10 +801,9 @@ export class FileSchedulerStoreAdapter {
                     || (typeof event.payload.progressAt === "string"
                         && Number.isFinite(Date.parse(event.payload.progressAt))
                         && Date.parse(event.payload.progressAt) >= Date.parse(input.progressAt)))));
-            const stalledAt = latestRunEventTime(events, RUN_STALLED_EVENT, run.id);
-            const recoveredAt = latestRunEventTime(events, RUN_RECOVERED_EVENT, run.id);
-            const recovered = stalledAt !== undefined
-                && (recoveredAt === undefined || Date.parse(recoveredAt) <= Date.parse(stalledAt));
+            // Advisory 30-minute diagnostics are intentionally not lifecycle
+            // episodes and therefore must never synthesize run.recovered.
+            const recovered = isRoleRunStalled(events, run.id);
             if (!existing) {
                 store.saveEvent(task.id, createTaskEvent(store.nextEventId(task.id), task.id, RUN_PROGRESS_EVENT, {
                     runId: run.id,
@@ -813,11 +828,92 @@ export class FileSchedulerStoreAdapter {
         const sessions = this.store.getTaskRoleSessionSet(taskId, roleName);
         return sessions !== null && sessions.inFlight !== null;
     }
+    detachAgentHostProviderForConversationSwitch(input) {
+        return this.store.transaction((store) => {
+            const sessions = store.getTaskRoleSessionSet(input.taskId, input.roleName);
+            const run = store.getAgentRun(input.taskId, input.runId);
+            const mailbox = store.getWorkMailbox({
+                kind: "role",
+                taskId: input.taskId,
+                roleName: input.roleName
+            });
+            const binding = sessions?.providerBinding;
+            const session = sessions?.sessions[input.agentId];
+            const task = store.getTask(input.taskId);
+            const role = store.getRole(input.taskId, input.roleName);
+            const activeRun = store.getActiveAgentRun(input.taskId, input.roleName);
+            if (task === null || task.status !== "active"
+                || role === null || role.activeAgentId !== input.agentId
+                || sessions === null || sessions === undefined
+                || run === null || run.status !== "active" || run.mode !== "new"
+                || activeRun?.id !== run.id
+                || run.effective.agentId !== input.agentId
+                || session?.nativeSessionId !== input.previousNativeSessionId
+                || binding === null || binding === undefined
+                || currentProviderConversation(binding).conversationId !== input.previousConversationId
+                || sessions.inFlight?.runId !== input.runId
+                || mailbox?.processing?.batchId !== sessions.inFlight.receiptId
+                || mailbox.processing.owner !== "controller"
+                || mailbox.processing.executionRef?.type !== "run"
+                || mailbox.processing.executionRef.taskId !== input.taskId
+                || mailbox.processing.executionRef.id !== input.runId
+                || mailbox.inputDelivery !== null
+                || pendingConversationSwitch(store.listEvents(input.taskId), input.roleName, sessions) === null
+                || !runtimeHookMatchesReservation(store, { scope: "task", taskId: input.taskId, roleName: input.roleName }, input.launchId)
+                || input.nextAuthorityHolderId !== input.launchId) {
+                throw new Error("Provider Conversation detachment no longer matches the exact switch Run.");
+            }
+            const target = binding.activations.find((entry) => (entry.activationId === input.previousActivationId
+                && entry.conversationId === input.previousConversationId));
+            if (target === undefined) {
+                throw new Error("Provider Conversation detachment targets an unknown Activation.");
+            }
+            if (target.status !== "active") {
+                if (binding.authority.owner !== "none"
+                    || input.nextAuthorityEpoch !== binding.authority.epoch + 1) {
+                    throw new Error("Provider Conversation detachment replay has a stale authority fence.");
+                }
+                return "already-detached";
+            }
+            if (conversationDetachmentBasis({
+                sessions,
+                events: store.listEvents(input.taskId),
+                mailbox,
+                roleName: input.roleName,
+                runId: input.runId,
+                runMode: run.mode
+            }) !== "actor-request"
+                || binding.authority.owner !== "controller"
+                || binding.authority.holderId !== target.activationId
+                || input.nextAuthorityEpoch !== binding.authority.epoch + 2) {
+                throw new Error("Provider Conversation detachment is not authorized at this boundary.");
+            }
+            const detached = endProviderActivation(binding, target.activationId, {
+                status: "ended",
+                endedAt: input.now.toISOString(),
+                reason: "conversation-switch"
+            });
+            store.saveTaskRoleSessionSet(updateTaskRoleProviderRuntime(sessions, detached, input.now));
+            store.saveEvent(input.taskId, createTaskEvent(store.nextEventId(input.taskId), input.taskId, CONVERSATION_SWITCH_DETACHED_EVENT, {
+                runId: input.runId,
+                roleName: input.roleName,
+                launchId: input.launchId,
+                conversationId: input.previousConversationId,
+                activationId: input.previousActivationId
+            }, input.now));
+            return "detached";
+        });
+    }
     beginAgentHostProviderTurn(input) {
         this.store.transaction((store) => {
             const sessions = store.getTaskRoleSessionSet(input.taskId, input.roleName);
             const session = sessions?.sessions[input.agentId];
             const binding = sessions?.providerBinding;
+            const mailbox = store.getWorkMailbox({
+                kind: "role",
+                taskId: input.taskId,
+                roleName: input.roleName
+            });
             if (sessions === null || sessions === undefined
                 || binding === null || binding === undefined
                 || sessions.inFlight?.runId !== input.runId
@@ -827,7 +923,8 @@ export class FileSchedulerStoreAdapter {
                 || currentProviderConversation(binding).conversationId !== input.nativeSessionId
                 || binding.authority.owner !== input.authorityOwner
                 || binding.authority.epoch !== input.authorityEpoch
-                || binding.authority.holderId !== input.holderId) {
+                || binding.authority.holderId !== input.holderId
+                || !processingOwnsExactInitialDelivery(mailbox, input.taskId, input.runId, input.attemptId)) {
                 throw new AgentHostProviderTurnFenceError("Agent Host Provider Turn carries a stale durable writer fence. Release and reacquire Provider authority before retrying input.");
             }
             const exactReplay = binding.turn?.attemptId === input.attemptId
@@ -852,21 +949,15 @@ export class FileSchedulerStoreAdapter {
             if (sessions === null || sessions === undefined
                 || binding === null || binding === undefined
                 || binding.runId !== input.runId
-                || binding.turn?.attemptId !== input.attemptId
-                || binding.turn.status !== "submitting") {
+                || binding.turn?.attemptId !== input.attemptId) {
                 throw new Error("Agent Host Provider Turn submission is no longer current.");
             }
-            const updated = input.status === "delivery-unknown"
-                ? markProviderTurnDeliveryUnknown(binding, {
-                    attemptId: input.attemptId,
-                    observedAt: input.now.toISOString(),
-                    reason: input.reason
-                })
-                : rejectProviderTurn(binding, {
-                    attemptId: input.attemptId,
-                    rejectedAt: input.now.toISOString(),
-                    reason: input.reason
-                });
+            const updated = settleProviderTurnSubmission(binding, {
+                attemptId: input.attemptId,
+                status: input.status,
+                reason: input.reason,
+                resolvedAt: input.now.toISOString()
+            });
             store.saveTaskRoleSessionSet(updateTaskRoleProviderRuntime(sessions, updated, input.now));
         });
     }
@@ -889,68 +980,6 @@ export class FileSchedulerStoreAdapter {
             ...binding.authority
         };
     }
-    beginRoleRunProviderTurn(input) {
-        return this.store.transaction((store) => {
-            const sessions = store.getTaskRoleSessionSet(input.taskId, input.roleName);
-            const session = sessions?.sessions[input.agentId];
-            const binding = sessions?.providerBinding;
-            if (sessions === null || sessions === undefined
-                || binding === null || binding === undefined
-                || sessions.inFlight?.runId !== input.runId
-                || binding.runId !== input.runId
-                || session?.launchId !== input.launchId
-                || session.nativeSessionId !== input.nativeSessionId
-                || currentProviderConversation(binding).conversationId !== input.nativeSessionId
-                || binding.authority.owner !== "controller")
-                return false;
-            store.saveTaskRoleSessionSet(updateTaskRoleProviderRuntime(sessions, beginProviderTurn(binding, {
-                attemptId: input.attemptId,
-                authorityEpoch: binding.authority.epoch,
-                submittedAt: input.now.toISOString()
-            }), input.now));
-            return true;
-        });
-    }
-    resolveRoleRunProviderSubmission(input) {
-        return this.store.transaction((store) => {
-            const sessions = store.getTaskRoleSessionSet(input.taskId, input.roleName);
-            const binding = sessions?.providerBinding;
-            if (sessions === null || sessions === undefined
-                || binding === null || binding === undefined
-                || binding.runId !== input.runId
-                || binding.turn?.attemptId !== input.attemptId
-                || binding.turn.status !== "submitting")
-                return false;
-            const updated = input.status === "delivery-unknown"
-                ? markProviderTurnDeliveryUnknown(binding, {
-                    attemptId: input.attemptId,
-                    observedAt: input.now.toISOString(),
-                    reason: input.reason
-                })
-                : rejectProviderTurn(binding, {
-                    attemptId: input.attemptId,
-                    rejectedAt: input.now.toISOString(),
-                    reason: input.reason
-                });
-            store.saveTaskRoleSessionSet(updateTaskRoleProviderRuntime(sessions, updated, input.now));
-            return true;
-        });
-    }
-    isRoleGenerationProviderReady(input) {
-        // A session.ready observation for this exact generation is the durable
-        // pre-input fence. This reads folded Driver truth
-        // only — no liveness, screen, or pane/PID inference. Served from the
-        // revision projection: a stale miss only repeats an idempotent first push.
-        return this.listEvents(input.taskId).some((event) => {
-            const observation = runtimeObservationFromTaskEvent(event);
-            return observation?.kind === "session.ready"
-                && observation.fence.roleName === input.roleName
-                && observation.fence.agentId === input.agentId
-                && (input.launchId === undefined || observation.fence.launchId === input.launchId)
-                && (input.nativeSessionId === undefined
-                    || observation.fence.nativeSessionId === input.nativeSessionId);
-        });
-    }
     peekNextAgentRunId(taskId) {
         return this.store.peekNextAgentRunId(taskId);
     }
@@ -1211,12 +1240,6 @@ export class FileSchedulerStoreAdapter {
             }
             const owner = runtimeOwnerFromTarget(target);
             markRuntimeOwnerSessionStopped(store, owner, now);
-            if (owner.scope === "task") {
-                const sessions = store.getTaskRoleSessionSet(owner.taskId, owner.roleName);
-                if (sessions !== null && sessions.providerBinding !== null) {
-                    store.saveTaskRoleSessionSet(clearTaskRoleProviderRuntimeForCleanup(sessions, now));
-                }
-            }
             saveRuntimeLifecycleMailbox(store, mailbox);
             return true;
         });
@@ -1353,7 +1376,9 @@ export class FileSchedulerStoreAdapter {
                     now: input.now
                 }));
             }
-            if (input.session !== null && input.session.nativeSessionId !== undefined) {
+            if (input.run.mode !== "new"
+                && input.session !== null
+                && input.session.nativeSessionId !== undefined) {
                 saveTaskSession(store, role, {
                     ...input.session,
                     nativeSessionId: input.session.nativeSessionId
@@ -1450,9 +1475,13 @@ export class FileSchedulerStoreAdapter {
             if (input.session !== null && input.session.nativeSessionId !== undefined) {
                 const existing = store.getRoleSession(input.task.id, input.role.name);
                 matchingPreparedRuntimeReservation(store, input);
-                if (existing?.nativeSessionId !== input.session.nativeSessionId
-                    || (input.launchId !== undefined && existing.launchId !== input.launchId)
-                    || existing.status !== "running") {
+                const defersConversationReplacement = active.mode === "new"
+                    && existing !== null
+                    && existing.nativeSessionId !== input.session.nativeSessionId;
+                if (!defersConversationReplacement
+                    && (existing?.nativeSessionId !== input.session.nativeSessionId
+                        || (input.launchId !== undefined && existing.launchId !== input.launchId)
+                        || existing.status !== "running")) {
                     saveTaskSession(store, role, {
                         ...input.session,
                         nativeSessionId: input.session.nativeSessionId
@@ -1496,7 +1525,8 @@ export class FileSchedulerStoreAdapter {
                 || !preparedReservationMatches(runtimeMailbox, input.taskId, input.runId, input.launchId)) {
                 return "state-changed";
             }
-            const summary = `Role delivery retry limit exhausted before exact Run input delivery: ${input.runId}.`;
+            const summary = input.summary
+                ?? `Role delivery retry limit exhausted before exact Run input delivery: ${input.runId}.`;
             const result = terminalizeExactTaskRun(store, {
                 taskId: input.taskId,
                 roleName: input.roleName,
@@ -1512,11 +1542,13 @@ export class FileSchedulerStoreAdapter {
             if (result.disposition !== "applied" || result.run === null) {
                 return "state-changed";
             }
-            enqueueWork(store, runtimeLifecycleTarget({
-                scope: "task",
-                taskId: input.taskId,
-                roleName: input.roleName
-            }), RUNTIME_CLEANUP_REQUIRED_REASON, input.now, [{ type: "task", id: input.taskId }]);
+            if (input.cleanupRequired !== false) {
+                enqueueWork(store, runtimeLifecycleTarget({
+                    scope: "task",
+                    taskId: input.taskId,
+                    roleName: input.roleName
+                }), RUNTIME_CLEANUP_REQUIRED_REASON, input.now, [{ type: "task", id: input.taskId }]);
+            }
             const terminal = result.run;
             const deliveryFailureEvent = createTaskEvent(store.nextEventId(input.taskId), input.taskId, "runtime.role-delivery-failed", {
                 runId: terminal.id,
@@ -2430,7 +2462,7 @@ export class FileSchedulerStoreAdapter {
     /**
      * Issue 04: reopens each due retry on its original Native Session. A Run
      * whose Session is proven dead terminalizes with an exact replacement
-     * blocker; a live Session is reset for the existing delivery path, which
+     * blocker; a live Session is reopened for the existing delivery path, which
      * re-pushes the exact same input in the same pass.
      */
     resolveDueProviderRetries(now, taskIds) {
@@ -2463,9 +2495,10 @@ export class FileSchedulerStoreAdapter {
                     || !providerRetryIsDue(run.providerRetry, now)) {
                     return;
                 }
-                let sessions = store.getTaskRoleSessionSet(entry.taskId, entry.roleName);
+                const sessions = store.getTaskRoleSessionSet(entry.taskId, entry.roleName);
                 const providerBinding = sessions?.providerBinding;
                 let recoveryMode = "resume";
+                let replacementRequired = false;
                 if (providerBinding === null || providerBinding === undefined) {
                     deferUnprovenProviderRecovery(store, run, entry.roleName, "Provider Conversation identity is missing; automatic recovery is fenced.", now);
                     return;
@@ -2510,13 +2543,7 @@ export class FileSchedulerStoreAdapter {
                         deferUnprovenProviderRecovery(store, run, entry.roleName, "Provider replacement lacks an exact missing-Conversation observation.", now);
                         return;
                     }
-                    recoveryMode = "new";
-                    const currentSession = sessions?.sessions[run.effective.agentId];
-                    if (sessions !== null && currentSession !== undefined
-                        && currentSession.status !== "broken") {
-                        sessions = updateRoleAgentSessionStatus(sessions, run.effective.agentId, "broken", now);
-                        store.saveTaskRoleSessionSet(sessions);
-                    }
+                    replacementRequired = true;
                 }
                 const session = sessions?.sessions[run.effective.agentId];
                 const identityMatches = session !== undefined
@@ -2549,7 +2576,12 @@ export class FileSchedulerStoreAdapter {
                     routeRoleEvent(store, attentionEvent, entry.roleName, "provider-retry-native-resume-unproven", now);
                     return;
                 }
-                if (hasUnsettledRuntimeOperations(store, entry.taskId, run.id)) {
+                if (runHasActiveRuntimeOperations(store.listEvents(entry.taskId), {
+                    taskId: entry.taskId,
+                    roleName: entry.roleName,
+                    runId: run.id,
+                    agentId: run.effective.agentId
+                })) {
                     const deferred = deferProviderRetry(run.providerRetry, now);
                     if (deferred === null) {
                         finalizeProviderRetryDeadline(store, run, "Provider retry stopped because tool/subagent outcome remained uncertain through the bounded episode deadline.", "operation-outcome-uncertain", now);
@@ -2558,6 +2590,21 @@ export class FileSchedulerStoreAdapter {
                     store.saveAgentRun(withProviderRetry(run, deferred));
                     return;
                 }
+                if (replacementRequired) {
+                    try {
+                        recoveryMode = roleSessionDispatchModeWithConversationSwitch(sessions, store.listEvents(entry.taskId), roleMailbox, entry.roleName, run.effective.agentId, run.effective);
+                    }
+                    catch (error) {
+                        deferUnprovenProviderRecovery(store, run, entry.roleName, error instanceof Error
+                            ? error.message
+                            : "Independent Conversation-switch evaluation failed closed.", now);
+                        return;
+                    }
+                    if (recoveryMode !== "new") {
+                        deferUnprovenProviderRecovery(store, run, entry.roleName, "Independent Conversation-switch evaluation kept the current Conversation.", now);
+                        return;
+                    }
+                }
                 // Reopen the Run on its original Session: reset transport markers,
                 // switch to resume, and mark the projection in-flight. The delivery
                 // pass re-pushes the exact same input in this same pass.
@@ -2667,7 +2714,30 @@ export class FileSchedulerStoreAdapter {
                             recordCanonicalObservationObsolete(store, input, "bind-state-missing", now);
                             return "obsolete";
                         }
-                        const bound = recordRoleAgentSession(sessions, {
+                        const mailbox = store.getWorkMailbox({
+                            kind: "role",
+                            taskId,
+                            roleName: input.fence.roleName
+                        });
+                        const existingNativeSessionId = sessions.sessions[input.fence.agentId]
+                            ?.nativeSessionId;
+                        const replacingNativeSession = existingNativeSessionId !== undefined
+                            && existingNativeSessionId !== decision.outcome.nativeSessionId;
+                        const replacementBasis = replacingNativeSession
+                            ? conversationReplacementBasis({
+                                sessions,
+                                events: store.listEvents(taskId),
+                                mailbox,
+                                roleName: input.fence.roleName,
+                                runId: run.id,
+                                runMode: run.mode
+                            })
+                            : null;
+                        if (replacingNativeSession && replacementBasis === null) {
+                            recordCanonicalObservationObsolete(store, input, "conversation-switch-not-authorized", now);
+                            return "obsolete";
+                        }
+                        const sessionInput = {
                             agentId: input.fence.agentId,
                             adapterId,
                             nativeSessionId: decision.outcome.nativeSessionId,
@@ -2675,9 +2745,20 @@ export class FileSchedulerStoreAdapter {
                             policy: "fixed",
                             status: "running",
                             effective: run.effective
-                        }, now);
-                        const withProvider = bindOrSupersedeProviderRuntime(bound, input, now);
+                        };
+                        const bound = replacementBasis === null
+                            ? recordRoleAgentSession(sessions, sessionInput, now)
+                            : replaceTaskRoleAgentSessionForConversationSwitch(sessions, sessionInput, now);
+                        const withProvider = bindOrSupersedeProviderRuntime(bound, input, now, replacementBasis ?? undefined);
                         store.saveTaskRoleSessionSet(withProvider);
+                        if (replacementBasis === "actor-request") {
+                            resolveConversationSwitchRequest(store, taskId, input.fence.roleName, sessions, "applied", now, {
+                                conversationId: input.fence.conversationId
+                                    ?? decision.outcome.nativeSessionId,
+                                activationId: input.fence.activationId ?? input.fence.launchId,
+                                launchId: input.fence.launchId
+                            });
+                        }
                         const driver = this.drivers.require(input.fence.driverId);
                         if (driver.capabilities.observation.sessionBootstrap === "discovered"
                             && run.pushedAt === undefined) {
@@ -2898,7 +2979,6 @@ export class FileSchedulerStoreAdapter {
             return null;
         const sessionSet = store.getTaskRoleSessionSet(fence.taskId, fence.roleName);
         const session = sessionSet?.sessions[fence.agentId] ?? null;
-        const boundNativeSessionId = session?.nativeSessionId;
         if (runId === undefined) {
             return {
                 fence,
@@ -2907,7 +2987,9 @@ export class FileSchedulerStoreAdapter {
                 pushed: false,
                 accepted: false,
                 terminal: false,
-                ...(boundNativeSessionId === undefined ? {} : { boundNativeSessionId })
+                ...(session?.nativeSessionId === undefined
+                    ? {}
+                    : { boundNativeSessionId: session.nativeSessionId })
             };
         }
         const run = store.getAgentRun(fence.taskId, runId);
@@ -2919,8 +3001,15 @@ export class FileSchedulerStoreAdapter {
             || inFlight.agentId !== run.effective.agentId)
             return null;
         const owner = { scope: "task", taskId: fence.taskId, roleName: fence.roleName };
-        const launchId = session?.launchId
-            ?? (runtimeHookMatchesReservation(store, owner, fence.launchId) ? fence.launchId : undefined);
+        const freshConversationLaunch = run.mode === "new"
+            && runtimeHookMatchesReservation(store, owner, fence.launchId);
+        const boundNativeSessionId = freshConversationLaunch
+            ? undefined
+            : session?.nativeSessionId;
+        const launchId = freshConversationLaunch
+            ? fence.launchId
+            : session?.launchId
+                ?? (runtimeHookMatchesReservation(store, owner, fence.launchId) ? fence.launchId : undefined);
         if (launchId === undefined)
             return null;
         const expectedFence = {
@@ -3037,14 +3126,6 @@ export class FileSchedulerStoreAdapter {
         return "apply";
     }
 }
-function hasUnsettledRuntimeOperations(store, taskId, runId) {
-    return store.listEvents(taskId).some((event) => {
-        const observation = runtimeObservationFromTaskEvent(event);
-        return observation !== null
-            && observation.fence.runId === runId
-            && observation.kind === "operation.started";
-    });
-}
 function runtimeTurnFailureSummary(input) {
     return [
         "Agent runtime turn failed.",
@@ -3270,9 +3351,12 @@ function markRuntimeOwnerSessionStopped(store, owner, now) {
         if (sessions === null)
             return false;
         const active = sessions.sessions[sessions.activeAgentId];
-        if (active === undefined || active.status === "stopped")
+        if (active === undefined)
             return false;
-        store.saveTaskRoleSessionSet(updateRoleAgentSessionStatus(sessions, sessions.activeAgentId, "stopped", now));
+        const stopped = stopTaskRoleRuntimeAfterPhysicalExit(sessions, now);
+        if (stopped === sessions)
+            return false;
+        store.saveTaskRoleSessionSet(stopped);
         return true;
     }
     const sessions = store.getGlobalRoleSessionSet(owner.roleName);
@@ -3688,6 +3772,19 @@ function schedulerRoleSessionsMatch(current, expected) {
         && current.launchId === expected.launchId
         && isDeepStrictEqual(current.effective, expected.effective);
 }
+/**
+ * The durable Run/mailbox claim is the pre-Host delivery intent. The Host may
+ * create a ProviderTurn only while that exact reservation still owns the Run;
+ * this closes the gap where a Session could start without any user Turn.
+ */
+function processingOwnsExactInitialDelivery(mailbox, taskId, runId, attemptId) {
+    const processing = mailbox?.processing;
+    return processing?.batchId === attemptId
+        && processing.owner === "controller"
+        && processing.executionRef?.type === "run"
+        && processing.executionRef.taskId === taskId
+        && processing.executionRef.id === runId;
+}
 function matchesStallSessionFence(current, expected) {
     if (current === null || expected === null)
         return current === expected;
@@ -3838,7 +3935,7 @@ function canonicalStructuredProviderTurnId(sessions, observedTurnId, attemptId)
         ? turn.turnId
         : observedTurnId;
 }
-function bindOrSupersedeProviderRuntime(sessions, input, now) {
+function bindOrSupersedeProviderRuntime(sessions, input, now, replacementBasis) {
     if (sessions.inFlight === null)
         return sessions;
     const conversationId = input.fence.conversationId ?? input.fence.nativeSessionId;
@@ -3873,9 +3970,22 @@ function bindOrSupersedeProviderRuntime(sessions, input, now) {
         conversationId,
         activationId,
         switchedAt: input.observedAt ?? input.receivedAt,
-        noUnsettledInputDelivery
+        noUnsettledInputDelivery,
+        ...(replacementBasis === undefined ? {} : { basis: replacementBasis })
     }), now);
 }
+function resolveConversationSwitchRequest(store, taskId, roleName, previousSessions, status, now, replacement) {
+    const request = pendingConversationSwitch(store.listEvents(taskId), roleName, previousSessions);
+    if (request === null)
+        return;
+    store.saveEvent(taskId, createTaskEvent(store.nextEventId(taskId), taskId, CONVERSATION_SWITCH_RESOLVED_EVENT, {
+        requestId: request.requestId,
+        roleName,
+        generation: request.generation,
+        status,
+        ...(replacement === undefined ? {} : replacement)
+    }, now));
+}
 function rejectSubmittingProviderTurn(store, target, delivery, now, reason) {
     if (target.kind !== "role"
         || delivery.executionRef.type !== "run"