@rynx-ai/runtime 0.1.11-beta.20 → 0.1.11-beta.22

package/dist/host.js

@@ -247,7 +247,13 @@ export class LocalAgentHost {
     // multi-connection model). Defaults to an ExternalWsChannel client attached to
     // the backend's app-server; tests inject a fake.
     forwarderClientFactory;
-    observerReconnectTimeoutMs;
+    // Builds Omnigent's short-lived cold-resume preload connection. This must be
+    // distinct from both the app-server owner/injector and the background
+    // observer: the owner's initialize handshake is the readiness probe, then a
+    // freshly initialized connection performs the one resume and closes.
+    preloadClientFactory;
+    /** Builds one short-lived message/interrupt client. */
+    injectionClientFactory;
     // Keyed by `codexBackendKey` — the bare runtime id for budget-less agents, or
     // a `${runtime}::${retryHash}` composite for a per-agent retry budget.
     backends = new Map();
@@ -281,7 +287,7 @@ export class LocalAgentHost {
     /** Short-lived dedupe for managed fork notifications delivered after the
      * `thread/fork` response. Values are expected source Provider thread ids. */
     managedForkThreadStarts = new Map();
-    constructor({ config, commandRunner, sessionStore = new FileCodexSessionStore(resolveCodexSessionStorePath(config)), allowedRoots = resolveAllowedRoots(config), appServerClient, now = () => Date.now(), backendIdleTtlMs = 300_000, forwarderClientFactory, observerReconnectTimeoutMs = 15_000, sessionId, runtimeHomeSessionId, }) {
+    constructor({ config, commandRunner, sessionStore = new FileCodexSessionStore(resolveCodexSessionStorePath(config)), allowedRoots = resolveAllowedRoots(config), appServerClient, now = () => Date.now(), backendIdleTtlMs = 300_000, forwarderClientFactory, preloadClientFactory, injectionClientFactory, sessionId, runtimeHomeSessionId, }) {
         this.config = config;
         this.sessionId = sessionId ?? "__default__";
         this.runtimeHomeSessionId = runtimeHomeSessionId ?? this.sessionId;
@@ -292,10 +298,10 @@ export class LocalAgentHost {
         this.injectedAppServerClient = appServerClient;
         this.clock = now;
         this.backendIdleTtlMs = backendIdleTtlMs;
-        this.observerReconnectTimeoutMs = observerReconnectTimeoutMs;
-        this.forwarderClientFactory =
-            forwarderClientFactory ??
-                ((appServerUrl) => new CodexAppServerClient({ channel: new ExternalWsChannel(appServerUrl) }));
+        const defaultAttachedClientFactory = (appServerUrl) => new CodexAppServerClient({ channel: new ExternalWsChannel(appServerUrl) });
+        this.forwarderClientFactory = forwarderClientFactory ?? defaultAttachedClientFactory;
+        this.preloadClientFactory = preloadClientFactory ?? defaultAttachedClientFactory;
+        this.injectionClientFactory = injectionClientFactory ?? defaultAttachedClientFactory;
     }
     getBackend(runtime, budget) {
         this.reapIdleBackends();
@@ -412,36 +418,7 @@ export class LocalAgentHost {
         if (live.settledInteractions.has(interactionId)) {
             return { disposition: "already_resolved" };
         }
-        if (live.interactionRecoveries.has(interactionId)) {
-            return {
-                disposition: "invalid",
-                message: "interaction delivery is recovering; retry shortly",
-            };
-        }
-        const submit = (client) => {
-            // Store before entering the client: a transport can report a synchronous
-            // write failure, and failover must already have the exact accepted answer
-            // available for replay. A synchronous terminal event may delete it again.
-            const hadPrevious = live.interactionSubmissions.has(interactionId);
-            const previous = live.interactionSubmissions.get(interactionId);
-            live.interactionSubmissions.set(interactionId, resolution);
-            const result = client.resolveInteraction(interactionId, resolution);
-            if (result.disposition !== "applied") {
-                if (hadPrevious && previous)
-                    live.interactionSubmissions.set(interactionId, previous);
-                else
-                    live.interactionSubmissions.delete(interactionId);
-            }
-            return result;
-        };
-        const owner = live.interactionOwners.get(interactionId);
-        if (owner)
-            return submit(owner);
-        const injected = submit(live.injectClient);
-        if (injected.disposition !== "not_found") {
-            return injected;
-        }
-        return submit(live.forwarderClient);
+        return live.forwarderClient.resolveInteraction(interactionId, resolution);
     }
     /**
      * The command to run in a session's live terminal so it co-drives the codex
@@ -596,7 +573,7 @@ export class LocalAgentHost {
                 snapshotSkills = await this.prepareExecutionSkills(execution);
             }
             catch (err) {
-                this.liveStartupErrors.set(localThreadId, `${runtime === "traex" ? "Traex" : "Codex"} skill preparation failed: ${err instanceof Error ? err.message : String(err)}`);
+                this.liveStartupErrors.set(localThreadId, nativeLiveFailure(runtime, "native_skill_preparation_failed", "skill preparation failed", err));
                 console.error(`[session-snapshot] session=${localThreadId} skill materialization failed: ${err instanceof Error ? err.message : String(err)}`);
                 return false;
             }
@@ -609,7 +586,7 @@ export class LocalAgentHost {
         }
         catch (err) {
             void snapshotSkills.skillsCleanup();
-            this.liveStartupErrors.set(localThreadId, `${runtime === "traex" ? "Traex" : "Codex"} skill persistence failed: ${err instanceof Error ? err.message : String(err)}`);
+            this.liveStartupErrors.set(localThreadId, nativeLiveFailure(runtime, "native_skill_persistence_failed", "skill persistence failed", err));
             console.error(`[session-snapshot] session=${localThreadId} skill persistence failed: ${err instanceof Error ? err.message : String(err)}`);
             return false;
         }
@@ -627,37 +604,45 @@ export class LocalAgentHost {
             void snapshotSkills.skillsCleanup();
             return false;
         };
-        const injectClient = this.getBackend(runtime, execution.budget ?? undefined).appServerClient;
-        if (!injectClient) {
-            this.liveStartupErrors.set(localThreadId, `${runtime === "traex" ? "Traex" : "Codex"} app-server is unavailable for this Session`);
+        const appServerOwner = this.getBackend(runtime, execution.budget ?? undefined).appServerClient;
+        if (!appServerOwner) {
+            this.liveStartupErrors.set(localThreadId, nativeLiveFailure(runtime, "native_app_server_unavailable", "app-server is unavailable for this Session"));
             console.error(`[codex-live] session=${localThreadId} runtime=${runtime} no app-server client`);
             return abandon();
         }
         try {
-            await injectClient.ensureInitialized();
+            await appServerOwner.ensureInitialized();
         }
         catch (err) {
-            this.liveStartupErrors.set(localThreadId, `${runtime === "traex" ? "Traex" : "Codex"} app-server initialization failed during its 10s readiness phase: ${err instanceof Error ? err.message : String(err)}`);
+            this.liveStartupErrors.set(localThreadId, nativeLiveFailure(runtime, "native_app_server_start_failed", "app-server initialization failed during its 10s readiness phase", err));
             console.error(`[codex-live] session=${localThreadId} runtime=${runtime} app-server init failed: ${err instanceof Error ? err.message : String(err)}`);
             return abandon();
         }
-        const appServerUrl = injectClient.terminalRemoteUrl();
+        const appServerUrl = appServerOwner.terminalRemoteUrl();
         if (!appServerUrl) {
-            this.liveStartupErrors.set(localThreadId, `${runtime === "traex" ? "Traex" : "Codex"} app-server started without a Terminal remote endpoint`);
+            this.liveStartupErrors.set(localThreadId, nativeLiveFailure(runtime, "native_app_server_endpoint_missing", "app-server started without a Terminal remote endpoint"));
             console.error(`[codex-live] session=${localThreadId} runtime=${runtime} app-server has no remote url`);
             return abandon(); // needs the ws app-server (live-terminal mode)
         }
         // reference implementation multi-connection: a SEPARATE forwarder connection to the SAME
         // app-server, which `thread/resume`s to subscribe to the thread's item/turn
         // notifications (the backend client injects; this one only observes).
+        // Fresh sessions must connect this listener before the TUI launches so its
+        // one-shot `thread/started` cannot race discovery. A known-thread cold resume
+        // already has its durable id: like Omnigent's `_codex_forward_known_thread`,
+        // its observer starts in the background only after the replacement TUI has
+        // launched and is never part of the resume admission boundary.
         const forwarderClient = this.forwarderClientFactory(appServerUrl);
-        try {
-            await forwarderClient.ensureInitialized();
-        }
-        catch (err) {
-            this.liveStartupErrors.set(localThreadId, `${runtime === "traex" ? "Traex" : "Codex"} observer could not attach to the ready app-server: ${err instanceof Error ? err.message : String(err)}`);
-            console.error(`[codex-live] session=${localThreadId} runtime=${runtime} forwarder init failed: ${err instanceof Error ? err.message : String(err)}`);
-            return abandon();
+        const coldResume = Boolean(record?.codexSessionId);
+        if (!coldResume) {
+            try {
+                await forwarderClient.ensureInitialized();
+            }
+            catch (err) {
+                this.liveStartupErrors.set(localThreadId, nativeLiveFailure(runtime, "native_fresh_listener_failed", "fresh-thread listener could not attach to the ready app-server", err));
+                console.error(`[codex-live] session=${localThreadId} runtime=${runtime} fresh-thread listener init failed: ${err instanceof Error ? err.message : String(err)}`);
+                return abandon();
+            }
         }
         const model = execution.model ?? "";
         const reasoningEffort = execution.reasoningEffort ?? undefined;
@@ -674,7 +659,8 @@ export class LocalAgentHost {
             markTerminalReady = resolve;
         });
         const live = {
-            injectClient,
+            appServerOwner,
+            appServerUrl,
             forwarderClient,
             forwarder: null,
             runtime,
@@ -698,16 +684,10 @@ export class LocalAgentHost {
             subscribing: false,
             rotationPending: false,
             stopped: false,
-            observerAvailable: true,
+            observerAvailable: !coldResume,
             skillsCleanup: snapshotSkills.skillsCleanup,
-            interactionOwners: new Map(),
-            interactionStandbys: new Map(),
-            interactionSubmissions: new Map(),
             canonicalInteractions: new Set(),
             settledInteractions: new Set(),
-            interactionRecoveries: new Map(),
-            interactionFailedClients: new Map(),
-            disconnectedClients: new Set(),
         };
         let currentSessionId = localThreadId;
         let pendingRotationEvents = null;
@@ -795,168 +775,81 @@ export class LocalAgentHost {
             for (const se of n.next(agentEvent))
                 emitCurrent(se);
         };
-        const clearRecovery = (interactionId) => {
-            live.interactionRecoveries.delete(interactionId);
-        };
-        const clearInteractionRouting = (interactionId) => {
-            clearRecovery(interactionId);
-            live.interactionOwners.delete(interactionId);
-            live.interactionStandbys.delete(interactionId);
-            live.interactionSubmissions.delete(interactionId);
-            live.interactionFailedClients.delete(interactionId);
-        };
-        const markInteractionClientFailed = (interactionId, client) => {
-            const failed = live.interactionFailedClients.get(interactionId) ?? new Set();
-            failed.add(client);
-            live.interactionFailedClients.set(interactionId, failed);
-        };
-        const interactionClientUnavailable = (interactionId, client) => live.disconnectedClients.has(client) ||
-            live.interactionFailedClients.get(interactionId)?.has(client) === true;
-        const allInteractionClientsUnavailable = (interactionId) => [live.injectClient, live.forwarderClient].every((client) => interactionClientUnavailable(interactionId, client));
-        const finishRecovery = (interactionId, event) => {
-            clearInteractionRouting(interactionId);
-            forwardInteraction(event);
-        };
-        const beginRecovery = (interactionId, event) => {
-            live.interactionOwners.delete(interactionId);
-            live.interactionRecoveries.set(interactionId, { event });
-        };
-        const promoteInteractionOwner = (interactionId, replacement) => {
-            const recovery = live.interactionRecoveries.get(interactionId);
-            live.interactionOwners.set(interactionId, replacement);
-            const submission = live.interactionSubmissions.get(interactionId);
-            if (!submission) {
-                clearRecovery(interactionId);
-                return true;
-            }
-            const replayed = replacement.resolveInteraction(interactionId, submission);
-            // A write failure can synchronously re-enter the listener and remove this
-            // owner. Only clear recovery when the replacement still owns the request.
-            if (replayed.disposition === "applied" &&
-                live.interactionOwners.get(interactionId) === replacement) {
-                clearRecovery(interactionId);
-                return true;
-            }
-            if (live.interactionOwners.get(interactionId) === replacement) {
-                live.interactionOwners.delete(interactionId);
-            }
-            if (recovery &&
-                live.canonicalInteractions.has(interactionId) &&
-                !live.settledInteractions.has(interactionId) &&
-                !live.interactionRecoveries.has(interactionId)) {
-                live.interactionRecoveries.set(interactionId, recovery);
-            }
-            return false;
-        };
-        const bindInteractionClient = (client) => {
-            client.setInteractionListener((event) => {
-                const interactionId = event.type === "requested"
-                    ? event.request.interactionId
-                    : event.interactionId;
-                const owner = live.interactionOwners.get(interactionId);
-                if (event.type === "requested") {
-                    // Receiving a native request proves this connection is alive and can
-                    // be retried even if an earlier copy failed on it.
-                    live.disconnectedClients.delete(client);
-                    const failed = live.interactionFailedClients.get(interactionId);
-                    failed?.delete(client);
-                    if (failed?.size === 0)
-                        live.interactionFailedClients.delete(interactionId);
-                    if (live.settledInteractions.has(interactionId))
-                        return;
-                    const recovery = live.interactionRecoveries.get(interactionId);
-                    if (recovery) {
-                        promoteInteractionOwner(interactionId, client);
-                        return;
-                    }
-                    if (owner && owner !== client) {
-                        const standbys = live.interactionStandbys.get(interactionId) ?? new Set();
-                        standbys.add(client);
-                        live.interactionStandbys.set(interactionId, standbys);
-                        return;
-                    }
-                    live.interactionOwners.set(interactionId, client);
-                    forwardInteraction(event);
-                    return;
-                }
-                const recoverableOwnerFailure = event.type === "cancelled" &&
-                    (event.reason === "app_server_disconnected" || event.reason === "response_write_failed");
-                if (recoverableOwnerFailure)
-                    markInteractionClientFailed(interactionId, client);
-                if (!owner || owner !== client) {
-                    const standbys = live.interactionStandbys.get(interactionId);
-                    standbys?.delete(client);
-                    if (standbys?.size === 0)
-                        live.interactionStandbys.delete(interactionId);
-                    const recovery = live.interactionRecoveries.get(interactionId);
-                    if (recoverableOwnerFailure &&
-                        live.canonicalInteractions.has(interactionId) &&
-                        allInteractionClientsUnavailable(interactionId)) {
-                        finishRecovery(interactionId, recovery?.event ?? event);
-                    }
-                    return;
-                }
-                if (recoverableOwnerFailure) {
-                    const standbys = live.interactionStandbys.get(interactionId);
-                    while (standbys && standbys.size > 0) {
-                        const replacement = standbys.values().next().value;
-                        if (!replacement)
-                            break;
-                        standbys.delete(replacement);
-                        if (interactionClientUnavailable(interactionId, replacement))
-                            continue;
-                        if (promoteInteractionOwner(interactionId, replacement)) {
-                            if (standbys.size === 0)
-                                live.interactionStandbys.delete(interactionId);
-                            return;
-                        }
-                        if (live.settledInteractions.has(interactionId))
-                            return;
-                    }
-                    if (!live.settledInteractions.has(interactionId)) {
-                        if (allInteractionClientsUnavailable(interactionId)) {
-                            finishRecovery(interactionId, event);
-                        }
-                        else {
-                            beginRecovery(interactionId, event);
-                        }
-                        return;
-                    }
-                }
-                clearInteractionRouting(interactionId);
-                forwardInteraction(event);
-            });
+        const bindObserverClient = (client) => {
+            client.setInteractionListener(forwardInteraction);
             client.setConnectionListener((state) => {
-                if (state === "connected") {
-                    // Observer transport recovery alone does not prove that an in-flight
-                    // interaction request was replayed onto this connection. Its request
-                    // listener clears disconnectedClients when that duplicate arrives.
-                    if (client !== live.forwarderClient)
-                        live.disconnectedClients.delete(client);
+                if (state === "connected" || live.stopped)
                     return;
+                live.observerAvailable = false;
+                for (const interactionId of [...live.canonicalInteractions]) {
+                    forwardInteraction({
+                        type: "cancelled",
+                        interactionId,
+                        reason: "app_server_disconnected",
+                    });
                 }
-                live.disconnectedClients.add(client);
-                if (client === live.forwarderClient && !live.stopped) {
-                    live.observerAvailable = false;
-                    this.armObserverReconnectDeadline(live);
-                    void this.reconnectForwarder(live);
-                }
-                for (const [interactionId, recovery] of [...live.interactionRecoveries]) {
-                    if (allInteractionClientsUnavailable(interactionId)) {
-                        finishRecovery(interactionId, recovery.event);
-                    }
-                }
+                this.failObserverLifecycle(localThreadId, live, nativeLiveFailure(runtime, "native_observer_disconnected", "observer connection closed"));
             });
         };
         const closeCanonicalInteractions = () => {
             for (const interactionId of live.canonicalInteractions) {
                 rememberSettledInteraction(interactionId);
-                clearInteractionRouting(interactionId);
             }
             live.canonicalInteractions.clear();
         };
+        const completeCurrentTurn = (usage, reason) => {
+            closeCanonicalInteractions();
+            if (!normalizer)
+                return;
+            const completedResponseId = currentResponseId;
+            if (usage) {
+                for (const se of normalizer.next({ type: "turn_completed", usage }))
+                    emitCurrent(se);
+            }
+            for (const se of normalizer.next({ type: "done" })) {
+                if (reason === "superseded" && se.type === "session.status")
+                    continue;
+                emitCurrent(se);
+            }
+            clearPendingInputsForResponse(completedResponseId);
+            normalizer = null;
+            currentResponseId = null;
+        };
+        const failCurrentTurn = (error) => {
+            closeCanonicalInteractions();
+            if (!normalizer)
+                return;
+            const failedResponseId = currentResponseId;
+            const responseStopped = error.message === "Codex turn was interrupted";
+            const providerName = runtime === "traex" ? "Traex" : "Codex";
+            const message = responseStopped
+                ? "Response stopped"
+                : runtime === "traex"
+                    ? error.message.replace(/^Codex\b/, providerName)
+                    : error.message;
+            for (const se of normalizer.fail({
+                code: responseStopped
+                    ? "response_stopped"
+                    : runtime === "traex" ? "traex_error" : "codex_error",
+                message,
+                source: "execution",
+            })) {
+                emitCurrent(se.type === "session.status"
+                    ? { ...se, status: "failed", note: message }
+                    : se);
+            }
+            clearPendingInputsForResponse(failedResponseId);
+            normalizer = null;
+            currentResponseId = null;
+        };
         const sink = {
             onTurnStart: (turnId) => startNormalizer(turnId),
+            onTurnObserved: (turnId) => {
+                const n = startNormalizer(turnId);
+                for (const event of n.next({ type: "turn_started", ...(turnId ? { turnId } : {}) })) {
+                    emitCurrent(event);
+                }
+            },
             onUserMessage: (content) => {
                 const normalizedContent = typeof content === "string"
                     ? [{ type: "input_text", text: content }]
@@ -990,45 +883,28 @@ export class LocalAgentHost {
                     ...(statusKind ? { statusKind } : {}),
                 });
             },
-            onTurnEnd: (usage) => {
-                closeCanonicalInteractions();
-                if (!normalizer)
+            // A newer authoritative turn/started completes the old canonical
+            // response without publishing a false idle edge in a running→running
+            // transition.
+            onTurnEnd: completeCurrentTurn,
+            onRecoveredTurnStatus: (status, turnId, error) => {
+                const responseId = turnId ? `resp_codex_${turnId}` : undefined;
+                if (normalizer && (!responseId || currentResponseId === responseId)) {
+                    if (status === "failed")
+                        failCurrentTurn(error ?? new Error("Codex turn failed"));
+                    else
+                        completeCurrentTurn();
                     return;
-                const completedResponseId = currentResponseId;
-                if (usage) {
-                    for (const se of normalizer.next({ type: "turn_completed", usage }))
-                        emitCurrent(se);
                 }
-                for (const se of normalizer.next({ type: "done" }))
-                    emitCurrent(se);
-                clearPendingInputsForResponse(completedResponseId);
-                normalizer = null;
-                currentResponseId = null;
-            },
-            onTurnError: (error) => {
-                closeCanonicalInteractions();
-                if (!normalizer)
-                    return;
-                const failedResponseId = currentResponseId;
-                const responseStopped = error.message === "Codex turn was interrupted";
-                const providerName = runtime === "traex" ? "Traex" : "Codex";
-                const message = responseStopped
-                    ? "Response stopped"
-                    : runtime === "traex"
-                        ? error.message.replace(/^Codex\b/, providerName)
-                        : error.message;
-                for (const se of normalizer.fail({
-                    code: responseStopped
-                        ? "response_stopped"
-                        : runtime === "traex" ? "traex_error" : "codex_error",
-                    message,
-                    source: "execution",
-                }))
-                    emitCurrent(se);
-                clearPendingInputsForResponse(failedResponseId);
-                normalizer = null;
-                currentResponseId = null;
+                emitCurrent({
+                    type: "session.status",
+                    sessionId: currentSessionId,
+                    ...(responseId ? { responseId } : {}),
+                    status,
+                    ...(error ? { note: error.message } : {}),
+                });
             },
+            onTurnError: failCurrentTurn,
             // A resumed TUI may rebroadcast `thread/started`; binding is idempotent.
             shouldIgnoreThreadStarted: (threadId, forkedFromId) => this.shouldIgnoreManagedForkThreadStarted(live, threadId, forkedFromId),
             onThreadStarted: (threadId, forkedFromId) => this.onLiveThreadStarted(live, localThreadId, threadId, forkedFromId),
@@ -1089,7 +965,7 @@ export class LocalAgentHost {
                 live.rotationPending = false;
                 for (const event of queued)
                     emit(event);
-                void this.subscribeUntilReady(live, threadId);
+                void this.subscribeUntilReady(newSessionId, live, threadId);
             })
                 .catch(() => {
                 pendingRotationEvents = null;
@@ -1097,8 +973,7 @@ export class LocalAgentHost {
                 live.stopped = true;
             });
         };
-        bindInteractionClient(injectClient);
-        bindInteractionClient(forwarderClient);
+        bindObserverClient(forwarderClient);
         this.liveSessions.set(localThreadId, live);
         forwarder.start();
         // Existing bindings resume through the public app-server API. A fresh thread
@@ -1108,57 +983,53 @@ export class LocalAgentHost {
         // turn-less app-server thread resumable by the TUI.
         try {
             if (record?.codexSessionId) {
-                let resumeError;
-                let resumedThreadId;
-                const attempts = 20;
-                for (let attempt = 0; attempt < attempts; attempt += 1) {
+                // Match Omnigent's cold-resume preload exactly: one history-free
+                // `thread/resume` on a short-lived, separately initialized connection.
+                // The backend owner's handshake above is the app-server readiness
+                // probe; reusing that first connection here races Codex's startup state
+                // and can return `Not initialized`. A failure stays attached to the
+                // original binding and is reported by this phase; it is not polled.
+                const preloadClient = this.preloadClientFactory(appServerUrl);
+                try {
+                    let resumed;
                     try {
-                        const resumed = await injectClient.threadResume({
+                        await preloadClient.ensureInitialized();
+                        resumed = await preloadClient.threadResume({
                             threadId: record.codexSessionId,
                             ...threadWorkspaceParams(runtime, workspace, sandbox),
                             approvalPolicy,
-                            // The injection connection only needs to bind/subcribe. Codex
-                            // 0.146 can ignore initialTurnsPage and return the whole rollout,
-                            // so explicitly suppress history here; it is never replayed.
                             excludeTurns: true,
-                            initialTurnsPage: {
-                                limit: 1,
-                                sortDirection: "desc",
-                                itemsView: "summary",
-                            },
                         });
-                        resumedThreadId = resumed.threadId;
-                        break;
                     }
-                    catch (error) {
-                        resumeError = error;
-                        if (!isRetryableThreadResumeError(error))
-                            throw error;
-                        if (attempt + 1 < attempts) {
-                            await new Promise((resolve) => setTimeout(resolve, 150));
-                        }
+                    finally {
+                        await preloadClient.stop().catch((error) => {
+                            console.warn(`[codex-live] session=${localThreadId} runtime=${runtime} preload client cleanup failed: ${error instanceof Error ? error.message : String(error)}`);
+                        });
                     }
+                    forwarder.noteThreadBound(resumed.threadId);
+                    this.onLiveThreadStarted(live, localThreadId, resumed.threadId);
                 }
-                if (resumedThreadId) {
-                    this.onLiveThreadStarted(live, localThreadId, resumedThreadId);
-                }
-                else if (resumeError &&
-                    isThreadNotReadyError(resumeError) &&
-                    !record.parentSessionId &&
-                    !record.runtimeHomeOwnerSessionId) {
-                    // A native thread that still has no rollout after the bounded retry
-                    // window has never materialized a Turn. It is safe to forget this
-                    // ordinary binding and let the TUI create a fresh native thread.
-                    // Fork bindings stay strict because their Provider-native ancestry
-                    // must not be silently replaced.
+                catch (error) {
+                    if (!isThreadNotReadyError(error) ||
+                        record.parentSessionId ||
+                        record.runtimeHomeOwnerSessionId) {
+                        throw error;
+                    }
+                    // Preserve the existing turn-less binding recovery without polling:
+                    // an ordinary native id with no rollout/turn has no Provider history
+                    // to retain. Fork bindings remain strict, and `thread not found` is
+                    // not classified here because it does not prove the history is empty.
                     await this.sessionStore.delete(localThreadId);
                     live.threadId = null;
+                    try {
+                        await forwarderClient.ensureInitialized();
+                    }
+                    catch (listenerError) {
+                        throw nativeLiveFailure(runtime, "native_fresh_listener_failed", "fresh-thread listener could not attach after the turn-less binding was replaced", listenerError);
+                    }
+                    live.observerAvailable = true;
                     live.markTerminalReady(true);
-                }
-                else {
-                    // A delayed/missing native index or a fork binding remains explicit:
-                    // neither is proof that replacing Provider history is safe.
-                    throw resumeError;
+                    console.warn(`[codex-live] session=${localThreadId} runtime=${runtime} replaced turn-less native binding ${record.codexSessionId} with fresh discovery`);
                 }
             }
             else {
@@ -1173,7 +1044,10 @@ export class LocalAgentHost {
             live.stopped = true;
             forwarder.stop();
             void forwarderClient.stop().catch(() => undefined);
-            this.liveStartupErrors.set(localThreadId, `${runtime === "traex" ? "Traex" : "Codex"} native thread binding failed: ${err instanceof Error ? err.message : String(err)}`);
+            const failure = err instanceof CodexRuntimeError
+                ? err
+                : nativeLiveFailure(runtime, "native_resume_failed", "existing native session could not be resumed", err);
+            this.liveStartupErrors.set(localThreadId, failure);
             console.error(`[codex-live] session=${localThreadId} runtime=${runtime} thread bind failed: ${err instanceof Error ? err.message : String(err)}`);
             return abandon();
         }
@@ -1213,7 +1087,57 @@ export class LocalAgentHost {
         })
             .catch(() => undefined);
         live.markReady(); // thread id known → injection can turn/start
-        void this.subscribeUntilReady(live, threadId).then(live.markTerminalReady);
+        if (live.observerAvailable) {
+            void this.subscribeUntilReady(localThreadId, live, threadId).then(live.markTerminalReady);
+        }
+        else {
+            // Known-thread cold resume has already completed the dedicated preload. Its
+            // observer is deliberately post-TUI background work, not Terminal
+            // readiness. RunnerSession calls startLiveCodexObserver after launch.
+            live.markTerminalReady(true);
+        }
+    }
+    /** Start the known-thread observer after the replacement TUI has launched.
+     * Fresh sessions already connected their discovery listener before launch;
+     * this is therefore an idempotent no-op for them and for a healthy observer. */
+    startLiveCodexObserver(localThreadId) {
+        const live = this.liveSessions.get(localThreadId);
+        if (!live ||
+            live.stopped ||
+            live.observerAvailable ||
+            !live.threadId)
+            return;
+        void (async () => {
+            try {
+                await live.forwarderClient.ensureInitialized();
+                if (live.stopped)
+                    return;
+                live.observerAvailable = true;
+                // Omnigent starts subscription as a sibling task after the transport
+                // connects. A no/empty rollout remains event-driven retryable; any
+                // other subscription rejection is diagnostic only and must not tear
+                // down the otherwise usable Terminal/injection lifecycle.
+                void this.subscribeUntilReady(localThreadId, live, live.threadId);
+            }
+            catch (error) {
+                this.failObserverLifecycle(localThreadId, live, nativeLiveFailure(live.runtime, "native_observer_connect_failed", "observer could not attach to the ready app-server", error));
+            }
+        })();
+    }
+    /** Omnigent treats the forwarder as a required component of one native
+     * lifecycle: if its transport dies, it closes the app-server instead of
+     * accepting turns that can no longer reach the canonical mirror. */
+    failObserverLifecycle(localThreadId, live, error) {
+        if (live.stopped)
+            return;
+        live.startupError = error;
+        this.liveStartupErrors.set(localThreadId, error);
+        live.forwarder.failOpenTurn(error);
+        const appServerOwner = live.appServerOwner;
+        this.stopLiveCodexSession(localThreadId);
+        void appServerOwner.stop().catch((stopError) => {
+            console.warn(`[codex-live] session=${localThreadId} runtime=${live.runtime} app-server cleanup after observer failure failed: ${stopError instanceof Error ? stopError.message : String(stopError)}`);
+        });
     }
     shouldIgnoreManagedForkThreadStarted(live, threadId, forkedFromId) {
         const pending = live.managedFork;
@@ -1237,37 +1161,36 @@ export class LocalAgentHost {
      * Subscribe the forwarder connection to a thread (reference implementation's
      * `_subscribe_until_ready`). A fresh TUI thread has no rollout until its first
      * turn, so `thread/resume` is retried: park until the forwarder observes the
-     * thread active, then retry. Resume only fetches the newest summarized Turn:
-     * recovery reconciles the exact active Turn's terminal status and never replays
-     * historical items. Once resume succeeds, subsequent turns arrive live.
+     * thread active, then retry. Like Omnigent, the first attempt always uses
+     * `excludeTurns`: a known-session cold resume therefore never reconstructs
+     * historical running/completed state. Only a fresh thread whose first attempt
+     * failed as not-ready retries without `excludeTurns`, backfilling the newly
+     * materialized first turn and de-duplicating it against live notifications.
      */
-    async subscribeUntilReady(live, threadId) {
+    async subscribeUntilReady(localThreadId, live, threadId) {
+        let sawNotReady = false;
         while (!live.stopped) {
             try {
                 const resp = await live.forwarderClient.threadResume({
                     threadId,
                     ...threadWorkspaceParams(live.runtime, live.workspace, live.sandbox),
                     approvalPolicy: live.approvalPolicy,
-                    initialTurnsPage: {
-                        limit: 1,
-                        sortDirection: "desc",
-                        itemsView: "summary",
-                    },
+                    ...(!sawNotReady ? { excludeTurns: true } : {}),
                 });
-                // Codex 0.146.1 accepts initialTurnsPage but can still return the entire
-                // rollout in chronological order. Never infer newest from array position:
-                // recovery may settle only the exact active turn id already owned here.
-                const activeTurnId = live.forwarder.currentTurnId();
-                const activeTurn = activeTurnId && Array.isArray(resp.thread.turns)
-                    ? resp.thread.turns.find((turn) => (turn.id ?? turn.turnId) === activeTurnId)
-                    : undefined;
-                live.forwarder.reconcileActiveTurn(activeTurn);
+                if (sawNotReady) {
+                    const turns = Array.isArray(resp.thread.turns)
+                        ? resp.thread.turns
+                        : [];
+                    live.forwarder.replayBackfill(turns);
+                }
                 return true; // subscribed — live item/turn notifications now flow to the forwarder
             }
             catch (error) {
                 if (!isThreadNotReadyError(error)) {
-                    return false; // other failure — injection still works via the backend client
+                    console.warn(`[codex-live] session=${localThreadId} runtime=${live.runtime} observer failed to subscribe to thread ${threadId}: ${error instanceof Error ? error.message : String(error)}`);
+                    return false;
                 }
+                sawNotReady = true;
                 // Park until the thread goes active (its first turn materializes the
                 // rollout); a short poll covers the flush race after "active".
                 await new Promise((resolve) => {
@@ -1279,54 +1202,6 @@ export class LocalAgentHost {
         }
         return false;
     }
-    /** Restore the independent observer after an unexpected exit. The active turn
-     * remains open during the bounded grace so resume can reconcile its exact id. */
-    reconnectForwarder(live) {
-        if (live.observerReconnect)
-            return live.observerReconnect;
-        const reconnect = (async () => {
-            while (!live.stopped && live.threadId) {
-                try {
-                    await live.forwarderClient.ensureInitialized();
-                    if (await this.subscribeUntilReady(live, live.threadId)) {
-                        live.observerAvailable = true;
-                        this.clearObserverReconnectDeadline(live);
-                        return;
-                    }
-                }
-                catch {
-                    // Retry below. Injection uses its independent client and remains usable.
-                }
-                await new Promise((resolve) => {
-                    const timer = setTimeout(resolve, 250);
-                    timer.unref?.();
-                });
-            }
-        })();
-        const settled = reconnect.finally(() => {
-            if (live.observerReconnect === settled)
-                live.observerReconnect = undefined;
-        });
-        live.observerReconnect = settled;
-        return settled;
-    }
-    armObserverReconnectDeadline(live) {
-        if (live.observerReconnectTimer || !live.forwarder.isTurnOpen())
-            return;
-        live.observerReconnectTimer = setTimeout(() => {
-            live.observerReconnectTimer = undefined;
-            if (live.stopped)
-                return;
-            const provider = live.runtime === "traex" ? "Traex" : "Codex";
-            live.forwarder.failOpenTurn(new Error(`${provider} observer did not reconnect within ${this.observerReconnectTimeoutMs}ms`));
-        }, this.observerReconnectTimeoutMs);
-        live.observerReconnectTimer.unref?.();
-    }
-    clearObserverReconnectDeadline(live) {
-        if (live.observerReconnectTimer)
-            clearTimeout(live.observerReconnectTimer);
-        live.observerReconnectTimer = undefined;
-    }
     /** Await a live session's thread binding. `null` leaves the deadline to the
      *  caller; a number keeps the Provider-local bound. Returns false on timeout /
      *  no live session. Injection and the runner's `live.ready` gate on this. */
@@ -1350,9 +1225,9 @@ export class LocalAgentHost {
             clearTimeout(timer);
         return ok;
     }
-    /** Await the stronger Terminal gate: another app-server connection has
-     * successfully resumed the thread, so the detached TUI cannot race rollout
-     * discovery or indexing. */
+    /** Await the observer subscription diagnostic. Codex/Traex Terminal startup
+     * deliberately does not gate on this promise: the dedicated preload owns resume,
+     * while the independent observer attaches in the background. */
     async waitTerminalReady(localThreadId, timeoutMs = 20_000) {
         const claude = this.liveClaudeSessions.get(localThreadId);
         // Claude has no separate app-server indexing gate. Its TUI must launch first;
@@ -1376,8 +1251,24 @@ export class LocalAgentHost {
     /** Diagnostic from the provider adapter when native discovery/resume failed. */
     liveSessionError(localThreadId) {
         return this.liveClaudeSessions.get(localThreadId)?.error
-            ?? this.liveSessions.get(localThreadId)?.startupError
+            ?? this.liveSessions.get(localThreadId)?.startupError?.message
+            ?? this.liveStartupErrors.get(localThreadId)?.message;
+    }
+    /** Structured phase + concrete cause used by the runner wire protocol. */
+    liveSessionFailure(localThreadId) {
+        const failure = this.liveSessions.get(localThreadId)?.startupError
             ?? this.liveStartupErrors.get(localThreadId);
+        if (failure) {
+            return {
+                message: failure.message,
+                code: failure.code,
+                statusCode: failure.statusCode,
+            };
+        }
+        const claudeError = this.liveClaudeSessions.get(localThreadId)?.error;
+        return claudeError
+            ? { message: claudeError, code: "claude_native_start_failed", statusCode: 503 }
+            : undefined;
     }
     /** Publish the background TUI/thread discovery failure so an executor
      * already waiting in the 60s bridge window exits immediately with the exact
@@ -1386,8 +1277,11 @@ export class LocalAgentHost {
         const live = this.liveSessions.get(localThreadId);
         if (!live || live.threadId || live.stopped)
             return false;
-        live.startupError = error.message;
-        this.liveStartupErrors.set(localThreadId, error.message);
+        const failure = error instanceof CodexRuntimeError
+            ? error
+            : new CodexRuntimeError(error.message, 503, "native_thread_discovery_failed");
+        live.startupError = failure;
+        this.liveStartupErrors.set(localThreadId, failure);
         live.markStartupFailed();
         return true;
     }
@@ -1470,36 +1364,20 @@ export class LocalAgentHost {
                 if (index >= 0)
                     live.pendingInjectedInputs.splice(index, 1);
             };
+            const injectionClient = this.injectionClientFactory(live.appServerUrl);
             try {
-                // Inject via the BACKEND client (the forwarder connection only observes).
+                await injectionClient.ensureInitialized();
+                // Match Omnigent's executor: each message uses one initialized client
+                // that closes as soon as turn/start or turn/steer is acknowledged.
                 if (live.forwarder.isTurnOpen()) {
                     const turnId = live.forwarder.currentTurnId();
                     if (turnId) {
                         injectionMethod = "turn/steer";
-                        let steered;
-                        let retryIndex = 0;
-                        while (!steered) {
-                            try {
-                                steered = await live.injectClient.turnSteer({
-                                    threadId,
-                                    expectedTurnId: turnId,
-                                    input: nativeInput,
-                                });
-                            }
-                            catch (error) {
-                                const delayMs = TURN_STEER_ACTIVATION_RETRY_DELAYS_MS[retryIndex];
-                                if (delayMs === undefined ||
-                                    !isTransientTurnSteerActivationRace(error) ||
-                                    live.stopped ||
-                                    live.rotationPending ||
-                                    !live.forwarder.isTurnOpen() ||
-                                    live.forwarder.currentTurnId() !== turnId) {
-                                    throw error;
-                                }
-                                retryIndex += 1;
-                                await new Promise((resolve) => setTimeout(resolve, delayMs));
-                            }
-                        }
+                        const steered = await injectionClient.turnSteer({
+                            threadId,
+                            expectedTurnId: turnId,
+                            input: nativeInput,
+                        });
                         if (pendingInput.state === "prepublished") {
                             // The caller already persisted and published this user input
                             // before waiting for the native Terminal to become ready.
@@ -1512,15 +1390,12 @@ export class LocalAgentHost {
                             pendingInput.state = "optimistic";
                         }
                         live.forwarder.noteTurnAccepted(steered.turnId);
-                        if (!live.observerAvailable) {
-                            this.armObserverReconnectDeadline(live);
-                        }
-                        return "injected";
+                        return "steered";
                     }
                 }
                 // Carry the agent-spec model on the turn so a web-injected turn runs the
                 // agent's model even if the TUI's config default differs.
-                const started = await live.injectClient.turnStart({
+                const started = await injectionClient.turnStart({
                     threadId,
                     input: nativeInput,
                     ...turnWorkspaceParams(live.runtime, live.workspace, live.sandbox),
@@ -1543,9 +1418,6 @@ export class LocalAgentHost {
                 // Do not wait for the independent observer connection's `turn/started`:
                 // a second message accepted in that window must steer, not double-start.
                 live.forwarder.noteTurnAccepted(started.turnId);
-                if (!live.observerAvailable) {
-                    this.armObserverReconnectDeadline(live);
-                }
                 return "injected";
             }
             catch (error) {
@@ -1556,7 +1428,12 @@ export class LocalAgentHost {
                 const startupDetail = live.forwarder.mcpStartupDetail();
                 const detail = startupDetail ? `${baseDetail} (${startupDetail})` : baseDetail;
                 console.error(`[codex-live] session=${localThreadId} runtime=${live.runtime} injection failed: ${detail}`);
-                throw new Error(detail, { cause: error });
+                throw nativeLiveFailure(live.runtime, "native_message_injection_failed", `message injection via ${injectionMethod} failed`, detail);
+            }
+            finally {
+                await injectionClient.stop().catch((stopError) => {
+                    console.warn(`[codex-live] session=${localThreadId} runtime=${live.runtime} injection client cleanup failed: ${stopError instanceof Error ? stopError.message : String(stopError)}`);
+                });
             }
         });
         live.injectLock = run.then(() => undefined, () => undefined);
@@ -1607,27 +1484,34 @@ export class LocalAgentHost {
         if (!threadId)
             return pendingMcp.length > 0;
         let handled = pendingMcp.length > 0;
-        if (pendingMcp.length > 0) {
-            // Codex's TUI cancels a provider-owned MCP startup round with an empty
-            // turn id. Best-effort for Traex: it shares the app-server surface, while
-            // the active-turn interrupt below remains authoritative if it rejects this.
-            try {
-                await live.injectClient.turnInterrupt({ threadId, turnId: "" });
+        const interruptClient = this.injectionClientFactory(live.appServerUrl);
+        try {
+            await interruptClient.ensureInitialized();
+            if (pendingMcp.length > 0) {
+                // Codex's TUI cancels a provider-owned MCP startup round with an empty
+                // turn id. Best-effort for Traex: it shares the app-server surface, while
+                // the active-turn interrupt below remains authoritative if it rejects this.
+                try {
+                    await interruptClient.turnInterrupt({ threadId, turnId: "" });
+                }
+                catch (error) {
+                    console.warn(`[codex-live] session=${localThreadId} runtime=${live.runtime} MCP startup interrupt failed: ${codexRpcError(error, "turn/interrupt")}`);
+                }
             }
-            catch (error) {
-                console.warn(`[codex-live] session=${localThreadId} runtime=${live.runtime} MCP startup interrupt failed: ${codexRpcError(error, "turn/interrupt")}`);
+            if (turnId) {
+                try {
+                    await interruptClient.turnInterrupt({ threadId, turnId });
+                    handled = true;
+                }
+                catch {
+                    // The startup cancellation above is still a handled Stop operation.
+                }
             }
+            return handled;
         }
-        if (turnId) {
-            try {
-                await live.injectClient.turnInterrupt({ threadId, turnId });
-                handled = true;
-            }
-            catch {
-                // The startup cancellation above is still a handled Stop operation.
-            }
+        finally {
+            await interruptClient.stop().catch(() => undefined);
         }
-        return handled;
     }
     /** Stop + drop a session's live forwarder and its dedicated connection (session
      *  close / runner shutdown). The backend inject client is shared — left running. */
@@ -1654,24 +1538,17 @@ export class LocalAgentHost {
         this.liveSessions.delete(localThreadId);
         live.stopped = true;
         if (!live.threadId) {
-            live.startupError ??= "native Session stopped before thread discovery completed";
+            live.startupError ??= nativeLiveFailure(live.runtime, "native_thread_discovery_stopped", "Session stopped before native thread discovery completed");
             live.markStartupFailed();
         }
-        this.clearObserverReconnectDeadline(live);
         live.releaseActive?.();
-        live.injectClient.cancelInteractions("session_stopped");
+        live.appServerOwner.cancelInteractions("session_stopped");
         live.forwarderClient.cancelInteractions("session_stopped");
-        live.injectClient.setInteractionListener(null);
+        live.appServerOwner.setInteractionListener(null);
         live.forwarderClient.setInteractionListener(null);
-        live.injectClient.setConnectionListener(null);
+        live.appServerOwner.setConnectionListener(null);
         live.forwarderClient.setConnectionListener(null);
-        live.interactionOwners.clear();
-        live.interactionStandbys.clear();
-        live.interactionSubmissions.clear();
         live.forwarder.stop();
-        live.interactionRecoveries.clear();
-        live.interactionFailedClients.clear();
-        live.disconnectedClients.clear();
         live.canonicalInteractions.clear();
         live.settledInteractions.clear();
         void live.forwarderClient.stop().catch(() => undefined);
@@ -1988,6 +1865,17 @@ export class LocalAgentHost {
                     emitCurrent(se);
             },
             onInteraction: forwardInteraction,
+            onStatus: (status, blockedOn) => {
+                const responseId = currentResponseId ??
+                    live.pendingInjectedInputs.find((entry) => entry.responseId)?.responseId;
+                emitCurrent({
+                    type: "session.status",
+                    sessionId: currentSessionId,
+                    ...(responseId ? { responseId } : {}),
+                    status,
+                    ...(blockedOn ? { note: blockedOn } : {}),
+                });
+            },
             onTurnEnd: (usage) => {
                 if (!normalizer)
                     return;
@@ -2028,16 +1916,20 @@ export class LocalAgentHost {
                     });
                 }
             },
-            onTurnError: () => {
+            onTurnError: (error) => {
                 if (!normalizer)
                     return;
                 const rid = currentResponseId;
+                const message = error.message || "Agent turn failed";
                 for (const se of normalizer.fail({
                     code: "agent_error",
-                    message: "Agent turn failed",
+                    message,
                     source: "execution",
-                }))
-                    emitCurrent(se);
+                })) {
+                    emitCurrent(se.type === "session.status"
+                        ? { ...se, status: "failed", note: message }
+                        : se);
+                }
                 live.pendingInjectedInputs = live.pendingInjectedInputs.filter((entry) => entry.responseId !== rid);
                 normalizer = null;
                 currentResponseId = undefined;
@@ -2196,21 +2088,22 @@ export class LocalAgentHost {
      *  (they inject via the app-server). Idempotent. */
     attachTerminalInjector(localThreadId, injector) {
         const live = this.liveClaudeSessions.get(localThreadId);
-        if (live)
+        if (live) {
+            if (live.injector === injector)
+                return;
             live.injector = injector;
+            live.forwarder.attachStatusSource({ panePid: () => injector.panePid?.() });
+        }
     }
     /** Close an active native response when its terminal or runner disappears. */
     failLiveSession(localThreadId, error) {
         const claude = this.liveClaudeSessions.get(localThreadId);
         if (claude)
-            return claude.forwarder.failOpenTurn(error);
+            return claude.forwarder.noteTerminalExit(error);
         const codex = this.liveSessions.get(localThreadId);
         if (!codex)
             return false;
-        const failed = codex.forwarder.failOpenTurn(error);
-        if (failed)
-            this.clearObserverReconnectDeadline(codex);
-        return failed;
+        return codex.forwarder.failOpenTurn(error);
     }
     /** List the models a runtime exposes (App Server for codex/traex; static for claude). */
     async listModels(runtime) {
@@ -2240,7 +2133,7 @@ export class LocalAgentHost {
             return { ok: false, reason: "unsupported" };
         }
         try {
-            return { ok: true, data: await fn(live.injectClient, record.codexSessionId) };
+            return { ok: true, data: await fn(live.appServerOwner, record.codexSessionId) };
         }
         catch (error) {
             return {
@@ -2312,7 +2205,7 @@ export class LocalAgentHost {
                 return { ok: true, data: undefined };
             }
             const runtime = execution.provider;
-            const client = live?.injectClient ??
+            const client = live?.appServerOwner ??
                 this.getBackend(runtime, execution.budget ?? undefined).appServerClient;
             if (!client) {
                 return { ok: false, reason: "unsupported" };
@@ -2387,20 +2280,6 @@ function codexRpcError(error, method) {
     }
     return `Codex ${method} failed: ${error instanceof Error ? error.message : String(error)}`;
 }
-/**
- * Codex 0.146 can acknowledge `turn/start` a few milliseconds before its
- * internal active-turn pointer becomes visible to `turn/steer`. The injection
- * lock still prevents double-starts, but the immediately following steer must
- * briefly retry the same expected turn id. Keep this narrow: all other RPC
- * errors remain terminal and visible to the caller.
- */
-function isTransientTurnSteerActivationRace(error) {
-    return error instanceof CodexTransportError &&
-        error.code === -32600 &&
-        (/no active turn to steer/i.test(error.message) ||
-            /expected active turn id\b.+\bfound\b/i.test(error.message));
-}
-const TURN_STEER_ACTIVATION_RETRY_DELAYS_MS = [10, 20, 40, 80, 160, 250, 440];
 export function parseCodexLoginStatus(exitCode, output) {
     const normalized = output.trim();
     const match = normalized.match(/Logged in using (.+)$/im);
@@ -2502,10 +2381,13 @@ export function isThreadNotReadyError(error) {
     const message = (error instanceof Error ? error.message : String(error)).toLowerCase();
     return message.includes("no rollout found") || (message.includes("rollout") && message.includes("empty"));
 }
-/** A persisted thread id that a freshly started app-server cannot load yet.
- * During startup, both errors can be transient while the rollout index catches
- * up. Retry the same id; never use either error as permission to replace it. */
-export function isRetryableThreadResumeError(error) {
-    const message = (error instanceof Error ? error.message : String(error)).toLowerCase();
-    return message.includes("thread not found") || isThreadNotReadyError(error);
+/** Build the user-facing native lifecycle failure once, at the phase that owns
+ * it. Downstream layers preserve this code/message verbatim instead of replacing
+ * it with a generic "failed to start; see logs" wrapper. */
+function nativeLiveFailure(runtime, code, phase, cause, statusCode = 503) {
+    const provider = runtime === "traex" ? "Traex" : "Codex";
+    const detail = cause === undefined
+        ? ""
+        : `: ${cause instanceof Error ? cause.message : String(cause)}`;
+    return new CodexRuntimeError(`${provider} ${phase}${detail}`, statusCode, code);
 }