@rynx-ai/runtime 0.1.11-beta.3 → 0.1.11-beta.31

package/dist/runner/child.js

@@ -1,5 +1,118 @@
+/**
+ * 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 { randomUUID } from "node:crypto";
+import { AgentRuntimeError, } from "@rynx-ai/core";
 import { TerminalRegistry } from "../terminal/registry.js";
-import { toWireError } from "./protocol.js";
+import { RUNNER_IMAGE_CHUNK_CHARS, RUNNER_IMAGE_MAX_RESULT_CHARS, 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) {
+    // A captured pane is a screen snapshot, not stderr. Do not present ordinary
+    // TUI chrome ("Working", shortcuts, model/status bars) as the process's exit
+    // cause. Retain only lines that plausibly carry an actual startup/runtime
+    // failure; the structured error still reports the proven pane exit itself.
+    return pane
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .filter((line) => /\b(?:error|fatal|failed|failure|panic|refused|denied|unauthorized|invalid)\b/i.test(line))
+        .slice(-6)
+        .join(" ")
+        .slice(-1_000);
+}
+const TRAEX_STARTUP_WATCH_MS = 20_000;
+const TRAEX_STARTUP_DISCOVERY_MS = 5_000;
+const TRAEX_STARTUP_POLL_MS = 100;
+const TRAEX_AUTHORIZATION_POLL_MS = 500;
+const TRAEX_AUTHORIZATION_WAIT_MS = 15 * 60_000;
+const TRAEX_ESCAPE_CONFIRM_MS = 1_000;
+const TRAEX_ESCAPE_COOLDOWN_MS = 1_000;
+const TRAEX_REPEAT_PROMPT_CONFIRM_MS = 5_000;
+const MIRROR_IMAGE_ACK_TIMEOUT_MS = 30_000;
+function normalizeTraexPane(pane) {
+    return pane.toLowerCase().replace(/\s+/g, " ").trim();
+}
+function isTraexAuthorizationPending(pane) {
+    return pane.includes("waiting for authorization") &&
+        pane.includes("open this link in your browser") &&
+        pane.includes("press esc to cancel");
+}
+function isTraexStartupActivity(pane) {
+    return pane.includes("updating traecode cli") || pane.includes("updating trae cli");
+}
+function isTerminalProtocolResponse(input) {
+    // xterm answers terminal queries through the same onData channel as real
+    // keystrokes. CSI carries device/focus/position reports; OSC carries color
+    // query replies such as `OSC 10;rgb:... ST` and `OSC 11;rgb:... ST`.
+    // Neither is evidence that the user has taken over startup prompt handling.
+    return /^(?:\x1b\[(?:(?:\?|>)[0-9;]*c|[0-9;]*(?:n|R|t)|[IO])|\x1b\][0-9]+;[^\x07\x1b]*(?:\x07|\x1b\\))+$/.test(input);
+}
+function detachGeneratedImageResult(event) {
+    if (event.type !== "response.output_item.done" ||
+        event.item.type !== "function_call_output") {
+        return undefined;
+    }
+    const data = event.item.data;
+    const pending = data.__rynxGeneratedImage;
+    if (!pending?.result)
+        return undefined;
+    const { result, ...withoutResult } = pending;
+    return {
+        result,
+        event: {
+            ...event,
+            item: {
+                ...event.item,
+                data: {
+                    ...data,
+                    __rynxGeneratedImage: withoutResult,
+                },
+            },
+        },
+    };
+}
+function generatedImagePreviewUnavailable(event) {
+    if (event.type !== "response.output_item.done" ||
+        event.item.type !== "function_call_output") {
+        return event;
+    }
+    const data = event.item.data;
+    const { __rynxGeneratedImage: _omitted, ...publicData } = data;
+    return {
+        ...event,
+        item: {
+            ...event.item,
+            data: {
+                ...publicData,
+                output: `${event.item.data.output}\nImage preview unavailable.`.trim(),
+            },
+        },
+    };
+}
 export class RunnerSession {
     transport;
     executor;
@@ -7,11 +120,19 @@ export class RunnerSession {
     /** Live terminals hosted by this session, and per-attach client handles. */
     terminals = new TerminalRegistry();
     attachments = new Map();
+    attachmentThreadIds = new Map();
+    traexStartupWatchers = new Map();
+    traexStartupGates = new Map();
+    terminalWatchers = new Map();
     /** Opens are async; a close received before attach resolves tombstones the id. */
     pendingTerminalOpens = new Set();
     cancelledTerminalOpens = new Set();
     /** Session ids with a live codex forwarder started here (stopped on shutdown). */
     liveIds = new Set();
+    mirrorQueue = Promise.resolve();
+    mirrorImageAcks = new Map();
+    /** Provider name retained for asynchronous Terminal-exit diagnostics. */
+    liveRuntimes = new Map();
     shuttingDown = false;
     constructor({ transport, executor, onShutdown }) {
         this.transport = transport;
@@ -22,10 +143,36 @@ export class RunnerSession {
                     transport.close();
                 });
         this.transport.onMessage((msg) => this.handle(msg));
+        this.transport.onClose((error) => {
+            this.rejectMirrorImageAcks(error ?? new Error("runner transport closed"));
+        });
         this.transport.send({ t: "ready" });
     }
     handle(msg) {
         switch (msg.t) {
+            case "mirror.image.ack": {
+                const pending = this.mirrorImageAcks.get(msg.transferId);
+                if (!pending)
+                    return;
+                if (pending.seq !== msg.seq) {
+                    pending.reject(new Error("generated image acknowledgement sequence changed"));
+                    return;
+                }
+                if (pending.timer)
+                    clearTimeout(pending.timer);
+                this.mirrorImageAcks.delete(msg.transferId);
+                pending.resolve();
+                return;
+            }
+            case "mirror.image.hold": {
+                const pending = this.mirrorImageAcks.get(msg.transferId);
+                if (!pending || pending.seq !== msg.seq)
+                    return;
+                if (pending.timer)
+                    clearTimeout(pending.timer);
+                pending.timer = undefined;
+                return;
+            }
             case "cap":
                 void this.runCap(msg.capId, msg.name, msg.args);
                 return;
@@ -46,7 +193,17 @@ export class RunnerSession {
                 });
                 return;
             case "term.input":
-                this.attachments.get(msg.attachId)?.write(Buffer.from(msg.dataB64, "base64").toString("utf8"));
+                {
+                    const localThreadId = this.attachmentThreadIds.get(msg.attachId);
+                    const input = Buffer.from(msg.dataB64, "base64").toString("utf8");
+                    // xterm sends device/focus reports through the same onData channel as
+                    // keystrokes. They must reach the TUI without pretending the user has
+                    // taken over startup prompt handling.
+                    if (!isTerminalProtocolResponse(input)) {
+                        this.cancelTraexStartupWatcher(localThreadId);
+                    }
+                    this.attachments.get(msg.attachId)?.write(input);
+                }
                 return;
             case "term.resize":
                 this.attachments.get(msg.attachId)?.resize(msg.cols, msg.rows);
@@ -57,6 +214,7 @@ export class RunnerSession {
                 }
                 const attachment = this.attachments.get(msg.attachId);
                 this.attachments.delete(msg.attachId);
+                this.attachmentThreadIds.delete(msg.attachId);
                 attachment?.kill();
                 return;
             }
@@ -70,6 +228,9 @@ export class RunnerSession {
             case "inject":
                 void this.inject(msg);
                 return;
+            case "collaboration.update":
+                void this.updateCollaborationMode(msg);
+                return;
             case "live.interrupt":
                 void this.interruptLive(msg);
                 return;
@@ -106,27 +267,97 @@ export class RunnerSession {
      *  the new session stays injectable. */
     mirrorChannel(localThreadId) {
         const target = { id: localThreadId };
-        const emit = (event) => this.transport.send({ t: "mirror", sessionId: target.id, event });
+        const emit = (event) => {
+            const sessionId = target.id;
+            this.enqueueMirror(() => this.sendMirroredEvent(sessionId, event));
+        };
         const retarget = (newId, meta) => {
             target.id = newId;
-            this.transport.send({
-                t: "rotate",
-                from: localThreadId,
-                to: newId,
-                kind: meta.kind,
-                workspace: meta.workspace,
-                execution: meta.execution,
-                ...(meta.parentSessionId ? { parentSessionId: meta.parentSessionId } : {}),
+            this.enqueueMirror(() => {
+                this.transport.send({
+                    t: "rotate",
+                    from: localThreadId,
+                    to: newId,
+                    kind: meta.kind,
+                    workspace: meta.workspace,
+                    execution: meta.execution,
+                    ...(meta.parentSessionId ? { parentSessionId: meta.parentSessionId } : {}),
+                });
             });
         };
         return { emit, retarget };
     }
+    enqueueMirror(operation) {
+        this.mirrorQueue = this.mirrorQueue.then(operation).catch((error) => {
+            if (!this.shuttingDown) {
+                this.rejectMirrorImageAcks(error instanceof Error ? error : new Error(String(error)));
+                this.shutdown();
+            }
+        });
+    }
+    async sendMirroredEvent(sessionId, event) {
+        const detached = detachGeneratedImageResult(event);
+        if (!detached) {
+            this.transport.send({ t: "mirror", sessionId, event });
+            return;
+        }
+        if (detached.result.length > RUNNER_IMAGE_MAX_RESULT_CHARS) {
+            this.transport.send({
+                t: "mirror",
+                sessionId,
+                event: generatedImagePreviewUnavailable(detached.event),
+            });
+            return;
+        }
+        const transferId = `img_${randomUUID()}`;
+        let seq = 0;
+        await this.sendMirrorImageFrame(transferId, seq, {
+            t: "mirror.image.begin",
+            transferId,
+            sessionId,
+            event: detached.event,
+            totalChars: detached.result.length,
+        });
+        for (let offset = 0; offset < detached.result.length; offset += RUNNER_IMAGE_CHUNK_CHARS) {
+            seq += 1;
+            await this.sendMirrorImageFrame(transferId, seq, {
+                t: "mirror.image.chunk",
+                transferId,
+                seq,
+                data: detached.result.slice(offset, offset + RUNNER_IMAGE_CHUNK_CHARS),
+            });
+        }
+        seq += 1;
+        await this.sendMirrorImageFrame(transferId, seq, {
+            t: "mirror.image.commit",
+            transferId,
+            seq,
+        });
+    }
+    sendMirrorImageFrame(transferId, seq, frame) {
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.mirrorImageAcks.delete(transferId);
+                reject(new Error("generated image transfer acknowledgement timed out"));
+            }, MIRROR_IMAGE_ACK_TIMEOUT_MS);
+            timer.unref?.();
+            this.mirrorImageAcks.set(transferId, { seq, resolve, reject, timer });
+            this.transport.send(frame);
+        });
+    }
+    rejectMirrorImageAcks(error) {
+        for (const pending of this.mirrorImageAcks.values()) {
+            if (pending.timer)
+                clearTimeout(pending.timer);
+            pending.reject(error);
+        }
+        this.mirrorImageAcks.clear();
+    }
     /**
-     * Eagerly bring up a session's codex-native live view: start the persistent
-     * forwarder connection (which resume-subscribes to mirror every turn) and
-     * launch the detached `codex --remote resume` TUI against the thread the
-     * structured runtime created. The forwarder subscribes to that same thread,
-     * so the TUI is usable immediately and its turns mirror to chat.
+     * 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;
@@ -138,43 +369,121 @@ 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: "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);
+            const runtime = msg.execution?.provider;
+            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)
-                    : 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({
                         t: "live.ready",
                         reqId: msg.reqId,
                         localThreadId: msg.localThreadId,
                         ok: false,
-                        error: "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);
+                }
             }
-            const ready = msg.waitForReady === false
-                ? true
-                : provider.waitLiveReady
-                    ? await provider.waitLiveReady(msg.localThreadId)
-                    : true;
-            const terminal = this.terminals.get(`${msg.localThreadId}-main`);
-            const paneFailure = !ready && terminal && !terminal.isAlive()
+            // reference implementation'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") {
+                // Discover thread/started in the background for 30s while injection
+                // waits up to 60s for either bridge readiness or that startup error.
+                // Do not serialize the two waits here.
+                this.monitorCodexThreadStartup(msg.localThreadId, runtime, provider);
+            }
+            else if (msg.waitForReady !== false && provider.waitLiveReady) {
+                ready = await provider.waitLiveReady(msg.localThreadId);
+            }
+            // Message delivery is serialized behind Traex's startup modal handling.
+            // Otherwise app-server can accept a Turn while the TUI watcher is still
+            // sending Escape, and the same key becomes `turn/interrupt` as soon as
+            // the modal disappears. Setup-terminal opens remain non-blocking.
+            if (runtime === "traex" && msg.waitForReady !== false) {
+                await this.traexStartupGates.get(msg.localThreadId);
+            }
+            const readinessError = ready
+                ? undefined
+                : 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,
+                localThreadId: msg.localThreadId,
+                ok: ready,
+                ...(ready ? {} : { error: readinessError }),
+            });
+        }
+        catch (error) {
+            this.transport.send({
+                t: "live.ready",
+                reqId: msg.reqId,
+                localThreadId: msg.localThreadId,
+                ok: false,
+                error: toWireError(error),
+            });
+        }
+    }
+    monitorCodexThreadStartup(localThreadId, runtime, provider) {
+        if (!provider.waitLiveReady)
+            return;
+        void provider.waitLiveReady(localThreadId, CODEX_THREAD_START_TIMEOUT_MS).then((ready) => {
+            if (ready)
+                return;
+            const terminal = this.terminals.get(`${localThreadId}-main`);
+            const paneFailure = terminal && !terminal.isAlive()
                 ? terminal
                     .capturePane()
                     .split("\n")
@@ -184,42 +493,106 @@ export class RunnerSession {
                     .join(" ")
                     .slice(-1_000)
                 : "";
-            const readinessError = provider.liveSessionError?.(msg.localThreadId)
+            const detail = provider.liveSessionError?.(localThreadId)
                 ?? (paneFailure
-                    ? `Provider terminal exited before session discovery: ${paneFailure}`
-                    : "live session was not ready before timeout");
+                    ? `${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 AgentRuntimeError(detail, 503, paneFailure
+                ? "native_terminal_exited_before_session"
+                : "native_thread_discovery_timeout"));
+        }).catch((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
+     * exact cause first so an in-flight injection wakes, then drop the observer
+     * and TUI so a later task retry creates a clean launch instead of reusing an
+     * already-rejected readiness promise. */
+    failCodexThreadStartup(localThreadId, provider, error) {
+        if (!provider.failLiveStartup?.(localThreadId, error))
+            return false;
+        const watcher = this.terminalWatchers.get(localThreadId);
+        if (watcher)
+            clearInterval(watcher);
+        this.terminalWatchers.delete(localThreadId);
+        this.cancelTraexStartupWatcher(localThreadId);
+        try {
+            this.terminals.close(`${localThreadId}-main`);
+        }
+        catch (closeError) {
+            console.warn(`[runner] session=${localThreadId} failed to close native Terminal after startup failure: ${closeError instanceof Error ? closeError.message : String(closeError)}`);
+        }
+        if (provider.teardownLiveCodexSession) {
+            provider.teardownLiveCodexSession(localThreadId);
+        }
+        else {
+            provider.stopLiveCodexSession?.(localThreadId);
+        }
+        this.liveIds.delete(localThreadId);
+        return true;
+    }
+    async inject(msg) {
+        const provider = this.liveProvider;
+        try {
+            const input = msg.input ?? msg.text;
+            const result = (await provider.injectMessage?.(msg.localThreadId, input, msg.options))
+                ?? { outcome: "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 = result.outcome === "injected" || result.outcome === "steered"
+                ? undefined
+                : providerFailure(provider, msg.localThreadId, {
+                    code: result.outcome === "notReady"
+                        ? "native_thread_not_ready"
+                        : result.outcome === "notLive"
+                            ? "native_session_not_live"
+                            : "native_message_injection_failed",
+                    message: result.outcome === "notReady"
+                        ? "Native session was not ready for message injection"
+                        : result.outcome === "notLive"
+                            ? "Native session was not live for message injection"
+                            : "Native message injection failed",
+                });
             this.transport.send({
-                t: "live.ready",
+                t: "injected",
                 reqId: msg.reqId,
                 localThreadId: msg.localThreadId,
-                ok: ready,
-                ...(ready ? {} : { error: readinessError }),
+                result,
+                ...(error ? { error } : {}),
             });
         }
         catch (error) {
             this.transport.send({
-                t: "live.ready",
+                t: "injected",
                 reqId: msg.reqId,
                 localThreadId: msg.localThreadId,
-                ok: false,
-                error: error instanceof Error ? error.message : String(error),
+                result: { outcome: "failed" },
+                error: toWireError(error),
             });
         }
     }
-    async inject(msg) {
-        const provider = this.liveProvider;
+    async updateCollaborationMode(msg) {
         try {
-            const input = msg.input ?? msg.text;
-            const outcome = (await provider.injectMessage?.(msg.localThreadId, input)) ?? "notLive";
-            this.transport.send({ t: "injected", reqId: msg.reqId, localThreadId: msg.localThreadId, outcome });
+            if (!this.liveProvider.updateCollaborationMode) {
+                throw new AgentRuntimeError("Native collaboration mode is unavailable", 409, "collaboration_mode_unavailable");
+            }
+            await this.liveProvider.updateCollaborationMode(msg.localThreadId, msg.mode);
+            this.transport.send({
+                t: "collaboration.updated",
+                reqId: msg.reqId,
+                localThreadId: msg.localThreadId,
+                ok: true,
+            });
         }
         catch (error) {
             this.transport.send({
-                t: "injected",
+                t: "collaboration.updated",
                 reqId: msg.reqId,
                 localThreadId: msg.localThreadId,
-                outcome: "failed",
-                error: error instanceof Error ? error.message : String(error),
+                ok: false,
+                error: toWireError(error),
             });
         }
     }
@@ -231,7 +604,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",
@@ -248,7 +621,8 @@ export class RunnerSession {
         const spec = await this.liveProvider.codexTerminalSpec?.(localThreadId);
         if (!spec)
             return;
-        const term = this.terminals.getOrCreate(`${localThreadId}-main`, {
+        const terminalId = `${localThreadId}-main`;
+        const term = this.terminals.getOrCreate(terminalId, {
             cwd: spec.cwd,
             command: spec.command,
             args: spec.args,
@@ -256,15 +630,218 @@ export class RunnerSession {
             rows: rows ?? 40,
             ...(spec.env ? { env: spec.env } : {}),
         });
+        if (spec.skipTraexStartupPrompts) {
+            const watcher = Symbol(localThreadId);
+            this.traexStartupWatchers.set(localThreadId, watcher);
+            const gate = this.skipTraexStartupPrompts(localThreadId, term, watcher);
+            this.traexStartupGates.set(localThreadId, gate);
+            void gate.finally(() => {
+                if (this.traexStartupGates.get(localThreadId) === gate) {
+                    this.traexStartupGates.delete(localThreadId);
+                }
+            });
+        }
         this.liveProvider.attachTerminalInjector?.(localThreadId, term);
+        this.watchNativeTerminal(localThreadId, terminalId, term);
+    }
+    watchNativeTerminal(localThreadId, terminalId, terminal) {
+        const previous = this.terminalWatchers.get(localThreadId);
+        if (previous)
+            clearInterval(previous);
+        let checking = false;
+        const timer = setInterval(() => {
+            if (checking || this.shuttingDown || this.terminals.get(terminalId) !== terminal)
+                return;
+            checking = true;
+            const probe = terminal.lifecycleLivenessAsync
+                ? terminal.lifecycleLivenessAsync()
+                : terminal.livenessAsync
+                    ? terminal.livenessAsync()
+                    : terminal.isAliveAsync
+                        ? terminal.isAliveAsync().then((alive) => alive ? "alive" : "dead")
+                        : Promise.resolve(terminal.isAlive() ? "alive" : "dead");
+            void probe.then((liveness) => {
+                // A failed pane probe is inconclusive. Only reference implementation's lifecycle
+                // evidence — capture target gone or explicit pane_dead — may fail it.
+                if (liveness !== "dead" ||
+                    this.shuttingDown ||
+                    this.terminals.get(terminalId) !== terminal)
+                    return;
+                clearInterval(timer);
+                this.terminalWatchers.delete(localThreadId);
+                this.cancelTraexStartupWatcher(localThreadId);
+                const runtime = this.liveRuntimes.get(localThreadId);
+                const paneFailure = terminalFailureDetail(terminal.capturePane?.() ?? "");
+                const startupFailed = this.failCodexThreadStartup(localThreadId, this.liveProvider, nativePhaseError(runtime, "native_terminal_exited_before_session", "Terminal exited before native session discovery completed", paneFailure || undefined));
+                if (isCodexLineageProvider(runtime)) {
+                    if (!startupFailed) {
+                        try {
+                            this.terminals.close(terminalId);
+                        }
+                        catch (closeError) {
+                            console.warn(`[runner] session=${localThreadId} failed to close exited native Terminal: ${closeError instanceof Error ? closeError.message : String(closeError)}`);
+                        }
+                        const exitError = nativePhaseError(runtime, "native_terminal_exited", "Terminal exited unexpectedly", paneFailure || undefined);
+                        if (this.liveProvider.teardownLiveCodexSession) {
+                            this.liveProvider.teardownLiveCodexSession(localThreadId, exitError);
+                        }
+                        else {
+                            this.liveProvider.failLiveSession?.(localThreadId, exitError);
+                            this.liveProvider.stopLiveCodexSession?.(localThreadId);
+                        }
+                        this.liveIds.delete(localThreadId);
+                        console.warn(`[runner] session=${localThreadId} ${providerDisplayName(runtime)} auxiliary Terminal exited; native runtime torn down for cold resume`);
+                    }
+                    return;
+                }
+                this.liveProvider.failLiveSession?.(localThreadId, nativePhaseError(runtime, "native_terminal_exited", "Terminal exited unexpectedly", paneFailure || undefined));
+            }).catch((error) => {
+                console.warn(`[runner] session=${localThreadId} native Terminal liveness probe failed: ${error instanceof Error ? error.message : String(error)}`);
+            }).finally(() => {
+                checking = false;
+            });
+        }, 1_000);
+        timer.unref?.();
+        this.terminalWatchers.set(localThreadId, timer);
+    }
+    cancelTraexStartupWatcher(localThreadId) {
+        if (localThreadId)
+            this.traexStartupWatchers.delete(localThreadId);
+    }
+    async skipTraexStartupPrompts(localThreadId, terminal, watcher) {
+        const prompts = [
+            {
+                id: "welcome",
+                matches: (pane) => pane.includes("welcome to trae cli") && pane.includes("press enter to continue"),
+                dismiss: () => terminal.sendEnter(),
+                requiresEscapeConfirmation: false,
+            },
+            {
+                id: "migration",
+                matches: (pane) => (pane.includes("legacy traecode cli data detected") ||
+                    pane.includes("legacy trae cli data detected")) &&
+                    pane.includes("select what to import") &&
+                    (pane.includes("skip for now") || pane.includes("don't ask again")),
+                dismiss: () => terminal.interrupt(),
+                requiresEscapeConfirmation: true,
+            },
+            {
+                id: "hooks",
+                matches: (pane) => pane.includes("hooks need review") &&
+                    pane.includes("trust all and continue") &&
+                    pane.includes("continue without trusting"),
+                dismiss: () => terminal.interrupt(),
+                requiresEscapeConfirmation: true,
+            },
+        ];
+        let activeWelcome = false;
+        let pendingEscapePromptId;
+        const dismissedPromptIds = new Set();
+        let dismissedAnyPrompt = false;
+        const startedAt = Date.now();
+        let deadline = startedAt + TRAEX_STARTUP_WATCH_MS;
+        let discoveryDeadline = startedAt + TRAEX_STARTUP_DISCOVERY_MS;
+        const authorizationDeadline = startedAt + TRAEX_AUTHORIZATION_WAIT_MS;
+        const terminalId = `${localThreadId}-main`;
+        while (!this.shuttingDown &&
+            Date.now() < deadline &&
+            this.traexStartupWatchers.get(localThreadId) === watcher &&
+            this.terminals.get(terminalId) === terminal) {
+            // Do not treat a composer frame as completion: Traex can render it before
+            // the startup modals arrive. The bounded deadline stops this watcher.
+            const pane = normalizeTraexPane(terminal.capturePane());
+            const prompt = prompts.find((candidate) => candidate.matches(pane));
+            const now = Date.now();
+            const authorizationPending = isTraexAuthorizationPending(pane);
+            if (isTraexStartupActivity(pane)) {
+                discoveryDeadline = now + TRAEX_STARTUP_DISCOVERY_MS;
+            }
+            // Human device authorization routinely takes longer than the normal
+            // startup-modal window. Keep watching while that known screen remains,
+            // then preserve a full window for welcome/migration/hooks after sign-in.
+            // The separate cap prevents an abandoned auth screen from polling forever.
+            if (authorizationPending && now < authorizationDeadline) {
+                deadline = now + TRAEX_STARTUP_WATCH_MS;
+            }
+            if (!prompt) {
+                activeWelcome = false;
+                pendingEscapePromptId = undefined;
+                // Every dismissal is followed by a one-second cooldown before the next
+                // capture. If no known modal remains then, startup prompt handling is
+                // complete and message injection may safely begin.
+                if (dismissedAnyPrompt)
+                    break;
+                // A clean Traex home may have no startup modal at all. Preserve a
+                // five-second discovery window for late modals, but do not impose the
+                // old full 20-second watcher lifetime on every cold message. A visible
+                // updater keeps the full startup window because prompts may follow it.
+                if (now >= discoveryDeadline &&
+                    !authorizationPending &&
+                    !isTraexStartupActivity(pane))
+                    break;
+            }
+            else if (!prompt.requiresEscapeConfirmation) {
+                pendingEscapePromptId = undefined;
+                if (!activeWelcome && !dismissedPromptIds.has(prompt.id)) {
+                    prompt.dismiss();
+                    dismissedPromptIds.add(prompt.id);
+                    dismissedAnyPrompt = true;
+                    await new Promise((resolve) => {
+                        const timer = setTimeout(resolve, TRAEX_ESCAPE_COOLDOWN_MS);
+                        timer.unref();
+                    });
+                    continue;
+                }
+                activeWelcome = true;
+            }
+            else if (prompt.id !== pendingEscapePromptId) {
+                activeWelcome = false;
+                pendingEscapePromptId = prompt.id;
+                await new Promise((resolve) => {
+                    // Traex can show hooks -> migration -> hooks during one startup. The
+                    // trailing hooks screen normally disappears on its own, so observe a
+                    // previously handled prompt type for five seconds before acting.
+                    const timer = setTimeout(resolve, dismissedPromptIds.has(prompt.id)
+                        ? TRAEX_REPEAT_PROMPT_CONFIRM_MS
+                        : TRAEX_ESCAPE_CONFIRM_MS);
+                    timer.unref();
+                });
+                continue;
+            }
+            else {
+                prompt.dismiss();
+                dismissedPromptIds.add(prompt.id);
+                dismissedAnyPrompt = true;
+                // Keep the id through the cooldown. If the same prompt is genuinely
+                // still active after a sent key, the next check retries it; a prompt
+                // that disappeared during the cooldown never receives another key.
+                pendingEscapePromptId = prompt.id;
+                await new Promise((resolve) => {
+                    const timer = setTimeout(resolve, TRAEX_ESCAPE_COOLDOWN_MS);
+                    timer.unref();
+                });
+                continue;
+            }
+            await new Promise((resolve) => {
+                const timer = setTimeout(resolve, authorizationPending ? TRAEX_AUTHORIZATION_POLL_MS : TRAEX_STARTUP_POLL_MS);
+                timer.unref();
+            });
+        }
+        if (this.traexStartupWatchers.get(localThreadId) === watcher) {
+            this.traexStartupWatchers.delete(localThreadId);
+        }
     }
     stopLive() {
+        for (const timer of this.terminalWatchers.values())
+            clearInterval(timer);
+        this.terminalWatchers.clear();
         for (const id of this.liveIds) {
             this.liveProvider.stopLiveCodexSession?.(id, {
                 deferClaudeInteractionCleanup: true,
             });
         }
         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. */
@@ -272,6 +849,7 @@ export class RunnerSession {
         if (this.shuttingDown)
             return;
         this.shuttingDown = true;
+        this.rejectMirrorImageAcks(new Error("runner is shutting down"));
         this.stopLive();
         this.terminals.closeAll();
         this.liveProvider.finalizeStoppedLiveSessions?.();
@@ -336,6 +914,8 @@ export class RunnerSession {
             return;
         }
         this.attachments.set(msg.attachId, attachment);
+        if (msg.localThreadId)
+            this.attachmentThreadIds.set(msg.attachId, msg.localThreadId);
         attachment.onData((chunk) => this.transport.send({
             t: "term.data",
             attachId: msg.attachId,
@@ -343,6 +923,7 @@ export class RunnerSession {
         }));
         attachment.onExit((info) => {
             this.attachments.delete(msg.attachId);
+            this.attachmentThreadIds.delete(msg.attachId);
             this.transport.send({ t: "term.exit", attachId: msg.attachId, exitCode: info.exitCode });
         });
         this.transport.send({ t: "term.opened", attachId: msg.attachId, role });