@rynx-ai/runtime 0.1.11-beta.4 → 0.1.11-beta.41

package/dist/runner/child.js

@@ -1,20 +1,216 @@
-import { TerminalRegistry } from "../terminal/registry.js";
-import { toWireError } from "./protocol.js";
+/**
+ * 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 { appendFileSync, mkdirSync, renameSync, rmSync, statSync, } from "node:fs";
+import { dirname } from "node:path";
+import { AgentRuntimeError, } from "@rynx-ai/core";
+import { TerminalRegistry, } from "../terminal/registry.js";
+import { RUNNER_IMAGE_CHUNK_CHARS, RUNNER_IMAGE_MAX_RESULT_CHARS, toWireError, } from "./protocol.js";
+import { isCodexLineageProvider } from "./startup-policy.js";
+import { RunnerTransportWriteError, } from "./transport.js";
+const TERMINAL_PREPARATION_TTL_MS = 30_000;
+/** 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;
+const MIRROR_ACK_TIMEOUT_MS = 30_000;
+const MIRROR_DEAD_LETTER_MAX_BYTES = 50 * 1024 * 1024;
+class MirrorDeliveryError extends Error {
+    classification;
+    deliveryId;
+    constructor(message, classification, deliveryId) {
+        super(message);
+        this.classification = classification;
+        this.deliveryId = deliveryId;
+        this.name = "MirrorDeliveryError";
+    }
+}
+class MirrorGenerationSupersededError extends Error {
+    generation;
+    deliveryId;
+    constructor(generation, deliveryId) {
+        super(`mirror generation ${generation} was superseded by Session rotation`);
+        this.generation = generation;
+        this.deliveryId = deliveryId;
+        this.name = "MirrorGenerationSupersededError";
+    }
+}
+/** Delivery retry schedule: 1, 2, 4, 8, 16, 30, 30… seconds.
+ * Clamp before exponentiation so an indefinitely transient outage cannot
+ * overflow after thousands of attempts. */
+export function mirrorRetryDelayMs(failedAttempt) {
+    const exponent = Math.min(Math.max(failedAttempt - 1, 0), 32);
+    return Math.min(2 ** exponent, 30) * 1_000;
+}
+function defaultMirrorDeliveryPolicy(event) {
+    switch (event.type) {
+        case "response.output_item.done":
+        case "session.input.consumed":
+        case "session.interaction.requested":
+        case "session.interaction.resolved":
+        case "session.interaction.cancelled":
+            return "ordinary";
+        default:
+            return "best-effort";
+    }
+}
+function appendMirrorDeadLetter(path, entry) {
+    const line = `${JSON.stringify(entry)}\n`;
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    let currentBytes = 0;
+    try {
+        currentBytes = statSync(path).size;
+    }
+    catch {
+        // absent
+    }
+    if (currentBytes >= MIRROR_DEAD_LETTER_MAX_BYTES) {
+        rmSync(`${path}.1`, { force: true });
+        try {
+            renameSync(path, `${path}.1`);
+        }
+        catch {
+            // absent/raced — append creates the active file below
+        }
+    }
+    appendFileSync(path, line, { mode: 0o600 });
+}
+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;
     onShutdown;
     /** Live terminals hosted by this session, and per-attach client handles. */
     terminals = new TerminalRegistry();
+    preparations = new Map();
     attachments = new Map();
     attachmentThreadIds = new Map();
+    attachmentRoles = new Map();
     traexStartupWatchers = new Map();
+    traexStartupGates = new Map();
+    codexStartupMonitors = 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();
+    mirrorQueues = new Map();
+    mirrorAcks = new Map();
+    mirrorImageAcks = new Map();
+    mirrorRetryWaiters = new Map();
+    rotationPublishAcks = new Map();
+    rotationAppliedAcks = new Map();
+    /** Provider name retained for asynchronous Terminal-exit diagnostics. */
+    liveRuntimes = new Map();
+    terminalStatuses = new Map();
+    consecutiveMirrorFailures = 0;
+    mirrorDegraded = false;
     shuttingDown = false;
+    shutdownPromise = null;
     constructor({ transport, executor, onShutdown }) {
         this.transport = transport;
         this.executor = executor;
@@ -24,15 +220,107 @@ export class RunnerSession {
                     transport.close();
                 });
         this.transport.onMessage((msg) => this.handle(msg));
+        this.transport.onClose((error) => {
+            this.rejectMirrorAcks(new MirrorDeliveryError(error?.message ?? "runner transport closed before mirror acknowledgement", "ambiguous"));
+            this.rejectMirrorImageAcks(error ?? new Error("runner transport closed"));
+            this.rejectRotationAcks(error ?? new Error("runner transport closed"));
+        });
         this.transport.send({ t: "ready" });
     }
     handle(msg) {
         switch (msg.t) {
+            case "mirror.ack": {
+                const pending = this.mirrorAcks.get(msg.deliveryId);
+                if (!pending || msg.generation !== pending.generation) {
+                    return;
+                }
+                clearTimeout(pending.timer);
+                this.mirrorAcks.delete(msg.deliveryId);
+                pending.resolve();
+                return;
+            }
+            case "mirror.nack": {
+                const pending = this.mirrorAcks.get(msg.deliveryId);
+                if (!pending || msg.generation !== pending.generation) {
+                    return;
+                }
+                clearTimeout(pending.timer);
+                this.mirrorAcks.delete(msg.deliveryId);
+                pending.reject(new MirrorDeliveryError(msg.message, msg.classification, msg.deliveryId));
+                return;
+            }
+            case "mirror.image.ack": {
+                const pending = this.mirrorImageAcks.get(msg.transferId);
+                if (!pending || msg.generation !== pending.generation) {
+                    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 ||
+                    msg.generation !== pending.generation)
+                    return;
+                if (pending.timer)
+                    clearTimeout(pending.timer);
+                pending.timer = undefined;
+                return;
+            }
+            case "mirror.image.nack": {
+                const pending = this.mirrorImageAcks.get(msg.transferId);
+                if (!pending ||
+                    pending.seq !== msg.seq ||
+                    msg.generation !== pending.generation)
+                    return;
+                if (pending.timer)
+                    clearTimeout(pending.timer);
+                this.mirrorImageAcks.delete(msg.transferId);
+                pending.reject(new MirrorDeliveryError(msg.message, msg.classification));
+                return;
+            }
+            case "rotate.ack": {
+                const pending = this.rotationPublishAcks.get(msg.rotationId);
+                if (!pending || pending.generation !== msg.generation)
+                    return;
+                clearTimeout(pending.timer);
+                this.rotationPublishAcks.delete(msg.rotationId);
+                pending.resolve();
+                return;
+            }
+            case "rotate.nack": {
+                const pending = this.rotationPublishAcks.get(msg.rotationId);
+                if (!pending || pending.generation !== msg.generation)
+                    return;
+                clearTimeout(pending.timer);
+                this.rotationPublishAcks.delete(msg.rotationId);
+                pending.reject(new MirrorDeliveryError(msg.message, msg.classification));
+                return;
+            }
+            case "rotate.applied.ack": {
+                const pending = this.rotationAppliedAcks.get(msg.rotationId);
+                if (!pending || pending.generation !== msg.generation)
+                    return;
+                clearTimeout(pending.timer);
+                this.rotationAppliedAcks.delete(msg.rotationId);
+                pending.resolve();
+                return;
+            }
             case "cap":
                 void this.runCap(msg.capId, msg.name, msg.args);
                 return;
             case "term.open":
-                if (this.pendingTerminalOpens.has(msg.attachId) || this.attachments.has(msg.attachId)) {
+                if (this.pendingTerminalOpens.has(msg.attachId) ||
+                    this.preparations.has(msg.attachId) ||
+                    this.attachments.has(msg.attachId)) {
                     this.transport.send({
                         t: "term.error",
                         attachId: msg.attachId,
@@ -47,20 +335,35 @@ export class RunnerSession {
                     this.cancelledTerminalOpens.delete(msg.attachId);
                 });
                 return;
+            case "term.seed.read":
+                void this.readTerminalSeed(msg);
+                return;
+            case "term.start":
+                void this.startTerminal(msg);
+                return;
+            case "term.read":
+                void this.readTerminalOutput(msg);
+                return;
             case "term.input":
-                this.cancelTraexStartupWatcher(this.attachmentThreadIds.get(msg.attachId));
-                this.attachments.get(msg.attachId)?.write(Buffer.from(msg.dataB64, "base64").toString("utf8"));
+                void this.writeTerminalInput(msg);
                 return;
             case "term.resize":
-                this.attachments.get(msg.attachId)?.resize(msg.cols, msg.rows);
+                void this.resizeTerminal(msg);
                 return;
             case "term.close": {
                 if (this.pendingTerminalOpens.has(msg.attachId)) {
                     this.cancelledTerminalOpens.add(msg.attachId);
                 }
+                const pending = this.preparations.get(msg.attachId);
+                if (pending) {
+                    clearTimeout(pending.timer);
+                    this.preparations.delete(msg.attachId);
+                    pending.preparation.kill();
+                }
                 const attachment = this.attachments.get(msg.attachId);
                 this.attachments.delete(msg.attachId);
                 this.attachmentThreadIds.delete(msg.attachId);
+                this.attachmentRoles.delete(msg.attachId);
                 attachment?.kill();
                 return;
             }
@@ -74,11 +377,17 @@ 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;
+            case "terminal.reap":
+                void this.reapTerminal(msg);
+                return;
             case "shutdown":
-                this.shutdown();
+                void this.shutdown();
                 return;
         }
     }
@@ -109,28 +418,571 @@ export class RunnerSession {
      *  new session AND tells the daemon to alias the runner (terminal transfer) so
      *  the new session stays injectable. */
     mirrorChannel(localThreadId) {
-        const target = { id: localThreadId };
-        const emit = (event) => this.transport.send({ t: "mirror", sessionId: target.id, event });
+        const target = { id: localThreadId, generation: 0 };
+        let pendingRetarget;
+        const emit = (event, delivery) => {
+            const sessionId = target.id;
+            const generation = target.generation;
+            if (event.type === "session.status") {
+                this.terminalStatuses.set(sessionId, event.status);
+            }
+            return this.enqueueMirror(delivery?.lane ?? "main", () => this.sendMirroredEvent(sessionId, event, delivery, generation, () => generation === target.generation));
+        };
         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 } : {}),
+            let publication = pendingRetarget;
+            if (!publication && target.id === newId)
+                return Promise.resolve();
+            if (publication && publication.to !== newId) {
+                return Promise.reject(new Error(`Session rotation to ${publication.to} is still pending; cannot retarget to ${newId}`));
+            }
+            if (!publication) {
+                const previousGeneration = target.generation;
+                publication = {
+                    from: target.id,
+                    to: newId,
+                    generation: previousGeneration + 1,
+                    rotationId: `rotate_${randomUUID()}`,
+                    meta,
+                };
+                pendingRetarget = publication;
+                // Fence every source delivery immediately, but do not mutate the target
+                // identity or transfer resources until the parent ACKs publication.
+                target.generation = publication.generation;
+                this.cancelMirrorGeneration(previousGeneration);
+            }
+            if (publication.operation)
+                return publication.operation;
+            const current = publication;
+            const operation = this.enqueueMirror("control", async () => {
+                if (!current.resourcesApplied) {
+                    let attempt = 0;
+                    let publicationAcked = false;
+                    while (!publicationAcked) {
+                        attempt += 1;
+                        try {
+                            await this.sendRotationFrame(current.rotationId, current.generation, {
+                                t: "rotate",
+                                rotationId: current.rotationId,
+                                generation: current.generation,
+                                from: current.from,
+                                to: current.to,
+                                kind: current.meta.kind,
+                                workspace: current.meta.workspace,
+                                execution: current.meta.execution,
+                                ...(current.meta.parentSessionId
+                                    ? { parentSessionId: current.meta.parentSessionId }
+                                    : {}),
+                            });
+                            publicationAcked = true;
+                        }
+                        catch (error) {
+                            const failure = error instanceof MirrorDeliveryError
+                                ? error
+                                : new MirrorDeliveryError(error instanceof Error ? error.message : String(error), "transient");
+                            if (failure.classification === "permanent" && attempt >= 3) {
+                                // The parent still owns source/target reservations for this
+                                // half-published cutover. End the child so failHandle releases
+                                // them; leaving a live fenced pane would deadlock both ids.
+                                await this.shutdown();
+                                throw failure;
+                            }
+                            await this.waitForMirrorRetry(attempt, current.generation);
+                        }
+                    }
+                    if (pendingRetarget !== current)
+                        return;
+                    this.transferNativeSessionResources(current.from, current.to);
+                    target.id = current.to;
+                    current.resourcesApplied = true;
+                }
+                if (pendingRetarget !== current)
+                    return;
+                if (!current.hostApplied) {
+                    await current.meta.beforeApplied?.();
+                    if (pendingRetarget !== current)
+                        return;
+                    current.hostApplied = true;
+                }
+                // Ordered after the actual child-side ownership transfer. The parent
+                // keeps source and target admissions reserved until it observes this.
+                await this.sendRotationAppliedFrame(current.rotationId, current.generation, {
+                    t: "rotate.applied",
+                    rotationId: current.rotationId,
+                    generation: current.generation,
+                    from: current.from,
+                    to: current.to,
+                });
+                if (pendingRetarget !== current)
+                    return;
+                pendingRetarget = undefined;
+            }, { recoverable: true }).finally(() => {
+                if (pendingRetarget === current)
+                    delete current.operation;
             });
+            current.operation = operation;
+            return operation;
         };
         return { emit, retarget };
     }
+    transferNativeSessionResources(sourceId, targetId) {
+        if (sourceId === targetId)
+            return;
+        const sourceTerminalId = `${sourceId}-main`;
+        const targetTerminalId = `${targetId}-main`;
+        this.terminals.transfer(sourceTerminalId, targetTerminalId);
+        const watcher = this.terminalWatchers.get(sourceId);
+        if (watcher)
+            clearInterval(watcher);
+        this.terminalWatchers.delete(sourceId);
+        const runtime = this.liveRuntimes.get(sourceId);
+        if (runtime) {
+            this.liveRuntimes.delete(sourceId);
+            this.liveRuntimes.set(targetId, runtime);
+        }
+        const status = this.terminalStatuses.get(sourceId);
+        if (status) {
+            this.terminalStatuses.delete(sourceId);
+            this.terminalStatuses.set(targetId, status);
+        }
+        if (this.liveIds.delete(sourceId))
+            this.liveIds.add(targetId);
+        for (const [attachId, sessionId] of this.attachmentThreadIds) {
+            if (sessionId === sourceId)
+                this.attachmentThreadIds.set(attachId, targetId);
+        }
+        const terminal = this.terminals.get(targetTerminalId);
+        if (terminal)
+            this.watchNativeTerminal(targetId, targetTerminalId, terminal);
+    }
+    enqueueMirror(lane, operation, options = {}) {
+        const previous = this.mirrorQueues.get(lane) ?? Promise.resolve();
+        const queued = previous.then(operation);
+        const tail = queued.catch((error) => {
+            if (!this.shuttingDown && !options.recoverable) {
+                this.rejectMirrorImageAcks(error instanceof Error ? error : new Error(String(error)));
+                void this.shutdown();
+            }
+        });
+        this.mirrorQueues.set(lane, tail);
+        void tail.finally(() => {
+            if (this.mirrorQueues.get(lane) === tail)
+                this.mirrorQueues.delete(lane);
+        });
+        return queued;
+    }
+    async sendMirroredEvent(sessionId, event, delivery, generation = 0, isCurrent = () => true) {
+        if (!isCurrent())
+            return;
+        try {
+            const detached = detachGeneratedImageResult(event);
+            if (!detached) {
+                await this.deliverMirrorEvent(sessionId, event, delivery, generation, isCurrent);
+                return;
+            }
+            if (detached.result.length > RUNNER_IMAGE_MAX_RESULT_CHARS) {
+                await this.deliverMirrorEvent(sessionId, generatedImagePreviewUnavailable(detached.event), delivery, generation, isCurrent);
+                return;
+            }
+            await this.deliverMirrorImageEvent(sessionId, detached.event, detached.result, delivery, generation, isCurrent);
+        }
+        catch (error) {
+            if (error instanceof MirrorGenerationSupersededError)
+                return;
+            throw error;
+        }
+    }
+    async deliverMirrorImageEvent(sessionId, event, result, delivery, generation, isCurrent) {
+        const transferId = `img_${randomUUID()}`;
+        const abandon = () => this.transport.sendAndDrain({
+            t: "mirror.image.abandon",
+            transferId,
+            generation,
+        }).catch(() => {
+            // Parent/child teardown already releases process-local transfer state.
+        });
+        let seq = 0;
+        try {
+            await this.deliverMirrorImageTransportFrame(transferId, seq, generation, {
+                t: "mirror.image.begin",
+                transferId,
+                sessionId,
+                event,
+                totalChars: result.length,
+                generation,
+            }, isCurrent);
+            for (let offset = 0; offset < result.length; offset += RUNNER_IMAGE_CHUNK_CHARS) {
+                if (!isCurrent())
+                    throw new MirrorGenerationSupersededError(generation);
+                seq += 1;
+                await this.deliverMirrorImageTransportFrame(transferId, seq, generation, {
+                    t: "mirror.image.chunk",
+                    transferId,
+                    seq,
+                    data: result.slice(offset, offset + RUNNER_IMAGE_CHUNK_CHARS),
+                    generation,
+                }, isCurrent);
+            }
+        }
+        catch (error) {
+            await abandon();
+            throw error;
+        }
+        seq += 1;
+        const policy = delivery?.policy ?? defaultMirrorDeliveryPolicy(event);
+        let attempt = 0;
+        while (!this.shuttingDown) {
+            if (!isCurrent()) {
+                delivery?.onOutcome?.("superseded");
+                await abandon();
+                return;
+            }
+            attempt += 1;
+            try {
+                await this.sendMirrorImageFrame(transferId, seq, generation, {
+                    t: "mirror.image.commit",
+                    transferId,
+                    seq,
+                    generation,
+                }, "ambiguous");
+                this.noteMirrorDeliveryRecovered();
+                delivery?.onOutcome?.("confirmed");
+                return;
+            }
+            catch (error) {
+                if (error instanceof MirrorGenerationSupersededError || !isCurrent()) {
+                    delivery?.onOutcome?.("superseded");
+                    await abandon();
+                    return;
+                }
+                if (this.shuttingDown)
+                    break;
+                const failure = error instanceof MirrorDeliveryError
+                    ? error
+                    : new MirrorDeliveryError(error instanceof Error ? error.message : String(error), "ambiguous");
+                this.noteMirrorDeliveryFailed(failure);
+                if (policy === "best-effort") {
+                    delivery?.onOutcome?.("dropped");
+                    await abandon();
+                    return;
+                }
+                if (failure.classification === "ambiguous" &&
+                    (policy === "ordinary" || policy === "compaction" || policy === "compaction-hook")) {
+                    this.noteMirrorDeliveryRecovered();
+                    delivery?.onOutcome?.("ambiguous");
+                    await abandon();
+                    return;
+                }
+                if (failure.classification === "permanent" &&
+                    policy !== "compaction" &&
+                    attempt >= 3) {
+                    if (policy === "ordinary" && delivery?.deadLetterPath) {
+                        try {
+                            appendMirrorDeadLetter(delivery.deadLetterPath, {
+                                ts: Date.now() / 1_000,
+                                session_id: sessionId,
+                                event_type: "session_event",
+                                reason: "permanent IPC persistence failure after retries",
+                                delivered_ambiguous: false,
+                                http_status: null,
+                                transport_error: null,
+                                payload: {
+                                    source_id: delivery.sourceId,
+                                    attempts: attempt,
+                                    event,
+                                    generated_image_result: result,
+                                },
+                            });
+                        }
+                        catch (deadLetterError) {
+                            // The dead-letter writer is observability-only and never
+                            // turns an exhausted poison item into a runner-wide failure.
+                            console.error("[mirror] failed to append dead letter:", deadLetterError);
+                        }
+                    }
+                    delivery?.onOutcome?.("dropped");
+                    await abandon();
+                    return;
+                }
+                await this.waitForMirrorRetry(attempt, generation);
+            }
+        }
+        await abandon();
+        throw new MirrorDeliveryError("runner shut down before generated image delivery was handled", "transient");
+    }
+    async deliverMirrorImageTransportFrame(transferId, seq, generation, frame, isCurrent) {
+        let attempt = 0;
+        while (!this.shuttingDown) {
+            if (!isCurrent())
+                throw new MirrorGenerationSupersededError(generation);
+            attempt += 1;
+            try {
+                await this.sendMirrorImageFrame(transferId, seq, generation, frame, "transient");
+                return;
+            }
+            catch (error) {
+                if (error instanceof MirrorGenerationSupersededError || !isCurrent())
+                    throw error;
+                const failure = error instanceof MirrorDeliveryError
+                    ? error
+                    : new MirrorDeliveryError(error instanceof Error ? error.message : String(error), "transient");
+                this.noteMirrorDeliveryFailed(failure);
+                await this.waitForMirrorRetry(attempt, generation);
+            }
+        }
+        throw new MirrorDeliveryError("runner shut down during generated image transfer", "transient");
+    }
+    async deliverMirrorEvent(sessionId, event, delivery, generation = 0, isCurrent = () => true) {
+        const policy = delivery?.policy ?? defaultMirrorDeliveryPolicy(event);
+        let attempt = 0;
+        let lastFailedDeliveryId;
+        while (!this.shuttingDown) {
+            if (!isCurrent()) {
+                delivery?.onOutcome?.("superseded");
+                await this.abandonMirrorDelivery(lastFailedDeliveryId, generation);
+                return;
+            }
+            attempt += 1;
+            try {
+                await this.sendMirrorEventFrame(sessionId, event, generation, attempt);
+                this.noteMirrorDeliveryRecovered();
+                delivery?.onOutcome?.("confirmed");
+                return;
+            }
+            catch (error) {
+                if (error instanceof MirrorGenerationSupersededError || !isCurrent()) {
+                    delivery?.onOutcome?.("superseded");
+                    await this.abandonMirrorDelivery(error instanceof MirrorGenerationSupersededError
+                        ? error.deliveryId
+                        : error instanceof MirrorDeliveryError
+                            ? error.deliveryId
+                            : lastFailedDeliveryId, generation);
+                    return;
+                }
+                if (this.shuttingDown)
+                    break;
+                const failure = error instanceof MirrorDeliveryError
+                    ? error
+                    : new MirrorDeliveryError(error instanceof Error ? error.message : String(error), "ambiguous");
+                lastFailedDeliveryId = failure.deliveryId;
+                this.noteMirrorDeliveryFailed(failure);
+                if (policy === "best-effort") {
+                    console.warn(`[mirror] best-effort event dropped: ${failure.message}`);
+                    delivery?.onOutcome?.("dropped");
+                    return;
+                }
+                if (failure.classification === "ambiguous" &&
+                    (policy === "ordinary" || policy === "compaction" || policy === "compaction-hook")) {
+                    console.warn(`[mirror] ordinary delivery result is ambiguous; treating as handled: ${failure.message}`);
+                    this.noteMirrorDeliveryRecovered();
+                    delivery?.onOutcome?.("ambiguous");
+                    await this.abandonMirrorDelivery(failure.deliveryId, generation);
+                    return;
+                }
+                if (failure.classification === "permanent" &&
+                    policy !== "compaction" &&
+                    attempt >= 3) {
+                    if (policy === "ordinary" && delivery?.deadLetterPath) {
+                        try {
+                            appendMirrorDeadLetter(delivery.deadLetterPath, {
+                                ts: Date.now() / 1_000,
+                                session_id: sessionId,
+                                event_type: "session_event",
+                                reason: "permanent IPC persistence failure after retries",
+                                delivered_ambiguous: false,
+                                http_status: null,
+                                transport_error: null,
+                                payload: {
+                                    source_id: delivery.sourceId,
+                                    attempts: attempt,
+                                    event,
+                                },
+                            });
+                        }
+                        catch (deadLetterError) {
+                            console.error("[mirror] failed to append dead letter:", deadLetterError);
+                        }
+                    }
+                    console.error(`[mirror] permanent delivery failed after ${attempt} attempts; skipping: ${failure.message}`);
+                    delivery?.onOutcome?.("dropped");
+                    await this.abandonMirrorDelivery(failure.deliveryId, generation);
+                    return;
+                }
+                await this.waitForMirrorRetry(attempt, generation);
+            }
+        }
+        throw new MirrorDeliveryError("runner shut down before mirror delivery was handled", "transient");
+    }
+    noteMirrorDeliveryFailed(error) {
+        this.consecutiveMirrorFailures += 1;
+        if (!this.mirrorDegraded && this.consecutiveMirrorFailures >= 5) {
+            this.mirrorDegraded = true;
+            console.warn(`[mirror] delivery degraded after ${this.consecutiveMirrorFailures} consecutive failures: ${error.message}`);
+        }
+    }
+    noteMirrorDeliveryRecovered() {
+        if (this.mirrorDegraded)
+            console.info("[mirror] delivery recovered");
+        this.consecutiveMirrorFailures = 0;
+        this.mirrorDegraded = false;
+    }
+    sendMirrorEventFrame(sessionId, event, generation, attempt) {
+        const deliveryId = `mirror_${randomUUID()}`;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.mirrorAcks.delete(deliveryId);
+                reject(new MirrorDeliveryError("mirror acknowledgement timed out", "ambiguous", deliveryId));
+            }, MIRROR_ACK_TIMEOUT_MS);
+            timer.unref?.();
+            this.mirrorAcks.set(deliveryId, { generation, resolve, reject, timer });
+            void this.transport.sendAndDrain({
+                t: "mirror",
+                deliveryId,
+                generation,
+                attempt,
+                sessionId,
+                event,
+            }).catch((error) => {
+                const pending = this.mirrorAcks.get(deliveryId);
+                if (!pending)
+                    return;
+                clearTimeout(pending.timer);
+                this.mirrorAcks.delete(deliveryId);
+                const classification = error instanceof RunnerTransportWriteError &&
+                    error.delivery === "not-sent"
+                    ? "transient"
+                    : "ambiguous";
+                pending.reject(new MirrorDeliveryError(error instanceof Error ? error.message : String(error), classification, deliveryId));
+            });
+        });
+    }
+    async abandonMirrorDelivery(deliveryId, generation) {
+        if (!deliveryId)
+            return;
+        await this.transport.sendAndDrain({
+            t: "mirror.abandon",
+            deliveryId,
+            generation,
+        }).catch(() => {
+            // Parent/child teardown already releases process-local projection state.
+        });
+    }
+    waitForMirrorRetry(failedAttempt, generation) {
+        return new Promise((resolve) => {
+            const waiters = this.mirrorRetryWaiters.get(generation) ?? new Set();
+            let timer;
+            const done = () => {
+                clearTimeout(timer);
+                waiters.delete(done);
+                if (waiters.size === 0)
+                    this.mirrorRetryWaiters.delete(generation);
+                resolve();
+            };
+            timer = setTimeout(done, mirrorRetryDelayMs(failedAttempt));
+            timer.unref?.();
+            waiters.add(done);
+            this.mirrorRetryWaiters.set(generation, waiters);
+        });
+    }
+    cancelMirrorGeneration(generation) {
+        const error = new MirrorGenerationSupersededError(generation);
+        for (const [deliveryId, pending] of this.mirrorAcks) {
+            if (pending.generation !== generation)
+                continue;
+            clearTimeout(pending.timer);
+            this.mirrorAcks.delete(deliveryId);
+            pending.reject(new MirrorGenerationSupersededError(generation, deliveryId));
+        }
+        for (const [transferId, pending] of this.mirrorImageAcks) {
+            if (pending.generation !== generation)
+                continue;
+            if (pending.timer)
+                clearTimeout(pending.timer);
+            this.mirrorImageAcks.delete(transferId);
+            pending.reject(error);
+        }
+        for (const wake of this.mirrorRetryWaiters.get(generation) ?? [])
+            wake();
+        this.mirrorRetryWaiters.delete(generation);
+    }
+    rejectMirrorAcks(error) {
+        for (const pending of this.mirrorAcks.values()) {
+            clearTimeout(pending.timer);
+            pending.reject(error);
+        }
+        this.mirrorAcks.clear();
+    }
+    sendMirrorImageFrame(transferId, seq, generation, frame, timeoutClassification = "transient") {
+        return new Promise((resolve, reject) => {
+            const pending = { generation, seq, resolve, reject };
+            const timer = setTimeout(() => {
+                if (this.mirrorImageAcks.get(transferId) !== pending)
+                    return;
+                this.mirrorImageAcks.delete(transferId);
+                reject(new MirrorDeliveryError("generated image transfer acknowledgement timed out", timeoutClassification));
+            }, MIRROR_IMAGE_ACK_TIMEOUT_MS);
+            timer.unref?.();
+            pending.timer = timer;
+            this.mirrorImageAcks.set(transferId, pending);
+            void this.transport.sendAndDrain(frame).catch((error) => {
+                if (this.mirrorImageAcks.get(transferId) !== pending)
+                    return;
+                clearTimeout(timer);
+                this.mirrorImageAcks.delete(transferId);
+                const classification = timeoutClassification === "ambiguous" &&
+                    (!(error instanceof RunnerTransportWriteError) || error.delivery === "ambiguous")
+                    ? "ambiguous"
+                    : "transient";
+                reject(new MirrorDeliveryError(error instanceof Error ? error.message : String(error), classification));
+            });
+        });
+    }
+    rejectMirrorImageAcks(error) {
+        for (const pending of this.mirrorImageAcks.values()) {
+            if (pending.timer)
+                clearTimeout(pending.timer);
+            pending.reject(error);
+        }
+        this.mirrorImageAcks.clear();
+    }
+    sendRotationFrame(rotationId, generation, frame) {
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.rotationPublishAcks.delete(rotationId);
+                reject(new Error("Session rotation acknowledgement timed out"));
+            }, MIRROR_ACK_TIMEOUT_MS);
+            timer.unref?.();
+            this.rotationPublishAcks.set(rotationId, { generation, resolve, reject, timer });
+            this.transport.send(frame);
+        });
+    }
+    sendRotationAppliedFrame(rotationId, generation, frame) {
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.rotationAppliedAcks.delete(rotationId);
+                reject(new Error("Session rotation applied acknowledgement timed out"));
+            }, MIRROR_ACK_TIMEOUT_MS);
+            timer.unref?.();
+            this.rotationAppliedAcks.set(rotationId, { generation, resolve, reject, timer });
+            this.transport.send(frame);
+        });
+    }
+    rejectRotationAcks(error) {
+        for (const pending of this.rotationPublishAcks.values()) {
+            clearTimeout(pending.timer);
+            pending.reject(error);
+        }
+        this.rotationPublishAcks.clear();
+        for (const pending of this.rotationAppliedAcks.values()) {
+            clearTimeout(pending.timer);
+            pending.reject(error);
+        }
+        this.rotationAppliedAcks.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;
@@ -142,43 +994,142 @@ 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);
-            }
-            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()
+                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);
+                }
+            }
+            // 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) {
+        // Starting (or declining to start) a new monitor invalidates every callback
+        // owned by the previous launch before it can touch the replacement state.
+        this.codexStartupMonitors.delete(localThreadId);
+        if (!provider.waitLiveReady)
+            return;
+        if (provider.liveSessionFailure?.(localThreadId)?.code === "login_required")
+            return;
+        const expectedTerminal = this.terminals.get(`${localThreadId}-main`);
+        const monitor = Symbol(localThreadId);
+        this.codexStartupMonitors.set(localThreadId, monitor);
+        const claimCurrentLaunch = () => {
+            if (this.codexStartupMonitors.get(localThreadId) !== monitor ||
+                this.terminals.get(`${localThreadId}-main`) !== expectedTerminal)
+                return false;
+            this.codexStartupMonitors.delete(localThreadId);
+            return true;
+        };
+        void provider.waitLiveReady(localThreadId, CODEX_THREAD_START_TIMEOUT_MS).then((ready) => {
+            if (ready) {
+                if (this.codexStartupMonitors.get(localThreadId) === monitor) {
+                    this.codexStartupMonitors.delete(localThreadId);
+                }
+                return;
+            }
+            if (!claimCurrentLaunch())
+                return;
+            const terminal = this.terminals.get(`${localThreadId}-main`);
+            const paneFailure = terminal && !terminal.isAlive()
                 ? terminal
                     .capturePane()
                     .split("\n")
@@ -188,44 +1139,109 @@ 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"), expectedTerminal);
+        }).catch((error) => {
+            if (!claimCurrentLaunch())
+                return;
+            this.failCodexThreadStartup(localThreadId, provider, error instanceof AgentRuntimeError
+                ? error
+                : nativePhaseError(runtime, "native_thread_discovery_failed", "native session discovery failed", error), expectedTerminal);
+        });
+    }
+    /** 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, expectedTerminal) {
+        if (!provider.failLiveStartup?.(localThreadId, error))
+            return false;
+        this.codexStartupMonitors.delete(localThreadId);
+        const watcher = this.terminalWatchers.get(localThreadId);
+        if (watcher)
+            clearInterval(watcher);
+        this.terminalWatchers.delete(localThreadId);
+        this.cancelTraexStartupWatcher(localThreadId);
+        try {
+            this.terminals.close(`${localThreadId}-main`, expectedTerminal);
+        }
+        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";
-            if (outcome === "injected")
-                this.cancelTraexStartupWatcher(msg.localThreadId);
-            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),
             });
         }
     }
@@ -237,7 +1253,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",
@@ -247,6 +1263,43 @@ export class RunnerSession {
             ...(error ? { error } : {}),
         });
     }
+    async reapTerminal(msg) {
+        let error;
+        try {
+            const lifecycle = this.terminals.lifecycle(msg.terminalId);
+            const watcher = this.terminalWatchers.get(msg.localThreadId);
+            if (watcher)
+                clearInterval(watcher);
+            this.terminalWatchers.delete(msg.localThreadId);
+            this.cancelTraexStartupWatcher(msg.localThreadId);
+            for (const [attachId, sessionId] of this.attachmentThreadIds) {
+                if (sessionId !== msg.localThreadId)
+                    continue;
+                this.attachments.get(attachId)?.kill();
+                this.attachments.delete(attachId);
+                this.attachmentThreadIds.delete(attachId);
+                this.attachmentRoles.delete(attachId);
+            }
+            this.terminals.close(msg.terminalId);
+            if (lifecycle === "auxiliary") {
+                await this.liveProvider.teardownAuxiliaryTerminalRuntime?.(msg.localThreadId);
+                this.liveIds.delete(msg.localThreadId);
+                this.liveRuntimes.delete(msg.localThreadId);
+                this.terminalStatuses.delete(msg.localThreadId);
+            }
+        }
+        catch (cause) {
+            error = toWireError(cause);
+        }
+        this.transport.send({
+            t: "terminal.reaped",
+            reqId: msg.reqId,
+            localThreadId: msg.localThreadId,
+            terminalId: msg.terminalId,
+            ok: error === undefined,
+            ...(error ? { error } : {}),
+        });
+    }
     /** Launch (idempotently) the session's codex TUI pane from the executor's
      *  `codexTerminalSpec`. Shares the `${id}-main` terminal id with `term.open`,
      *  so the web attach reuses the same detached pane. */
@@ -255,21 +1308,107 @@ export class RunnerSession {
         if (!spec)
             return;
         const terminalId = `${localThreadId}-main`;
-        const coldStart = !this.terminals.has(terminalId);
         const term = this.terminals.getOrCreate(terminalId, {
+            lifecycle: spec.lifecycle,
             cwd: spec.cwd,
             command: spec.command,
             args: spec.args,
             cols: cols ?? 120,
             rows: rows ?? 40,
             ...(spec.env ? { env: spec.env } : {}),
+            ...(spec.scrollback === undefined ? {} : { scrollback: spec.scrollback }),
+            ...(spec.tmuxAllowPassthrough === undefined
+                ? {}
+                : { tmuxAllowPassthrough: spec.tmuxAllowPassthrough }),
+            ...(spec.tmuxStartOnAttach === undefined
+                ? {}
+                : { tmuxStartOnAttach: spec.tmuxStartOnAttach }),
+            ...(spec.keepAliveAfterExit === undefined
+                ? {}
+                : { keepAliveAfterExit: spec.keepAliveAfterExit }),
         });
-        if (coldStart && spec.skipTraexStartupPrompts) {
+        if (spec.skipTraexStartupPrompts) {
             const watcher = Symbol(localThreadId);
             this.traexStartupWatchers.set(localThreadId, watcher);
-            void this.skipTraexStartupPrompts(localThreadId, term, 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 lifecycle = this.terminals.lifecycle(terminalId);
+                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), terminal);
+                if (startupFailed || lifecycle === undefined)
+                    return;
+                try {
+                    this.terminals.close(terminalId, terminal);
+                }
+                catch (closeError) {
+                    console.warn(`[runner] session=${localThreadId} failed to close exited native Terminal: ${closeError instanceof Error ? closeError.message : String(closeError)}`);
+                }
+                const status = this.terminalStatuses.get(localThreadId) ?? "unknown";
+                if (lifecycle === "auxiliary") {
+                    console.warn(`[runner] session=${localThreadId} ${providerDisplayName(runtime)} auxiliary Terminal exited`);
+                }
+                else {
+                    if (status !== "idle") {
+                        this.liveProvider.failLiveSession?.(localThreadId, nativePhaseError(runtime, "required_terminal_exited", "Required Terminal exited unexpectedly", paneFailure || undefined));
+                    }
+                    this.liveProvider.stopLiveCodexSession?.(localThreadId);
+                    this.liveIds.delete(localThreadId);
+                    this.liveRuntimes.delete(localThreadId);
+                    this.terminalStatuses.delete(localThreadId);
+                }
+                this.enqueueMirror("main", () => {
+                    this.transport.send({
+                        t: "terminal.lifecycle.ended",
+                        localThreadId,
+                        terminalId,
+                        lifecycle,
+                        status,
+                    });
+                });
+            }).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)
@@ -279,46 +1418,118 @@ export class RunnerSession {
         const prompts = [
             {
                 id: "welcome",
-                matches: (pane) => pane.includes("Welcome to TRAE CLI") && pane.includes("Press enter to continue"),
+                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 TRAE CLI data detected") &&
-                    pane.includes("Would you like to migrate detected data to the new TRAE CLI storage?") &&
-                    pane.includes("Select what to import:"),
+                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("hooks are new or changed.") &&
-                    pane.includes("Trust all and continue") &&
-                    pane.includes("Continue without trusting"),
+                matches: (pane) => pane.includes("hooks need review") &&
+                    pane.includes("trust all and continue") &&
+                    pane.includes("continue without trusting"),
                 dismiss: () => terminal.interrupt(),
+                requiresEscapeConfirmation: true,
             },
         ];
-        const dismissed = new Set();
-        const deadline = Date.now() + 20_000;
+        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) {
-            const pane = terminal.capturePane();
-            // Once the normal composer is visible, startup is complete and there is
-            // no reason to keep polling the tmux pane for the remainder of the window.
-            if (pane.includes("TRAE CLI Next"))
-                break;
+            // 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));
-            if (prompt && !dismissed.has(prompt.id)) {
-                prompt.dismiss();
-                dismissed.add(prompt.id);
-                if (dismissed.size === prompts.length)
+            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, 100);
+                const timer = setTimeout(resolve, authorizationPending ? TRAEX_AUTHORIZATION_POLL_MS : TRAEX_STARTUP_POLL_MS);
                 timer.unref();
             });
         }
@@ -327,28 +1538,54 @@ export class RunnerSession {
         }
     }
     stopLive() {
+        for (const timer of this.terminalWatchers.values())
+            clearInterval(timer);
+        this.terminalWatchers.clear();
+        this.codexStartupMonitors.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. */
     shutdown() {
-        if (this.shuttingDown)
-            return;
+        if (this.shutdownPromise)
+            return this.shutdownPromise;
         this.shuttingDown = true;
-        this.stopLive();
-        this.terminals.closeAll();
-        this.liveProvider.finalizeStoppedLiveSessions?.();
-        this.onShutdown();
+        this.shutdownPromise = (async () => {
+            const shutdownError = new Error("runner is shutting down");
+            this.rejectMirrorAcks(shutdownError);
+            this.rejectMirrorImageAcks(shutdownError);
+            this.rejectRotationAcks(shutdownError);
+            for (const waiters of this.mirrorRetryWaiters.values()) {
+                for (const wake of waiters)
+                    wake();
+            }
+            this.mirrorRetryWaiters.clear();
+            this.stopLive();
+            for (const pending of this.preparations.values()) {
+                clearTimeout(pending.timer);
+                pending.preparation.kill();
+            }
+            this.preparations.clear();
+            for (const attachment of this.attachments.values())
+                attachment.kill();
+            this.terminals.closeAll();
+            this.attachments.clear();
+            this.attachmentThreadIds.clear();
+            this.attachmentRoles.clear();
+            await this.liveProvider.finalizeStoppedLiveSessions?.();
+            this.onShutdown();
+        })();
+        return this.shutdownPromise;
     }
     async openTerminal(msg) {
         try {
-            // codex/claude-native session (no explicit command): DUMB ATTACH — reference implementation's
-            // reattach (codex_native.py:905-942, `app_server=None`). A tab switch ONLY
+            // codex/claude-native session (no explicit command): DUMB ATTACH. A tab switch ONLY
             // attaches an already-live pane; it NEVER ensures the forwarder or relaunches a
             // dead pane. Creation/relaunch happens on message-send (`live.ensure`) or an
             // explicit restart. A missing/dead pane → `term.error`, so the web shows the
@@ -370,6 +1607,7 @@ export class RunnerSession {
             }
             // Login-shell terminal (explicit command): create-or-reuse as before.
             this.terminals.getOrCreate(msg.terminalId, {
+                lifecycle: "auxiliary",
                 cwd: msg.cwd,
                 command: msg.command,
                 args: msg.args,
@@ -387,14 +1625,14 @@ export class RunnerSession {
             });
         }
     }
-    /** Attach an already-created terminal and forward its data/exit to the parent. */
+    /** Prepare captured history without starting the live control client. */
     async attachExisting(msg) {
-        const { attachment, role } = await this.terminals.attach(msg.terminalId, msg.role, {
+        const { preparation, role } = await this.terminals.prepare(msg.terminalId, msg.role, {
             cols: msg.cols,
             rows: msg.rows,
         });
         if (this.cancelledTerminalOpens.has(msg.attachId)) {
-            attachment.kill();
+            preparation.kill();
             this.transport.send({
                 t: "term.error",
                 attachId: msg.attachId,
@@ -403,20 +1641,168 @@ export class RunnerSession {
             });
             return;
         }
-        this.attachments.set(msg.attachId, attachment);
+        const timer = setTimeout(() => {
+            const pending = this.preparations.get(msg.attachId);
+            if (!pending || pending.preparation !== preparation)
+                return;
+            this.preparations.delete(msg.attachId);
+            this.attachmentThreadIds.delete(msg.attachId);
+            this.attachmentRoles.delete(msg.attachId);
+            preparation.kill();
+        }, TERMINAL_PREPARATION_TTL_MS);
+        timer.unref?.();
+        this.preparations.set(msg.attachId, { preparation, timer });
+        this.attachmentRoles.set(msg.attachId, role);
         if (msg.localThreadId)
             this.attachmentThreadIds.set(msg.attachId, msg.localThreadId);
-        attachment.onData((chunk) => this.transport.send({
-            t: "term.data",
+        this.transport.send({
+            t: "term.prepared",
             attachId: msg.attachId,
-            dataB64: Buffer.from(chunk, "utf8").toString("base64"),
-        }));
-        attachment.onExit((info) => {
-            this.attachments.delete(msg.attachId);
+            role,
+            seedBytes: preparation.seedBytes,
+            ...(preparation.dimensions ?? {}),
+        });
+    }
+    async readTerminalSeed(msg) {
+        const pending = this.preparations.get(msg.attachId);
+        if (!pending) {
+            this.sendTerminalOperationError(msg.attachId, msg.reqId, "terminal is not prepared");
+            return;
+        }
+        try {
+            const result = await pending.preparation.readSeed(msg.offset, msg.maxBytes);
+            await this.transport.sendAndDrain({
+                t: "term.seed.chunk",
+                attachId: msg.attachId,
+                reqId: msg.reqId,
+                dataB64: Buffer.from(result.data).toString("base64"),
+                nextOffset: result.nextOffset,
+                done: result.done,
+                ...(result.finalOffset === undefined ? {} : { finalOffset: result.finalOffset }),
+            });
+        }
+        catch (error) {
+            this.sendTerminalOperationError(msg.attachId, msg.reqId, error);
+        }
+    }
+    async startTerminal(msg) {
+        const pending = this.preparations.get(msg.attachId);
+        if (!pending) {
+            this.sendTerminalOperationError(msg.attachId, msg.reqId, "terminal is not prepared");
+            return;
+        }
+        clearTimeout(pending.timer);
+        this.preparations.delete(msg.attachId);
+        try {
+            const attachment = await pending.preparation.start();
+            this.attachments.set(msg.attachId, attachment);
+            attachment.onResize(({ cols, rows }) => {
+                this.transport.send({ t: "term.dimensions", attachId: msg.attachId, cols, rows });
+            });
+            await this.transport.sendAndDrain({
+                t: "term.started",
+                attachId: msg.attachId,
+                reqId: msg.reqId,
+            });
+            void attachment.readerDone.then(async (info) => {
+                await this.transport.sendAndDrain({
+                    t: "term.reader.done",
+                    attachId: msg.attachId,
+                    finalOffset: info.finalOffset,
+                    reason: info.reason,
+                    exitCode: info.exitCode,
+                }).catch(() => undefined);
+            });
+        }
+        catch (error) {
+            pending.preparation.kill();
             this.attachmentThreadIds.delete(msg.attachId);
-            this.transport.send({ t: "term.exit", attachId: msg.attachId, exitCode: info.exitCode });
+            this.attachmentRoles.delete(msg.attachId);
+            this.sendTerminalOperationError(msg.attachId, msg.reqId, error);
+        }
+    }
+    async readTerminalOutput(msg) {
+        const attachment = this.attachments.get(msg.attachId);
+        if (!attachment) {
+            this.sendTerminalOperationError(msg.attachId, msg.reqId, "terminal has not started");
+            return;
+        }
+        try {
+            const result = await attachment.read(msg.offset, msg.maxBytes);
+            await this.transport.sendAndDrain({
+                t: "term.chunk",
+                attachId: msg.attachId,
+                reqId: msg.reqId,
+                dataB64: Buffer.from(result.data).toString("base64"),
+                nextOffset: result.nextOffset,
+                done: result.done,
+                ...(result.finalOffset === undefined ? {} : { finalOffset: result.finalOffset }),
+            });
+        }
+        catch (error) {
+            this.sendTerminalOperationError(msg.attachId, msg.reqId, error);
+        }
+    }
+    async writeTerminalInput(msg) {
+        if (this.attachmentRoles.get(msg.attachId) !== "owner") {
+            await this.transport.sendAndDrain({
+                t: "term.ack",
+                attachId: msg.attachId,
+                reqId: msg.reqId,
+                operation: "input",
+            });
+            return;
+        }
+        const attachment = this.attachments.get(msg.attachId);
+        if (!attachment) {
+            this.sendTerminalOperationError(msg.attachId, msg.reqId, "terminal has not started");
+            return;
+        }
+        const localThreadId = this.attachmentThreadIds.get(msg.attachId);
+        const input = Buffer.from(msg.dataB64, "base64");
+        if (!isTerminalProtocolResponse(input.toString("utf8"))) {
+            this.cancelTraexStartupWatcher(localThreadId);
+        }
+        try {
+            await attachment.write(input);
+            await this.transport.sendAndDrain({
+                t: "term.ack",
+                attachId: msg.attachId,
+                reqId: msg.reqId,
+                operation: "input",
+            });
+        }
+        catch (error) {
+            this.sendTerminalOperationError(msg.attachId, msg.reqId, error);
+        }
+    }
+    async resizeTerminal(msg) {
+        const attachment = this.attachments.get(msg.attachId);
+        if (!attachment) {
+            this.sendTerminalOperationError(msg.attachId, msg.reqId, "terminal has not started");
+            return;
+        }
+        try {
+            await attachment.resize(msg.cols, msg.rows);
+            await this.transport.sendAndDrain({
+                t: "term.ack",
+                attachId: msg.attachId,
+                reqId: msg.reqId,
+                operation: "resize",
+            });
+        }
+        catch (error) {
+            this.sendTerminalOperationError(msg.attachId, msg.reqId, error);
+        }
+    }
+    sendTerminalOperationError(attachId, reqId, error) {
+        this.transport.send({
+            t: "term.error",
+            attachId,
+            reqId,
+            code: "terminal_open_failed",
+            message: error instanceof Error ? error.message : String(error),
         });
-        this.transport.send({ t: "term.opened", attachId: msg.attachId, role });
     }
     async runCap(capId, name, args) {
         try {