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

package/dist/runner/child.d.ts

@@ -7,7 +7,7 @@
  * per-thread capabilities, answered against the same backend so the parent never
  * needs an app-server of its own.
  */
-import { type AgentCapabilities, type ResolvedExecutionSnapshot, type RuntimeUserInput, type SessionInteractionResolution, type SessionWorkspaceSnapshot } from "@rynx-ai/core";
+import { type AgentCapabilities, type LiveSessionFailure, type ResolvedExecutionSnapshot, type RuntimeUserInput, type SessionInteractionResolution, type SessionWorkspaceSnapshot } from "@rynx-ai/core";
 import type { SessionEvent } from "@rynx-ai/core";
 import type { TerminalInjector } from "../claude/native-integration.js";
 import type { ResolveInteractionResult } from "../interactions.js";
@@ -38,11 +38,16 @@ interface LiveCodexProvider {
         execution: ResolvedExecutionSnapshot;
         retargetMirror?: RetargetMirror;
     }): Promise<boolean>;
+    /** Known-thread Codex/Traex resume only: start the independent transcript
+     * observer after the replacement TUI has launched. Fresh discovery connects
+     * its listener before launch and this method is an idempotent no-op. */
+    startLiveCodexObserver?(localThreadId: string): void;
     /** `null` delegates the deadline to RunnerManager. */
     waitLiveReady?(localThreadId: string, timeoutMs?: number | null): Promise<boolean>;
     /** `null` delegates the deadline to RunnerManager. */
     waitTerminalReady?(localThreadId: string, timeoutMs?: number | null): Promise<boolean>;
     liveSessionError?(localThreadId: string): string | undefined;
+    liveSessionFailure?(localThreadId: string): LiveSessionFailure | undefined;
     failLiveStartup?(localThreadId: string, error: Error): boolean;
     failLiveSession?(localThreadId: string, error: Error): boolean;
     injectMessage?(localThreadId: string, input: RuntimeUserInput | string): Promise<InjectOutcome>;
@@ -84,6 +89,8 @@ export declare class RunnerSession {
     private readonly cancelledTerminalOpens;
     /** Session ids with a live codex forwarder started here (stopped on shutdown). */
     private readonly liveIds;
+    /** Provider name retained for asynchronous Terminal-exit diagnostics. */
+    private readonly liveRuntimes;
     private shuttingDown;
     constructor({ transport, executor, onShutdown }: RunnerSessionDeps);
     private handle;
@@ -96,10 +103,10 @@ export declare class RunnerSession {
      *  the new session stays injectable. */
     private mirrorChannel;
     /**
-     * Eagerly bring up a session's codex-native live view: start the persistent
-     * observer connection before launching the detached Codex TUI. Fresh-session
-     * thread discovery then continues in the background while the first
-     * injection waits for the same bridge state.
+     * Eagerly bring up a session's codex-native live view. Fresh sessions connect
+     * the discovery listener before launching the detached TUI; known-thread
+     * resumes preload first, launch the replacement TUI, then start their
+     * persistent observer in the background.
      */
     private ensureLive;
     private monitorCodexThreadStartup;

package/dist/runner/child.js

@@ -1,8 +1,43 @@
+/**
+ * Child-side runner session. One per runner process (i.e. per session); owns the
+ * single execution backend via the injected executor (a {@link LocalAgentHost}
+ * in production, which in a per-session process holds exactly one backend). It
+ * translates inbound {@link ToChild} control messages into the live co-drive
+ * surface (bring up the session's forwarder + TUI, inject / interrupt turns) and
+ * per-thread capabilities, answered against the same backend so the parent never
+ * needs an app-server of its own.
+ */
+import { AgentRuntimeError, } from "@rynx-ai/core";
 import { TerminalRegistry } from "../terminal/registry.js";
-import { toWireError } from "./protocol.js";
-import { isManagedNativeProvider } from "./startup-policy.js";
+import { toWireError, } from "./protocol.js";
+import { isCodexLineageProvider } from "./startup-policy.js";
 /** Maximum time for a fresh Codex-lineage TUI to publish its native thread. */
 const CODEX_THREAD_START_TIMEOUT_MS = 30_000;
+function providerDisplayName(runtime) {
+    return runtime === "traex" ? "Traex" : runtime === "claude" ? "Claude" : "Codex";
+}
+function providerFailure(provider, localThreadId, fallback) {
+    return provider.liveSessionFailure?.(localThreadId) ?? {
+        message: provider.liveSessionError?.(localThreadId) ?? fallback.message,
+        code: fallback.code,
+        statusCode: 503,
+    };
+}
+function nativePhaseError(runtime, code, phase, cause) {
+    const detail = cause === undefined
+        ? ""
+        : `: ${cause instanceof Error ? cause.message : String(cause)}`;
+    return new AgentRuntimeError(`${providerDisplayName(runtime)} ${phase}${detail}`, 503, code);
+}
+function terminalFailureDetail(pane) {
+    return pane
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .slice(-6)
+        .join(" ")
+        .slice(-1_000);
+}
 const TRAEX_STARTUP_WATCH_MS = 20_000;
 const TRAEX_STARTUP_POLL_MS = 100;
 const TRAEX_AUTHORIZATION_POLL_MS = 500;
@@ -38,6 +73,8 @@ export class RunnerSession {
     cancelledTerminalOpens = new Set();
     /** Session ids with a live codex forwarder started here (stopped on shutdown). */
     liveIds = new Set();
+    /** Provider name retained for asynchronous Terminal-exit diagnostics. */
+    liveRuntimes = new Map();
     shuttingDown = false;
     constructor({ transport, executor, onShutdown }) {
         this.transport = transport;
@@ -159,10 +196,10 @@ export class RunnerSession {
         return { emit, retarget };
     }
     /**
-     * Eagerly bring up a session's codex-native live view: start the persistent
-     * observer connection before launching the detached Codex TUI. Fresh-session
-     * thread discovery then continues in the background while the first
-     * injection waits for the same bridge state.
+     * Eagerly bring up a session's codex-native live view. Fresh sessions connect
+     * the discovery listener before launching the detached TUI; known-thread
+     * resumes preload first, launch the replacement TUI, then start their
+     * persistent observer in the background.
      */
     async ensureLive(msg) {
         const provider = this.liveProvider;
@@ -174,34 +211,38 @@ export class RunnerSession {
                 retargetMirror: retarget,
             });
             if (!started) {
+                const runtime = msg.execution?.provider;
                 this.transport.send({
                     t: "live.ready",
                     reqId: msg.reqId,
                     localThreadId: msg.localThreadId,
                     ok: false,
-                    error: provider.liveSessionError?.(msg.localThreadId)
-                        ?? "live provider did not start",
+                    error: providerFailure(provider, msg.localThreadId, {
+                        runtime,
+                        code: "native_start_failed",
+                        message: `${providerDisplayName(runtime)} native session did not start`,
+                    }),
                 });
                 return;
             }
             this.liveIds.add(msg.localThreadId);
-            // Codex-lineage startup is phase-bounded: app-server readiness is
-            // handled by its channel, then the already-connected
-            // observer gets a full window for the TUI's thread/started event.
-            // Claude retains the parent-owned SessionStart deadline.
             const runtime = msg.execution?.provider;
-            // Do not add another provider-local deadline around resume/preload. The
-            // parent control request remains bounded for process safety; fresh-thread
-            // discovery owns the separate 30s phase below.
-            const terminalReadyTimeoutMs = isManagedNativeProvider(runtime) ? null : undefined;
+            if (runtime)
+                this.liveRuntimes.set(msg.localThreadId, runtime);
             // Launch the TUI attached to the already-bound thread. Re-launch when the
             // pane is absent OR its process has died (`isAlive` probes `#{pane_dead}`) — so a
             // reconnect after the TUI exited restarts it instead of skipping (a
             // launched-once guard would leave a dead "Pane is dead" husk forever).
             if (!this.terminals.get(`${msg.localThreadId}-main`)?.isAlive()) {
-                const terminalReady = provider.waitTerminalReady
-                    ? await provider.waitTerminalReady(msg.localThreadId, terminalReadyTimeoutMs)
-                    : true;
+                // Codex/Traex `ensureLiveCodexSession` already performs the backend
+                // preload for an existing thread. Match the native lifecycle: launch
+                // the TUI immediately after that preload and let the observer subscribe
+                // in the background. Fresh sessions likewise launch before discovery.
+                const terminalReady = isCodexLineageProvider(runtime)
+                    ? true
+                    : provider.waitTerminalReady
+                        ? await provider.waitTerminalReady(msg.localThreadId)
+                        : true;
                 if (!terminalReady) {
                     const providerName = runtime === "traex" ? "Traex" : runtime === "codex" ? "Codex" : "Provider";
                     this.transport.send({
@@ -209,14 +250,31 @@ export class RunnerSession {
                         reqId: msg.reqId,
                         localThreadId: msg.localThreadId,
                         ok: false,
-                        error: runtime === "codex" || runtime === "traex"
-                            ? provider.liveSessionError?.(msg.localThreadId)
-                                ?? `${providerName} app-server was ready, but its existing thread could not be resumed for the Terminal`
-                            : "Provider thread was not ready for Terminal resume",
+                        error: providerFailure(provider, msg.localThreadId, {
+                            runtime,
+                            code: "native_resume_failed",
+                            message: runtime === "codex" || runtime === "traex"
+                                ? `${providerName} app-server was ready, but its existing session could not be resumed for the Terminal`
+                                : "Provider thread was not ready for Terminal resume",
+                        }),
                     });
                     return;
                 }
-                await this.launchCodexPane(msg.localThreadId, msg.cols, msg.rows);
+                try {
+                    await this.launchCodexPane(msg.localThreadId, msg.cols, msg.rows);
+                }
+                catch (error) {
+                    throw error instanceof AgentRuntimeError
+                        ? error
+                        : nativePhaseError(runtime, "native_terminal_launch_failed", "Terminal failed to launch", error);
+                }
+            }
+            // Omnigent's known-thread path launches `codex --remote resume` first,
+            // then creates `_codex_forward_known_thread` as background work. Keep the
+            // ordering explicit here: observer connection failure cannot delay or
+            // reject cold-resume admission.
+            if (isCodexLineageProvider(runtime)) {
+                provider.startLiveCodexObserver?.(msg.localThreadId);
             }
             let ready = true;
             if (runtime === "codex" || runtime === "traex") {
@@ -226,12 +284,15 @@ export class RunnerSession {
                 this.monitorCodexThreadStartup(msg.localThreadId, runtime, provider);
             }
             else if (msg.waitForReady !== false && provider.waitLiveReady) {
-                ready = await provider.waitLiveReady(msg.localThreadId, terminalReadyTimeoutMs);
+                ready = await provider.waitLiveReady(msg.localThreadId);
             }
             const readinessError = ready
                 ? undefined
-                : provider.liveSessionError?.(msg.localThreadId)
-                    ?? "live session was not ready before timeout";
+                : providerFailure(provider, msg.localThreadId, {
+                    runtime,
+                    code: "native_readiness_failed",
+                    message: `${providerDisplayName(runtime)} native session was not ready`,
+                });
             this.transport.send({
                 t: "live.ready",
                 reqId: msg.reqId,
@@ -246,7 +307,7 @@ export class RunnerSession {
                 reqId: msg.reqId,
                 localThreadId: msg.localThreadId,
                 ok: false,
-                error: error instanceof Error ? error.message : String(error),
+                error: toWireError(error),
             });
         }
     }
@@ -269,11 +330,15 @@ export class RunnerSession {
                 : "";
             const detail = provider.liveSessionError?.(localThreadId)
                 ?? (paneFailure
-                    ? `Provider terminal exited before session discovery: ${paneFailure}`
+                    ? `${providerDisplayName(runtime)} Terminal exited before native session discovery: ${paneFailure}`
                     : `${runtime === "traex" ? "Traex" : "Codex"} TUI did not publish thread/started within ${CODEX_THREAD_START_TIMEOUT_MS / 1_000}s after app-server and observer readiness`);
-            this.failCodexThreadStartup(localThreadId, provider, new Error(detail));
+            this.failCodexThreadStartup(localThreadId, provider, new AgentRuntimeError(detail, 503, paneFailure
+                ? "native_terminal_exited_before_session"
+                : "native_thread_discovery_timeout"));
         }).catch((error) => {
-            this.failCodexThreadStartup(localThreadId, provider, error instanceof Error ? error : new Error(String(error)));
+            this.failCodexThreadStartup(localThreadId, provider, error instanceof AgentRuntimeError
+                ? error
+                : nativePhaseError(runtime, "native_thread_discovery_failed", "native session discovery failed", error));
         });
     }
     /** Discovery failure is terminal for this partial native launch. Publish the
@@ -306,7 +371,18 @@ export class RunnerSession {
             // must not cancel prompt handling for the pane that is still starting.
             const error = outcome === "injected" || outcome === "steered"
                 ? undefined
-                : provider.liveSessionError?.(msg.localThreadId);
+                : providerFailure(provider, msg.localThreadId, {
+                    code: outcome === "notReady"
+                        ? "native_thread_not_ready"
+                        : outcome === "notLive"
+                            ? "native_session_not_live"
+                            : "native_message_injection_failed",
+                    message: outcome === "notReady"
+                        ? "Native session was not ready for message injection"
+                        : outcome === "notLive"
+                            ? "Native session was not live for message injection"
+                            : "Native message injection failed",
+                });
             this.transport.send({
                 t: "injected",
                 reqId: msg.reqId,
@@ -321,7 +397,7 @@ export class RunnerSession {
                 reqId: msg.reqId,
                 localThreadId: msg.localThreadId,
                 outcome: "failed",
-                error: error instanceof Error ? error.message : String(error),
+                error: toWireError(error),
             });
         }
     }
@@ -333,7 +409,7 @@ export class RunnerSession {
             ok = (await provider.interruptLive?.(msg.localThreadId)) ?? false;
         }
         catch (e) {
-            error = e instanceof Error ? e.message : String(e);
+            error = toWireError(e);
         }
         this.transport.send({
             t: "interrupted",
@@ -383,8 +459,10 @@ export class RunnerSession {
                 clearInterval(timer);
                 this.terminalWatchers.delete(localThreadId);
                 this.cancelTraexStartupWatcher(localThreadId);
-                this.liveProvider.failLiveSession?.(localThreadId, new Error("Provider terminal exited unexpectedly"));
-                this.failCodexThreadStartup(localThreadId, this.liveProvider, new Error("Provider terminal exited before native thread discovery completed"));
+                const runtime = this.liveRuntimes.get(localThreadId);
+                const paneFailure = terminalFailureDetail(terminal.capturePane?.() ?? "");
+                this.liveProvider.failLiveSession?.(localThreadId, nativePhaseError(runtime, "native_terminal_exited", "Terminal exited unexpectedly", paneFailure || undefined));
+                this.failCodexThreadStartup(localThreadId, this.liveProvider, nativePhaseError(runtime, "native_terminal_exited_before_session", "Terminal exited before native session discovery completed", paneFailure || undefined));
             }).finally(() => {
                 checking = false;
             });
@@ -469,6 +547,7 @@ export class RunnerSession {
             });
         }
         this.liveIds.clear();
+        this.liveRuntimes.clear();
     }
     /** Stop event forwarding, kill native terminals/hooks, then synchronously
      * scrub provider handoff files before the child process is allowed to exit. */

package/dist/runner/manager.d.ts

@@ -16,7 +16,7 @@
  * channel.
  */
 import { spawn as nodeSpawn, type ChildProcess } from "node:child_process";
-import { type AdmissionReservation, type AgentCapabilities, type AgentRuntimeId, type AppConfig, type CapabilityResult, type ModelListResponse, type ResolvedExecutionSnapshot, type RuntimeUserInput, type SessionInteractionResolution, type SessionEvent, type SessionWorkspaceSnapshot, type ThreadGoal } from "@rynx-ai/core";
+import { type AdmissionReservation, type AgentCapabilities, type AgentRuntimeId, type AppConfig, type CapabilityResult, type ModelListResponse, type LiveSessionFailure, type ResolvedExecutionSnapshot, type RuntimeUserInput, type SessionInteractionResolution, type SessionEvent, type SessionWorkspaceSnapshot, type ThreadGoal } from "@rynx-ai/core";
 import { type CodexSessionStore } from "../host.js";
 import type { ResolveInteractionResult } from "../interactions.js";
 import { type InjectOutcome, type TerminalOpenErrorCode, type TerminalRole } from "./protocol.js";
@@ -53,12 +53,13 @@ export interface RunnerManagerOptions {
     shutdownGraceMs?: number;
     /** Final bounded wait for child exit after SIGKILL. */
     shutdownKillGraceMs?: number;
-    /** Max wait for a setup-pane launch acknowledgement. */
+    /** Max wait for a legacy setup-pane launch acknowledgement. Codex/Traex use
+     * their internal phase deadlines and are not wrapped by this timer. */
     liveStartTimeoutMs?: number;
     /** Max wait for a Provider-native thread to become ready. */
     liveReadyTimeoutMs?: number;
-    /** Claude SessionStart deadline. Codex/Traex use `liveStartTimeoutMs` for the
-     * pane/observer acknowledgement; their thread discovery is asynchronous. */
+    /** Claude SessionStart deadline. Codex/Traex have no parent-owned startup
+     * deadline; their app-server/discovery/injection phases report directly. */
     nativeLiveStartTimeoutMs?: number;
     /** Max wait for a native interrupt acknowledgement before reporting it
      * unproven. Callers may then use the explicit force-stop path. */
@@ -247,9 +248,10 @@ export declare class RunnerManager implements AgentCapabilities {
     /**
      * Eagerly bring up a session's codex-native live view (persistent forwarder +
      * detached `codex --remote` TUI) in its runner child, spawning the runner if
-     * needed. Idempotent. For Codex-lineage fresh sessions, resolves after the
-     * app-server/observer and pane are launched; thread discovery continues in
-     * parallel with injection. Other providers retain their readiness gate.
+     * needed. Idempotent. For Codex-lineage sessions, resolves after backend
+     * preload and pane launch; known-thread observer attach and fresh-thread
+     * discovery continue in the background. Other providers retain their
+     * readiness gate.
      */
     ensureLiveSession(localThreadId: string, opts: {
         workspace: SessionWorkspaceSnapshot;
@@ -268,6 +270,7 @@ export declare class RunnerManager implements AgentCapabilities {
     }): Promise<boolean>;
     private requestLiveSession;
     lastLiveSessionError(localThreadId: string): string | undefined;
+    lastLiveSessionFailure(localThreadId: string): LiveSessionFailure | undefined;
     /**
      * Inject a user turn into a session's live codex thread — reference implementation's
      * single-writer web send (`turn/start` / `turn/steer`); the forwarder mirrors

package/dist/runner/manager.js

@@ -24,7 +24,7 @@ import { listRuntimeModels } from "../models-catalog.js";
 import { probeRuntimeStatus } from "../runtime-status.js";
 import { terminateTmuxServer, tmuxHasAttachedClient, tmuxWindowActivityAt, } from "../terminal/tmux.js";
 import { fromWireError, } from "./protocol.js";
-import { isManagedNativeProvider } from "./startup-policy.js";
+import { isCodexLineageProvider, isManagedNativeProvider } from "./startup-policy.js";
 import { StdioRunnerTransport } from "./transport.js";
 /** Routing key for the shared capability runner (slash-command RPCs). */
 const CAP_KEY = "__cap__";
@@ -34,9 +34,8 @@ const STDERR_TAIL_LINES = 40;
 const DEFAULT_SHUTDOWN_GRACE_MS = 5_000;
 /** Time allowed for exit after SIGKILL before shutdown reports failure. */
 const DEFAULT_SHUTDOWN_KILL_GRACE_MS = 5_000;
-/** Setup-pane launch includes the app-server readiness phase but does not wait
- * for native thread discovery. Keep enough headroom around the app-server's
- * own 10s gate so scheduling/IPC overhead cannot win the same deadline. */
+/** Legacy setup-pane acknowledgement deadline for providers that do not own
+ * phase-specific startup errors. Codex/Traex are deliberately excluded. */
 const DEFAULT_LIVE_START_TIMEOUT_MS = 30_000;
 /** Legacy fallback for a provider without a native startup policy. */
 const DEFAULT_LIVE_READY_TIMEOUT_MS = 25_000;
@@ -509,9 +508,10 @@ export class RunnerManager {
     /**
      * Eagerly bring up a session's codex-native live view (persistent forwarder +
      * detached `codex --remote` TUI) in its runner child, spawning the runner if
-     * needed. Idempotent. For Codex-lineage fresh sessions, resolves after the
-     * app-server/observer and pane are launched; thread discovery continues in
-     * parallel with injection. Other providers retain their readiness gate.
+     * needed. Idempotent. For Codex-lineage sessions, resolves after backend
+     * preload and pane launch; known-thread observer attach and fresh-thread
+     * discovery continue in the background. Other providers retain their
+     * readiness gate.
      */
     ensureLiveSession(localThreadId, opts) {
         const admission = this.reserveAdmission();
@@ -550,55 +550,66 @@ export class RunnerManager {
         this.liveSessionKeys.add(localThreadId);
         const reqId = randomUUID();
         return new Promise((resolve) => {
-            const timeoutMs = !waitForReady
-                ? this.liveStartTimeoutMs
-                : opts.execution.provider === "claude"
-                    ? this.nativeLiveStartTimeoutMs
-                    : isManagedNativeProvider(opts.execution.provider)
-                        ? this.liveStartTimeoutMs
+            const provider = opts.execution.provider;
+            const timeoutMs = isCodexLineageProvider(provider)
+                ? null
+                : !waitForReady
+                    ? this.liveStartTimeoutMs
+                    : provider === "claude"
+                        ? this.nativeLiveStartTimeoutMs
                         : this.liveReadyTimeoutMs;
-            const timeout = setTimeout(() => {
-                if (!handle.live.delete(reqId))
-                    return;
-                const finishTimeout = () => {
-                    const provider = opts.execution.provider;
-                    const reason = !waitForReady
-                        ? `runner did not acknowledge terminal start within ${timeoutMs}ms`
-                        : provider === "claude"
-                            ? `Claude SessionStart was not observed within ${Math.round(timeoutMs / 1_000)}s; the runner process was reset before retry`
-                            : provider === "codex" || provider === "traex"
-                                ? `${provider === "traex" ? "Traex" : "Codex"} app-server/observer/Terminal launch was not acknowledged within ${Math.round(timeoutMs / 1_000)}s; the runner process was reset before retry`
+            const timeout = timeoutMs === null
+                ? undefined
+                : setTimeout(() => {
+                    if (!handle.live.delete(reqId))
+                        return;
+                    const finishTimeout = () => {
+                        const reason = !waitForReady
+                            ? `runner did not acknowledge terminal start within ${timeoutMs}ms`
+                            : provider === "claude"
+                                ? `Claude SessionStart was not observed within ${Math.round(timeoutMs / 1_000)}s; the runner process was reset before retry`
                                 : `runner did not acknowledge live readiness within ${timeoutMs}ms`;
-                    this.liveErrors.set(localThreadId, reason);
-                    this.liveSessionKeys.delete(localThreadId);
-                    // A child that cannot answer a bounded control round-trip is unsafe
-                    // to reuse. Reap it so the next click gets a fresh runner.
-                    void this.terminateHandle(handle, reason).catch((error) => {
-                        logTerminationFailure(handle, error);
-                    });
-                    return false;
-                };
-                const reservation = allowReservedForkTarget
-                    ? undefined
-                    : this.forkReservations.get(localThreadId);
-                if (reservation) {
-                    void reservation
-                        .then(() => finishTimeout())
-                        .then(resolve, () => resolve(false));
-                    return;
-                }
-                resolve(finishTimeout());
-            }, timeoutMs);
-            timeout.unref?.();
+                        this.liveErrors.set(localThreadId, {
+                            message: reason,
+                            code: provider === "claude"
+                                ? "claude_session_start_timeout"
+                                : "native_runner_ack_timeout",
+                            statusCode: 503,
+                        });
+                        this.liveSessionKeys.delete(localThreadId);
+                        // Legacy providers without phase-owned startup errors retain the
+                        // bounded control guard. Codex/Traex never enter this branch.
+                        void this.terminateHandle(handle, reason).catch((error) => {
+                            logTerminationFailure(handle, error);
+                        });
+                        return false;
+                    };
+                    const reservation = allowReservedForkTarget
+                        ? undefined
+                        : this.forkReservations.get(localThreadId);
+                    if (reservation) {
+                        void reservation
+                            .then(() => finishTimeout())
+                            .then(resolve, () => resolve(false));
+                        return;
+                    }
+                    resolve(finishTimeout());
+                }, timeoutMs);
+            timeout?.unref?.();
             handle.live.set(reqId, (res) => {
-                clearTimeout(timeout);
+                if (timeout)
+                    clearTimeout(timeout);
                 const ok = res.ok ?? false;
                 const finish = () => {
                     if (ok) {
                         this.liveErrors.delete(localThreadId);
                     }
                     else {
-                        this.liveErrors.set(localThreadId, res.error ?? "live session did not become ready");
+                        this.liveErrors.set(localThreadId, res.error ?? {
+                            message: "live session did not become ready",
+                            code: "native_readiness_failed",
+                            statusCode: 503,
+                        });
                     }
                     return ok;
                 };
@@ -626,7 +637,11 @@ export class RunnerManager {
         });
     }
     lastLiveSessionError(localThreadId) {
-        return this.liveErrors.get(localThreadId);
+        return this.liveErrors.get(localThreadId)?.message;
+    }
+    lastLiveSessionFailure(localThreadId) {
+        const failure = this.liveErrors.get(localThreadId);
+        return failure ? { ...failure } : undefined;
     }
     /**
      * Inject a user turn into a session's live codex thread — reference implementation's
@@ -659,7 +674,15 @@ export class RunnerManager {
                         this.liveErrors.delete(localThreadId);
                     }
                     else {
-                        this.liveErrors.set(localThreadId, res.error ?? `live injection ${outcome}`);
+                        this.liveErrors.set(localThreadId, res.error ?? {
+                            message: `live injection ${outcome}`,
+                            code: outcome === "notReady"
+                                ? "native_thread_not_ready"
+                                : outcome === "notLive"
+                                    ? "native_session_not_live"
+                                    : "native_message_injection_failed",
+                            statusCode: 503,
+                        });
                     }
                     return outcome;
                 };
@@ -714,7 +737,7 @@ export class RunnerManager {
             handle.live.set(reqId, (reply) => {
                 resolve(reply.interactionResult ?? {
                     disposition: "invalid",
-                    message: reply.error ?? "runner did not return an interaction result",
+                    message: reply.error?.message ?? "runner did not return an interaction result",
                 });
             });
             handle.transport.send({
@@ -1318,7 +1341,10 @@ export class RunnerManager {
             terminal._fail(message);
         }
         for (const resolve of handle.live.values()) {
-            resolve({ ok: false, error: message });
+            resolve({
+                ok: false,
+                error: { message, code: "runner_crashed", statusCode: 500 },
+            });
         }
         handle.caps.clear();
         handle.terminals.clear();

package/dist/runner/protocol.d.ts

@@ -64,9 +64,9 @@ export type ToChild = {
 }
 /** Eagerly bring up a session's live codex TUI + forwarder (codex-native), so
  *  its turns mirror to the bus regardless of whether the web has attached the
- *  terminal. For Codex-lineage fresh sessions, `live.ready` acknowledges that
- *  the pane and observer exist; background thread discovery races the
- *  executor's bridge wait. */
+ *  terminal. Fresh sessions connect the discovery listener before TUI launch;
+ *  known-thread resumes launch the TUI after backend preload and attach their
+ *  observer in the background. */
  | {
     t: "live.ensure";
     reqId: string;
@@ -155,15 +155,16 @@ export type FromChild = {
     execution: ResolvedExecutionSnapshot;
     parentSessionId?: string;
 }
-/** Result of a `live.ensure`: for Codex-lineage sessions `ok` means the pane
- *  and observer started; thread discovery continues in parallel with
- *  injection. Other Providers retain their own readiness gate. */
+/** Result of a `live.ensure`: for Codex-lineage sessions `ok` means backend
+ *  preload and pane launch completed. A resume observer and fresh-thread
+ *  discovery may continue in the background. Other Providers retain their
+ *  own readiness gate. */
  | {
     t: "live.ready";
     reqId: string;
     localThreadId: string;
     ok: boolean;
-    error?: string;
+    error?: WireError;
 }
 /** Result of an `inject`: `outcome` distinguishes a new turn, an active-turn
  *  steer, and failures so the caller never falls back to a second output path.
@@ -173,7 +174,7 @@ export type FromChild = {
     reqId: string;
     localThreadId: string;
     outcome: InjectOutcome;
-    error?: string;
+    error?: WireError;
 }
 /** Result of a `live.interrupt`: `ok` when an active turn was interrupted (false
  *  when there was none). Echoes the request `reqId`. */
@@ -182,7 +183,7 @@ export type FromChild = {
     reqId: string;
     localThreadId: string;
     ok: boolean;
-    error?: string;
+    error?: WireError;
 } | {
     t: "interaction.resolved";
     reqId: string;

package/dist/runner/startup-policy.d.ts

@@ -2,3 +2,6 @@ import type { AgentRuntimeId } from "@rynx-ai/core";
 /** Current live providers are native CLI sessions. Keep this explicit so a
  * future non-native provider does not silently inherit their startup budget. */
 export declare function isManagedNativeProvider(provider: AgentRuntimeId | undefined): provider is AgentRuntimeId;
+/** Codex-lineage providers own app-server, thread-discovery, and injection
+ * phase errors. Claude instead retains its parent-owned SessionStart gate. */
+export declare function isCodexLineageProvider(provider: AgentRuntimeId | undefined): provider is Exclude<AgentRuntimeId, "claude">;

package/dist/runner/startup-policy.js

@@ -3,3 +3,8 @@
 export function isManagedNativeProvider(provider) {
     return provider === "codex" || provider === "traex" || provider === "claude";
 }
+/** Codex-lineage providers own app-server, thread-discovery, and injection
+ * phase errors. Claude instead retains its parent-owned SessionStart gate. */
+export function isCodexLineageProvider(provider) {
+    return provider === "codex" || provider === "traex";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rynx-ai/runtime",
-  "version": "0.1.11-beta.21",
+  "version": "0.1.11-beta.22",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/rynx-ai/rynx.git",
@@ -27,7 +27,7 @@
     "node-pty": "1.2.0-beta.15",
     "smol-toml": "1.7.1",
     "ws": "^8.21.0",
-    "@rynx-ai/core": "0.1.11-beta.21"
+    "@rynx-ai/core": "0.1.11-beta.22"
   },
   "devDependencies": {
     "@types/ws": "^8.18.1"