@rynx-ai/runtime 0.1.11-beta.21 → 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,163 +775,25 @@ 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();
         };
@@ -1123,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;
@@ -1131,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
@@ -1142,58 +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) {
-                    forwarder.noteThreadBound(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 {
@@ -1208,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();
         }
@@ -1248,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;
@@ -1272,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 or publishes the newest explicit
-     * terminal status without replaying 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. An identified active turn is matched
-                // by id; the no-active fallback reads only the final explicit status.
-                const turns = Array.isArray(resp.thread.turns)
-                    ? resp.thread.turns
-                    : [];
-                live.forwarder.reconcileResumeTurns(turns);
+                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) => {
@@ -1314,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. */
@@ -1385,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;
@@ -1411,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
@@ -1421,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;
     }
@@ -1505,13 +1364,16 @@ 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";
-                        const steered = await live.injectClient.turnSteer({
+                        const steered = await injectionClient.turnSteer({
                             threadId,
                             expectedTurnId: turnId,
                             input: nativeInput,
@@ -1528,15 +1390,12 @@ export class LocalAgentHost {
                             pendingInput.state = "optimistic";
                         }
                         live.forwarder.noteTurnAccepted(steered.turnId);
-                        if (!live.observerAvailable) {
-                            this.armObserverReconnectDeadline(live);
-                        }
                         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),
@@ -1559,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) {
@@ -1572,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);
@@ -1623,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. */
@@ -1670,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);
@@ -2242,10 +2103,7 @@ export class LocalAgentHost {
         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) {
@@ -2275,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 {
@@ -2347,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" };
@@ -2523,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);
 }