@zq-silk/yui 0.8.1 → 0.8.2

package/dist/runtime/agentHost.js

@@ -1,16 +1,22 @@
-import { spawn } from "node:child_process";
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { appendFileSync, chmodSync, closeSync, fsyncSync, mkdirSync, openSync, rmSync } from "node:fs";
 import { readdir, readFile, rename, unlink } from "node:fs/promises";
-import { join, resolve } from "node:path";
-import { createServer, createConnection } from "node:net";
-import { callController } from "../core/controllerClient.js";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { createConnection, createServer } from "node:net";
+import { createInterface } from "node:readline";
+import { callController, ControllerClientError } from "../core/controllerClient.js";
+import { readHomeFilesystemId } from "../core/homeFilesystemIdentity.js";
+import { publishStructuredProviderAccepted, publishStructuredProviderActivationTerminal, publishStructuredConversationRecoverability, publishStructuredProviderOpened, publishStructuredProviderTerminal } from "../controller/structuredProviderObservation.js";
 import { validateAgentHostLaunchPayload } from "./launchBroker.js";
+import { ProviderDeliveryUnknownError, ProviderConversationMissingError, ProviderTurnRejectedError, startStructuredProviderSession } from "./structuredProviderHost.js";
+import { sameProviderAuthorityFence, validateProviderAuthorityFence } from "./providerAuthorityFence.js";
 import { validateRuntimeProcessExitObservation } from "./processExitObservation.js";
 import { readRuntimeStopReceipt, removeRuntimeStopReceipt } from "./runtimeStopReceipt.js";
-export const AGENT_HOST_CONTROL_PROTOCOL = "yui-agent-host/v1";
-const HOST_CONTROL_TIMEOUT_MS = 5_000;
-const HOST_CONTROL_MAX_BYTES = 8 * 1024;
+export const AGENT_HOST_CONTROL_PROTOCOL = "yui-agent-host/v2";
+const HOST_CONTROL_TIMEOUT_MS = 35_000;
+const HOST_READY_TIMEOUT_MS = 35_000;
+const HOST_CONTROL_MAX_BYTES = 32 * 1024;
 export function serializeAgentHostLaunchControl(control) {
     return JSON.stringify(validateControl(control));
 }
@@ -18,65 +24,609 @@ export async function runAgentHost(input) {
     const hostInstanceId = randomUUID();
     let hostSequence = 0;
     let payload = await redeem(input.home, input.launchId, input.ticket);
+    let session;
+    let sessionPayload;
+    let activeTurnPayload;
+    let activationId;
+    let conversationRecoverability = "unknown";
+    let authority;
+    let hostStopRequested = false;
+    let snapshot = hostSnapshot("idle");
+    let dispatchTail = Promise.resolve();
+    let promptHuman = () => { };
     await replayExitOutbox(input.home);
-    const control = await openHostControl(input.home, payload);
-    try {
-        for (;;) {
-            while (payload.startMode === "idle") {
-                const next = await control.next();
-                payload = await redeem(input.home, next.launchId, next.ticket);
+    const updateSnapshot = (next) => {
+        snapshot = validateSnapshot(next);
+    };
+    const authorityFields = () => authority === undefined ? {} : {
+        authorityEpoch: authority.epoch,
+        authorityOwner: authority.owner,
+        authorityHolderId: authority.holderId
+    };
+    const handleTerminal = (terminal) => {
+        const terminalPayload = activeTurnPayload;
+        if (terminalPayload === undefined)
+            return;
+        const terminalActivationId = activationId ?? terminalPayload.launchId;
+        void enqueueSerialized(async () => {
+            if (activeTurnPayload !== terminalPayload)
+                return;
+            if (session !== undefined) {
+                updateSnapshot(hostSnapshot("settling", {
+                    launchId: terminalPayload.launchId,
+                    adapterId: terminalPayload.providerControl.adapterId,
+                    processInstanceId: session.processInstanceId,
+                    nativeSessionId: terminal.nativeSessionId,
+                    conversationId: terminal.conversationId,
+                    nativeTurnId: terminal.nativeTurnId,
+                    ...authorityFields()
+                }));
+            }
+            try {
+                await publishStructuredProviderTerminal({
+                    home: input.home,
+                    environment: terminalPayload.environment,
+                    activationId: terminalActivationId,
+                    terminal
+                });
+                if (activeTurnPayload !== terminalPayload)
+                    return;
+                activeTurnPayload = undefined;
+                if (session === undefined)
+                    return;
+                const currentPayload = sessionPayload ?? terminalPayload;
+                updateSnapshot(hostSnapshot("idle", {
+                    launchId: currentPayload.launchId,
+                    adapterId: currentPayload.providerControl.adapterId,
+                    processInstanceId: session.processInstanceId,
+                    nativeSessionId: terminal.nativeSessionId,
+                    conversationId: terminal.conversationId,
+                    ...authorityFields()
+                }));
+                promptHuman();
+            }
+            catch (error) {
+                updateSnapshot(hostSnapshot("failed", {
+                    launchId: terminalPayload.launchId,
+                    adapterId: terminalPayload.providerControl.adapterId,
+                    processInstanceId: session?.processInstanceId,
+                    nativeSessionId: terminal.nativeSessionId,
+                    conversationId: terminal.conversationId,
+                    nativeTurnId: terminal.nativeTurnId,
+                    ...authorityFields(),
+                    detail: errorText(error)
+                }));
+            }
+        }).catch(() => { });
+    };
+    const observeExit = (providerSession, launched) => {
+        void providerSession.waitForExit().then((result) => enqueueSerialized(async () => {
+            const ownsCurrentSession = session === providerSession;
+            const currentPayload = ownsCurrentSession ? sessionPayload ?? launched : launched;
+            const currentActivationId = ownsCurrentSession
+                ? activationId ?? launched.launchId
+                : launched.launchId;
+            const exitAuthority = authorityFields();
+            if (ownsCurrentSession) {
+                session = undefined;
+                activationId = undefined;
+                conversationRecoverability = "unknown";
+                authority = undefined;
             }
-            control.setActive(true, payload.launchId);
-            const result = await runAgentHostProviderChild(payload);
-            control.setActive(false);
             hostSequence += 1;
-            const stopReceipt = readRuntimeStopReceipt(input.home, payload.launchId);
-            await persistAndSubmitExit(input.home, validateRuntimeProcessExitObservation({
-                schemaVersion: 1,
-                observationId: `${hostInstanceId}-${hostSequence}`,
-                hostSequence,
-                hostInstanceId,
-                providerProcessInstanceId: result.processInstanceId,
-                ...(payload.environment.YUI_TASK_ID === undefined
-                    ? {}
-                    : { taskId: payload.environment.YUI_TASK_ID }),
-                roleName: payload.environment.YUI_ROLE ?? "unknown-role",
-                ...(payload.environment.YUI_RUN_ID === undefined
-                    ? {}
-                    : { runId: payload.environment.YUI_RUN_ID }),
-                launchId: payload.launchId,
-                ...(payload.environment.YUI_NATIVE_SESSION_ID === undefined
-                    ? {}
-                    : { nativeSessionId: payload.environment.YUI_NATIVE_SESSION_ID }),
-                processKind: "provider-child",
-                ...(result.code === null ? {} : { exitCode: result.code }),
-                ...(result.signal === null ? {} : { signal: result.signal }),
-                ...(stopReceipt === null ? {} : { stopReceiptId: stopReceipt.receiptId }),
+            const stopReceipt = readRuntimeStopReceipt(input.home, currentPayload.launchId);
+            const observedAt = new Date().toISOString();
+            const failures = [];
+            try {
+                await publishStructuredProviderActivationTerminal({
+                    home: input.home,
+                    environment: currentPayload.environment,
+                    conversationId: providerSession.conversationId,
+                    nativeSessionId: providerSession.nativeSessionId,
+                    activationId: currentActivationId,
+                    status: stopReceipt !== null || hostStopRequested ? "ended" : "failed",
+                    observedAt
+                });
+            }
+            catch (error) {
+                failures.push(`activation terminal: ${errorText(error)}`);
+            }
+            let exitPersisted = false;
+            try {
+                await persistAndSubmitExit(input.home, validateRuntimeProcessExitObservation({
+                    schemaVersion: 1,
+                    observationId: `${hostInstanceId}-${hostSequence}`,
+                    hostSequence,
+                    hostInstanceId,
+                    providerProcessInstanceId: result.processInstanceId,
+                    ...(currentPayload.environment.YUI_TASK_ID === undefined
+                        ? {}
+                        : { taskId: currentPayload.environment.YUI_TASK_ID }),
+                    roleName: currentPayload.environment.YUI_ROLE ?? "unknown-role",
+                    ...(currentPayload.environment.YUI_RUN_ID === undefined
+                        ? {}
+                        : { runId: currentPayload.environment.YUI_RUN_ID }),
+                    launchId: currentPayload.launchId,
+                    ...(providerSession.nativeSessionId.length === 0
+                        ? {}
+                        : { nativeSessionId: providerSession.nativeSessionId }),
+                    processKind: "provider-child",
+                    ...(result.code === null ? {} : { exitCode: result.code }),
+                    ...(result.signal === null ? {} : { signal: result.signal }),
+                    ...(stopReceipt === null ? {} : { stopReceiptId: stopReceipt.receiptId }),
+                    observedAt
+                }));
+                exitPersisted = true;
+            }
+            catch (error) {
+                failures.push(`process exit: ${errorText(error)}`);
+            }
+            if (stopReceipt !== null && exitPersisted) {
+                removeRuntimeStopReceipt(input.home, currentPayload.launchId);
+            }
+            if (hostStopRequested)
+                return;
+            updateSnapshot(hostSnapshot(failures.length === 0 ? "exited" : "failed", {
+                launchId: currentPayload.launchId,
+                adapterId: currentPayload.providerControl?.adapterId,
+                processInstanceId: result.processInstanceId,
+                nativeSessionId: providerSession.nativeSessionId,
+                conversationId: providerSession.conversationId,
+                ...exitAuthority,
+                ...(failures.length !== 0
+                    ? { detail: failures.join("; ") }
+                    : activeTurnPayload === undefined
+                        ? {}
+                        : { detail: "Provider process exited before the active Turn reached a terminal boundary." })
+            }));
+        })).catch((error) => updateSnapshot(hostSnapshot("failed", {
+            launchId: launched.launchId,
+            adapterId: launched.providerControl?.adapterId,
+            processInstanceId: providerSession.processInstanceId,
+            ...authorityFields(),
+            detail: errorText(error)
+        })));
+    };
+    const dispatch = async (next) => {
+        const providerControl = next.providerControl;
+        if (providerControl === undefined) {
+            throw new Error("Agent Host accepts only managed Provider control launches.");
+        }
+        if (activeTurnPayload !== undefined
+            || ["starting", "ready", "settling", "delivery-unknown"].includes(snapshot.state)) {
+            throw new Error("Agent Host still owns an unsettled Provider Turn.");
+        }
+        const requestedAuthority = validateProviderAuthorityFence(providerControl.authority);
+        if (authority === undefined)
+            authority = requestedAuthority;
+        else if (!sameProviderAuthorityFence(authority, requestedAuthority)) {
+            throw new Error("Agent Host launch carries a stale Provider authority fence.");
+        }
+        updateSnapshot(hostSnapshot("starting", {
+            launchId: next.launchId,
+            adapterId: providerControl.adapterId,
+            ...(providerControl.initialTurn === undefined
+                ? {}
+                : { attemptId: providerControl.initialTurn.attemptId }),
+            ...(session === undefined ? {} : {
+                processInstanceId: session.processInstanceId,
+                nativeSessionId: session.nativeSessionId,
+                conversationId: session.conversationId
+            }),
+            ...authorityFields()
+        }));
+        let providerAcceptedAttemptId;
+        let durableInitialTurn;
+        try {
+            if (session !== undefined) {
+                if (session.adapterId !== providerControl.adapterId
+                    || providerControl.mode !== "resume"
+                    || providerControl.nativeSessionId !== session.nativeSessionId) {
+                    throw new Error("Agent Host launch does not match its live Provider Conversation.");
+                }
+                sessionPayload = next;
+            }
+            else {
+                activationId = next.launchId;
+                conversationRecoverability = providerControl.adapterId === "codex"
+                    ? "recoverable"
+                    : "unknown";
+                const started = await startStructuredProviderSession(next, { onTerminal: handleTerminal });
+                session = started.session;
+                sessionPayload = next;
+                observeExit(started.session, next);
+            }
+            await publishStructuredProviderOpened({
+                home: input.home,
+                environment: next.environment,
+                conversationId: session.conversationId,
+                nativeSessionId: session.nativeSessionId,
+                activationId: activationId ?? next.launchId,
+                recoverability: conversationRecoverability,
                 observedAt: new Date().toISOString()
+            });
+            let receipt;
+            if (providerControl.initialTurn !== undefined) {
+                durableInitialTurn = hostTurnControlParams(next, session.nativeSessionId, requestedAuthority, providerControl.initialTurn.attemptId);
+                await beginDurableProviderTurn(input.home, durableInitialTurn);
+                activeTurnPayload = next;
+                try {
+                    receipt = await session.submitTurn(providerControl.initialTurn);
+                    providerAcceptedAttemptId = receipt.attemptId;
+                }
+                catch (error) {
+                    await resolveProviderTurnSubmission(input.home, durableInitialTurn, error);
+                    throw error;
+                }
+            }
+            if (receipt !== undefined) {
+                conversationRecoverability = "recoverable";
+                try {
+                    await publishStructuredProviderAccepted({
+                        home: input.home,
+                        environment: next.environment,
+                        activationId: activationId ?? next.launchId,
+                        receipt
+                    });
+                }
+                catch (error) {
+                    await resolveProviderTurnSubmission(input.home, durableInitialTurn, new ProviderDeliveryUnknownError(`Provider accepted input but its durable acknowledgement could not be confirmed: ${errorText(error)}`, receipt.attemptId));
+                    throw error;
+                }
+            }
+            updateSnapshot(hostSnapshot(receipt === undefined ? "idle" : "ready", {
+                launchId: next.launchId,
+                adapterId: providerControl.adapterId,
+                processInstanceId: session.processInstanceId,
+                nativeSessionId: receipt?.nativeSessionId ?? session.nativeSessionId,
+                conversationId: receipt?.conversationId ?? session.conversationId,
+                ...(receipt === undefined ? {} : {
+                    attemptId: receipt.attemptId,
+                    nativeTurnId: receipt.nativeTurnId
+                }),
+                ...authorityFields()
+            }));
+            return snapshot;
+        }
+        catch (error) {
+            if (error instanceof ProviderConversationMissingError) {
+                await publishStructuredConversationRecoverability({
+                    home: input.home,
+                    environment: next.environment,
+                    conversationId: error.conversationId,
+                    activationId: activationId ?? next.launchId,
+                    recoverability: "unrecoverable",
+                    observedAt: new Date().toISOString()
+                }).catch(() => { });
+            }
+            if (session === undefined) {
+                activationId = undefined;
+                conversationRecoverability = "unknown";
+                authority = undefined;
+            }
+            const deliveryUnknown = error instanceof ProviderDeliveryUnknownError
+                || providerAcceptedAttemptId !== undefined;
+            const state = deliveryUnknown
+                ? "delivery-unknown"
+                : error instanceof ProviderTurnRejectedError ? "rejected" : "failed";
+            updateSnapshot(hostSnapshot(state, {
+                launchId: next.launchId,
+                adapterId: providerControl.adapterId,
+                processInstanceId: session?.processInstanceId,
+                nativeSessionId: session?.nativeSessionId ?? providerControl.nativeSessionId,
+                conversationId: session?.conversationId ?? providerControl.nativeSessionId,
+                ...(providerControl.initialTurn === undefined
+                    ? {}
+                    : { attemptId: providerControl.initialTurn.attemptId }),
+                ...authorityFields(),
+                detail: errorText(error)
+            }));
+            if (state !== "delivery-unknown")
+                activeTurnPayload = undefined;
+            if (deliveryUnknown && !(error instanceof ProviderDeliveryUnknownError)) {
+                throw new ProviderDeliveryUnknownError(`Provider accepted input but its durable acknowledgement could not be confirmed: ${errorText(error)}`, providerAcceptedAttemptId);
+            }
+            throw error;
+        }
+    };
+    const enqueueSerialized = (action) => {
+        const operation = dispatchTail.then(action);
+        dispatchTail = operation.then(() => undefined, () => undefined);
+        return operation;
+    };
+    const enqueueDispatch = (next) => (enqueueSerialized(() => dispatch(next)));
+    const submitTurn = async (request) => {
+        if (session === undefined || sessionPayload === undefined) {
+            throw new Error("Agent Host has no live Provider Conversation.");
+        }
+        if (request.nativeSessionId !== session.nativeSessionId) {
+            throw new Error("Agent Host Turn targets a different Provider Conversation.");
+        }
+        if (authority === undefined
+            || !sameProviderAuthorityFence(authority, request.authority)) {
+            throw new Error("Agent Host rejected a stale Provider writer fence.");
+        }
+        if (activeTurnPayload !== undefined || snapshot.state === "settling") {
+            throw new Error("Agent Host still owns an unsettled Provider Turn.");
+        }
+        activeTurnPayload = sessionPayload;
+        updateSnapshot(hostSnapshot("starting", {
+            launchId: request.launchId,
+            adapterId: session.adapterId,
+            processInstanceId: session.processInstanceId,
+            nativeSessionId: session.nativeSessionId,
+            conversationId: session.conversationId,
+            attemptId: request.turn.attemptId,
+            ...authorityFields()
+        }));
+        let providerAccepted = false;
+        try {
+            const receipt = await session.submitTurn(request.turn);
+            providerAccepted = true;
+            await publishStructuredProviderAccepted({
+                home: input.home,
+                environment: sessionPayload.environment,
+                activationId: activationId ?? sessionPayload.launchId,
+                receipt
+            });
+            updateSnapshot(hostSnapshot("ready", {
+                launchId: request.launchId,
+                adapterId: session.adapterId,
+                processInstanceId: session.processInstanceId,
+                nativeSessionId: receipt.nativeSessionId,
+                conversationId: receipt.conversationId,
+                attemptId: receipt.attemptId,
+                nativeTurnId: receipt.nativeTurnId,
+                ...authorityFields()
             }));
-            if (stopReceipt !== null)
-                removeRuntimeStopReceipt(input.home, payload.launchId);
-            if (result.hostStopRequested)
-                return 0;
-            // The Agent Host is the durable pane owner. Provider-child exit only
-            // moves it to idle; an exact resume launch may arrive over the private
-            // control socket without replacing the Host or native conversation.
-            const next = await control.next();
-            payload = await redeem(input.home, next.launchId, next.ticket);
+            return snapshot;
+        }
+        catch (error) {
+            const deliveryUnknown = error instanceof ProviderDeliveryUnknownError || providerAccepted;
+            const state = deliveryUnknown
+                ? "delivery-unknown"
+                : error instanceof ProviderTurnRejectedError ? "rejected" : "failed";
+            updateSnapshot(hostSnapshot(state, {
+                launchId: request.launchId,
+                adapterId: session.adapterId,
+                processInstanceId: session.processInstanceId,
+                nativeSessionId: session.nativeSessionId,
+                conversationId: session.conversationId,
+                attemptId: request.turn.attemptId,
+                ...authorityFields(),
+                detail: errorText(error)
+            }));
+            if (state !== "delivery-unknown")
+                activeTurnPayload = undefined;
+            if (deliveryUnknown && !(error instanceof ProviderDeliveryUnknownError)) {
+                throw new ProviderDeliveryUnknownError(`Provider accepted input but its durable acknowledgement could not be confirmed: ${errorText(error)}`, request.turn.attemptId);
+            }
+            throw error;
+        }
+    };
+    const setAuthority = (request) => {
+        if (session === undefined || request.nativeSessionId !== session.nativeSessionId) {
+            throw new Error("Agent Host authority targets a different Provider Conversation.");
+        }
+        if (activeTurnPayload !== undefined
+            || ["starting", "ready", "settling", "delivery-unknown"].includes(snapshot.state)) {
+            throw new Error("Agent Host authority cannot transfer while a Turn is unsettled.");
+        }
+        const next = validateProviderAuthorityFence(request.authority);
+        if (authority !== undefined) {
+            if (sameProviderAuthorityFence(authority, next))
+                return snapshot;
+            if (next.epoch <= authority.epoch) {
+                throw new Error("Agent Host authority epoch did not advance monotonically.");
+            }
+        }
+        authority = next;
+        updateSnapshot(hostSnapshot("idle", {
+            launchId: sessionPayload?.launchId ?? snapshot.launchId,
+            adapterId: session.adapterId,
+            processInstanceId: session.processInstanceId,
+            nativeSessionId: session.nativeSessionId,
+            conversationId: session.conversationId,
+            ...authorityFields()
+        }));
+        promptHuman();
+        return snapshot;
+    };
+    const control = await openAgentHostControl(input.home, payload, () => snapshot, async (request) => {
+        if (request.type === "status") {
+            return controlResult("status", snapshot);
+        }
+        if (request.type === "submit-turn") {
+            const accepted = await enqueueSerialized(() => submitTurn(request));
+            return controlResult("accepted", accepted);
         }
+        if (request.type === "set-authority") {
+            const accepted = await enqueueSerialized(async () => setAuthority(request));
+            return controlResult("accepted", accepted);
+        }
+        if (snapshot.launchId === request.launchId
+            && ["starting", "ready", "settling", "delivery-unknown"].includes(snapshot.state)) {
+            return controlResult("active-same-launch", snapshot);
+        }
+        const redeemed = await redeem(input.home, request.launchId, request.ticket);
+        if (activeTurnPayload !== undefined
+            || ["starting", "ready", "settling", "delivery-unknown"].includes(snapshot.state)) {
+            return controlResult("active-other-launch", snapshot);
+        }
+        const accepted = await enqueueDispatch(redeemed);
+        return controlResult("accepted", accepted);
+    });
+    const humanConsole = process.stdin.isTTY
+        ? createInterface({ input: process.stdin, output: process.stdout, terminal: true })
+        : undefined;
+    promptHuman = () => {
+        if (humanConsole !== undefined && authority?.owner === "human"
+            && activeTurnPayload === undefined
+            && ["idle", "rejected", "failed"].includes(snapshot.state)) {
+            humanConsole.setPrompt("yui(provider)> ");
+            humanConsole.prompt();
+        }
+    };
+    humanConsole?.on("line", (line) => {
+        void enqueueSerialized(async () => {
+            const currentAuthority = authority;
+            const currentSession = session;
+            const currentPayload = sessionPayload;
+            if (currentAuthority?.owner !== "human"
+                || currentSession === undefined
+                || currentPayload === undefined) {
+                process.stderr.write("Provider input rejected: human authority is not active.\n");
+                return;
+            }
+            const boundedText = line.trim();
+            if (boundedText.length === 0)
+                return;
+            const attemptId = `human:${currentAuthority.holderId}:${randomUUID()}`;
+            const turnControl = {
+                protocol: AGENT_HOST_CONTROL_PROTOCOL,
+                type: "submit-turn",
+                launchId: currentPayload.launchId,
+                nativeSessionId: currentSession.nativeSessionId,
+                authority: currentAuthority,
+                turn: {
+                    attemptId,
+                    boundedText
+                }
+            };
+            const durableTurn = hostTurnControlParams(currentPayload, currentSession.nativeSessionId, currentAuthority, attemptId);
+            try {
+                await beginDurableProviderTurn(input.home, durableTurn);
+            }
+            catch (error) {
+                await callController(input.home, "runtime.provider-turn-submission-resolve", {
+                    ...durableTurn,
+                    status: "rejected",
+                    reason: `Human Turn intent acknowledgement failed before Provider write: ${errorText(error)}`,
+                    observedAt: new Date().toISOString()
+                }).catch(() => { });
+                throw error;
+            }
+            try {
+                await submitTurn(turnControl);
+            }
+            catch (error) {
+                await callController(input.home, "runtime.provider-turn-submission-resolve", {
+                    ...durableTurn,
+                    status: error instanceof ProviderDeliveryUnknownError
+                        ? "delivery-unknown"
+                        : "rejected",
+                    reason: errorText(error),
+                    observedAt: new Date().toISOString()
+                }).catch(() => { });
+                throw error;
+            }
+            process.stdout.write("Provider accepted the human Turn; waiting for its terminal boundary.\n");
+        }).catch((error) => {
+            process.stderr.write(`Provider input failed: ${errorText(error)}\n`);
+            promptHuman();
+        });
+    });
+    promptHuman();
+    let stopResolve;
+    const stopped = new Promise((resolvePromise) => {
+        stopResolve = resolvePromise;
+    });
+    const signals = ["SIGINT", "SIGTERM", "SIGHUP"];
+    const handlers = new Map();
+    let forceKillTimer;
+    for (const signal of signals) {
+        const handler = () => {
+            if (hostStopRequested)
+                return;
+            hostStopRequested = true;
+            session?.terminate(signal);
+            forceKillTimer = setTimeout(() => session?.terminate("SIGKILL"), 10_000);
+            forceKillTimer.unref();
+            stopResolve();
+        };
+        handlers.set(signal, handler);
+        process.on(signal, handler);
+    }
+    try {
+        if (payload.startMode === "provider") {
+            void enqueueDispatch(payload).catch(() => { });
+        }
+        await stopped;
+        return 0;
     }
     finally {
+        for (const [signal, handler] of handlers)
+            process.removeListener(signal, handler);
+        if (forceKillTimer !== undefined)
+            clearTimeout(forceKillTimer);
+        humanConsole?.close();
+        session?.terminate("SIGTERM");
         await control.close();
+        void sessionPayload;
     }
 }
 export function agentHostControlSocketPath(input) {
     const owner = input.scope === "task" ? input.taskId ?? "missing-task" : "global";
-    const digest = Buffer.from(`${input.scope}\0${owner}\0${input.roleName}`, "utf8")
-        .toString("base64url")
-        .slice(0, 80);
-    return resolve(join(input.home, "runtime", "agent-host-control", `${digest}.sock`));
+    const homeDigest = createHash("sha256")
+        .update(readHomeFilesystemId(resolve(input.home)))
+        .digest("hex")
+        .slice(0, 16);
+    const ownerDigest = createHash("sha256")
+        .update(`${input.scope}\0${owner}\0${input.roleName}`)
+        .digest("hex")
+        .slice(0, 16);
+    const uid = typeof process.getuid === "function" ? process.getuid() : 0;
+    // Linux sockaddr_un paths have a small fixed budget. Keep the endpoint
+    // independent of a potentially deep YUI_HOME while fencing aliases and
+    // copied Homes by their physical filesystem identity.
+    const root = process.platform === "linux" ? "/tmp" : tmpdir();
+    return join(root, `yui-${uid}`, "agent-host", `${homeDigest}-${ownerDigest}.sock`);
 }
 export async function sendAgentHostLaunchControl(input) {
+    return await sendAgentHostControl(input);
+}
+export async function sendAgentHostTurnControl(input) {
+    return await sendAgentHostControl(input);
+}
+export async function sendAgentHostAuthorityControl(input) {
+    return await sendAgentHostControl(input);
+}
+export async function inspectAgentHost(input) {
+    const result = await sendAgentHostControl({
+        ...input,
+        control: { protocol: AGENT_HOST_CONTROL_PROTOCOL, type: "status" }
+    });
+    return result.snapshot;
+}
+export async function waitForAgentHostLaunchAck(input) {
+    const deadline = Date.now() + (input.timeoutMs ?? HOST_READY_TIMEOUT_MS);
+    let lastError;
+    while (Date.now() < deadline) {
+        try {
+            const snapshot = await inspectAgentHost(input);
+            if (snapshot.launchId === input.launchId) {
+                if (snapshot.state === "ready"
+                    || (input.requireTurnAck !== true && snapshot.state === "idle"))
+                    return snapshot;
+                if (snapshot.state === "delivery-unknown" || snapshot.state === "rejected") {
+                    return snapshot;
+                }
+                if (snapshot.state === "failed" || snapshot.state === "exited") {
+                    throw new Error(`Agent Host Provider launch ${snapshot.state}: ${snapshot.detail ?? "no detail"}.`);
+                }
+            }
+        }
+        catch (error) {
+            lastError = error;
+            const code = error.code;
+            if (code !== "ENOENT" && code !== "ECONNREFUSED")
+                throw error;
+        }
+        await new Promise((resolvePromise) => setTimeout(resolvePromise, 50));
+    }
+    throw new Error(`Agent Host did not acknowledge Provider launch ${input.launchId}: ${errorText(lastError)}.`);
+}
+async function sendAgentHostControl(input) {
     const path = agentHostControlSocketPath(input);
     return await new Promise((resolvePromise, reject) => {
         const client = createConnection(path);
@@ -85,12 +635,16 @@ export async function sendAgentHostLaunchControl(input) {
             client.destroy();
             reject(new Error("Agent Host control request timed out."));
         }, HOST_CONTROL_TIMEOUT_MS);
+        let settled = false;
         const settle = (callback, value) => {
+            if (settled)
+                return;
+            settled = true;
             clearTimeout(timer);
             callback(value);
         };
         client.setEncoding("utf8");
-        client.once("connect", () => client.end(`${serializeAgentHostLaunchControl(input.control)}\n`));
+        client.once("connect", () => client.end(`${JSON.stringify(validateControl(input.control))}\n`));
         client.on("data", (chunk) => {
             response += chunk;
             if (Buffer.byteLength(response, "utf8") > HOST_CONTROL_MAX_BYTES) {
@@ -99,12 +653,12 @@ export async function sendAgentHostLaunchControl(input) {
         });
         client.once("error", (error) => settle(reject, error));
         client.once("close", () => {
-            const value = response.trim();
-            if (value === "accepted" || value === "active-same-launch"
-                || value === "active-other-launch")
-                settle(resolvePromise, value);
-            else
-                settle(reject, new Error(`Agent Host control response is invalid: ${value || "empty"}.`));
+            try {
+                settle(resolvePromise, validateControlResult(JSON.parse(response.trim())));
+            }
+            catch (error) {
+                settle(reject, error);
+            }
         });
     });
 }
@@ -116,66 +670,6 @@ async function redeem(home, launchId, ticket) {
     });
     return validateAgentHostLaunchPayload(result);
 }
-export async function runAgentHostProviderChild(payload) {
-    const processInstanceId = randomUUID();
-    const child = spawn(payload.command, [...payload.args], {
-        cwd: payload.cwd,
-        env: { ...payload.environment },
-        stdio: payload.providerInput === undefined ? "inherit" : ["pipe", "inherit", "inherit"],
-        detached: true
-    });
-    if (payload.providerInput !== undefined) {
-        if (child.stdin === null)
-            throw new Error("Provider input pipe is unavailable.");
-        const providerInput = `${JSON.stringify({
-            type: "user",
-            message: {
-                role: "user",
-                content: [{ type: "text", text: payload.providerInput.boundedText }]
-            }
-        })}\n`;
-        child.stdin.end(providerInput, "utf8");
-    }
-    const forward = (signal) => {
-        if (child.pid === undefined)
-            return;
-        try {
-            process.kill(-child.pid, signal);
-        }
-        catch (error) {
-            if (error.code !== "ESRCH")
-                throw error;
-        }
-    };
-    const signals = ["SIGINT", "SIGTERM", "SIGHUP"];
-    const handlers = new Map();
-    let hostStopRequested = false;
-    let forceKillTimer;
-    for (const signal of signals) {
-        const handler = () => {
-            hostStopRequested = true;
-            forward(signal);
-            forceKillTimer ??= setTimeout(() => forward("SIGKILL"), 10_000);
-            forceKillTimer.unref();
-        };
-        handlers.set(signal, handler);
-        process.on(signal, handler);
-    }
-    try {
-        return await new Promise((resolve, reject) => {
-            child.once("error", reject);
-            child.once("close", (code, signal) => {
-                resolve({ code, signal, processInstanceId, hostStopRequested });
-            });
-        });
-    }
-    finally {
-        for (const [signal, handler] of handlers)
-            process.removeListener(signal, handler);
-        if (forceKillTimer !== undefined)
-            clearTimeout(forceKillTimer);
-    }
-}
 async function persistAndSubmitExit(home, observation) {
     const directory = resolve(join(home, "runtime", "agent-host-outbox"));
     mkdirSync(directory, { recursive: true, mode: 0o700 });
@@ -222,9 +716,8 @@ async function replayExitOutbox(home) {
         await unlink(claimed);
     }
 }
-async function openHostControl(home, payload) {
-    const directory = resolve(join(home, "runtime", "agent-host-control"));
-    mkdirSync(directory, { recursive: true, mode: 0o700 });
+/** Internal socket boundary exported for transport-level verification. */
+export async function openAgentHostControl(home, payload, snapshot, dispatch) {
     const path = agentHostControlSocketPath({
         home,
         scope: payload.environment.YUI_SESSION_SCOPE ?? "task",
@@ -233,16 +726,17 @@ async function openHostControl(home, payload) {
             : { taskId: payload.environment.YUI_TASK_ID }),
         roleName: payload.environment.YUI_ROLE ?? "unknown-role"
     });
+    const directory = dirname(path);
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
     if (await hostControlSocketIsLive(path)) {
         throw new Error(`Agent Host control socket is already owned: ${path}.`);
     }
     rmSync(path, { force: true });
-    let active = false;
-    let activeLaunchId;
-    const queued = [];
-    const waiters = [];
-    const server = createServer((socket) => {
+    const server = createServer({ allowHalfOpen: true }, (socket) => {
         socket.setEncoding("utf8");
+        // A control client can disappear after sending its bounded request. Keep
+        // that connection-local failure from terminating the persistent Host.
+        socket.on("error", () => { });
         let body = "";
         socket.on("data", (chunk) => {
             body += chunk;
@@ -251,24 +745,20 @@ async function openHostControl(home, payload) {
             }
         });
         socket.once("end", () => {
-            try {
-                const control = validateControl(JSON.parse(body.trim()));
-                if (active || queued.length > 0) {
-                    socket.end(activeLaunchId === control.launchId
-                        ? "active-same-launch\n"
-                        : "active-other-launch\n");
-                    return;
+            void (async () => {
+                try {
+                    const request = validateControl(JSON.parse(body.trim()));
+                    socket.end(`${JSON.stringify(await dispatch(request))}\n`);
                 }
-                const waiter = waiters.shift();
-                if (waiter === undefined)
-                    queued.push(control);
-                else
-                    waiter(control);
-                socket.end("accepted\n");
-            }
-            catch (error) {
-                socket.destroy(error);
-            }
+                catch (error) {
+                    const current = snapshot();
+                    socket.end(`${JSON.stringify(controlResult("rejected", validateSnapshot({
+                        ...current,
+                        detail: errorText(error),
+                        updatedAt: new Date().toISOString()
+                    })))}\n`);
+                }
+            })();
         });
     });
     await new Promise((resolvePromise, reject) => {
@@ -277,16 +767,6 @@ async function openHostControl(home, payload) {
     });
     chmodSync(path, 0o600);
     return Object.freeze({
-        setActive(value, launchId) {
-            active = value;
-            activeLaunchId = value ? launchId : undefined;
-        },
-        next() {
-            const available = queued.shift();
-            if (available !== undefined)
-                return Promise.resolve(available);
-            return new Promise((resolvePromise) => waiters.push(resolvePromise));
-        },
         close: async () => {
             await new Promise((resolvePromise) => server.close(() => resolvePromise()));
             rmSync(path, { force: true });
@@ -313,15 +793,144 @@ async function hostControlSocketIsLive(path) {
     });
 }
 function validateControl(control) {
-    if (control.protocol !== AGENT_HOST_CONTROL_PROTOCOL || control.type !== "launch") {
+    if (control.protocol !== AGENT_HOST_CONTROL_PROTOCOL) {
         throw new Error("Agent Host control protocol is invalid.");
     }
-    if (typeof control.launchId !== "string" || control.launchId.length === 0
-        || control.launchId.length > 256 || control.launchId.includes("\0")) {
-        throw new Error("Agent Host launch control identity is invalid.");
+    if (control.type === "status")
+        return Object.freeze({ ...control });
+    if (control.type === "submit-turn") {
+        validateLaunchId(control.launchId);
+        validateIdentity(control.nativeSessionId, "native Session id");
+        validateProviderAuthorityFence(control.authority);
+        validateIdentity(control.turn.attemptId, "Provider input attempt id");
+        if (typeof control.turn.boundedText !== "string"
+            || control.turn.boundedText.includes("\0")
+            || Buffer.byteLength(control.turn.boundedText, "utf8") > 32 * 1024) {
+            throw new Error("Agent Host Provider input is invalid.");
+        }
+        return Object.freeze({
+            ...control,
+            turn: Object.freeze({ ...control.turn })
+        });
+    }
+    if (control.type === "set-authority") {
+        validateIdentity(control.nativeSessionId, "native Session id");
+        return Object.freeze({
+            ...control,
+            authority: validateProviderAuthorityFence(control.authority)
+        });
     }
+    if (control.type !== "launch")
+        throw new Error("Agent Host control type is invalid.");
+    validateLaunchId(control.launchId);
     if (typeof control.ticket !== "string" || !/^[a-f0-9]{64}$/u.test(control.ticket)) {
         throw new Error("Agent Host launch control ticket is invalid.");
     }
     return Object.freeze({ ...control });
 }
+function validateLaunchId(value) {
+    if (typeof value !== "string" || value.length === 0
+        || value.length > 256 || value.includes("\0")) {
+        throw new Error("Agent Host launch control identity is invalid.");
+    }
+}
+function validateIdentity(value, label) {
+    if (typeof value !== "string" || value.trim().length === 0 || value.includes("\0")) {
+        throw new Error(`Agent Host ${label} is invalid.`);
+    }
+}
+function validateControlResult(result) {
+    if (result.protocol !== AGENT_HOST_CONTROL_PROTOCOL
+        || !["status", "accepted", "rejected", "active-same-launch", "active-other-launch"].includes(result.outcome)) {
+        throw new Error("Agent Host control response is invalid.");
+    }
+    return Object.freeze({ ...result, snapshot: validateSnapshot(result.snapshot) });
+}
+function validateSnapshot(snapshot) {
+    if (snapshot.schemaVersion !== 1
+        || !["idle", "starting", "ready", "settling", "delivery-unknown", "rejected", "failed", "exited"]
+            .includes(snapshot.state)) {
+        throw new Error("Agent Host snapshot is invalid.");
+    }
+    if (!Number.isFinite(Date.parse(snapshot.updatedAt))) {
+        throw new Error("Agent Host snapshot timestamp is invalid.");
+    }
+    const authorityFields = [
+        snapshot.authorityEpoch,
+        snapshot.authorityOwner,
+        snapshot.authorityHolderId
+    ];
+    if (authorityFields.some((value) => value !== undefined)) {
+        if (authorityFields.some((value) => value === undefined)) {
+            throw new Error("Agent Host snapshot authority is incomplete.");
+        }
+        validateProviderAuthorityFence({
+            epoch: snapshot.authorityEpoch,
+            owner: snapshot.authorityOwner,
+            holderId: snapshot.authorityHolderId
+        });
+    }
+    return Object.freeze({ ...snapshot });
+}
+function hostSnapshot(state, fields = {}) {
+    return validateSnapshot({
+        schemaVersion: 1,
+        state,
+        ...definedFields(fields),
+        updatedAt: new Date().toISOString()
+    });
+}
+function controlResult(outcome, snapshot) {
+    return Object.freeze({ protocol: AGENT_HOST_CONTROL_PROTOCOL, outcome, snapshot });
+}
+function definedFields(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, member]) => member !== undefined));
+}
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error ?? "unknown error");
+}
+function hostTurnControlParams(payload, nativeSessionId, authority, attemptId) {
+    const environment = payload.environment;
+    return Object.freeze({
+        taskId: requiredEnvironment(environment.YUI_TASK_ID, "Task id"),
+        roleName: requiredEnvironment(environment.YUI_ROLE, "Role name"),
+        runId: requiredEnvironment(environment.YUI_RUN_ID, "Run id"),
+        agentId: requiredEnvironment(environment.YUI_AGENT_ID, "Agent id"),
+        launchId: payload.launchId,
+        nativeSessionId: requiredEnvironment(nativeSessionId, "native Session id"),
+        attemptId,
+        authorityEpoch: authority.epoch,
+        authorityOwner: authority.owner,
+        holderId: authority.holderId,
+        observedAt: new Date().toISOString()
+    });
+}
+async function beginDurableProviderTurn(home, durableTurn) {
+    try {
+        await callController(home, "runtime.provider-turn-begin", durableTurn);
+    }
+    catch (error) {
+        if (!(error instanceof ControllerClientError) || error.code !== "INTERNAL_ERROR") {
+            throw error;
+        }
+        // The exact attempt is idempotent, so one lost acknowledgement can be
+        // retried without creating a second Provider write.
+        await callController(home, "runtime.provider-turn-begin", durableTurn);
+    }
+}
+async function resolveProviderTurnSubmission(home, durableTurn, error) {
+    await callController(home, "runtime.provider-turn-submission-resolve", {
+        ...durableTurn,
+        status: error instanceof ProviderDeliveryUnknownError
+            ? "delivery-unknown"
+            : "rejected",
+        reason: errorText(error),
+        observedAt: new Date().toISOString()
+    }).catch(() => { });
+}
+function requiredEnvironment(value, label) {
+    if (typeof value !== "string" || value.trim().length === 0 || value.includes("\0")) {
+        throw new Error(`Agent Host ${label} is unavailable.`);
+    }
+    return value.trim();
+}