@zq-silk/yui 0.13.8 → 0.13.9

package/dist/runtime/agentHost.js

@@ -16,7 +16,8 @@ import { validateRuntimeProcessExitObservation } from "./processExitObservation.
 import { persistRuntimeProcessExitObservation, replayRuntimeProcessExitOutbox } from "./processExitOutbox.js";
 import { readRuntimeStopReceipt, removeRuntimeStopReceipt } from "./runtimeStopReceipt.js";
 import { AGENT_HOST_CONTROL_TIMEOUT_MS, AGENT_HOST_READY_TIMEOUT_MS } from "./runtimeDeadlines.js";
-export const AGENT_HOST_CONTROL_PROTOCOL = "yui-agent-host/v2";
+import { serializeAgentErrorRaw } from "./agentError.js";
+export const AGENT_HOST_CONTROL_PROTOCOL = "yui-agent-host/v3";
 const HOST_CONTROL_MAX_BYTES = 32 * 1024;
 const CODEX_CLIENT_STABLE_MS = 5_000;
 const MAX_CONSECUTIVE_CODEX_DISCONNECTS = 3;
@@ -146,7 +147,7 @@ export async function runAgentHost(input) {
                 schemaVersion: 1,
                 adapterId: "codex",
                 transport: "codex-app-server-proxy",
-                kind: "ensure",
+                kind: "restore",
                 mode: "resume",
                 nativeSessionId: disconnectedSession.nativeSessionId,
                 ...(previousControl.sessionTitle === undefined
@@ -351,7 +352,7 @@ export async function runAgentHost(input) {
             throw new Error("Agent Host still owns an unsettled Provider Turn.");
         }
         const requestedAuthority = validateProviderAuthorityFence(providerControl.authority);
-        const replacesCurrentConversation = session !== undefined && providerControl.kind === "new";
+        const replacesCurrentConversation = session !== undefined && providerControl.kind === "start";
         if (replacesCurrentConversation) {
             throw new Error("Agent Host cannot replace a live Provider Session; stop it before starting a fresh Session.");
         }
@@ -364,9 +365,6 @@ export async function runAgentHost(input) {
         updateSnapshot(hostSnapshot("starting", {
             launchId: next.launchId,
             adapterId: providerControl.adapterId,
-            ...(providerControl.initialTurn === undefined
-                ? {}
-                : { attemptId: providerControl.initialTurn.attemptId }),
             ...(session === undefined ? {} : {
                 processInstanceId: session.processInstanceId,
                 nativeSessionId: session.nativeSessionId,
@@ -374,8 +372,6 @@ export async function runAgentHost(input) {
             }),
             ...authorityFields()
         }));
-        let providerAcceptedAttemptId;
-        let durableInitialTurn;
         try {
             if (session !== undefined) {
                 if (session.adapterId !== providerControl.adapterId
@@ -390,7 +386,7 @@ export async function runAgentHost(input) {
                 conversationRecoverability = providerControl.adapterId === "codex"
                     ? "recoverable"
                     : "unknown";
-                if (providerControl.kind === "ensure" && providerControl.ownedTurn !== undefined) {
+                if (providerControl.kind === "restore" && providerControl.ownedTurn !== undefined) {
                     activeTurnPayload = next;
                     activeTurnAttemptId = providerControl.ownedTurn.attemptId;
                     activeNativeTurnId = providerControl.ownedTurn.turnId;
@@ -416,58 +412,24 @@ export async function runAgentHost(input) {
                 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;
-                activeTurnAttemptId = providerControl.initialTurn.attemptId;
-                activeNativeTurnId = undefined;
-                try {
-                    receipt = await session.submitTurn(providerControl.initialTurn);
-                    providerAcceptedAttemptId = receipt.attemptId;
-                    activeNativeTurnId = receipt.nativeTurnId;
-                }
-                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;
-                }
-            }
-            const ensuredOwnedTurn = providerControl.kind === "ensure"
+            const restoredOwnedTurn = providerControl.kind === "restore"
                 ? providerControl.ownedTurn
                 : undefined;
-            const providerState = receipt !== undefined || ensuredOwnedTurn !== undefined
+            const providerState = restoredOwnedTurn !== undefined
                 ? "ready"
                 : session.activeTurnId === undefined ? "idle" : "busy";
             updateSnapshot(hostSnapshot(providerState, {
                 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 }
-                    : ensuredOwnedTurn === undefined
-                        ? {}
-                        : {
-                            attemptId: ensuredOwnedTurn.attemptId,
-                            nativeTurnId: ensuredOwnedTurn.turnId
-                        }),
+                nativeSessionId: session.nativeSessionId,
+                conversationId: session.conversationId,
+                ...(restoredOwnedTurn === undefined
+                    ? {}
+                    : {
+                        attemptId: restoredOwnedTurn.attemptId,
+                        nativeTurnId: restoredOwnedTurn.turnId
+                    }),
                 ...authorityFields()
             }));
             return snapshot;
@@ -488,33 +450,21 @@ export async function runAgentHost(input) {
                 conversationRecoverability = "unknown";
                 authority = undefined;
             }
-            const deliveryUnknown = error instanceof ProviderDeliveryUnknownError
-                || providerAcceptedAttemptId !== undefined;
-            const state = deliveryUnknown
-                ? "delivery-unknown"
-                : error instanceof ProviderTurnBusyError
-                    ? "busy"
-                    : error instanceof ProviderTurnRejectedError ? "rejected" : "failed";
+            const state = error instanceof ProviderTurnBusyError
+                ? "busy"
+                : 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;
-                activeTurnAttemptId = undefined;
-                activeNativeTurnId = undefined;
-            }
-            if (deliveryUnknown && !(error instanceof ProviderDeliveryUnknownError)) {
-                throw new ProviderDeliveryUnknownError(`Provider accepted input but its durable acknowledgement could not be confirmed: ${errorText(error)}`, providerAcceptedAttemptId);
-            }
+            activeTurnPayload = undefined;
+            activeTurnAttemptId = undefined;
+            activeNativeTurnId = undefined;
             throw error;
         }
     };
@@ -536,9 +486,15 @@ export async function runAgentHost(input) {
             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.");
+            throw new ProviderTurnBusyError("Agent Host still owns an unsettled Provider Turn.", request.turn.attemptId, activeNativeTurnId);
         }
-        activeTurnPayload = sessionPayload;
+        activeTurnPayload = {
+            ...sessionPayload,
+            environment: {
+                ...sessionPayload.environment,
+                YUI_RUN_ID: request.runId
+            }
+        };
         activeTurnAttemptId = request.turn.attemptId;
         activeNativeTurnId = undefined;
         updateSnapshot(hostSnapshot("starting", {
@@ -550,17 +506,26 @@ export async function runAgentHost(input) {
             attemptId: request.turn.attemptId,
             ...authorityFields()
         }));
+        const durableTurn = hostTurnControlParams(sessionPayload, session.nativeSessionId, request.authority, request.turn.attemptId, request.runId);
+        await beginDurableProviderTurn(input.home, durableTurn);
         let providerAccepted = false;
         try {
             const receipt = await session.submitTurn(request.turn);
             providerAccepted = true;
             activeNativeTurnId = receipt.nativeTurnId;
-            await publishStructuredProviderAccepted({
-                home: input.home,
-                environment: sessionPayload.environment,
-                activationId: activationId ?? sessionPayload.launchId,
-                receipt
-            });
+            try {
+                await publishStructuredProviderAccepted({
+                    home: input.home,
+                    environment: sessionPayload.environment,
+                    activationId: activationId ?? sessionPayload.launchId,
+                    receipt
+                });
+            }
+            catch (error) {
+                const unknown = new ProviderDeliveryUnknownError(`Provider accepted input but its durable acknowledgement could not be confirmed: ${errorText(error)}`, request.turn.attemptId);
+                await resolveProviderTurnSubmission(input.home, durableTurn, unknown);
+                throw unknown;
+            }
             updateSnapshot(hostSnapshot("ready", {
                 launchId: request.launchId,
                 adapterId: session.adapterId,
@@ -574,6 +539,9 @@ export async function runAgentHost(input) {
             return snapshot;
         }
         catch (error) {
+            if (!providerAccepted) {
+                await resolveProviderTurnSubmission(input.home, durableTurn, error);
+            }
             const deliveryUnknown = error instanceof ProviderDeliveryUnknownError || providerAccepted;
             const state = deliveryUnknown
                 ? "delivery-unknown"
@@ -684,6 +652,7 @@ export async function runAgentHost(input) {
                 type: "submit-turn",
                 launchId: currentPayload.launchId,
                 nativeSessionId: currentSession.nativeSessionId,
+                runId: requiredEnvironment(currentPayload.environment.YUI_RUN_ID, "Run id"),
                 authority: currentAuthority,
                 turn: {
                     attemptId,
@@ -902,8 +871,10 @@ export async function openAgentHostControl(home, payload, snapshot, dispatch) {
                 }
                 catch (error) {
                     const current = snapshot();
-                    socket.end(`${JSON.stringify(controlResult("rejected", validateSnapshot({
+                    const busy = error instanceof ProviderTurnBusyError;
+                    socket.end(`${JSON.stringify(controlResult(busy ? "accepted" : "rejected", validateSnapshot({
                         ...current,
+                        ...(busy ? { state: "busy" } : {}),
                         detail: errorText(error),
                         updatedAt: new Date().toISOString()
                     })))}\n`);
@@ -951,6 +922,7 @@ function validateControl(control) {
     if (control.type === "submit-turn") {
         validateLaunchId(control.launchId);
         validateIdentity(control.nativeSessionId, "native Session id");
+        validateIdentity(control.runId, "Run id");
         validateProviderAuthorityFence(control.authority);
         validateIdentity(control.turn.attemptId, "Provider input attempt id");
         if (typeof control.turn.boundedText !== "string"
@@ -1056,12 +1028,12 @@ async function delay(milliseconds) {
         timer.unref();
     });
 }
-function hostTurnControlParams(payload, nativeSessionId, authority, attemptId) {
+function hostTurnControlParams(payload, nativeSessionId, authority, attemptId, runId = requiredEnvironment(payload.environment.YUI_RUN_ID, "Run id")) {
     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"),
+        runId: requiredEnvironment(runId, "Run id"),
         agentId: requiredEnvironment(environment.YUI_AGENT_ID, "Agent id"),
         launchId: payload.launchId,
         nativeSessionId: requiredEnvironment(nativeSessionId, "native Session id"),
@@ -1120,6 +1092,7 @@ async function resolveProviderTurnSubmission(home, durableTurn, error) {
             ? "delivery-unknown"
             : "rejected",
         reason: errorText(error),
+        raw: serializeAgentErrorRaw(error),
         observedAt: new Date().toISOString()
     };
     try {

package/dist/runtime/builtinAgentDrivers.js

@@ -1,6 +1,7 @@
 import { AgentDriverRegistry } from "./agentDriver.js";
 import { claudeTranscriptObserver, codexTranscriptObserver, transcriptObserverSource } from "./builtinTranscriptObserver.js";
-import { parseClaudeError } from "./providerErrorCodes.js";
+import { mapClaudeAgentError, mapCodexAgentError } from "./builtinAgentErrorMappers.js";
+import { serializeAgentErrorRaw, standardAgentError } from "./agentError.js";
 export const CODEX_DRIVER_ID = "openai/codex";
 export const CLAUDE_CODE_DRIVER_ID = "anthropic/claude-code";
 export function builtinDriverIdForAdapter(adapterId) {
@@ -77,6 +78,7 @@ export const BUILTIN_AGENT_DRIVERS = Object.freeze([
         runtime: Object.freeze({
             nativeSessionId: ({ payload }) => (optionalIdentityFrom(payload, ["session_id"])),
             nativeTurnId: ({ payload }) => (optionalIdentityFrom(payload, ["prompt_id", "turn_id"])),
+            mapError: mapClaudeAgentError,
             mapHook: ({ hookEventName, payload, occurrenceId }) => (mapClaudeHook(hookEventName, payload, occurrenceId)),
             classifyHook: ({ hookEventName, payload }) => Object.freeze({
                 ...(hookEventName === "SessionStart" && payload.source === "startup"
@@ -133,6 +135,7 @@ export const BUILTIN_AGENT_DRIVERS = Object.freeze([
         runtime: Object.freeze({
             nativeSessionId: ({ payload }) => (optionalIdentityFrom(payload, ["session_id"])),
             nativeTurnId: ({ payload }) => (optionalIdentityFrom(payload, ["turn_id", "prompt_id"])),
+            mapError: mapCodexAgentError,
             mapHook: ({ hookEventName, payload, occurrenceId }) => (mapCodexHook(hookEventName, payload, occurrenceId)),
             classifyHook: ({ hookEventName, payload }) => Object.freeze({
                 ...(hookEventName === "SessionStart"
@@ -237,7 +240,10 @@ function mapClaudeHook(name, payload, occurrenceId) {
         case "StopFailure":
             return mapped("turn.failed", claudeFailure(payload));
         case "SessionEnd":
-            return [mapped("session.ended"), mapped("activation.ended")];
+            // Native CLI exit ends this local Provider attachment, not the
+            // resumable Conversation. Durable Session end is an explicit Yui
+            // mutation or a Provider fact that the Conversation is unrecoverable.
+            return mapped("activation.ended");
         default:
             throw new Error(`Claude Code Driver does not support Hook event: ${name}.`);
     }
@@ -291,7 +297,7 @@ function mapCodexHook(name, payload, occurrenceId) {
         case "Stop":
             return mapped("turn.completed", optionalSummary(payload));
         case "SessionEnd":
-            return [mapped("session.ended"), mapped("activation.ended")];
+            return mapped("activation.ended");
         default:
             throw new Error(`Codex Driver does not support Hook event: ${name}.`);
     }
@@ -376,7 +382,8 @@ function claudeFailure(payload) {
     const code = firstIdentity(payload, ["error"], "Claude StopFailure error");
     const details = optionalText(payload.error_details);
     const lastOutput = optionalText(payload.last_assistant_message);
-    const parsed = parseClaudeError(code, details);
+    const raw = serializeAgentErrorRaw(payload);
+    const classification = mapClaudeAgentError({ message: code, raw });
     const retryAfterMs = typeof payload.retry_after_ms === "number"
         && Number.isSafeInteger(payload.retry_after_ms)
         && payload.retry_after_ms > 0
@@ -384,14 +391,19 @@ function claudeFailure(payload) {
         : undefined;
     return {
         failure: {
-            ...(parsed.code !== "unknown" ? { errorCode: parsed.code } : {}),
-            code,
-            ...(details === undefined ? {} : { details }),
+            error: standardAgentError({
+                source: "provider",
+                phase: "turn-execute",
+                classification,
+                message: code,
+                raw,
+                inputDisposition: "accepted",
+                ...(retryAfterMs === undefined ? {} : { retryAfterMs })
+            }),
             ...(lastOutput === undefined ? {} : { lastOutput }),
             ...(payload.run_terminal === true || payload.unrecoverable === true
                 ? { runTerminal: true }
-                : {}),
-            ...(retryAfterMs === undefined ? {} : { retryAfterMs })
+                : {})
         },
         summary: [
             "Agent turn failed.",

package/dist/runtime/builtinAgentErrorMappers.js

@@ -0,0 +1,150 @@
+/** Provider-specific Claude Code failure recognition. */
+export function mapClaudeAgentError(input) {
+    const text = `${input.message}\n${input.raw}`;
+    if (/^server_error$/iu.test(input.message) || /\bapi_error\b/iu.test(text)) {
+        return recoverable("availability", "provider.server-error");
+    }
+    if (/^overloaded_error$/iu.test(input.message) || /\boverloaded\b/iu.test(text)) {
+        return recoverable("availability", "provider.overloaded");
+    }
+    if (/^rate_limit_error$/iu.test(input.message) || /rate[\s_-]?limit/iu.test(text)) {
+        return recoverable("rate-limit", "provider.rate-limit");
+    }
+    if (/^(authentication_error|permission_error)$/iu.test(input.message)) {
+        return classification("access", "provider.access-denied");
+    }
+    if (/^not_found_error$/iu.test(input.message)) {
+        return sessionUnavailable("provider.session-not-found");
+    }
+    return mapSharedAgentError(text, "claude-code");
+}
+/** Provider-specific Codex failure recognition. */
+export function mapCodexAgentError(input) {
+    const text = `${input.message}\n${input.raw}`;
+    if (/^server_error$/iu.test(input.message)) {
+        return recoverable("availability", "provider.server-error");
+    }
+    if (/^overloaded_error$/iu.test(input.message)
+        || /selected model is at capacity/iu.test(text)
+        || /\bmodel\b.*\bat capacity\b/iu.test(text)) {
+        return recoverable("availability", "provider.model-capacity");
+    }
+    if (/^rate_limit_error$/iu.test(input.message)) {
+        return recoverable("rate-limit", "provider.rate-limit");
+    }
+    if (/^(authentication_error|permission_error)$/iu.test(input.message)) {
+        return classification("access", "provider.access-denied");
+    }
+    if (/\[codex:(unrecognized_model|invalid_model|model_not_found)\]/iu.test(text)
+        || /model.*not supported|invalid.*model|model.*not found/iu.test(text)) {
+        return classification("invalid-request", "provider.invalid-model");
+    }
+    if (/stream disconnected/iu.test(text)) {
+        return recoverable("transport", "transport.stream-disconnected");
+    }
+    return mapSharedAgentError(text, "codex");
+}
+function mapSharedAgentError(text, namespace) {
+    if (/stream error:.*INTERNAL_ERROR/iu.test(text)) {
+        return recoverable("transport", "transport.stream-internal-error");
+    }
+    if (/stream error:.*PROTOCOL_ERROR/iu.test(text)) {
+        return recoverable("transport", "transport.stream-protocol-error");
+    }
+    if (/stream error/iu.test(text))
+        return recoverable("transport", "transport.stream-error");
+    if (/\b429\b/u.test(text) || /rate[\s_-]?limit/iu.test(text)) {
+        return recoverable("rate-limit", "provider.rate-limit");
+    }
+    if (/\b40[0-9]\b/u.test(text))
+        return classification("invalid-request", "provider.http-4xx");
+    if (/\b50[0-9]\b/u.test(text)
+        || /bad gateway|service unavailable|temporarily unavailable/iu.test(text)) {
+        return recoverable("availability", "provider.http-5xx");
+    }
+    if (/server[\s_-]?error/iu.test(text)) {
+        return recoverable("availability", "provider.server-error");
+    }
+    if (/\boverloaded\b/iu.test(text)) {
+        return recoverable("availability", "provider.overloaded");
+    }
+    if (/gateway timeout|timed?[ -]?out|etimedout/iu.test(text)) {
+        return recoverable("transport", "transport.timeout");
+    }
+    if (/connection[\s_-]?reset|econnreset|socket hang up/iu.test(text)) {
+        return recoverable("transport", "transport.connection-reset");
+    }
+    if (/connection[\s_-]?lost/iu.test(text)) {
+        return recoverable("transport", "transport.connection-lost");
+    }
+    if (/\beconnrefused\b|connection refused|connect[^\n]*refused/iu.test(text)) {
+        return recoverable("transport", "transport.connection-refused");
+    }
+    if (/\bepipe\b|broken pipe/iu.test(text)) {
+        return recoverable("transport", "transport.broken-pipe");
+    }
+    if (/\b(?:enotfound|eai_again)\b|dns[^\n]*(?:failed|unavailable)/iu.test(text)) {
+        return recoverable("transport", "transport.name-resolution");
+    }
+    if (/\benoent\b[^\n]*(?:socket|agent-host)|no such file[^\n]*(?:socket|agent-host)/iu.test(text)) {
+        return recoverable("transport", "transport.endpoint-missing");
+    }
+    if (/delivery[^\n]*unknown|acknowledgement[^\n]*unknown/iu.test(text)) {
+        return Object.freeze({
+            category: "transport",
+            code: "transport.delivery-unknown",
+            inputDisposition: "unknown",
+            sessionDisposition: "recoverable"
+        });
+    }
+    if (/unsettled turn|turn[^\n]*busy|session[^\n]*busy|writer fence|writer authority|human writer/iu.test(text)) {
+        return Object.freeze({
+            category: "conflict",
+            code: "runtime.session-busy",
+            inputDisposition: "not-accepted",
+            sessionDisposition: "recoverable"
+        });
+    }
+    if (/cyber[_-]?policy|policy[\s_-]?violation|usage[\s_-]?policy|content[\s_-]?policy|safety[\s_-]?policy/iu.test(text)) {
+        return classification("access", "provider.policy-denied");
+    }
+    if (/maximum context length|context length exceeded|context window (?:is )?(?:full|exceeded)|prompt (?:is )?too long|too many tokens/iu.test(text)) {
+        return classification("context", "provider.context-capacity");
+    }
+    if (/session[\s_-]?not[\s_-]?found|no[\s_-]?such[\s_-]?(?:session|thread)|thread[\s_-]?not[\s_-]?found/iu.test(text)) {
+        return sessionUnavailable("provider.session-not-found");
+    }
+    if (/session[\s_-]?(?:has[\s_-]?)?expired/iu.test(text)) {
+        return sessionUnavailable("provider.session-expired");
+    }
+    if (/session[\s_-]?(?:has[\s_-]?)?ended/iu.test(text)) {
+        return sessionUnavailable("provider.session-ended");
+    }
+    if (/process[\s_-]?exited/iu.test(text)) {
+        return recoverable("runtime", "runtime.process-exited");
+    }
+    if (/invalid[\s_-]?request|validation[\s_-]?error|bad[\s_-]?request|unknown[\s_-]?(?:flag|tool|argument)|unexpected argument|invalid schema/iu.test(text)
+        || (namespace === "codex"
+            ? /\[codex:(?:unrecognized_model|invalid_model|model_not_found)\]/iu.test(text)
+            : /\[claude-code:(?:unrecognized_model|invalid_model|model_not_found)\]/iu.test(text))) {
+        return classification("invalid-request", "provider.invalid-request");
+    }
+    return classification("unknown", "unknown");
+}
+function classification(category, code) {
+    return Object.freeze({ category, code });
+}
+function recoverable(category, code) {
+    return Object.freeze({
+        category,
+        code,
+        sessionDisposition: "recoverable"
+    });
+}
+function sessionUnavailable(code) {
+    return Object.freeze({
+        category: "session",
+        code,
+        sessionDisposition: "unrecoverable"
+    });
+}

package/dist/runtime/exactControlPlane.js

@@ -304,21 +304,16 @@ export function assertExactTaskRuntimeState(runtime, store, options = {}) {
         && isRuntimeLaunchReservation(lifecycleMailbox?.processing, runtime.launchId);
     const sessionLaunch = runtime.launchId !== undefined
         && session?.launchId === runtime.launchId;
-    const executionRef = lifecycleMailbox?.processing?.executionRef;
     const preallocated = options.preallocatedDriverSessionReservation;
-    const exactRunLaunchReservation = runtime.runId !== undefined
-        && runtime.launchId !== undefined
+    const exactHostLaunchReservation = runtime.launchId !== undefined
         && reservation
-        && !hasRuntimeCleanupObligation(lifecycleMailbox)
-        && executionRef?.type === "run"
-        && executionRef.taskId === runtime.taskId
-        && executionRef.id === runtime.runId;
-    const terminalSessionReplacementReservation = exactRunLaunchReservation
+        && !hasRuntimeCleanupObligation(lifecycleMailbox);
+    const terminalSessionReplacementReservation = exactHostLaunchReservation
         && session !== undefined
-        && (session.status === "stopped" || session.status === "broken");
+        && session.status === "ended";
     const exactPreallocatedReservation = preallocated !== undefined
         && runtime.adapterId === preallocated.adapterId
-        && exactRunLaunchReservation
+        && exactHostLaunchReservation
         && runtime.nativeSessionId !== undefined
         && (session === undefined || terminalSessionReplacementReservation)
         && runtime.nativeSessionId === nativeSessionIdForLaunch(preallocated.yuiHome, runtime.launchId, runtime.agentId, runtime.adapterId);
@@ -346,8 +341,7 @@ export function assertExactTaskRuntimeState(runtime, store, options = {}) {
         || session.adapterId !== runtime.adapterId
         || session.nativeSessionId !== runtime.nativeSessionId
         || session.launchId !== runtime.launchId
-        || session.status === "stopped"
-        || session.status === "broken"
+        || session.status === "ended"
         || session.effective.agentId !== runtime.agentId
         || session.effective.adapterId !== runtime.adapterId
         || canonicalPath(session.effective.workspace.root) !== runtime.workspace) {

package/dist/runtime/index.js

@@ -17,5 +17,4 @@ export { codexNotificationBoundary, codexAppServerErrorIsMissing, CodexAppServer
 export { createProviderRuntimeBinding, acceptProviderTurn, beginProviderTurn, currentProviderActivation, currentProviderAuthority, currentProviderConversation, endProviderActivation, markProviderTurnDeliveryUnknown, rejectProviderTurn, settleProviderTurnSubmission, settleProviderTurn, startProviderActivation, supersedeProviderConversation, transferProviderAuthority, updateProviderConversationRecoverability, validateProviderRuntimeBinding } from "./providerRuntimeIdentity.js";
 export { FencedProviderControl } from "./providerControl.js";
 export { sameProviderAuthorityFence, validateProviderAuthorityFence } from "./providerAuthorityFence.js";
-export { decideProviderRecovery } from "./providerRecoveryDecision.js";
 export { reconcileSessionOwners } from "./sessionReconciliation.js";

package/dist/runtime/launchBroker.js

@@ -98,22 +98,16 @@ function validateProviderControl(control) {
     if (control.mode !== "new" && control.mode !== "resume") {
         throw new Error("Agent Host Provider control mode is invalid.");
     }
-    if (control.kind !== "new" && control.kind !== "resume" && control.kind !== "ensure") {
+    if (control.kind !== "start" && control.kind !== "restore") {
         throw new Error("Agent Host Provider control kind is invalid.");
     }
-    if ((control.kind === "new") !== (control.mode === "new")) {
+    if ((control.kind === "start") !== (control.mode === "new")) {
         throw new Error("Agent Host Provider control kind does not match its transport mode.");
     }
-    if (control.kind !== "ensure" && control.initialTurn === undefined) {
-        throw new Error("Managed Provider new/resume launch requires its initial Turn.");
+    if (control.kind !== "restore" && "ownedTurn" in control) {
+        throw new Error("Only Session restore can reconcile an owned Turn.");
     }
-    if (control.kind === "ensure" && control.initialTurn !== undefined) {
-        throw new Error("Managed Provider ensure launch cannot carry a new Turn.");
-    }
-    if (control.kind !== "ensure" && "ownedTurn" in control) {
-        throw new Error("Only a managed Provider ensure launch can recover an owned Turn.");
-    }
-    if (control.kind === "ensure" && control.ownedTurn !== undefined) {
+    if (control.kind === "restore" && control.ownedTurn !== undefined) {
         if (control.adapterId !== "codex") {
             throw new Error("Only Managed Codex can recover an owned Turn across client attachment.");
         }
@@ -135,14 +129,6 @@ function validateProviderControl(control) {
         }
     }
     validateProviderAuthorityFence(control.authority);
-    if (control.initialTurn !== undefined) {
-        text(control.initialTurn.attemptId, "Provider input attemptId");
-        if (typeof control.initialTurn.boundedText !== "string"
-            || control.initialTurn.boundedText.includes("\0")
-            || Buffer.byteLength(control.initialTurn.boundedText, "utf8") > 32 * 1024) {
-            throw new Error("Agent Host Provider input must be bounded bootstrap text.");
-        }
-    }
 }
 function validateCodexThreadOptions(options) {
     if (options === null || typeof options !== "object" || Array.isArray(options)) {

package/dist/runtime/lifecycleReservation.js

@@ -2,6 +2,7 @@ import { mailboxHasWork } from "../coordination/workMailbox.js";
 export const RUNTIME_LIFECYCLE_OWNER = "runtime-lifecycle";
 export const RUNTIME_LAUNCH_RESERVED_REASON = "runtime-launch-reserved";
 export const RUNTIME_CLEANUP_REQUIRED_REASON = "runtime-cleanup-required";
+export const RUNTIME_HOST_DETACH_REQUIRED_REASON = "runtime-host-detach-required";
 /**
  * A Role runtime lifecycle lane already holds an in-flight operation (a
  * launch reservation or a cleanup obligation). This is scheduler
@@ -42,10 +43,25 @@ export function hasRuntimeLaunchReservation(mailbox) {
     return isRuntimeLaunchReservation(mailbox?.processing);
 }
 export function hasRuntimeCleanupObligation(mailbox) {
-    const pending = mailbox?.pending.normal;
-    return pending?.reasons.includes(RUNTIME_CLEANUP_REQUIRED_REASON) === true
-        || (!isRuntimeLaunchReservation(mailbox?.processing)
-            && mailbox?.processing?.batch.reasons.includes(RUNTIME_CLEANUP_REQUIRED_REASON) === true);
+    return runtimeCleanupDisposition(mailbox) !== null;
+}
+/** Explicit Session end dominates a coalesced physical Host detach request. */
+export function runtimeCleanupDisposition(mailbox) {
+    const reasons = [
+        ...(mailbox?.pending.normal?.reasons ?? []),
+        ...(!isRuntimeLaunchReservation(mailbox?.processing)
+            ? mailbox?.processing?.batch.reasons ?? []
+            : [])
+    ];
+    if (reasons.includes(RUNTIME_CLEANUP_REQUIRED_REASON))
+        return "end-session";
+    if (reasons.includes(RUNTIME_HOST_DETACH_REQUIRED_REASON))
+        return "detach-host";
+    return null;
+}
+export function isRuntimeCleanupReason(reason) {
+    return reason === RUNTIME_CLEANUP_REQUIRED_REASON
+        || reason === RUNTIME_HOST_DETACH_REQUIRED_REASON;
 }
 export function hasRuntimeLifecycleWork(mailbox) {
     return mailbox !== null && mailboxHasWork(mailbox);

package/dist/runtime/providerRuntimeIdentity.js

@@ -227,7 +227,7 @@ export function rejectProviderTurn(raw, input) {
         }
     });
 }
-/** Resolves an Agent Host submission exactly once and accepts an exact acknowledgement replay. */
+/** Resolves an Agent Host submission; an unknown delivery may later gain exact negative evidence. */
 export function settleProviderTurnSubmission(raw, input) {
     const binding = validateProviderRuntimeBinding(raw);
     const attemptId = identity(input.attemptId, "Provider input attempt id");
@@ -236,7 +236,8 @@ export function settleProviderTurnSubmission(raw, input) {
     }
     if (binding.turn.status === input.status)
         return binding;
-    if (binding.turn.status !== "submitting") {
+    if (binding.turn.status !== "submitting"
+        && !(binding.turn.status === "delivery-unknown" && input.status === "rejected")) {
         throw new Error("Provider Turn does not match a resolvable delivery state.");
     }
     return input.status === "delivery-unknown"