@rynx-ai/runtime 0.1.11-beta.20 → 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
@@ -304,9 +369,20 @@ export class RunnerSession {
             const outcome = (await provider.injectMessage?.(msg.localThreadId, input)) ?? "notLive";
             // App-server injection is independent of the Terminal TUI startup, so it
             // must not cancel prompt handling for the pane that is still starting.
-            const error = outcome === "injected"
+            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";
@@ -43,21 +43,23 @@ export interface RunnerManagerOptions {
     runnerEntry?: string;
     /** Idle TTL (ms) after which an unused runner is reaped. */
     idleTtlMs?: number;
-    /** Maximum time without user/control activity that an active response may
-     * protect a detached runner from idle reaping. */
-    staleActiveTtlMs?: number;
+    /** Native pane idle window. `<= 0` disables native-pane idle reaping. */
+    nativePaneIdleTtlMs?: number;
+    /** Recent tmux-output window used as independent native-pane busy evidence. */
+    nativePaneOutputBusyWindowMs?: number;
     /** Background reap sweep interval (ms); `0` disables the timer (tests). */
     reapIntervalMs?: number;
     /** Grace period between SIGTERM and SIGKILL during runner shutdown. */
     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. */
@@ -75,7 +77,13 @@ export interface RunnerManagerOptions {
     /** Injected for tests. Kills and verifies the deterministic private tmux
      * server owned by a Session runner. */
     terminateTerminalServer?: (terminalName: string) => boolean | Promise<boolean>;
+    /** Injected tmux `#{window_activity}` reader. Returns epoch seconds. */
+    terminalWindowActivityAt?: (terminalName: string) => number | null | Promise<number | null>;
+    /** Injected tmux attached-client probe. */
+    terminalHasAttachedClient?: (terminalName: string) => boolean | Promise<boolean>;
     now?: () => number;
+    /** Wall clock used to compare tmux's epoch timestamp. */
+    wallNow?: () => number;
     /** Extra env merged into every spawned runner child — e.g. the control-plane
      *  URL + token so a claude-native PermissionRequest hook can POST back. */
     childEnv?: Record<string, string>;
@@ -142,7 +150,8 @@ export declare class RunnerManager implements AgentCapabilities {
     private readonly sessionStore;
     private readonly runnerEntry;
     private readonly idleTtlMs;
-    private readonly staleActiveTtlMs;
+    private readonly nativePaneIdleTtlMs;
+    private readonly nativePaneOutputBusyWindowMs;
     private readonly spawn;
     private readonly childEnv;
     private readonly sessionContextProvider;
@@ -159,12 +168,16 @@ export declare class RunnerManager implements AgentCapabilities {
     private readonly shutdownKillGraceMs;
     private readonly signalChild;
     private readonly terminateTerminalServer;
+    private readonly terminalWindowActivityAt;
+    private readonly terminalHasAttachedClient;
+    private readonly wallNow;
     private readonly liveStartTimeoutMs;
     private readonly liveReadyTimeoutMs;
     private readonly nativeLiveStartTimeoutMs;
     private readonly liveInterruptTimeoutMs;
     private readonly terminalInputHandoffTimeoutMs;
     private readonly terminalInputCleanupRetryMs;
+    private reapPromise;
     private stopping;
     private stopPromise;
     /** Sink for mirrored {@link SessionEvent}s from every session's forwarder. */
@@ -235,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;
@@ -256,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
@@ -321,14 +336,17 @@ export declare class RunnerManager implements AgentCapabilities {
     private failHandle;
     private terminateHandle;
     private reapIdle;
-    /** Close server-side runtime state before fencing a Provider that stayed
-     * active past its hard inactivity deadline. The child transport is closed by
-     * terminateHandle immediately afterwards, so these are the final events for
-     * the abandoned responses. */
-    private failStaleActiveResponses;
+    private reapIdleOnce;
+    /** Provider-authoritative turn state is the lifecycle truth; attached clients
+     * and tmux's own activity clock are independent busy evidence. There is no
+     * "user was inactive for an hour" override for an active turn. */
+    private reapNativePane;
+    private isNativePaneBusy;
+    private isManagedNativeHandle;
     private failActiveResponses;
-    /** Track only response lifecycle, not output volume. Output deltas from a
-     * runaway TUI/Provider must not refresh the stale-active deadline. */
+    /** Track the provider-authoritative response lifecycle. Native-pane busy
+     * classification consumes this level directly; output volume is separately
+     * grounded in tmux's own activity clock. */
     private observeHandleRuntimeEvent;
     private openSessionContext;
 }