@rynx-ai/runtime 0.1.11-beta.37 → 0.1.11-beta.39

package/dist/runner/child.js

@@ -8,10 +8,13 @@
  * 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;
@@ -54,6 +57,68 @@ 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();
 }
@@ -133,11 +198,17 @@ export class RunnerSession {
     cancelledTerminalOpens = new Set();
     /** Session ids with a live codex forwarder started here (stopped on shutdown). */
     liveIds = new Set();
-    mirrorQueue = Promise.resolve();
+    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 }) {
@@ -150,16 +221,39 @@ export class RunnerSession {
                 });
         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)
+                if (!pending || msg.generation !== pending.generation) {
                     return;
+                }
                 if (pending.seq !== msg.seq) {
                     pending.reject(new Error("generated image acknowledgement sequence changed"));
                     return;
@@ -172,13 +266,54 @@ export class RunnerSession {
             }
             case "mirror.image.hold": {
                 const pending = this.mirrorImageAcks.get(msg.transferId);
-                if (!pending || pending.seq !== msg.seq)
+                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;
@@ -283,29 +418,109 @@ 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) => {
+        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);
             }
-            this.enqueueMirror(() => this.sendMirroredEvent(sessionId, event));
+            return this.enqueueMirror(delivery?.lane ?? "main", () => this.sendMirroredEvent(sessionId, event, delivery, generation, () => generation === target.generation));
         };
         const retarget = (newId, meta) => {
-            const previousId = target.id;
-            this.transferNativeSessionResources(previousId, newId);
-            target.id = newId;
-            this.enqueueMirror(() => {
-                this.transport.send({
-                    t: "rotate",
-                    from: previousId,
+            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,
-                    kind: meta.kind,
-                    workspace: meta.workspace,
-                    execution: meta.execution,
-                    ...(meta.parentSessionId ? { parentSessionId: meta.parentSessionId } : {}),
+                    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 };
     }
@@ -339,62 +554,386 @@ export class RunnerSession {
         if (terminal)
             this.watchNativeTerminal(targetId, targetTerminalId, terminal);
     }
-    enqueueMirror(operation) {
-        this.mirrorQueue = this.mirrorQueue.then(operation).catch((error) => {
-            if (!this.shuttingDown) {
+    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) {
-        const detached = detachGeneratedImageResult(event);
-        if (!detached) {
-            this.transport.send({ t: "mirror", sessionId, event });
+    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);
         }
-        if (detached.result.length > RUNNER_IMAGE_MAX_RESULT_CHARS) {
-            this.transport.send({
-                t: "mirror",
-                sessionId,
-                event: generatedImagePreviewUnavailable(detached.event),
-            });
-            return;
+        catch (error) {
+            if (error instanceof MirrorGenerationSupersededError)
+                return;
+            throw error;
         }
+    }
+    async deliverMirrorImageEvent(sessionId, event, result, delivery, generation, isCurrent) {
         const transferId = `img_${randomUUID()}`;
-        let seq = 0;
-        await this.sendMirrorImageFrame(transferId, seq, {
-            t: "mirror.image.begin",
+        const abandon = () => this.transport.sendAndDrain({
+            t: "mirror.image.abandon",
             transferId,
-            sessionId,
-            event: detached.event,
-            totalChars: detached.result.length,
+            generation,
+        }).catch(() => {
+            // Parent/child teardown already releases process-local transfer state.
         });
-        for (let offset = 0; offset < detached.result.length; offset += RUNNER_IMAGE_CHUNK_CHARS) {
-            seq += 1;
-            await this.sendMirrorImageFrame(transferId, seq, {
-                t: "mirror.image.chunk",
+        let seq = 0;
+        try {
+            await this.deliverMirrorImageTransportFrame(transferId, seq, generation, {
+                t: "mirror.image.begin",
                 transferId,
-                seq,
-                data: detached.result.slice(offset, offset + RUNNER_IMAGE_CHUNK_CHARS),
-            });
+                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;
-        await this.sendMirrorImageFrame(transferId, seq, {
-            t: "mirror.image.commit",
-            transferId,
-            seq,
+        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.
         });
     }
-    sendMirrorImageFrame(transferId, seq, frame) {
+    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 Error("generated image transfer acknowledgement timed out"));
+                reject(new MirrorDeliveryError("generated image transfer acknowledgement timed out", timeoutClassification));
             }, MIRROR_IMAGE_ACK_TIMEOUT_MS);
             timer.unref?.();
-            this.mirrorImageAcks.set(transferId, { seq, resolve, reject, timer });
-            this.transport.send(frame);
+            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) {
@@ -405,6 +944,40 @@ export class RunnerSession {
         }
         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. Fresh sessions connect
      * the discovery listener before launching the detached TUI; known-thread
@@ -819,7 +1392,7 @@ export class RunnerSession {
                     this.liveRuntimes.delete(localThreadId);
                     this.terminalStatuses.delete(localThreadId);
                 }
-                this.enqueueMirror(() => {
+                this.enqueueMirror("main", () => {
                     this.transport.send({
                         t: "terminal.lifecycle.ended",
                         localThreadId,
@@ -984,7 +1557,15 @@ export class RunnerSession {
             return this.shutdownPromise;
         this.shuttingDown = true;
         this.shutdownPromise = (async () => {
-            this.rejectMirrorImageAcks(new Error("runner is shutting down"));
+            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);