@zq-silk/yui 0.15.9 → 0.15.12

package/dist/runtime/agentHost.js

@@ -4,13 +4,11 @@ import { tmpdir, homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { createConnection, createServer } from "node:net";
 import { createInterface } from "node:readline";
-import { assertAgentExecutionEnvironment } from "./executionEnvironment.js";
 import { withSessionContextPointer } from "../context/sessionBootstrapManifest.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, publishStructuredProviderAttachmentExit, publishStructuredProviderActivity, publishStructuredProviderInputSettlement, publishStructuredProviderInputObserved, publishStructuredProviderGoal, publishStructuredConversationRecoverability, publishStructuredProviderOpened, publishStructuredProviderStarted, publishStructuredProviderTerminal } from "../controller/structuredProviderObservation.js";
+import { publishStructuredProviderAccepted, publishStructuredProviderAttachmentExit, publishStructuredProviderActivity, publishStructuredProviderInputSettlement, publishStructuredProviderInputObserved, publishStructuredProviderGoal, publishStructuredConversationRecoverability, publishStructuredProviderOpened, publishStructuredProviderStarted, publishStructuredProviderTerminal, publishStructuredProviderConnection, structuredProviderEventDelivery } from "../controller/structuredProviderObservation.js";
 import { validateAgentHostLaunchPayload } from "./launchBroker.js";
 import { ProviderDeliveryUnknownError, ProviderConversationMissingError, ProviderTurnBusyError, ProviderTurnRejectedError } from "./structuredProviderHost.js";
 import { createAgentEndpointOwner } from "./agentEndpointOwnership.js";
@@ -20,16 +18,50 @@ import { persistRuntimeProcessExitObservation, replayRuntimeProcessExitOutbox }
 import { AGENT_HOST_CLIENT_EXIT_GRACE_MS, AGENT_HOST_CONTROL_TIMEOUT_MS, AGENT_HOST_READY_TIMEOUT_MS, ENDPOINT_DRAIN_TIMEOUT_MS, PROVIDER_ACCEPT_TIMEOUT_MS } from "./runtimeDeadlines.js";
 import { providerDeliveryFailure, providerDeliveryFailureFrom, redactAgentErrorText, serializeAgentErrorRaw } from "./agentError.js";
 import { runCodexInteractiveHost } from "./codexInteractiveHost.js";
+import { CodexPreSubmissionError } from "./codexAppServerRuntime.js";
 import { readAgentRunConfigurationObservation, unknownAgentRunConfiguration } from "./agentRunConfiguration.js";
-import { openCurrentTaskStore } from "../storage/currentTaskStore.js";
 import { createSessionOwnerIdentity, readLinuxProcessIdentity } from "./sessionOwnerIdentity.js";
 import { yuiTmuxServerName, yuiTmuxSessionName } from "../tmux/tmuxManager.js";
 import { tmuxSocketDirectory } from "../tmux/tmuxSocketEndpoint.js";
-import { createTaskEvent } from "../event/taskEvent.js";
-export const AGENT_HOST_CONTROL_PROTOCOL = "yui-agent-host/v5";
+import { AGENT_HOST_CONTROL_PROTOCOL, AGENT_HOST_EVENT_PROTOCOL } from "./agentHostProtocol.js";
+import { FILE_TASK_CONTROLLER_PROTOCOL_VERSION } from "../core/protocol.js";
+export { AGENT_HOST_CONTROL_PROTOCOL } from "./agentHostProtocol.js";
 const HOST_CONTROL_MAX_BYTES = 32 * 1024;
 const CODEX_CLIENT_STABLE_MS = 5_000;
 const MAX_CONSECUTIVE_CODEX_DISCONNECTS = 3;
+export function foldSteerLiveReceipt(control) {
+    const detail = control.failure?.detail ?? control.snapshot.detail;
+    const withDetail = detail === undefined ? {} : { detail };
+    switch (control.outcome) {
+        case "accepted":
+            // The only ok state. A live-accepted steer keeps `not-steered` (static,
+            // pre-flight) and this live disposition strictly separate phases.
+            return { state: "steered", outcome: "accepted" };
+        case "pending":
+            return { state: "steer-unknown", outcome: "pending", ...withDetail };
+        case "rejected":
+            return { state: "steer-rejected", outcome: "rejected", ...withDetail };
+        default:
+            // A steer edge only ever answers accepted/pending/rejected; `busy`,
+            // `status`, or `cancel-requested` here means the Host could not run the
+            // steer. Report it faithfully rather than flattening to success.
+            return { state: "steer-unavailable", outcome: control.outcome, ...withDetail };
+    }
+}
+export function foldInterruptLiveReceipt(control) {
+    const cancellation = control.cancellation;
+    const withCancellation = cancellation === undefined ? {} : { cancellation };
+    if (control.outcome !== "cancel-requested") {
+        const detail = control.failure?.detail ?? control.snapshot.detail;
+        return { state: "interrupt-unavailable", outcome: control.outcome,
+            ...withCancellation, ...(detail === undefined ? {} : { detail }) };
+    }
+    // A transport outcome without native cancellation evidence proves no stop.
+    const state = cancellation?.status === "not-active" ? "interrupt-not-active"
+        : cancellation?.status === "requested" ? "interrupt-requested"
+            : "interrupt-unknown";
+    return { state, outcome: "cancel-requested", ...withCancellation };
+}
 export function serializeAgentHostLaunchControl(control) {
     return JSON.stringify(validateControl(control));
 }
@@ -37,6 +69,11 @@ export async function runAgentHost(input) {
     const hostInstanceId = randomUUID();
     let hostSequence = 0;
     let payload = await redeem(input.home, input.ticket);
+    if (payload.environment.YUI_SESSION_SCOPE === "global" && payload.providerControl !== undefined) {
+        process.stdout.write("Yui controlled Global Session: this is the Host console, not the native Agent TUI. "
+            + "Type a line to submit to this Session; model, permissions and workspace remain as configured. "
+            + "Queued inputs and live controls use the same Endpoint.\n");
+    }
     if (payload.environment.YUI_SESSION_SCOPE === "global"
         && payload.environment.YUI_ADAPTER_ID === "codex"
         && payload.providerControl === undefined) {
@@ -304,7 +341,7 @@ export async function runAgentHost(input) {
             if (hostStopRequested)
                 return;
             try {
-                assertAgentExecutionEnvironment(input.home, reconnectPayload);
+                await assertHostExecutionEnvironment(input.home, reconnectPayload, disconnectedSession.nativeSessionId);
                 // Reattaching a dropped client continues the same Session on the same
                 // pinned generation; it never re-selects an implementation.
                 if (endpointLease === undefined) {
@@ -549,7 +586,8 @@ export async function runAgentHost(input) {
                     activeRunAttemptId = providerControl.ownedTurn.attemptId;
                     activeNativeTurnId = providerControl.ownedTurn.turnId;
                 }
-                assertAgentExecutionEnvironment(input.home, next);
+                // The Controller revalidates the adopted execution environment while
+                // redeeming this launch; a persistent Host must not reopen its schema.
                 // Pin before opening: the Session holds this exact generation for every
                 // later Turn. A pinned reference naming code this process is not running
                 // fails here, rather than silently starting on a different generation.
@@ -559,8 +597,7 @@ export async function runAgentHost(input) {
                     ? endpointLease.open(next) : endpointLease.resume(next));
                 session = started.session;
                 sessionPayload = next;
-                recordOwnedProviderProcess(input.home, next.environment, started.session);
-                recordNativeConnection(input.home, next, started.session);
+                await recordProviderConnection(input.home, next, started.session);
                 lastTerminalPayload = undefined;
                 lastTerminal = undefined;
                 // Recoverable means a later process can rebind this Conversation by
@@ -611,6 +648,7 @@ export async function runAgentHost(input) {
                 await publishStructuredProviderOpened({
                     home: input.home,
                     environment: next.environment,
+                    startupRunId: next.startupRunId,
                     conversationId: session.conversationId,
                     nativeSessionId: session.nativeSessionId,
                     recoverability: conversationRecoverability,
@@ -730,13 +768,25 @@ export async function runAgentHost(input) {
             attemptId: request.run.attemptId,
             ...authorityFields()
         }));
-        const durableRun = hostRunControlParams(sessionPayload, session.nativeSessionId, request.authority, request.run.attemptId, request.runId);
+        const durableRun = { ...hostRunControlParams(sessionPayload, session.nativeSessionId, request.authority, request.run.attemptId, request.runId), boundedText: request.run.boundedText,
+            retrySupport: session.adapterId === "codex" ? "codex-failed-turn-v1" : "unsupported" };
+        let recoveryInput;
         // Registration precedes the Provider write, so its failure modes are not
         // the Provider's. A definite failure means the Provider never saw this
         // input and the occupancy must be released; anything unconfirmed leaves
         // durable state ambiguous and keeps it held.
         try {
-            await beginDurableProviderTurn(input.home, durableRun);
+            const admitted = await beginDurableProviderTurn(input.home, durableRun);
+            if (admitted !== null && typeof admitted === "object" && !Array.isArray(admitted)) {
+                const retry = admitted.retryInput;
+                if (retry !== null && typeof retry === "object" && !Array.isArray(retry)
+                    && typeof retry.text === "string")
+                    recoveryInput = {
+                        text: retry.text,
+                        ...(typeof retry.expectedFailedNativeTurnId === "string"
+                            ? { expectedFailedNativeTurnId: retry.expectedFailedNativeTurnId } : {})
+                    };
+            }
         }
         catch (error) {
             // Registration ends in one of three states and they are not
@@ -790,10 +840,15 @@ export async function runAgentHost(input) {
         let providerAccepted = false;
         let transportAccepted = false;
         try {
-            assertAgentExecutionEnvironment(input.home, activeRunPayload);
+            // beginDurableProviderTurn validated current execution-environment,
+            // authority and Session identity before this native write.
             const receipt = endpointReceipt(await session.submit({
                 ...request.run,
-                boundedText: withSessionContextPointer(request.run.boundedText, activeRunPayload.environment),
+                boundedText: withSessionContextPointer(recoveryInput?.text ?? request.run.boundedText, activeRunPayload.environment),
+                ...(recoveryInput === undefined ? {} : { requireQuiescent: true }),
+                ...(recoveryInput?.expectedFailedNativeTurnId === undefined ? {} : {
+                    expectedFailedNativeTurnId: recoveryInput.expectedFailedNativeTurnId
+                }),
                 inputRef: request.runId ?? request.run.attemptId
             }), request.run.attemptId);
             transportAccepted = true;
@@ -906,7 +961,7 @@ export async function runAgentHost(input) {
             throw new Error("Agent Host rejected a stale Provider writer fence.");
         }
         try {
-            assertAgentExecutionEnvironment(input.home, sessionPayload);
+            await assertHostExecutionEnvironment(input.home, sessionPayload, session.nativeSessionId);
             const receipt = endpointReceipt(await session.steer({
                 ...request.run,
                 boundedText: withSessionContextPointer(request.run.boundedText, sessionPayload.environment),
@@ -972,6 +1027,9 @@ export async function runAgentHost(input) {
                 }));
         }
         if (request.type === "cancel") {
+            if (request.nativeOnly === true && session?.capabilities.cancel !== "native-interrupt") {
+                throw new Error("This Endpoint cannot natively interrupt; owned-process termination is not input control.");
+            }
             if (session === undefined || request.nativeSessionId !== session.nativeSessionId
                 || request.attemptId !== activeRunAttemptId
                 || authority === undefined || !sameProviderAuthorityFence(authority, request.authority)) {
@@ -1079,7 +1137,8 @@ export async function runAgentHost(input) {
         ? createInterface({ input: process.stdin, output: process.stdout, terminal: true })
         : undefined;
     promptHuman = () => {
-        if (humanConsole !== undefined && authority?.owner === "human"
+        if (humanConsole !== undefined && (authority?.owner === "human"
+            || sessionPayload?.environment.YUI_SESSION_SCOPE === "global" && authority?.owner === "controller")
             && activeRunPayload === undefined
             && ["idle", "rejected", "failed"].includes(snapshot.state)) {
             humanConsole.setPrompt("yui(provider)> ");
@@ -1091,7 +1150,8 @@ export async function runAgentHost(input) {
             const currentAuthority = authority;
             const currentSession = session;
             const currentPayload = sessionPayload;
-            if (currentAuthority?.owner !== "human"
+            if ((currentAuthority?.owner !== "human"
+                && !(currentPayload?.environment.YUI_SESSION_SCOPE === "global" && currentAuthority?.owner === "controller"))
                 || currentSession === undefined
                 || currentPayload === undefined) {
                 process.stderr.write("Provider input rejected: human authority is not active.\n");
@@ -1111,8 +1171,10 @@ export async function runAgentHost(input) {
                     boundedText
                 }
             };
-            await submitRun(runControl, {});
-            process.stdout.write("Provider accepted the human AgentRun; waiting for its terminal boundary.\n");
+            const submitted = await submitRun(runControl, {});
+            process.stdout.write(submitted.inputAcceptance === "provider"
+                ? "Provider accepted this console input; waiting for its terminal boundary.\n"
+                : "Input written to transport; Provider acceptance is not yet proven.\n");
         }).catch((error) => {
             process.stderr.write(`Provider input failed: ${errorText(error)}\n`);
             promptHuman();
@@ -1204,58 +1266,42 @@ export async function runAgentHost(input) {
     }
 }
 /** Host-restart-independent OS custody. No secret or launch payload is stored. */
-function recordOwnedProviderProcess(home, environment, endpoint) {
-    if (endpoint.ownedProcessId === undefined || environment.YUI_SESSION_SCOPE !== "task")
-        return;
-    const identity = readLinuxProcessIdentity(endpoint.ownedProcessId);
-    if (identity === undefined)
+async function recordProviderConnection(home, payload, endpoint) {
+    const environment = payload.environment;
+    const identity = endpoint.ownedProcessId === undefined ? undefined : readLinuxProcessIdentity(endpoint.ownedProcessId);
+    if (endpoint.ownedProcessId !== undefined && identity === undefined) {
         throw new Error("Dedicated Provider process identity was lost before registration.");
+    }
     const taskId = environment.YUI_TASK_ID;
     const roleName = environment.YUI_ROLE;
-    const store = openCurrentTaskStore(home);
-    try {
-        store.saveSessionOwner(createSessionOwnerIdentity({
-            owner: { scope: "task", taskId, roleName },
-            agentId: environment.YUI_AGENT_ID, adapterId: endpoint.adapterId,
-            nativeSessionId: endpoint.nativeSessionId,
-            tmux: {
-                serverName: yuiTmuxServerName(home),
-                socketPath: join(tmuxSocketDirectory(environment), yuiTmuxServerName(home)),
-                sessionName: yuiTmuxSessionName(home, taskId), windowName: roleName, panePid: process.pid
-            },
-            providerRoot: { pid: identity.pid, startIdentity: identity.startIdentity,
-                processGroupId: identity.processGroupId, processSessionId: identity.processSessionId,
-                attribution: "owned-child" },
-            recordedAt: new Date()
-        }));
-    }
-    finally {
-        store.close();
-    }
-}
-function recordNativeConnection(home, payload, endpoint) {
-    if (endpoint.adapterId !== "codex" || payload.environment.YUI_SESSION_SCOPE !== "task")
-        return;
-    const taskId = payload.environment.YUI_TASK_ID;
-    const store = openCurrentTaskStore(home);
-    try {
-        if (store.listEvents(taskId).some(event => event.type === "runtime.native-connection-bound"
-            && event.payload.nativeSessionId === endpoint.nativeSessionId))
-            return;
-        const userHome = resolve(payload.cwd, payload.environment.HOME ?? homedir());
-        store.saveEvent(taskId, createTaskEvent(store.nextEventId(taskId), taskId, "runtime.native-connection-bound", {
-            roleName: payload.environment.YUI_ROLE, agentId: payload.environment.YUI_AGENT_ID,
-            nativeSessionId: endpoint.nativeSessionId,
-            // Account location is needed after Controller/Host loss. Never retain
-            // resolved credentials or duplicate the full process environment.
-            home: userHome,
-            codexHome: resolve(payload.cwd, payload.environment.CODEX_HOME ?? join(userHome, ".codex")),
-            ...(endpoint.nativeAccountHome === undefined ? {} : { nativeAccountHome: endpoint.nativeAccountHome })
-        }, new Date()));
-    }
-    finally {
-        store.close();
-    }
+    const userHome = resolve(payload.cwd, environment.HOME ?? homedir());
+    await publishStructuredProviderConnection({
+        home, environment, nativeSessionId: endpoint.nativeSessionId, startupRunId: payload.startupRunId,
+        connection: {
+            ...(identity === undefined ? {} : { processOwner: createSessionOwnerIdentity({
+                    owner: environment.YUI_SESSION_SCOPE === "global"
+                        ? { scope: "global", roleName } : { scope: "task", taskId, roleName },
+                    agentId: environment.YUI_AGENT_ID, adapterId: endpoint.adapterId,
+                    nativeSessionId: endpoint.nativeSessionId,
+                    tmux: {
+                        serverName: yuiTmuxServerName(home),
+                        socketPath: join(tmuxSocketDirectory(environment), yuiTmuxServerName(home)),
+                        sessionName: yuiTmuxSessionName(home, taskId ?? "operator"), windowName: roleName, panePid: process.pid
+                    },
+                    providerRoot: { pid: identity.pid, startIdentity: identity.startIdentity,
+                        processGroupId: identity.processGroupId, processSessionId: identity.processSessionId,
+                        attribution: "owned-child" },
+                    recordedAt: new Date()
+                }) }),
+            ...(endpoint.adapterId !== "codex" ? {} : { account: {
+                    // Account location is needed after Controller/Host loss. Never retain
+                    // resolved credentials or duplicate the full process environment.
+                    home: userHome,
+                    codexHome: resolve(payload.cwd, environment.CODEX_HOME ?? join(userHome, ".codex")),
+                    ...(endpoint.nativeAccountHome === undefined ? {} : { nativeAccountHome: endpoint.nativeAccountHome })
+                } })
+        }
+    });
 }
 export function agentHostControlSocketPath(input) {
     const owner = input.scope === "task" ? input.taskId ?? "missing-task" : "global";
@@ -1329,13 +1375,22 @@ export async function waitForAgentHostLaunchAck(input) {
 }
 async function sendAgentHostControl(input) {
     const path = agentHostControlSocketPath(input);
+    return exchangeAgentHostControl(path, input.control, AGENT_HOST_CONTROL_TIMEOUT_MS);
+}
+/** Read-only upgrade/diagnostic probe of a Home-fenced socket. Never launches a Host. */
+export async function inspectAgentHostSocket(path, timeoutMs = 250) {
+    return (await exchangeAgentHostControl(path, {
+        protocol: AGENT_HOST_CONTROL_PROTOCOL, type: "status"
+    }, timeoutMs)).snapshot;
+}
+async function exchangeAgentHostControl(path, control, timeoutMs) {
     return await new Promise((resolvePromise, reject) => {
         const client = createConnection(path);
         let response = "";
         const timer = setTimeout(() => {
             client.destroy();
             reject(new Error("Agent Host control request timed out."));
-        }, AGENT_HOST_CONTROL_TIMEOUT_MS);
+        }, timeoutMs);
         let settled = false;
         const settle = (callback, value) => {
             if (settled)
@@ -1345,7 +1400,7 @@ async function sendAgentHostControl(input) {
             callback(value);
         };
         client.setEncoding("utf8");
-        client.once("connect", () => client.end(`${JSON.stringify(validateControl(input.control))}\n`));
+        client.once("connect", () => client.end(`${JSON.stringify(validateControl(control))}\n`));
         client.on("data", (chunk) => {
             response += chunk;
             if (Buffer.byteLength(response, "utf8") > HOST_CONTROL_MAX_BYTES) {
@@ -1370,6 +1425,17 @@ async function redeem(home, ticket) {
     });
     return validateAgentHostLaunchPayload(result);
 }
+async function assertHostExecutionEnvironment(home, payload, nativeSessionId) {
+    if (payload.executionEnvironment === undefined)
+        return;
+    await callController(home, "runtime.execution-environment-check", {
+        taskId: payload.environment.YUI_TASK_ID,
+        roleName: payload.environment.YUI_ROLE,
+        agentId: payload.environment.YUI_AGENT_ID,
+        workspace: payload.cwd,
+        nativeSessionId
+    });
+}
 async function persistAndSubmitExit(home, observation) {
     try {
         await persistRuntimeProcessExitObservation(home, observation, (value) => callController(home, "runtime.process-exit-observe", value).then(() => undefined));
@@ -1426,7 +1492,26 @@ export async function openAgentHostControl(home, payload, snapshot, dispatch) {
             void (async () => {
                 try {
                     const request = validateControl(JSON.parse(body.trim()));
-                    socket.end(`${JSON.stringify(boundControlResponse(await dispatch(request)))}\n`);
+                    const result = await dispatch(request);
+                    socket.end(`${JSON.stringify(boundControlResponse({
+                        ...result,
+                        snapshot: {
+                            ...result.snapshot,
+                            compatibility: {
+                                control: AGENT_HOST_CONTROL_PROTOCOL, events: AGENT_HOST_EVENT_PROTOCOL,
+                                rpc: FILE_TASK_CONTROLLER_PROTOCOL_VERSION, storage: "controller-owned"
+                            },
+                            hostProcess: { pid: process.pid, startIdentity: readLinuxProcessIdentity(process.pid).startIdentity },
+                            owner: {
+                                scope: payload.environment.YUI_SESSION_SCOPE ?? "task",
+                                ...(payload.environment.YUI_TASK_ID === undefined ? {} : { taskId: payload.environment.YUI_TASK_ID }),
+                                roleName: payload.environment.YUI_ROLE ?? "unknown-role"
+                            },
+                            ...(payload.environment.YUI_SESSION_SCOPE !== "task" ? {} : {
+                                eventDelivery: structuredProviderEventDelivery(home, payload.environment, result.snapshot.nativeSessionId)
+                            })
+                        }
+                    }))}\n`);
                 }
                 catch (caught) {
                     const error = caught instanceof AgentHostOperationError ? caught.cause : caught;
@@ -1565,6 +1650,9 @@ function validateControl(control) {
     if (control.type === "status")
         return Object.freeze({ ...control });
     if (control.type === "cancel") {
+        if (control.nativeOnly !== undefined && typeof control.nativeOnly !== "boolean") {
+            throw new Error("Native-only cancellation flag is invalid.");
+        }
         validateIdentity(control.nativeSessionId, "native Session id");
         validateIdentity(control.attemptId, "Provider input attempt id");
         validateProviderAuthorityFence(control.authority);
@@ -1746,9 +1834,11 @@ async function observePendingHostSubmission(submission, snapshot) {
 function signalRoleMailbox(home, payload) {
     const taskId = payload.environment.YUI_TASK_ID;
     const roleName = payload.environment.YUI_ROLE;
-    if (taskId === undefined || roleName === undefined)
+    if (roleName === undefined)
         return;
-    const key = `role:${encodeURIComponent(taskId)}/${encodeURIComponent(roleName)}`;
+    const key = taskId === undefined
+        ? `global-role:${encodeURIComponent(roleName)}`
+        : `role:${encodeURIComponent(taskId)}/${encodeURIComponent(roleName)}`;
     void callController(home, "scheduler.signal", { key }).catch(() => {
         // This is a low-latency hint. Durable mailbox state and periodic
         // reconciliation remain the recovery path across a Controller handover.
@@ -1763,7 +1853,9 @@ async function delay(milliseconds) {
 function hostRunControlParams(payload, nativeSessionId, authority, attemptId, runId) {
     const environment = payload.environment;
     return Object.freeze({
-        taskId: requiredEnvironment(environment.YUI_TASK_ID, "Task id"),
+        ...(environment.YUI_SESSION_SCOPE === "global" ? {} : {
+            taskId: requiredEnvironment(environment.YUI_TASK_ID, "Task id")
+        }),
         roleName: requiredEnvironment(environment.YUI_ROLE, "Role name"),
         ...(runId === undefined ? {} : { runId: requiredEnvironment(runId, "AgentRun id") }),
         agentId: requiredEnvironment(environment.YUI_AGENT_ID, "Agent id"),
@@ -1777,7 +1869,7 @@ function hostRunControlParams(payload, nativeSessionId, authority, attemptId, ru
 }
 async function beginDurableProviderTurn(home, durableRun) {
     try {
-        await callControllerIdempotently(home, "runtime.provider-turn-begin", durableRun);
+        return await callControllerIdempotently(home, "runtime.provider-turn-begin", durableRun);
     }
     catch (error) {
         if (error instanceof ControllerClientError && error.code === "SESSION_BUSY") {
@@ -1785,7 +1877,7 @@ async function beginDurableProviderTurn(home, durableRun) {
         }
         if (!(error instanceof ControllerAcknowledgementUnknownError))
             throw error;
-        await resolveProviderTurnSubmission(home, durableRun, new Error(`Provider Turn intent acknowledgement failed before Provider write: ${errorText(error)}`, { cause: error }));
+        await resolveProviderTurnSubmission(home, durableRun, new Error(`Provider Turn intent acknowledgement failed before Provider write: ${errorText(error)}`, { cause: error }), true);
         // The resolve is fenced on this exact attempt id, so its success proves
         // the registration did commit and is now settled with nothing written to
         // the Provider. That is a known outcome; reporting it as unknown would
@@ -1796,7 +1888,7 @@ async function beginDurableProviderTurn(home, durableRun) {
 }
 async function callControllerIdempotently(home, method, request) {
     try {
-        await callAgentController(home, method, request);
+        return await callAgentController(home, method, request);
     }
     catch (error) {
         if (!(error instanceof ControllerClientError)
@@ -1807,7 +1899,7 @@ async function callControllerIdempotently(home, method, request) {
         // 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);
+            return await callAgentController(home, method, request);
         }
         catch (replayError) {
             if (firstCallMayHaveApplied || controllerCallMayHaveApplied(replayError)) {
@@ -1828,7 +1920,7 @@ class ControllerAcknowledgementUnknownError extends Error {
 class ProviderTurnRegistrationSettledError extends Error {
     name = "ProviderTurnRegistrationSettledError";
 }
-async function resolveProviderTurnSubmission(home, durableRun, error) {
+async function resolveProviderTurnSubmission(home, durableRun, error, noProviderWrite = false) {
     const attemptId = durableRun.attemptId;
     if (typeof attemptId !== "string") {
         throw new Error("Provider Turn resolution has no attempt id.");
@@ -1840,6 +1932,7 @@ async function resolveProviderTurnSubmission(home, durableRun, error) {
             : error instanceof ProviderTurnBusyError ? "deferred" : "rejected",
         reason: errorText(error),
         raw: serializeAgentErrorRaw(error),
+        ...(noProviderWrite || error instanceof CodexPreSubmissionError ? { providerWrite: "not-issued" } : {}),
         observedAt: new Date().toISOString()
     };
     try {
@@ -1860,15 +1953,19 @@ async function resolveProviderTurnSubmission(home, durableRun, error) {
  */
 async function callAgentController(home, method, params) {
     try {
-        await callController(home, method, params);
-        return;
+        return await callController(home, method, params);
     }
     catch (error) {
         if (!isControllerUnavailable(error) || !isForeignHandoverLockHeld(home)) {
             throw error;
         }
     }
-    await callFileTaskController(home, method, params);
+    const deadline = Date.now() + AGENT_HOST_CONTROL_TIMEOUT_MS;
+    while (isForeignHandoverLockHeld(home) && Date.now() < deadline)
+        await delay(50);
+    // The pinned Host can rediscover a replacement, but must never start a
+    // Controller using its own old implementation or open the Home's database.
+    return await callController(home, method, params);
 }
 function isControllerUnavailable(error) {
     return error instanceof ControllerClientError

package/dist/runtime/agentHostCompatibility.js

@@ -0,0 +1,127 @@
+import { lstatSync, readdirSync, readFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { agentHostControlSocketPath, inspectAgentHostSocket } from "./agentHost.js";
+import { AGENT_HOST_CONTROL_PROTOCOL, AGENT_HOST_EVENT_PROTOCOL } from "./agentHostProtocol.js";
+import { FILE_TASK_CONTROLLER_PROTOCOL_VERSION } from "../core/protocol.js";
+import { readHomeFilesystemId } from "../core/homeFilesystemIdentity.js";
+import { readLinuxProcessIdentity } from "./sessionOwnerIdentity.js";
+/** Inspect the concrete Home's existing control sockets, independently of the
+ * database layout. No discovery write, process signal, input replay or repair.
+ * Idle legacy Hosts are not safe: their next event still opens their old schema.
+ */
+export async function inspectAgentHostCompatibility(home) {
+    const sample = agentHostControlSocketPath({ home, scope: "global", roleName: "compatibility-probe" });
+    const directory = dirname(sample);
+    const prefix = `${basename(sample).split("-")[0]}-`;
+    let names;
+    try {
+        names = readdirSync(directory).filter(name => name.startsWith(prefix) && /^[a-f0-9]{16}-[a-f0-9]{16}\.sock$/.test(name));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            names = [];
+        else
+            return [{ socket: directory, reason: `Host inventory is unreadable: ${messageOf(error)}` }];
+    }
+    // A launch can have redeemed its payload but not yet bound its socket.
+    // It is still a loaded Host implementation. Do not miss it just because
+    // preflight happened in that short startup interval.
+    const processes = liveHostProcesses(home);
+    const sockets = new Set([...names.map(name => join(directory, name)), ...processes.map(p => p.socket)]);
+    const results = await Promise.all([...sockets].map(async (socket) => {
+        const live = processes.filter(p => p.socket === socket);
+        try {
+            const stat = lstatSync(socket);
+            if (!stat.isSocket() || (stat.mode & 0o077) !== 0
+                || (process.getuid !== undefined && stat.uid !== process.getuid())) {
+                return { socket, reason: "Host socket ownership cannot be verified." };
+            }
+            const snapshot = await inspectAgentHostSocket(socket);
+            if (live.some(p => snapshot.hostProcess?.pid !== p.pid
+                || snapshot.hostProcess?.startIdentity !== p.startIdentity)) {
+                return {
+                    socket, pid: live[0].pid,
+                    nativeSessionId: snapshot.nativeSessionId,
+                    reason: "The live Host process has no exact matching compatibility response (legacy or still starting)."
+                };
+            }
+            const compatibility = snapshot.compatibility;
+            if (compatibility?.control === AGENT_HOST_CONTROL_PROTOCOL
+                && compatibility.events === AGENT_HOST_EVENT_PROTOCOL
+                && compatibility.rpc === FILE_TASK_CONTROLLER_PROTOCOL_VERSION
+                && compatibility.storage === "controller-owned")
+                return undefined;
+            return {
+                socket,
+                ...(snapshot.owner === undefined ? {} : { owner: snapshot.owner }),
+                ...(snapshot.nativeSessionId === undefined ? {} : { nativeSessionId: snapshot.nativeSessionId }),
+                ...(snapshot.attemptId === undefined ? {} : { attemptId: snapshot.attemptId }),
+                state: snapshot.state,
+                reason: compatibility === undefined
+                    ? "Legacy Host has no schema-independent event capability; its loaded code cannot be upgraded in place."
+                    : "Host control/event/RPC compatibility is outside this Controller's supported range."
+            };
+        }
+        catch (error) {
+            const stillLive = live.find(p => readLinuxProcessIdentity(p.pid)?.startIdentity === p.startIdentity);
+            if (["ENOENT", "ECONNREFUSED"].includes(error.code ?? "")
+                && stillLive === undefined)
+                return undefined;
+            return { socket, ...(stillLive === undefined ? {} : { pid: stillLive.pid }),
+                reason: `Live Host compatibility is unconfirmed: ${messageOf(error)}` };
+        }
+    }));
+    return results.filter((entry) => entry !== undefined);
+}
+export function describeAgentHostUpgradeBlockers(blockers) {
+    return blockers.map(blocker => [
+        blocker.owner === undefined ? blocker.socket
+            : `${blocker.owner.taskId ?? blocker.owner.scope}/${blocker.owner.roleName}`,
+        blocker.nativeSessionId === undefined ? "" : `Session=${blocker.nativeSessionId}`,
+        blocker.attemptId === undefined ? "" : `input=${blocker.attemptId}`,
+        blocker.state === undefined ? "" : `Host=${blocker.state}`,
+        blocker.pid === undefined ? "" : `PID=${blocker.pid}`,
+        blocker.reason
+    ].filter(Boolean).join("; ")).join("\n");
+}
+function liveHostProcesses(home) {
+    if (process.platform !== "linux")
+        return [];
+    const expected = readHomeFilesystemId(home);
+    const hosts = [];
+    for (const name of readdirSync("/proc")) {
+        if (!/^[1-9][0-9]*$/.test(name))
+            continue;
+        const pid = Number(name);
+        try {
+            const status = readFileSync(`/proc/${pid}/status`, "utf8");
+            if (Number(/^Uid:\s+([0-9]+)/mu.exec(status)?.[1]) !== process.getuid?.())
+                continue;
+            const args = readFileSync(`/proc/${pid}/cmdline`, "utf8").split("\0");
+            if (!args.some((arg, i) => /(?:^|\/)cli\.js$/.test(arg)
+                && args[i + 1] === "internal" && args[i + 2] === "agent-host"))
+                continue;
+            const env = readFileSync(`/proc/${pid}/environ`, "utf8").split("\0");
+            const value = (key) => env.find(entry => entry.startsWith(`${key}=`))?.slice(key.length + 1);
+            const processHome = value("YUI_HOME");
+            if (processHome === undefined || readHomeFilesystemId(processHome) !== expected)
+                continue;
+            const identity = readLinuxProcessIdentity(pid);
+            if (identity === undefined || identity.state === "Z")
+                continue;
+            hosts.push({ pid, startIdentity: identity.startIdentity,
+                socket: agentHostControlSocketPath({
+                    home, scope: value("YUI_SESSION_SCOPE") ?? "task",
+                    taskId: value("YUI_TASK_ID"), roleName: value("YUI_ROLE") ?? "unknown-role"
+                }) });
+        }
+        catch {
+            // Other owners and processes that exited while being read are not this
+            // Home's proven Hosts. No PID is ever acted on by this read-only inventory.
+        }
+    }
+    return hosts;
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}