@zq-silk/yui 2.22.0 → 2.25.0

package/dist/runtime/agentHost.js

@@ -4,7 +4,7 @@ import { createConnection, createServer } from "node:net";
 import { homedir, tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { createInterface } from "node:readline";
-import { createSessionSkillNotice } from "../context/sessionSkillNotice.js";
+import { createSessionSkillNotice, createSessionSkillLifecycleCheck } from "../context/sessionSkillNotice.js";
 import { publishStructuredConversationRecoverability, publishStructuredProviderAccepted, publishStructuredProviderActivity, publishStructuredProviderAttachmentExit, publishStructuredProviderConnection, publishStructuredProviderDiagnostic, publishStructuredProviderGoal, publishStructuredProviderInputObserved, publishStructuredProviderInputSettlement, publishStructuredProviderOpened, publishStructuredProviderStarted, publishStructuredProviderTerminal, replayStructuredProviderPersistence, structuredProviderEventDelivery } from "../controller/structuredProviderObservation.js";
 import { callController, controllerCallMayHaveApplied, ControllerClientError } from "../core/controllerClient.js";
 import { readHomeFilesystemId } from "../core/homeFilesystemIdentity.js";
@@ -16,6 +16,9 @@ import { providerDeliveryFailure, providerDeliveryFailureFrom, redactAgentErrorT
 import { AGENT_HOST_CONTROL_PROTOCOL } from "./agentHostProtocol.js";
 import { AGENT_HOST_IMPLEMENTATION } from "./agentHostImplementation.js";
 import { closeAgentHostEndpoints } from "./agentHostCleanup.js";
+import { createHostUpgradeGate } from "./hostUpgradeGate.js";
+import { createHostSessionLifecycle } from "./hostSessionLifecycle.js";
+import { createNonBlockingChecks } from "./lifecycleChecks.js";
 import { readAgentRunConfigurationObservation, unknownAgentRunConfiguration } from "./agentRunConfiguration.js";
 import { CodexPreSubmissionError } from "./codexAppServerRuntime.js";
 import { runCodexInteractiveHost } from "./codexInteractiveHost.js";
@@ -83,6 +86,8 @@ export async function runAgentHost(input) {
     }
     let session;
     const skillNotice = createSessionSkillNotice(input.home);
+    const upgrade = createHostUpgradeGate();
+    let upgradeDetaching = false;
     // This process really holds the Endpoint code its Session runs on. The lease
     // spans the Session's Turns, so installing a newer generation does not change
     // the implementation under a Session that is still using this one.
@@ -112,6 +117,16 @@ export async function runAgentHost(input) {
         });
     };
     let snapshot = hostSnapshot("idle");
+    const lifecycleChecks = createNonBlockingChecks([
+        createSessionSkillLifecycleCheck(input.home, () => (sessionPayload ?? payload).environment), {
+            id: "controller-lifecycle-hint",
+            run: (_transition, signal) => {
+                if (!signal.aborted)
+                    return signalRoleMailbox(input.home, sessionPayload ?? payload);
+            }
+        }
+    ], error => process.stderr.write(`Session lifecycle check failed: ${errorText(error)}\n`));
+    const lifecycle = createHostSessionLifecycle({ after: lifecycleChecks });
     let dispatchTail = Promise.resolve();
     let promptHuman = () => { };
     let humanConsole;
@@ -120,10 +135,23 @@ export async function runAgentHost(input) {
     let modelChanging = false;
     const recentSteerAttempts = new Map();
     await replayExitOutbox(input.home);
+    const hostEvent = (event, fields) => ({
+        event: { ...event, processInstanceId: fields.processInstanceId, nativeSessionId: fields.nativeSessionId,
+            attemptId: fields.attemptId, nativeTurnId: fields.nativeTurnId },
+        fields
+    });
     const updateSnapshot = (next) => {
-        const { appliedGeneratedTitle: _oldTitle, ...rest } = next;
+        // Validate the payload before committing the FSM; an invalid observation
+        // must not leave the public snapshot and lifecycle on different states.
+        validateSnapshot(hostSnapshot(lifecycle.state, next.fields));
+        const result = lifecycle.send(next.event);
+        if (result.status === "ignored")
+            return;
+        if (result.status === "invalid")
+            throw new Error(result.reason);
+        const { appliedGeneratedTitle: _oldTitle, ...rest } = next.fields;
         snapshot = validateSnapshot({
-            ...rest,
+            ...hostSnapshot(result.state, rest),
             ...(session?.appliedGeneratedTitle === undefined ? {} : {
                 appliedGeneratedTitle: session.appliedGeneratedTitle
             })
@@ -150,7 +178,7 @@ export async function runAgentHost(input) {
             await publishStructuredProviderAccepted({
                 home: input.home, environment: observedPayload.environment, receipt
             });
-            updateSnapshot(hostSnapshot("ready", {
+            updateSnapshot(hostEvent({ type: "accepted" }, {
                 adapterId: session.adapterId,
                 processInstanceId: session.processInstanceId,
                 nativeSessionId: receipt.nativeSessionId,
@@ -178,7 +206,7 @@ export async function runAgentHost(input) {
         if (started.clientOwned || observedPayload === undefined)
             return;
         const observedAuthority = authority === undefined ? undefined : { ...authority };
-        updateSnapshot(hostSnapshot("busy", {
+        updateSnapshot(hostEvent({ type: "native-started" }, {
             adapterId: observedPayload.providerControl?.adapterId,
             processInstanceId: session?.processInstanceId,
             nativeSessionId: started.nativeSessionId,
@@ -239,7 +267,7 @@ export async function runAgentHost(input) {
                     terminal
                 });
                 if (session !== undefined && terminal.conversationId === session.conversationId) {
-                    updateSnapshot(hostSnapshot(session.inspect().activeNativeTurnId === undefined ? "idle" : "busy", {
+                    updateSnapshot(hostEvent({ type: "settled", occupancy: session.inspect().activeNativeTurnId === undefined ? "idle" : "busy" }, {
                         adapterId: session.adapterId,
                         processInstanceId: session.processInstanceId,
                         nativeSessionId: session.nativeSessionId,
@@ -282,7 +310,7 @@ export async function runAgentHost(input) {
                 || activeRunAttemptId !== terminalAttemptId)
                 return;
             if (session !== undefined) {
-                updateSnapshot(hostSnapshot("settling", {
+                updateSnapshot(hostEvent({ type: "terminal" }, {
                     adapterId: terminalPayload.providerControl.adapterId,
                     processInstanceId: session.processInstanceId,
                     nativeSessionId: terminal.nativeSessionId,
@@ -306,7 +334,7 @@ export async function runAgentHost(input) {
                 if (session === undefined)
                     return;
                 const currentPayload = sessionPayload ?? terminalPayload;
-                updateSnapshot(hostSnapshot(session.inspect().activeNativeTurnId === undefined ? "idle" : "busy", {
+                updateSnapshot(hostEvent({ type: "settled", occupancy: session.inspect().activeNativeTurnId === undefined ? "idle" : "busy" }, {
                     adapterId: currentPayload.providerControl.adapterId,
                     processInstanceId: session.processInstanceId,
                     nativeSessionId: terminal.nativeSessionId,
@@ -317,7 +345,7 @@ export async function runAgentHost(input) {
                 promptHuman();
             }
             catch (error) {
-                updateSnapshot(hostSnapshot("failed", {
+                updateSnapshot(hostEvent({ type: "failure", outcome: "failed" }, {
                     adapterId: terminalPayload.providerControl.adapterId,
                     processInstanceId: session?.processInstanceId,
                     nativeSessionId: terminal.nativeSessionId,
@@ -433,10 +461,10 @@ export async function runAgentHost(input) {
                 conversationRecoverability = "recoverable";
                 codexClientAttachedAt = Date.now();
                 observeExit(started.session, currentPayload);
-                const reconnectState = activeRunPayload !== undefined
-                    ? ownedTurn === undefined ? "delivery-unknown" : "ready"
+                const occupancy = activeRunPayload !== undefined
+                    ? ownedTurn === undefined ? "unknown" : "owned"
                     : started.session.inspect().activeNativeTurnId === undefined ? "idle" : "busy";
-                updateSnapshot(hostSnapshot(reconnectState, {
+                updateSnapshot(hostEvent({ type: "connected", occupancy }, {
                     adapterId: "codex",
                     processInstanceId: started.session.processInstanceId,
                     nativeSessionId: started.session.nativeSessionId,
@@ -470,7 +498,7 @@ export async function runAgentHost(input) {
                 lastError = error;
             }
         }
-        updateSnapshot(hostSnapshot("failed", {
+        updateSnapshot(hostEvent({ type: "failure", outcome: "failed" }, {
             adapterId: "codex",
             processInstanceId: disconnectedSession.processInstanceId,
             nativeSessionId: disconnectedSession.nativeSessionId,
@@ -483,6 +511,10 @@ export async function runAgentHost(input) {
     };
     const observeExit = (providerSession, launched) => {
         void providerSession.waitForExit().then((result) => enqueueSerialized(async () => {
+            // A drained attachment is not an ended native Session and must not
+            // trigger reconnect, cancellation, or session lifecycle replacement.
+            if (upgradeDetaching)
+                return;
             const ownsCurrentSession = session === providerSession;
             const currentPayload = ownsCurrentSession
                 ? activeRunPayload ?? lastTerminalPayload ?? sessionPayload ?? launched : launched;
@@ -501,7 +533,7 @@ export async function runAgentHost(input) {
                 }
                 consecutiveCodexDisconnects += 1;
                 if (consecutiveCodexDisconnects > MAX_CONSECUTIVE_CODEX_DISCONNECTS) {
-                    updateSnapshot(hostSnapshot("failed", {
+                    updateSnapshot(hostEvent({ type: "failure", outcome: "failed" }, {
                         adapterId: "codex",
                         processInstanceId: result.processInstanceId,
                         nativeSessionId: providerSession.nativeSessionId,
@@ -513,7 +545,7 @@ export async function runAgentHost(input) {
                     }));
                     return;
                 }
-                updateSnapshot(hostSnapshot("starting", {
+                updateSnapshot(hostEvent({ type: "disconnected" }, {
                     adapterId: "codex",
                     processInstanceId: result.processInstanceId,
                     nativeSessionId: providerSession.nativeSessionId,
@@ -583,7 +615,7 @@ export async function runAgentHost(input) {
             }
             if (hostStopRequested || !ownsCurrentSession)
                 return;
-            updateSnapshot(hostSnapshot(failures.length === 0 ? "exited" : "failed", {
+            updateSnapshot(hostEvent(failures.length === 0 ? { type: "exit" } : { type: "failure", outcome: "failed" }, {
                 adapterId: currentPayload.providerControl?.adapterId,
                 processInstanceId: result.processInstanceId,
                 nativeSessionId: providerSession.nativeSessionId,
@@ -595,7 +627,7 @@ export async function runAgentHost(input) {
                         ? {}
                         : { detail: "Provider process exited before the active AgentRun reached a terminal boundary." })
             }));
-        })).catch((error) => updateSnapshot(hostSnapshot("failed", {
+        })).catch((error) => updateSnapshot(hostEvent({ type: "failure", outcome: "failed" }, {
             adapterId: launched.providerControl?.adapterId,
             processInstanceId: providerSession.processInstanceId,
             ...authorityFields(),
@@ -610,7 +642,7 @@ export async function runAgentHost(input) {
         if (activeRunPayload !== undefined
             || sessionPayload !== undefined
                 && (structuredProviderEventDelivery(input.home, sessionPayload.environment).unpersisted ?? 0) > 0
-            || ["starting", "ready", "settling", "delivery-unknown"].includes(snapshot.state)) {
+            || !lifecycle.can({ type: "launch" })) {
             throw new Error("Agent Host still owns an unsettled Provider Turn.");
         }
         const requestedAuthority = validateProviderAuthorityFence(providerControl.authority);
@@ -624,7 +656,7 @@ export async function runAgentHost(input) {
             && !sameProviderAuthorityFence(authority, requestedAuthority)) {
             throw new Error("Agent Host launch carries a stale Provider authority fence.");
         }
-        updateSnapshot(hostSnapshot("starting", {
+        updateSnapshot(hostEvent({ type: "launch" }, {
             adapterId: providerControl.adapterId,
             ...(session === undefined ? {} : {
                 processInstanceId: session.processInstanceId,
@@ -734,10 +766,10 @@ export async function runAgentHost(input) {
             const restoredOwnedRun = providerControl.kind === "restore"
                 ? providerControl.ownedTurn
                 : undefined;
-            const providerState = restoredOwnedRun !== undefined
-                ? "ready"
+            const occupancy = restoredOwnedRun !== undefined
+                ? "owned"
                 : session.inspect().activeNativeTurnId === undefined ? "idle" : "busy";
-            updateSnapshot(hostSnapshot(providerState, {
+            updateSnapshot(hostEvent({ type: "connected", occupancy }, {
                 adapterId: providerControl.adapterId,
                 processInstanceId: session.processInstanceId,
                 nativeSessionId: session.nativeSessionId,
@@ -769,7 +801,7 @@ export async function runAgentHost(input) {
             const state = error instanceof ProviderTurnBusyError
                 ? "busy"
                 : error instanceof ProviderTurnRejectedError ? "rejected" : "failed";
-            updateSnapshot(hostSnapshot(state, {
+            updateSnapshot(hostEvent({ type: "failure", outcome: state }, {
                 adapterId: providerControl.adapterId,
                 processInstanceId: session?.processInstanceId,
                 nativeSessionId: session?.nativeSessionId ?? providerControl.nativeSessionId,
@@ -790,6 +822,8 @@ export async function runAgentHost(input) {
     };
     const enqueueDispatch = (next) => (enqueueSerialized(() => dispatch(next)));
     const submitRun = async (request, operation) => {
+        if (upgrade.fenced)
+            throw new ProviderTurnBusyError("Host upgrade admission is fenced.", request.run.attemptId);
         if (session === undefined || sessionPayload === undefined) {
             throw new Error("Agent Host has no live Provider Conversation.");
         }
@@ -800,7 +834,7 @@ export async function runAgentHost(input) {
             || !sameProviderAuthorityFence(authority, request.authority)) {
             throw new Error("Agent Host rejected a stale Provider writer fence.");
         }
-        if (activeRunPayload !== undefined || snapshot.state === "settling"
+        if (activeRunPayload !== undefined || !lifecycle.can({ type: "submit" })
             || (structuredProviderEventDelivery(input.home, sessionPayload.environment).unpersisted ?? 0) > 0
             || session.inspect().activeNativeTurnId !== undefined) {
             operation.failure = providerDeliveryFailure({
@@ -830,7 +864,7 @@ export async function runAgentHost(input) {
         };
         activeRunAttemptId = request.run.attemptId;
         activeNativeTurnId = undefined;
-        updateSnapshot(hostSnapshot("starting", {
+        updateSnapshot(hostEvent({ type: "submit" }, {
             adapterId: session.adapterId,
             processInstanceId: session.processInstanceId,
             nativeSessionId: session.nativeSessionId,
@@ -853,6 +887,7 @@ export async function runAgentHost(input) {
                     && typeof retry.text === "string")
                     recoveryInput = {
                         text: retry.text,
+                        ...(typeof retry.context === "string" ? { context: retry.context } : {}),
                         ...(typeof retry.expectedFailedNativeTurnId === "string"
                             ? { expectedFailedNativeTurnId: retry.expectedFailedNativeTurnId } : {})
                     };
@@ -871,8 +906,8 @@ export async function runAgentHost(input) {
             const registrationUnknown = !registrationSettled
                 && (error instanceof ControllerAcknowledgementUnknownError
                     || error instanceof ProviderDeliveryUnknownError);
-            updateSnapshot(hostSnapshot(registrationUnknown ? "delivery-unknown"
-                : error instanceof ProviderTurnBusyError ? "busy" : "failed", {
+            updateSnapshot(hostEvent({ type: "failure", outcome: registrationUnknown ? "delivery-unknown"
+                    : error instanceof ProviderTurnBusyError ? "busy" : "failed" }, {
                 adapterId: session.adapterId,
                 processInstanceId: session.processInstanceId,
                 nativeSessionId: session.nativeSessionId,
@@ -912,10 +947,20 @@ export async function runAgentHost(input) {
         try {
             // beginDurableProviderTurn validated current execution-environment,
             // authority and Session identity before this native write.
-            const notice = skillNotice.prepare(recoveryInput?.text ?? request.run.boundedText, activeRunPayload.environment, session.nativeSessionId, { recovery: recoveryInput !== undefined });
+            const notice = skillNotice.prepare(session.adapterId === "codex" ? request.run.boundedText : recoveryInput?.text ?? request.run.boundedText, activeRunPayload.environment, session.nativeSessionId, { contextEpoch: session.contextEpoch });
             const receipt = endpointReceipt(await session.submit({
                 ...request.run,
-                boundedText: notice.text,
+                boundedText: session.adapterId === "codex" ? notice.inputText : notice.text,
+                ...(session.adapterId !== "codex" || notice.context === undefined && recoveryInput?.context === undefined ? {} : {
+                    additionalContext: {
+                        ...(notice.context === undefined ? {} : {
+                            "yui.session-skills": { kind: "application", value: notice.context }
+                        }),
+                        ...(recoveryInput?.context === undefined ? {} : {
+                            "yui.recovery": { kind: "application", value: recoveryInput.context }
+                        })
+                    }
+                }),
                 ...(recoveryInput === undefined ? {} : { requireQuiescent: true }),
                 ...(recoveryInput?.expectedFailedNativeTurnId === undefined ? {} : {
                     expectedFailedNativeTurnId: recoveryInput.expectedFailedNativeTurnId
@@ -942,7 +987,7 @@ export async function runAgentHost(input) {
                 await resolveProviderTurnSubmission(input.home, durableRun, unknown);
                 throw unknown;
             }
-            updateSnapshot(hostSnapshot("ready", {
+            updateSnapshot(hostEvent({ type: "accepted" }, {
                 adapterId: session.adapterId,
                 processInstanceId: session.processInstanceId,
                 nativeSessionId: receipt.nativeSessionId,
@@ -973,7 +1018,7 @@ export async function runAgentHost(input) {
                 : error instanceof ProviderTurnBusyError
                     ? "busy"
                     : error instanceof ProviderTurnRejectedError ? "rejected" : "failed";
-            updateSnapshot(hostSnapshot(state, {
+            updateSnapshot(hostEvent({ type: "failure", outcome: state }, {
                 adapterId: session.adapterId,
                 processInstanceId: session.processInstanceId,
                 nativeSessionId: session.nativeSessionId,
@@ -1035,10 +1080,13 @@ export async function runAgentHost(input) {
         }
         try {
             await assertHostExecutionEnvironment(input.home, sessionPayload, session.nativeSessionId);
-            const notice = skillNotice.prepare(request.run.boundedText, sessionPayload.environment, session.nativeSessionId);
+            const notice = skillNotice.prepare(request.run.boundedText, sessionPayload.environment, session.nativeSessionId, { contextEpoch: session.contextEpoch });
             const receipt = endpointReceipt(await session.steer({
                 ...request.run,
-                boundedText: notice.text,
+                boundedText: session.adapterId === "codex" ? notice.inputText : notice.text,
+                ...(session.adapterId !== "codex" || notice.context === undefined ? {} : {
+                    additionalContext: { "yui.session-skills": { kind: "application", value: notice.context } }
+                }),
                 inputRef: request.run.attemptId
             }), request.run.attemptId);
             if (receipt.nativeTurnId !== request.nativeTurnId) {
@@ -1067,7 +1115,7 @@ export async function runAgentHost(input) {
         if (activeRunPayload !== undefined || session.inspect().activeNativeTurnId !== undefined
             || sessionPayload !== undefined
                 && (structuredProviderEventDelivery(input.home, sessionPayload.environment).unpersisted ?? 0) > 0
-            || ["starting", "ready", "settling", "delivery-unknown"].includes(snapshot.state)) {
+            || !lifecycle.can({ type: "authority-changed" })) {
             throw new Error("Agent Host authority cannot transfer while a AgentRun is unsettled.");
         }
         const next = validateProviderAuthorityFence(request.authority);
@@ -1079,7 +1127,7 @@ export async function runAgentHost(input) {
             }
         }
         authority = next;
-        updateSnapshot(hostSnapshot("idle", {
+        updateSnapshot(hostEvent({ type: "authority-changed" }, {
             adapterId: session.adapterId,
             processInstanceId: session.processInstanceId,
             nativeSessionId: session.nativeSessionId,
@@ -1138,6 +1186,64 @@ export async function runAgentHost(input) {
         return { turn: { id: accepted.nativeTurnId, items: [], status: "inProgress", error: null } };
     };
     const handleControl = async (request) => {
+        if (request.type === "prepare-upgrade" || request.type === "finish-upgrade") {
+            upgrade.request(request, {
+                nativeSessionId: snapshot.nativeSessionId ?? "",
+                processInstanceId: snapshot.processInstanceId ?? "",
+                hostGeneration: AGENT_HOST_IMPLEMENTATION.generation
+            });
+            if (request.type === "prepare-upgrade") {
+                // Fence synchronously, then join the same lane as submission and
+                // terminal publication. No check-then-submit gap on Host-owned paths.
+                await enqueueSerialized(async () => {
+                    upgrade.request(request, {
+                        nativeSessionId: snapshot.nativeSessionId ?? "", processInstanceId: snapshot.processInstanceId ?? "",
+                        hostGeneration: AGENT_HOST_IMPLEMENTATION.generation
+                    });
+                    await upgrade.drain({
+                        busy: session === undefined || activeRunPayload !== undefined || activeNativeTurnId !== undefined
+                            || snapshot.state !== "idle" || nativeTui !== undefined || nativeOpening !== undefined
+                            || modelChanging || session.inspect().activeNativeTurnId !== undefined
+                            || session.inspect().submissions.some(s => s.disposition.status === "unknown"
+                                || s.disposition.status === "pending" && s.disposition.reason === "submitting"),
+                        events: structuredProviderEventDelivery(input.home, sessionPayload?.environment ?? payload.environment, snapshot.nativeSessionId),
+                        checkQuiescent: async () => {
+                            if (authority?.owner !== "controller" || conversationRecoverability !== "recoverable") {
+                                throw new Error("Upgrade requires an exactly resumable controller-owned native Session.");
+                            }
+                            return await session.checkQuiescent()
+                                && session.inspect().activeNativeTurnId === undefined;
+                        },
+                        release: async () => {
+                            const events = structuredProviderEventDelivery(input.home, sessionPayload.environment, snapshot.nativeSessionId);
+                            if (events.pending !== 0 || events.unpersisted !== 0 || events.pendingTerminals !== 0 || events.failure
+                                || session.inspect().activeNativeTurnId !== undefined
+                                || session.nativeSessionId !== request.nativeSessionId
+                                || session.processInstanceId !== request.processInstanceId) {
+                                throw new Error("Native execution or event delivery changed before Endpoint release.");
+                            }
+                            upgradeDetaching = true;
+                            session.detach();
+                            await endpointLease?.release();
+                            const drain = await endpointOwner.stop(endpointAdapterId, ENDPOINT_DRAIN_TIMEOUT_MS);
+                            if (!drain.quiescent)
+                                throw new Error("Endpoint release did not prove owned client/implementation drain.");
+                        }
+                    });
+                });
+            }
+            else {
+                if (upgrade.observation?.state !== "drained")
+                    throw new Error("Host has not drained.");
+                // The Controller persists the drain receipt before this request.
+                // Delay close until this connection has had a chance to receive its ACK.
+                setImmediate(() => { hostStopRequested = true; stopResolve(); });
+            }
+            return controlResult("accepted", { ...snapshot, hostUpgrade: upgrade.observation });
+        }
+        if (upgrade.fenced && ["launch", "submit-turn", "steer-turn", "set-authority", "native-open", "native-model"].includes(request.type)) {
+            return controlResult("busy", { ...snapshot, hostUpgrade: upgrade.observation });
+        }
         if (request.type === "native-model") {
             return enqueueSerialized(async () => {
                 const current = session;
@@ -1226,7 +1332,7 @@ export async function runAgentHost(input) {
                 const persisted = await replayStructuredProviderPersistence(input.home, sessionPayload.environment);
                 if (persisted.length > 0 && activeRunPayload === undefined) {
                     const active = session.inspect().activeNativeTurnId;
-                    updateSnapshot(hostSnapshot(active === undefined ? "idle" : "busy", {
+                    updateSnapshot(hostEvent({ type: "settled", occupancy: active === undefined ? "idle" : "busy" }, {
                         adapterId: session.adapterId, processInstanceId: session.processInstanceId,
                         nativeSessionId: session.nativeSessionId, conversationId: session.conversationId,
                         nativeTurnId: active, ...authorityFields()
@@ -1270,7 +1376,7 @@ export async function runAgentHost(input) {
                     activeRunPayload = undefined;
                     activeRunAttemptId = undefined;
                     activeNativeTurnId = undefined;
-                    updateSnapshot(hostSnapshot(session.inspect().activeNativeTurnId === undefined ? "idle" : "busy", {
+                    updateSnapshot(hostEvent({ type: "settled", occupancy: session.inspect().activeNativeTurnId === undefined ? "idle" : "busy" }, {
                         adapterId: session.adapterId, processInstanceId: session.processInstanceId,
                         nativeSessionId: session.nativeSessionId, conversationId: session.conversationId,
                         ...authorityFields()
@@ -1293,9 +1399,10 @@ export async function runAgentHost(input) {
                 return requestBytes <= 8000;
             }).slice(0, 8);
             return controlResult("status", session === undefined
-                ? snapshot
+                ? { ...snapshot, hostUpgrade: upgrade.observation }
                 : validateSnapshot({
                     ...snapshot,
+                    hostUpgrade: upgrade.observation,
                     nativeTui: !!nativeTui,
                     ...(nativeRequests === undefined ? {} : { nativeRequests,
                         nativeRequestsOmitted: nativeRequests.length !== session.nativeAccess.requests.length }),
@@ -1403,7 +1510,7 @@ export async function runAgentHost(input) {
             throw new Error("Unsupported Host request.");
         const redeemed = await redeem(input.home, request.ticket);
         if (activeRunPayload !== undefined
-            || ["starting", "ready", "settling", "delivery-unknown"].includes(snapshot.state)) {
+            || !lifecycle.can({ type: "launch" })) {
             if (redeemed.providerControl?.mode === "resume"
                 && redeemed.providerControl.nativeSessionId === snapshot.nativeSessionId) {
                 return controlResult("accepted", snapshot);
@@ -1490,6 +1597,7 @@ export async function runAgentHost(input) {
         return 0;
     }
     finally {
+        lifecycleChecks.close();
         for (const [signal, handler] of handlers)
             process.removeListener(signal, handler);
         if (forceKillTimer !== undefined)
@@ -1577,6 +1685,9 @@ export async function sendAgentHostCancelControl(input) {
 export async function sendAgentHostNativeControl(input) {
     return sendAgentHostControl(input);
 }
+export async function sendAgentHostUpgradeControl(input) {
+    return sendAgentHostControl(input);
+}
 export async function inspectAgentHost(input) {
     const result = await sendAgentHostControl({
         ...input,
@@ -1758,7 +1869,8 @@ export async function openAgentHostControl(home, payload, snapshot, dispatch) {
                             hostImplementation: AGENT_HOST_IMPLEMENTATION,
                             controlCapabilities: payload.providerControl === undefined ? ["status"] : [
                                 "status", "launch", "submit-turn", "steer-turn", "cancel", "set-authority",
-                                "native-open", "native-respond", "native-model", "reconcile-turn"
+                                "native-open", "native-respond", "native-model", "reconcile-turn",
+                                ...(payload.providerControl.adapterId === "codex" ? ["prepare-upgrade", "finish-upgrade"] : [])
                             ],
                             ...(!["task", "global"].includes(payload.environment.YUI_SESSION_SCOPE ?? "") ? {} : {
                                 eventDelivery: structuredProviderEventDelivery(home, payload.environment, result.snapshot.nativeSessionId)
@@ -1909,6 +2021,12 @@ function validateControl(control) {
     }
     if (control.type === "status")
         return Object.freeze({ ...control });
+    if (control.type === "prepare-upgrade" || control.type === "finish-upgrade") {
+        for (const key of ["requestId", "nativeSessionId", "processInstanceId", "hostGeneration"]) {
+            validateIdentity(control[key], key);
+        }
+        return Object.freeze({ ...control });
+    }
     if (control.type === "reconcile-turn") {
         validateIdentity(control.nativeSessionId, "native Session id");
         validateIdentity(control.attemptId, "Provider input attempt id");
@@ -2025,6 +2143,13 @@ function validateSnapshot(snapshot) {
             || value.length === 0 || value.length > 64 || value.includes("\0")))) {
         throw new Error("Agent Host control capability advertisement is invalid.");
     }
+    if (snapshot.hostUpgrade !== undefined) {
+        for (const key of ["requestId", "nativeSessionId", "processInstanceId", "hostGeneration"]) {
+            validateIdentity(snapshot.hostUpgrade[key], key);
+        }
+        if (!["waiting", "drained", "failed"].includes(snapshot.hostUpgrade.state))
+            throw new Error("Invalid Host drain state.");
+    }
     const authorityFields = [
         snapshot.authorityEpoch,
         snapshot.authorityOwner,
@@ -2124,11 +2249,11 @@ function signalRoleMailbox(home, payload) {
     const taskId = payload.environment.YUI_TASK_ID;
     const roleName = payload.environment.YUI_ROLE;
     if (roleName === undefined)
-        return;
+        return Promise.resolve();
     const key = taskId === undefined
         ? `global-role:${encodeURIComponent(roleName)}`
         : `role:${encodeURIComponent(taskId)}/${encodeURIComponent(roleName)}`;
-    void callController(home, "scheduler.signal", { key }).catch(() => {
+    return callController(home, "scheduler.signal", { key }).then(() => undefined).catch(() => {
         // This is a low-latency hint. Durable mailbox state and periodic
         // reconciliation remain the recovery path across a Controller handover.
     });

package/dist/runtime/agentHostImplementation.js

@@ -8,7 +8,9 @@ const release = detectRunningRelease(fileURLToPath(import.meta.url));
 const modules = [
     "agentHost.js", "agentHostProtocol.js", "agentHostImplementation.js",
     "codexInteractiveHost.js", "../controller/structuredProviderObservation.js",
-    "../controller/runtimeEventInbox.js"
+    "../controller/runtimeEventInbox.js", "../context/sessionSkillNotice.js",
+    "../context/sessionBootstrapManifest.js", "../context/currentSkills.js", "contextRecovery.js", "hostUpgradeGate.js",
+    "hostSessionLifecycle.js", "lifecycleChecks.js"
 ];
 export const AGENT_HOST_IMPLEMENTATION = Object.freeze({
     id: "yui.agent-host",

package/dist/runtime/codexAppServerRuntime.js

@@ -171,6 +171,7 @@ export class CodexAppServerRuntime {
         return this.startTurn({
             conversationId: input.conversationId,
             text: input.text,
+            ...(input.additionalContext === undefined ? {} : { additionalContext: input.additionalContext }),
             expectedNoActiveTurn: input.expectedNoActiveTurn,
             ...(input.requireQuiescent ? { requireQuiescent: true } : {}),
             ...(input.expectedFailedNativeTurnId === undefined ? {} : {
@@ -230,6 +231,7 @@ export class CodexAppServerRuntime {
         try {
             const result = await this.transport.request("turn/start", {
                 threadId,
+                ...(input.additionalContext === undefined ? {} : { additionalContext: input.additionalContext }),
                 ...(input.clientUserMessageId === undefined
                     ? {}
                     : { clientUserMessageId: text(input.clientUserMessageId, "Codex input attempt id") }),
@@ -265,6 +267,7 @@ export class CodexAppServerRuntime {
         try {
             const result = await this.transport.request("turn/steer", {
                 threadId,
+                ...(input.additionalContext === undefined ? {} : { additionalContext: input.additionalContext }),
                 expectedTurnId,
                 ...(input.clientUserMessageId === undefined
                     ? {}