@zq-silk/yui 0.15.8 → 0.15.11

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";
@@ -21,15 +19,48 @@ import { AGENT_HOST_CLIENT_EXIT_GRACE_MS, AGENT_HOST_CONTROL_TIMEOUT_MS, AGENT_H
 import { providerDeliveryFailure, providerDeliveryFailureFrom, redactAgentErrorText, serializeAgentErrorRaw } from "./agentError.js";
 import { runCodexInteractiveHost } from "./codexInteractiveHost.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 +68,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 +340,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 +585,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 +596,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 +647,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,
@@ -790,7 +827,8 @@ 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),
@@ -906,7 +944,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 +1010,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 +1120,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 +1133,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 +1154,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 +1249,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 +1358,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 +1383,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 +1408,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 +1475,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 +1633,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 +1817,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 +1836,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"),
@@ -1868,7 +1943,12 @@ async function callAgentController(home, method, params) {
             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.
+    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);
+}

package/dist/runtime/agentHostProtocol.js

@@ -0,0 +1,53 @@
+import { createSessionOwnerIdentity } from "./sessionOwnerIdentity.js";
+/** Independent of CLI/RPC and Home schema. Keep v1 readable while v1 Hosts live. */
+export const AGENT_HOST_EVENT_PROTOCOL = "yui-agent-host-events/v1";
+export const AGENT_HOST_CONTROL_PROTOCOL = "yui-agent-host/v5";
+export function readAgentHostObservationSource(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("Agent Host observation source is invalid.");
+    }
+    const source = value;
+    if (source.protocol !== AGENT_HOST_EVENT_PROTOCOL) {
+        throw new Error("Agent Host event protocol is unsupported.");
+    }
+    if (source.connection !== undefined && (source.connection === null
+        || typeof source.connection !== "object" || Array.isArray(source.connection))) {
+        throw new Error("Agent Host connection evidence is invalid.");
+    }
+    if (source.connection?.processOwner !== undefined
+        && (source.connection.processOwner.schemaVersion !== 2
+            || source.connection.processOwner.kind !== "yui-session-owner")) {
+        throw new Error("Agent Host process custody wire contract is invalid.");
+    }
+    const text = (value) => {
+        if (typeof value !== "string" || !value.trim() || value.includes("\0") || value.length > 4096) {
+            throw new Error("Agent Host observation identity is invalid.");
+        }
+        return value;
+    };
+    return {
+        protocol: AGENT_HOST_EVENT_PROTOCOL,
+        adapterId: text(source.adapterId),
+        workspace: text(source.workspace),
+        ...(source.startupRunId === undefined ? {} : { startupRunId: text(source.startupRunId) }),
+        ...(source.connection === undefined ? {} : {
+            connection: {
+                ...(source.connection.processOwner === undefined ? {} : {
+                    processOwner: createSessionOwnerIdentity({
+                        ...source.connection.processOwner,
+                        recordedAt: new Date(source.connection.processOwner.recordedAt)
+                    })
+                }),
+                ...(source.connection.account === undefined ? {} : {
+                    account: {
+                        home: text(source.connection.account.home),
+                        codexHome: text(source.connection.account.codexHome),
+                        ...(source.connection.account.nativeAccountHome === undefined ? {} : {
+                            nativeAccountHome: text(source.connection.account.nativeAccountHome)
+                        })
+                    }
+                })
+            }
+        })
+    };
+}

package/dist/runtime/executionEnvironment.js

@@ -1,5 +1,4 @@
 import { isDeepStrictEqual } from "node:util";
-import { openCurrentTaskStore } from "../storage/currentTaskStore.js";
 import { createProjectResources } from "../resources/projectResourceService.js";
 /** Revalidate the adopted owner; a saved path alone never authorizes execution. */
 export function assertExecutionEnvironmentCurrent(store, taskId, snapshot) {
@@ -10,21 +9,3 @@ export function assertExecutionEnvironmentCurrent(store, taskId, snapshot) {
         throw new Error("Execution environment changed; select an adopted environment and start a new Session.");
     }
 }
-/** Last local check before native process creation or another Provider input. */
-export function assertAgentExecutionEnvironment(home, payload) {
-    const snapshot = payload.executionEnvironment;
-    if (snapshot === undefined)
-        return;
-    if (payload.environment.YUI_SESSION_SCOPE !== "task"
-        || payload.environment.YUI_TASK_ID !== snapshot.taskId
-        || payload.cwd !== snapshot.directory.path) {
-        throw new Error("Agent launch does not match its adopted execution environment.");
-    }
-    const store = openCurrentTaskStore(home);
-    try {
-        assertExecutionEnvironmentCurrent(store, snapshot.taskId, snapshot);
-    }
-    finally {
-        store.close();
-    }
-}

package/dist/runtime/launchBroker.js

@@ -60,6 +60,12 @@ function validatePayload(payload) {
         throw new Error("Agent Host launch payload version is invalid.");
     text(payload.command, "command");
     text(payload.cwd, "cwd");
+    if (payload.startupRunId !== undefined) {
+        text(payload.startupRunId, "startup Run id");
+        if (payload.environment?.YUI_SESSION_SCOPE !== "task") {
+            throw new Error("Only a Task launch may carry a startup Run identity.");
+        }
+    }
     if (!Array.isArray(payload.args))
         throw new Error("Agent Host launch args must be an array.");
     payload.args.forEach((value) => text(value, "argument"));

package/dist/runtime/sessionReconciliation.js

@@ -8,8 +8,8 @@
  * live Session can always be re-attributed and reported.
  *
  * Pure: all I/O is injected. Unknown owners are reported, never cleaned.
- * An entry is archive-blocking when its durable state is terminal but the
- * physical Provider root is still live, and the Task is terminal/archived.
+ * An entry blocks ordinary archive / workspace cleanup when a terminal Task
+ * still owns a live or unverified physical root, regardless of Session status.
  */
 export function reconcileSessionOwners(input) {
     const entries = input.records.map((record) => reconcileOne(record, input));
@@ -54,8 +54,8 @@ function reconcileOne(record, input) {
     const terminalTask = taskStatus === "completed"
         || taskStatus === "cancelled"
         || taskStatus === "archived";
-    const archiveBlocked = mismatch === "durable-terminal-physical-live"
-        && terminalTask;
+    const archiveBlocked = terminalTask && (physical === undefined
+        || physical.alive || physical.identityConflict);
     return {
         owner: {
             scope: owner.scope,