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

package/dist/runner/manager.js

@@ -26,6 +26,7 @@ import { terminateTmuxServer, tmuxHasAttachedClient, tmuxWindowActivityAt, } fro
 import { RUNNER_IMAGE_CHUNK_CHARS, RUNNER_IMAGE_MAX_RESULT_CHARS, fromWireError, } from "./protocol.js";
 import { isCodexLineageProvider, isManagedNativeProvider } from "./startup-policy.js";
 import { StdioRunnerTransport } from "./transport.js";
+import { cloneClaudeTranscript } from "../claude/transcript-clone.js";
 /** Routing key for the shared capability runner (slash-command RPCs). */
 const CAP_KEY = "__cap__";
 /** Max stderr lines retained per handle for the crash exit-report tail. */
@@ -57,6 +58,7 @@ const MAX_SESSION_CONTEXT_ENV_ENTRIES = 32;
 const MAX_SESSION_CONTEXT_ENV_KEY_BYTES = 128;
 const MAX_SESSION_CONTEXT_ENV_VALUE_BYTES = 8_192;
 const MAX_SESSION_CONTEXT_ENV_TOTAL_BYTES = 32_768;
+const MAX_TERMINAL_RESPONSE_IDS = 2_000;
 /** A typed attach failure so transport adapters can distinguish an expected
  * absent pane from an infrastructure failure without matching error strings. */
 export class TerminalOpenError extends Error {
@@ -295,6 +297,12 @@ export class RunnerManager {
     stopPromise;
     /** Sink for mirrored {@link SessionEvent}s from every session's forwarder. */
     mirrorListener = null;
+    /** Settles process-local projections only when an ordinary durable item has
+     * exhausted its permanent retry budget. */
+    mirrorAbandonListener = null;
+    /** Clears process-live optimistic state when /clear permanently moves the
+     * native pane away from the old Session. */
+    mirrorSupersedeListener = null;
     /** Synchronous persistence hook for native collaboration-mode reflection.
      * It runs before the event reaches the Session bus. */
     collaborationModeListener = null;
@@ -467,6 +475,12 @@ export class RunnerManager {
     onMirror(listener) {
         this.mirrorListener = listener;
     }
+    onMirrorAbandon(listener) {
+        this.mirrorAbandonListener = listener;
+    }
+    onMirrorSupersede(listener) {
+        this.mirrorSupersedeListener = listener;
+    }
     onCollaborationMode(listener) {
         this.collaborationModeListener = listener;
     }
@@ -553,7 +567,7 @@ export class RunnerManager {
             if (candidate === handle && this.liveSessionKeys.has(sessionId))
                 return sessionId;
         }
-        return fallback;
+        return handle.activeSessionId || fallback;
     }
     finishTerminalInputHandoff(handle, handoff) {
         if (handoff.timer) {
@@ -750,6 +764,14 @@ export class RunnerManager {
             .finally(() => admission.release());
     }
     injectMessageAdmitted(localThreadId, input, options) {
+        const rotatingHandle = this.handles.get(localThreadId);
+        if (rotatingHandle?.pendingRotation?.from === localThreadId &&
+            !rotatingHandle.dead) {
+            // Reject input addressed to the old active Session during
+            // cutover. Do not wait and then silently reopen the retired Session: the
+            // user can retry after the client follows session.rotated.
+            return Promise.resolve({ outcome: "notReady" });
+        }
         const sourceReservation = this.sourceForkReservations.get(localThreadId);
         if (sourceReservation) {
             return sourceReservation.then(() => this.injectMessageAdmitted(localThreadId, input, options));
@@ -1010,6 +1032,7 @@ export class RunnerManager {
             this.liveErrors.clear();
             this.liveOptions.clear();
             this.mirrorListener = null;
+            this.mirrorAbandonListener = null;
             this.rotateListener = null;
             const errors = results
                 .filter((result) => result.status === "rejected")
@@ -1131,29 +1154,67 @@ export class RunnerManager {
     }
     async performClaudeManagedFork(currentLocalThreadId, newLocalThreadId, options) {
         const source = await this.sessionStore.get(currentLocalThreadId);
+        const getIntent = this.sessionStore.getClaudeForkIntent?.bind(this.sessionStore);
         const setIntent = this.sessionStore.setClaudeForkIntent?.bind(this.sessionStore);
         const deleteIntent = this.sessionStore.deleteClaudeForkIntent?.bind(this.sessionStore);
-        if (!source?.codexSessionId || !setIntent || !deleteIntent) {
+        if (!source?.codexSessionId || !getIntent || !setIntent || !deleteIntent) {
             return {
                 ok: false,
                 reason: "unsupported",
                 message: "Claude fork persistence is unavailable",
             };
         }
-        const targetClaudeSessionId = randomUUID();
+        const persistedIntent = await getIntent(newLocalThreadId);
+        if (persistedIntent &&
+            persistedIntent.sourceSessionId !== currentLocalThreadId) {
+            return {
+                ok: false,
+                reason: "error",
+                message: "target Session already has a different Claude fork intent",
+            };
+        }
+        // A durable fork operation may be replayed after clone+intent persistence
+        // but before SessionStart commits the Provider binding. Reuse that exact
+        // target id/path/prefix: re-cloning would move the fork boundary if the
+        // source advanced (or silently lose history if it disappeared).
+        const targetClaudeSessionId = persistedIntent?.targetClaudeSessionId ?? randomUUID();
         try {
-            await setIntent({
-                targetSessionId: newLocalThreadId,
-                sourceSessionId: currentLocalThreadId,
-                sourceClaudeSessionId: source.codexSessionId,
-                targetClaudeSessionId,
-                updatedAt: new Date().toISOString(),
-            });
-            const ready = await this.requestLiveSession(newLocalThreadId, {
+            if (!persistedIntent) {
+                let clonedTranscript = null;
+                try {
+                    clonedTranscript = await cloneClaudeTranscript({
+                        sourceClaudeSessionId: source.codexSessionId,
+                        targetClaudeSessionId,
+                        targetCwd: options.workspace.cwd,
+                    });
+                }
+                catch (error) {
+                    console.error(`[claude-fork] could not clone source transcript for ${newLocalThreadId}; target will start without Provider history: ${error instanceof Error ? error.message : String(error)}`);
+                }
+                await setIntent({
+                    targetSessionId: newLocalThreadId,
+                    sourceSessionId: currentLocalThreadId,
+                    sourceClaudeSessionId: source.codexSessionId,
+                    targetClaudeSessionId,
+                    ...(clonedTranscript
+                        ? {
+                            forkTranscriptPath: clonedTranscript.transcriptPath,
+                            ...(clonedTranscript.prefixBytes === undefined
+                                ? {}
+                                : { forkTranscriptPrefixBytes: clonedTranscript.prefixBytes }),
+                        }
+                        : {}),
+                    updatedAt: new Date().toISOString(),
+                });
+            }
+            await this.requestLiveSession(newLocalThreadId, {
                 workspace: structuredClone(options.workspace),
                 execution: structuredClone(options.execution),
             }, true, true);
-            const target = ready ? await this.sessionStore.get(newLocalThreadId) : null;
+            // SessionStart commits the binding before the child reports live.ready.
+            // If that final ACK is lost (or the child exits in between), the durable
+            // binding is authoritative and must not be rolled back.
+            const target = await this.sessionStore.get(newLocalThreadId);
             if (!target ||
                 target.parentSessionId !== currentLocalThreadId ||
                 target.codexSessionId !== targetClaudeSessionId) {
@@ -1163,10 +1224,8 @@ export class RunnerManager {
             return { ok: true, data: undefined };
         }
         catch (error) {
-            await deleteIntent(newLocalThreadId).catch(() => undefined);
-            const target = await this.sessionStore.get(newLocalThreadId).catch(() => null);
-            if (target?.parentSessionId === currentLocalThreadId) {
-                await this.sessionStore.delete(newLocalThreadId).catch(() => undefined);
+            if (!persistedIntent) {
+                await deleteIntent(newLocalThreadId).catch(() => undefined);
             }
             const handle = this.handles.get(newLocalThreadId);
             if (handle && !handle.dead) {
@@ -1204,42 +1263,180 @@ export class RunnerManager {
     deliverMirrorMessage(handle, message) {
         if (handle.dead)
             return;
-        if (message.event.type === "session.collaboration_mode") {
-            this.collaborationModeListener?.(message.sessionId, message.event.mode);
+        if (this.isStaleMirrorGeneration(handle, message.generation)) {
+            if ("deliveryId" in message) {
+                handle.transport.send({
+                    t: "mirror.ack",
+                    deliveryId: message.deliveryId,
+                    generation: message.generation,
+                });
+            }
+            else {
+                handle.imageTransfers.delete(message.transferId);
+                handle.transport.send({
+                    t: "mirror.image.ack",
+                    transferId: message.transferId,
+                    seq: message.seq,
+                    generation: message.generation,
+                });
+            }
+            return;
         }
-        this.observeHandleRuntimeEvent(handle, message.event);
+        if ("deliveryId" in message) {
+            const existing = handle.mirrorDeliveries.get(message.deliveryId);
+            if (existing && existing.sessionId !== message.sessionId) {
+                void this.terminateHandle(handle, "conflicting ordinary mirror delivery replay").catch((error) => logTerminationFailure(handle, error));
+                return;
+            }
+            if (!existing) {
+                handle.mirrorDeliveries.set(message.deliveryId, {
+                    sessionId: message.sessionId,
+                    abandonRequested: false,
+                });
+            }
+        }
+        let observationCommitted = false;
+        const commitObservation = () => {
+            if (observationCommitted)
+                return;
+            observationCommitted = true;
+            if (this.isStaleMirrorGeneration(handle, message.generation))
+                return;
+            if (message.event.type === "session.collaboration_mode") {
+                this.collaborationModeListener?.(message.sessionId, message.event.mode);
+            }
+            this.observeHandleRuntimeEvent(handle, message.event);
+            if (message.event.type === "response.created") {
+                this.settleTerminalInputHandoff(handle, message.sessionId, "turn");
+            }
+        };
+        const commitDeliveredObservation = () => {
+            commitObservation();
+            if (handle.dead) {
+                // The listener may have persisted/observed this event before its
+                // Promise settled, while failHandle still saw no committed active id.
+                // Close that newly visible response instead of leaving server runtime
+                // state permanently running.
+                this.failActiveResponses(handle, "runner_crashed", handle.failureReason ?? "runner exited during mirror publication");
+            }
+        };
         let delivered;
         try {
-            delivered = Promise.resolve(this.mirrorListener?.(message.sessionId, message.event));
+            const result = this.mirrorListener?.(message.sessionId, message.event);
+            if (result && typeof result.then === "function") {
+                delivered = Promise.resolve(result);
+            }
+            else {
+                commitObservation();
+                delivered = Promise.resolve();
+            }
         }
         catch (error) {
             delivered = Promise.reject(error);
         }
-        if (message.event.type === "response.created") {
-            // The listener projects response.created into SessionRuntimeIndex
-            // synchronously. Only then may the accepted terminal reservation drain
-            // into a maintenance activity snapshot.
-            this.settleTerminalInputHandoff(handle, message.sessionId, "turn");
-        }
-        if (message.transferId && message.seq !== undefined) {
+        if ("transferId" in message) {
+            const transfer = handle.imageTransfers.get(message.transferId);
+            if (transfer)
+                transfer.publication = delivered;
             void delivered.then(() => {
+                commitDeliveredObservation();
                 if (!handle.dead) {
+                    if (handle.imageTransfers.get(message.transferId) === transfer) {
+                        handle.imageTransfers.delete(message.transferId);
+                    }
                     handle.transport.send({
                         t: "mirror.image.ack",
                         transferId: message.transferId,
                         seq: message.seq,
+                        generation: message.generation,
                     });
                 }
             }, (error) => {
-                this.failMirrorImageTransfer(handle, `generated image publication failed: ${errorMessage(error)}`);
+                if (handle.dead)
+                    return;
+                if (handle.imageTransfers.get(message.transferId) === transfer && transfer) {
+                    delete transfer.publication;
+                    delete transfer.commitSeq;
+                }
+                handle.transport.send({
+                    t: "mirror.image.nack",
+                    transferId: message.transferId,
+                    seq: message.seq,
+                    generation: message.generation,
+                    classification: mirrorNackClassification(error),
+                    message: errorMessage(error),
+                });
             });
         }
         else {
-            void delivered.catch((error) => {
-                console.error(`Session mirror publication failed: ${errorMessage(error)}`);
+            void delivered.then(() => {
+                commitDeliveredObservation();
+                this.releaseMirrorDelivery(handle, message.deliveryId);
+                if (!handle.dead) {
+                    handle.transport.send({
+                        t: "mirror.ack",
+                        deliveryId: message.deliveryId,
+                        generation: message.generation,
+                    });
+                }
+            }, (error) => {
+                const abandonToken = mirrorAbandonToken(error);
+                if (handle.dead) {
+                    // The child can disappear while SQLite publication is still in
+                    // flight. A later exact pending-input failure still owns cleanup;
+                    // only the wire NACK is impossible after process death.
+                    if (abandonToken) {
+                        this.mirrorAbandonListener?.(message.sessionId, abandonToken);
+                    }
+                    return;
+                }
+                {
+                    const classification = mirrorNackClassification(error);
+                    const delivery = handle.mirrorDeliveries.get(message.deliveryId);
+                    if (delivery && abandonToken)
+                        delivery.abandonToken = abandonToken;
+                    if (classification === "permanent" &&
+                        message.attempt >= 3 &&
+                        abandonToken) {
+                        this.mirrorAbandonListener?.(message.sessionId, abandonToken);
+                        this.releaseMirrorDelivery(handle, message.deliveryId);
+                    }
+                    else if (delivery?.abandonRequested && abandonToken) {
+                        this.mirrorAbandonListener?.(delivery.sessionId, abandonToken);
+                        this.releaseMirrorDelivery(handle, message.deliveryId);
+                    }
+                    else if (!abandonToken) {
+                        this.releaseMirrorDelivery(handle, message.deliveryId);
+                    }
+                    else if (delivery && !delivery.cleanupTimer) {
+                        // A timely NACK may be retried with a fresh delivery id. Retain
+                        // the old association briefly for the timeout/NACK race, then
+                        // release it if the child never reports an ambiguous outcome.
+                        const timer = setTimeout(() => {
+                            this.releaseMirrorDelivery(handle, message.deliveryId);
+                        }, 60_000);
+                        timer.unref?.();
+                        delivery.cleanupTimer = timer;
+                    }
+                    handle.transport.send({
+                        t: "mirror.nack",
+                        deliveryId: message.deliveryId,
+                        generation: message.generation,
+                        classification,
+                        message: errorMessage(error),
+                    });
+                }
             });
         }
     }
+    releaseMirrorDelivery(handle, deliveryId) {
+        const delivery = handle.mirrorDeliveries.get(deliveryId);
+        if (!delivery)
+            return;
+        if (delivery.cleanupTimer)
+            clearTimeout(delivery.cleanupTimer);
+        handle.mirrorDeliveries.delete(deliveryId);
+    }
     failMirrorImageTransfer(handle, reason) {
         handle.imageTransfers.clear();
         void this.terminateHandle(handle, reason).catch((error) => {
@@ -1247,95 +1444,361 @@ export class RunnerManager {
         });
     }
     deliverRotateMessage(handle, message) {
-        if (this.forkReservations.has(message.to) ||
-            this.sourceForkReservations.has(message.from)) {
-            void this.terminateHandle(handle, "conflicting Session rotation").catch((error) => logTerminationFailure(handle, error));
-            return;
-        }
-        try {
-            // Rotate the runtime-local context before publishing the new Session
-            // alias to routing or observers. This prevents the new identity from
-            // briefly inheriting stale context after `/clear` or `/fork`.
-            handle.sessionContext?.rotate(message.to);
-        }
-        catch (error) {
-            const reason = `runner Session context rotation failed: ${errorMessage(error)}`;
-            void this.terminateHandle(handle, reason).catch((terminationError) => {
-                logTerminationFailure(handle, terminationError);
+        const generation = message.generation;
+        if (handle.completedRotation?.rotationId === message.rotationId &&
+            handle.completedRotation.generation === generation &&
+            handle.completedRotation.from === message.from &&
+            handle.completedRotation.to === message.to) {
+            handle.transport.send({
+                t: "rotate.ack",
+                rotationId: message.rotationId,
+                generation,
             });
             return;
         }
-        let releaseTarget;
-        const targetReservation = new Promise((resolve) => {
-            releaseTarget = resolve;
-        });
-        let releaseSource;
-        const sourceReservation = new Promise((resolve) => {
-            releaseSource = resolve;
-        });
-        this.forkReservations.set(message.to, targetReservation);
-        this.sourceForkReservations.set(message.from, sourceReservation);
-        this.forkBufferedMessages.set(message.to, []);
-        this.forkBufferedTerminalInputs.set(message.to, []);
-        // The physical pane has already rotated. Remove every old routing alias now:
-        // a later request for the source must spawn a fresh runner that resumes the
-        // source Provider binding, while existing terminal attachments continue to
-        // follow the transferred pane.
-        for (const [key, candidate] of this.handles) {
-            if (candidate !== handle)
-                continue;
-            this.handles.delete(key);
-            this.liveSessionKeys.delete(key);
-            this.liveOptions.delete(key);
-        }
-        const rotation = {
-            from: message.from,
-            to: message.to,
-            kind: message.kind,
-            workspace: message.workspace,
-            execution: message.execution,
-            ...(message.parentSessionId ? { parentSessionId: message.parentSessionId } : {}),
-        };
-        void Promise.resolve(this.rotateListener?.(rotation))
-            .then(() => {
-            // The server's rotation listener resolves only after the target Session
-            // is published. Release the terminal admission handoff afterwards so a
-            // maintenance snapshot cannot observe a gap with neither source work
-            // nor the target Session.
-            this.settleTerminalRotationHandoff(handle, message.from, message.to);
-            if (handle.dead)
+        let pending = handle.pendingRotation;
+        if (pending) {
+            if (pending.rotationId !== message.rotationId ||
+                pending.generation !== generation ||
+                pending.from !== message.from ||
+                pending.to !== message.to ||
+                pending.kind !== message.kind) {
+                void this.terminateHandle(handle, "conflicting Session rotation replay").catch((error) => logTerminationFailure(handle, error));
+                return;
+            }
+            if (pending.publicationComplete) {
+                handle.transport.send({
+                    t: "rotate.ack",
+                    rotationId: pending.rotationId,
+                    generation: pending.generation,
+                });
+                return;
+            }
+            if (pending.inFlight)
+                return;
+        }
+        else {
+            if (this.forkReservations.has(message.to) ||
+                this.sourceForkReservations.has(message.from)) {
+                void this.terminateHandle(handle, "conflicting Session rotation").catch((error) => logTerminationFailure(handle, error));
                 return;
-            handle.activeResponseIds.clear();
-            this.handles.set(message.to, handle);
-            this.liveSessionKeys.add(message.to);
-            this.liveOptions.set(message.to, {
-                workspace: structuredClone(message.workspace),
-                execution: structuredClone(message.execution),
+            }
+            try {
+                // Rotate the runtime-local context before publishing the new Session
+                // alias to routing or observers. This prevents the new identity from
+                // briefly inheriting stale context after `/clear` or `/fork`.
+                handle.sessionContext?.rotate(message.to);
+            }
+            catch (error) {
+                const reason = `runner Session context rotation failed: ${errorMessage(error)}`;
+                void this.terminateHandle(handle, reason).catch((terminationError) => {
+                    logTerminationFailure(handle, terminationError);
+                });
+                return;
+            }
+            let releaseTarget;
+            const targetReservation = new Promise((resolve) => {
+                releaseTarget = resolve;
             });
-            for (const entry of this.forkBufferedMessages.get(message.to) ?? []) {
-                this.deliverForkBufferedMessage(entry.handle, entry.message);
+            let releaseSource;
+            const sourceReservation = new Promise((resolve) => {
+                releaseSource = resolve;
+            });
+            pending = {
+                rotationId: message.rotationId,
+                generation,
+                from: message.from,
+                to: message.to,
+                kind: message.kind,
+                rotation: {
+                    from: message.from,
+                    to: message.to,
+                    kind: message.kind,
+                    workspace: structuredClone(message.workspace),
+                    execution: structuredClone(message.execution),
+                    ...(message.parentSessionId ? { parentSessionId: message.parentSessionId } : {}),
+                },
+                targetReservation,
+                sourceReservation,
+                releaseTarget,
+                releaseSource,
+                inFlight: false,
+                logicalTargetPublished: false,
+                publicationComplete: false,
+            };
+            handle.pendingRotation = pending;
+            this.forkReservations.set(pending.to, targetReservation);
+            this.sourceForkReservations.set(pending.from, sourceReservation);
+            this.forkBufferedMessages.set(pending.to, []);
+            this.forkBufferedTerminalInputs.set(pending.to, []);
+        }
+        pending.inFlight = true;
+        void Promise.resolve().then(async () => {
+            if (pending.logicalTargetPublished)
+                return;
+            await this.rotateListener?.(pending.rotation);
+            if (handle.dead || handle.pendingRotation !== pending)
+                return false;
+            pending.logicalTargetPublished = true;
+            return true;
+        })
+            .then((current) => {
+            if (current === false || handle.dead || handle.pendingRotation !== pending)
+                return false;
+            return this.publishNativeRotationBinding(pending).then(() => true);
+        })
+            .then((current) => {
+            if (current === false || handle.dead || handle.pendingRotation !== pending) {
+                if (handle.pendingRotation === pending) {
+                    this.releasePendingNativeRotation(handle, pending);
+                }
+                return;
             }
-            for (const entry of this.forkBufferedTerminalInputs.get(message.to) ?? []) {
-                if (!entry.handle.dead)
-                    entry.handle.transport.send(entry.message);
+            pending.inFlight = false;
+            pending.publicationComplete = true;
+            // Durable publication grants the child permission to move ownership.
+            // Keep both logical ids fenced until rotate.applied proves that the
+            // child has actually transferred its terminal/runtime registries.
+            try {
+                handle.transport.send({
+                    t: "rotate.ack",
+                    rotationId: pending.rotationId,
+                    generation: pending.generation,
+                });
+            }
+            catch (error) {
+                this.releasePendingNativeRotation(handle, pending);
+                void this.terminateHandle(handle, `runner Session rotation commit failed: ${errorMessage(error)}`).catch((terminationError) => {
+                    logTerminationFailure(handle, terminationError);
+                });
             }
         })
             .catch((error) => {
-            void this.terminateHandle(handle, `Session rotation publication failed: ${errorMessage(error)}`).catch((terminationError) => logTerminationFailure(handle, terminationError));
-        })
-            .finally(() => {
-            if (this.forkReservations.get(message.to) === targetReservation) {
-                this.forkReservations.delete(message.to);
+            if (handle.pendingRotation !== pending)
+                return;
+            pending.inFlight = false;
+            if (handle.dead) {
+                this.releasePendingNativeRotation(handle, pending);
+                return;
             }
-            if (this.sourceForkReservations.get(message.from) === sourceReservation) {
-                this.sourceForkReservations.delete(message.from);
+            try {
+                handle.transport.send({
+                    t: "rotate.nack",
+                    rotationId: pending.rotationId,
+                    generation: pending.generation,
+                    classification: mirrorNackClassification(error),
+                    message: errorMessage(error),
+                });
             }
-            this.forkBufferedMessages.delete(message.to);
-            this.forkBufferedTerminalInputs.delete(message.to);
-            releaseTarget();
-            releaseSource();
+            catch (sendError) {
+                this.releasePendingNativeRotation(handle, pending);
+                void this.terminateHandle(handle, `runner Session rotation NACK failed: ${errorMessage(sendError)}`).catch((terminationError) => {
+                    logTerminationFailure(handle, terminationError);
+                });
+            }
+        });
+    }
+    /** Bridge ownership is a child-local binding, but the parent is the only
+     * process that knows logical target publication committed. Mark that fact
+     * durably before allowing the child to apply and expose the alias. */
+    async publishNativeRotationBinding(pending) {
+        await this.publishNativeRotationRecords(pending.from, pending.to, pending.kind);
+    }
+    async publishNativeRotationRecords(from, to, kind) {
+        const target = await this.sessionStore.get(to);
+        const source = await this.sessionStore.get(from);
+        if (!target) {
+            throw new AgentRuntimeError("native rotation target binding is missing", 422, "native_rotation_target_missing");
+        }
+        const publishedTarget = {
+            ...target,
+            nativeRotationSourceSessionId: from,
+            nativeRotationKind: kind,
+            nativeRotationPublished: true,
+            updatedAt: new Date().toISOString(),
+        };
+        await this.sessionStore.set(publishedTarget);
+        if (!source)
+            return;
+        await this.sessionStore.set({
+            ...source,
+            bridgeOwnerSessionId: `${from}-${kind}-retired-${to}`,
+            nativeRotationTargetSessionId: to,
+            updatedAt: new Date().toISOString(),
         });
     }
+    deliverRotateAppliedMessage(handle, message) {
+        const pending = handle.pendingRotation;
+        if (pending &&
+            pending.publicationComplete &&
+            pending.rotationId === message.rotationId &&
+            pending.generation === message.generation &&
+            pending.from === message.from &&
+            pending.to === message.to) {
+            void this.finalizeNativeRotation(handle, pending);
+            return;
+        }
+        if (handle.completedRotation?.rotationId === message.rotationId &&
+            handle.completedRotation.generation === message.generation &&
+            handle.completedRotation.from === message.from &&
+            handle.completedRotation.to === message.to) {
+            this.acknowledgeRotateApplied(handle, message.rotationId, message.generation);
+            return;
+        }
+        void this.terminateHandle(handle, "invalid Session rotation applied confirmation").catch((error) => logTerminationFailure(handle, error));
+    }
+    finalizeNativeRotation(handle, pending) {
+        if (pending.finalization)
+            return pending.finalization;
+        const operation = (async () => {
+            if (handle.pendingRotation !== pending)
+                return false;
+            pending.inFlight = true;
+            try {
+                // Change the active Session only after ownership transfer. In
+                // this IPC topology rotate.applied is the child-owned equivalent proof.
+                this.settleTerminalRotationHandoff(handle, pending.from, pending.to);
+                handle.activeResponseIds.clear();
+                for (const [key, candidate] of this.handles) {
+                    if (candidate !== handle)
+                        continue;
+                    this.handles.delete(key);
+                    this.liveSessionKeys.delete(key);
+                    this.liveOptions.delete(key);
+                }
+                handle.activeSessionId = pending.to;
+                this.handles.set(pending.to, handle);
+                this.liveSessionKeys.add(pending.to);
+                this.liveOptions.set(pending.to, {
+                    workspace: structuredClone(pending.rotation.workspace),
+                    execution: structuredClone(pending.rotation.execution),
+                });
+                handle.completedRotation = {
+                    rotationId: pending.rotationId,
+                    generation: pending.generation,
+                    from: pending.from,
+                    to: pending.to,
+                };
+                // Old-Session presentation is ordered internally but must not hold the
+                // ownership-transfer ACK. Each notice still receives the server queue's
+                // bounded result window; the rotated target can proceed immediately.
+                const noticePublication = this.publishNativeRotationNotice(pending);
+                if (handle.dead)
+                    return false;
+                this.acknowledgeRotateApplied(handle, pending.rotationId, pending.generation);
+                for (const entry of this.forkBufferedMessages.get(pending.to) ?? []) {
+                    this.deliverForkBufferedMessage(entry.handle, entry.message);
+                }
+                for (const entry of this.forkBufferedTerminalInputs.get(pending.to) ?? []) {
+                    if (!entry.handle.dead)
+                        entry.handle.transport.send(entry.message);
+                }
+                void noticePublication.catch((error) => {
+                    console.error(`Session rotation notice sequence failed for ${pending.from} -> ${pending.to}: ${errorMessage(error)}`);
+                });
+                return true;
+            }
+            catch (error) {
+                void this.terminateHandle(handle, `runner Session rotation finalization failed: ${errorMessage(error)}`).catch((terminationError) => {
+                    logTerminationFailure(handle, terminationError);
+                });
+                return false;
+            }
+            finally {
+                pending.inFlight = false;
+                this.releasePendingNativeRotation(handle, pending);
+            }
+        })();
+        pending.finalization = operation;
+        return operation;
+    }
+    acknowledgeRotateApplied(handle, rotationId, generation) {
+        try {
+            handle.transport.send({ t: "rotate.applied.ack", rotationId, generation });
+        }
+        catch (error) {
+            void this.terminateHandle(handle, `runner Session rotation applied ACK failed: ${errorMessage(error)}`).catch((terminationError) => {
+                logTerminationFailure(handle, terminationError);
+            });
+        }
+    }
+    releasePendingNativeRotation(handle, pending) {
+        if (handle.pendingRotation !== pending)
+            return;
+        delete handle.pendingRotation;
+        if (this.forkReservations.get(pending.to) === pending.targetReservation) {
+            this.forkReservations.delete(pending.to);
+        }
+        if (this.sourceForkReservations.get(pending.from) === pending.sourceReservation) {
+            this.sourceForkReservations.delete(pending.from);
+        }
+        this.forkBufferedMessages.delete(pending.to);
+        this.forkBufferedTerminalInputs.delete(pending.to);
+        pending.releaseTarget();
+        pending.releaseSource();
+    }
+    async publishNativeRotationNotice(pending) {
+        // Only /clear supersedes the old Session. A /fork keeps
+        // both conversations live and therefore emits no old-session redirect.
+        if (pending.kind !== "clear" || pending.from === pending.to)
+            return;
+        this.mirrorSupersedeListener?.(pending.from);
+        const noticeId = `msg_clear_${randomUUID().replaceAll("-", "")}`;
+        const notice = {
+            type: "response.output_item.done",
+            responseId: noticeId,
+            item: {
+                id: noticeId,
+                sessionId: pending.from,
+                position: 0,
+                responseId: noticeId,
+                status: "completed",
+                createdAt: Date.now(),
+                type: "message",
+                data: {
+                    role: "assistant",
+                    content: [{
+                            type: "output_text",
+                            text: "This session was ended by `/clear`. " +
+                                `Continue in [the new session](../${encodeURIComponent(pending.to)}). ` +
+                                "You can also send a message here to resume this session.",
+                        }],
+                },
+            },
+        };
+        const transient = {
+            type: "session.rotated",
+            sessionId: pending.from,
+            newSessionId: pending.to,
+            kind: "clear",
+        };
+        // Preserve the post-clear order: stop the old spinner, append a
+        // durable assistant notice, then tell a live viewer to follow the target.
+        const publications = [];
+        for (const event of [
+            {
+                type: "session.status",
+                sessionId: pending.from,
+                status: "idle",
+                backgroundTaskCount: 0,
+            },
+            notice,
+            transient,
+        ]) {
+            try {
+                // The server-side SessionMirrorQueue owns the per-record
+                // per-record result deadline. A second enqueue-time timer here would
+                // expire later records before they reach the head of that queue.
+                publications.push(Promise.resolve(this.mirrorListener?.(pending.from, event)).catch((error) => {
+                    console.error(`Session rotation notice failed for ${pending.from} -> ${pending.to}: ${errorMessage(error)}`);
+                }));
+            }
+            catch (error) {
+                console.error(`Session rotation notice failed for ${pending.from} -> ${pending.to}: ${errorMessage(error)}`);
+            }
+        }
+        await Promise.all(publications);
+    }
     spawnHandle(key) {
         const args = this.runnerEntry.endsWith(".ts")
             ? ["--import", "tsx", this.runnerEntry]
@@ -1368,11 +1831,13 @@ export class RunnerManager {
         const transport = new StdioRunnerTransport(child.stdout, child.stdin);
         const handle = {
             key,
+            activeSessionId: key,
             child,
             transport,
             stderr: [],
             lastUsedAt: this.now(),
             activeResponseIds: new Set(),
+            terminalResponseIds: new Set(),
             dead: false,
             completion,
             processGroup,
@@ -1381,6 +1846,7 @@ export class RunnerManager {
             terminals: new Map(),
             live: new Map(),
             imageTransfers: new Map(),
+            mirrorDeliveries: new Map(),
         };
         this.childHandles.add(handle);
         void completion.then(() => this.childHandles.delete(handle));
@@ -1457,13 +1923,65 @@ export class RunnerManager {
             case "mirror":
                 if (handle.dead)
                     return;
+                if (!msg.deliveryId ||
+                    !Number.isSafeInteger(msg.generation) ||
+                    !Number.isSafeInteger(msg.attempt) ||
+                    msg.attempt < 1) {
+                    void this.terminateHandle(handle, "invalid durable mirror delivery frame").catch((error) => logTerminationFailure(handle, error));
+                    return;
+                }
                 if (this.bufferForkTargetMessage(handle, msg))
                     return;
                 this.deliverMirrorMessage(handle, msg);
                 return;
+            case "mirror.abandon": {
+                if (!msg.deliveryId || !Number.isSafeInteger(msg.generation)) {
+                    void this.terminateHandle(handle, "invalid mirror abandon frame").catch((error) => logTerminationFailure(handle, error));
+                    return;
+                }
+                const delivery = handle.mirrorDeliveries.get(msg.deliveryId);
+                if (!delivery)
+                    return;
+                delivery.abandonRequested = true;
+                if (delivery.abandonToken) {
+                    this.mirrorAbandonListener?.(delivery.sessionId, delivery.abandonToken);
+                    this.releaseMirrorDelivery(handle, msg.deliveryId);
+                }
+                return;
+            }
             case "mirror.image.begin": {
+                if (!Number.isSafeInteger(msg.generation)) {
+                    this.failMirrorImageTransfer(handle, "invalid generated image transfer generation");
+                    return;
+                }
+                if (this.isStaleMirrorGeneration(handle, msg.generation)) {
+                    handle.transport.send({
+                        t: "mirror.image.ack",
+                        transferId: msg.transferId,
+                        seq: 0,
+                        generation: msg.generation,
+                    });
+                    return;
+                }
+                const existing = handle.imageTransfers.get(msg.transferId);
+                if (existing) {
+                    const exactReplay = existing.sessionId === msg.sessionId &&
+                        existing.generation === msg.generation &&
+                        existing.totalChars === msg.totalChars &&
+                        JSON.stringify(existing.event) === JSON.stringify(msg.event);
+                    if (!exactReplay) {
+                        this.failMirrorImageTransfer(handle, "conflicting generated image transfer replay");
+                        return;
+                    }
+                    handle.transport.send({
+                        t: "mirror.image.ack",
+                        transferId: msg.transferId,
+                        seq: 0,
+                        generation: msg.generation,
+                    });
+                    return;
+                }
                 if (handle.dead ||
-                    handle.imageTransfers.has(msg.transferId) ||
                     !Number.isSafeInteger(msg.totalChars) ||
                     msg.totalChars <= 0 ||
                     msg.totalChars > RUNNER_IMAGE_MAX_RESULT_CHARS ||
@@ -1473,17 +1991,48 @@ export class RunnerManager {
                 }
                 handle.imageTransfers.set(msg.transferId, {
                     sessionId: msg.sessionId,
+                    generation: msg.generation,
                     event: msg.event,
                     totalChars: msg.totalChars,
                     receivedChars: 0,
                     nextSeq: 1,
                     chunks: [],
                 });
-                handle.transport.send({ t: "mirror.image.ack", transferId: msg.transferId, seq: 0 });
+                handle.transport.send({
+                    t: "mirror.image.ack",
+                    transferId: msg.transferId,
+                    seq: 0,
+                    generation: msg.generation,
+                });
                 return;
             }
             case "mirror.image.chunk": {
+                if (!Number.isSafeInteger(msg.generation)) {
+                    this.failMirrorImageTransfer(handle, "invalid generated image transfer generation");
+                    return;
+                }
+                if (this.isStaleMirrorGeneration(handle, msg.generation)) {
+                    handle.transport.send({
+                        t: "mirror.image.ack",
+                        transferId: msg.transferId,
+                        seq: msg.seq,
+                        generation: msg.generation,
+                    });
+                    return;
+                }
                 const transfer = handle.imageTransfers.get(msg.transferId);
+                if (transfer &&
+                    msg.seq > 0 &&
+                    msg.seq < transfer.nextSeq &&
+                    transfer.chunks[msg.seq - 1] === msg.data) {
+                    handle.transport.send({
+                        t: "mirror.image.ack",
+                        transferId: msg.transferId,
+                        seq: msg.seq,
+                        generation: transfer.generation,
+                    });
+                    return;
+                }
                 if (handle.dead ||
                     !transfer ||
                     msg.seq !== transfer.nextSeq ||
@@ -1500,10 +2049,25 @@ export class RunnerManager {
                     t: "mirror.image.ack",
                     transferId: msg.transferId,
                     seq: msg.seq,
+                    generation: transfer.generation,
                 });
                 return;
             }
             case "mirror.image.commit": {
+                if (!Number.isSafeInteger(msg.generation)) {
+                    this.failMirrorImageTransfer(handle, "invalid generated image transfer generation");
+                    return;
+                }
+                if (this.isStaleMirrorGeneration(handle, msg.generation)) {
+                    handle.imageTransfers.delete(msg.transferId);
+                    handle.transport.send({
+                        t: "mirror.image.ack",
+                        transferId: msg.transferId,
+                        seq: msg.seq,
+                        generation: msg.generation,
+                    });
+                    return;
+                }
                 const transfer = handle.imageTransfers.get(msg.transferId);
                 if (handle.dead ||
                     !transfer ||
@@ -1512,7 +2076,16 @@ export class RunnerManager {
                     this.failMirrorImageTransfer(handle, "invalid generated image transfer commit");
                     return;
                 }
-                handle.imageTransfers.delete(msg.transferId);
+                if (transfer.commitSeq !== undefined) {
+                    if (transfer.commitSeq !== msg.seq) {
+                        this.failMirrorImageTransfer(handle, "conflicting generated image transfer commit");
+                    }
+                    // The original publication owns the eventual ACK/NACK. A replay can
+                    // arrive after its ACK timer elapsed; that eventual result resolves
+                    // the replacement waiter because transferId+seq are stable.
+                    return;
+                }
+                transfer.commitSeq = msg.seq;
                 const event = attachGeneratedImageResult(transfer.event, transfer.chunks.join(""));
                 if (!event) {
                     this.failMirrorImageTransfer(handle, "generated image transfer target changed");
@@ -1524,26 +2097,47 @@ export class RunnerManager {
                     event,
                     transferId: msg.transferId,
                     seq: msg.seq,
+                    generation: transfer.generation,
                 };
                 if (this.bufferForkTargetMessage(handle, mirrored)) {
                     handle.transport.send({
                         t: "mirror.image.hold",
                         transferId: msg.transferId,
                         seq: msg.seq,
+                        generation: transfer.generation,
                     });
                     return;
                 }
                 this.deliverMirrorMessage(handle, mirrored);
                 return;
             }
+            case "mirror.image.abandon": {
+                if (!Number.isSafeInteger(msg.generation))
+                    return;
+                const transfer = handle.imageTransfers.get(msg.transferId);
+                if (transfer && transfer.generation === msg.generation) {
+                    handle.imageTransfers.delete(msg.transferId);
+                }
+                return;
+            }
             case "rotate": {
                 if (handle.dead)
                     return;
+                if (!msg.rotationId || !Number.isSafeInteger(msg.generation)) {
+                    void this.terminateHandle(handle, "invalid Session rotation frame").catch((error) => logTerminationFailure(handle, error));
+                    return;
+                }
                 if (this.bufferForkTargetMessage(handle, msg))
                     return;
                 this.deliverRotateMessage(handle, msg);
                 return;
             }
+            case "rotate.applied": {
+                if (handle.dead)
+                    return;
+                this.deliverRotateAppliedMessage(handle, msg);
+                return;
+            }
             case "terminal.lifecycle.ended": {
                 if (msg.lifecycle === "required") {
                     void this.terminateHandle(handle, `required Terminal exited with status ${msg.status}`).catch((error) => logTerminationFailure(handle, error));
@@ -1589,6 +2183,7 @@ export class RunnerManager {
             return;
         }
         handle.dead = true;
+        handle.failureReason = reason;
         closeOwnedSessionContext(handle);
         // Drop every key mapping to this handle — its launch key AND any rotation
         // aliases (claude `/clear`·`/fork` terminal transfer).
@@ -1601,6 +2196,15 @@ export class RunnerManager {
                 }
             }
         }
+        if (handle.pendingRotation) {
+            // A publication already inside its durable binding write owns both
+            // reservations until that Promise settles. Releasing here would let a
+            // replacement source child open against the old binding while the stale
+            // chain can still commit target/source ownership records.
+            if (!handle.pendingRotation.inFlight) {
+                this.releasePendingNativeRotation(handle, handle.pendingRotation);
+            }
+        }
         const tail = handle.stderr.join("\n");
         const message = tail ? `${reason}\n--- runner log tail ---\n${tail}` : reason;
         if (opts.failActiveResponses !== false) {
@@ -1623,6 +2227,9 @@ export class RunnerManager {
         handle.terminals.clear();
         handle.live.clear();
         handle.imageTransfers.clear();
+        for (const deliveryId of handle.mirrorDeliveries.keys()) {
+            this.releaseMirrorDelivery(handle, deliveryId);
+        }
         handle.transport.close();
     }
     terminateHandle(handle, reason) {
@@ -1801,7 +2408,8 @@ export class RunnerManager {
         handle.activeResponseIds.clear();
         const sessionId = this.currentTerminalSessionId(handle, handle.key);
         for (const responseId of responseIds) {
-            this.mirrorListener?.(sessionId, {
+            rememberTerminalResponse(handle, responseId);
+            this.emitCompensatingMirror(handle, sessionId, {
                 type: "response.failed",
                 responseId,
                 error: {
@@ -1817,13 +2425,32 @@ export class RunnerManager {
         handle.activeResponseIds.clear();
         const sessionId = this.currentTerminalSessionId(handle, handle.key);
         for (const responseId of responseIds) {
-            this.mirrorListener?.(sessionId, {
+            this.emitCompensatingMirror(handle, sessionId, {
                 type: "session.interrupted",
                 sessionId,
                 responseId,
             });
         }
     }
+    /** Crash/termination compensation is intentionally best-effort because it is
+     * a terminal/status edge rather than an ordinary transcript delivery.
+     * Still consume an asynchronous persistence rejection so a dying child
+     * cannot take the parent daemon down with an unhandled rejection. */
+    emitCompensatingMirror(handle, sessionId, event) {
+        if (!this.mirrorListener)
+            return;
+        try {
+            const result = this.mirrorListener(sessionId, event);
+            if (result && typeof result.then === "function") {
+                void Promise.resolve(result).catch((error) => {
+                    logCompensatingMirrorFailure(handle, sessionId, event.type, error);
+                });
+            }
+        }
+        catch (error) {
+            logCompensatingMirrorFailure(handle, sessionId, event.type, error);
+        }
+    }
     /** Track the provider-authoritative response lifecycle. Native-pane busy
      * classification consumes this level directly; output volume is separately
      * grounded in tmux's own activity clock. */
@@ -1834,25 +2461,38 @@ export class RunnerManager {
             case "response.reasoning_summary_text.delta":
             case "response.function_call_output.delta":
             case "response.output_item.done":
+                if (handle.terminalResponseIds.has(event.responseId))
+                    return;
                 handle.activeResponseIds.add(event.responseId);
                 return;
             case "session.interaction.requested":
+                if (handle.terminalResponseIds.has(event.responseId))
+                    return;
                 handle.activeResponseIds.add(event.responseId);
                 return;
             case "response.completed":
             case "response.failed":
             case "session.interrupted":
                 handle.activeResponseIds.delete(event.responseId);
+                rememberTerminalResponse(handle, event.responseId);
                 return;
             case "session.status":
                 if (event.status === "running" && event.responseId) {
+                    if (handle.terminalResponseIds.has(event.responseId))
+                        return;
                     handle.activeResponseIds.add(event.responseId);
                 }
                 else if (event.status !== "running") {
-                    if (event.responseId)
+                    if (event.responseId) {
                         handle.activeResponseIds.delete(event.responseId);
-                    else
+                        rememberTerminalResponse(handle, event.responseId);
+                    }
+                    else {
+                        for (const responseId of handle.activeResponseIds) {
+                            rememberTerminalResponse(handle, responseId);
+                        }
                         handle.activeResponseIds.clear();
+                    }
                 }
                 return;
             case "session.rotated":
@@ -1862,6 +2502,12 @@ export class RunnerManager {
                 return;
         }
     }
+    isStaleMirrorGeneration(handle, generation) {
+        const currentGeneration = handle.pendingRotation?.generation ??
+            handle.completedRotation?.generation ??
+            0;
+        return generation < currentGeneration;
+    }
     openSessionContext(sessionId) {
         if (!this.sessionContextProvider)
             return undefined;
@@ -1880,6 +2526,16 @@ export class RunnerManager {
         }
     }
 }
+function rememberTerminalResponse(handle, responseId) {
+    handle.terminalResponseIds.delete(responseId);
+    handle.terminalResponseIds.add(responseId);
+    while (handle.terminalResponseIds.size > MAX_TERMINAL_RESPONSE_IDS) {
+        const oldest = handle.terminalResponseIds.values().next().value;
+        if (!oldest)
+            break;
+        handle.terminalResponseIds.delete(oldest);
+    }
+}
 function trackedTerminalSubmissions(tracker, data) {
     const pasteStart = "\u001b[200~";
     const pasteEnd = "\u001b[201~";
@@ -1923,8 +2579,8 @@ function trackedTerminalSubmissions(tracker, data) {
             if (command.length > 0 &&
                 (command.includes("\u001b") ||
                     !command.startsWith("/") ||
-                    /^\/(?:clear|fork)(?:\s|$)/u.test(command))) {
-                submissions.push(/^\/(?:clear|fork)(?:\s|$)/u.test(command) ? "rotation" : "turn");
+                    /^\/(?:branch|clear|fork)(?:\s|$)/u.test(command))) {
+                submissions.push(/^\/(?:branch|clear|fork)(?:\s|$)/u.test(command) ? "rotation" : "turn");
             }
             continue;
         }
@@ -2051,6 +2707,28 @@ function attachGeneratedImageResult(event, result) {
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
+function mirrorNackClassification(error) {
+    if (typeof error === "object" && error !== null &&
+        error.mirrorClassification === "ambiguous")
+        return "ambiguous";
+    const statusCode = error instanceof AgentRuntimeError
+        ? error.statusCode
+        : typeof error === "object" && error !== null &&
+            typeof error.statusCode === "number"
+            ? error.statusCode
+            : undefined;
+    return statusCode !== undefined &&
+        statusCode >= 400 && statusCode < 500 &&
+        ![408, 409, 425, 429].includes(statusCode)
+        ? "permanent"
+        : "transient";
+}
+function mirrorAbandonToken(error) {
+    if (typeof error !== "object" || error === null)
+        return undefined;
+    const token = error.abandonToken;
+    return typeof token === "string" && token.length > 0 ? token : undefined;
+}
 function defaultRunnerEntry() {
     if (process.env.RYNX_RUNNER_ENTRY?.trim()) {
         return process.env.RYNX_RUNNER_ENTRY.trim();
@@ -2125,6 +2803,18 @@ function logTerminationFailure(handle, error) {
         error: error instanceof Error ? error.message : String(error),
     }));
 }
+function logCompensatingMirrorFailure(handle, sessionId, eventType, error) {
+    console.error(JSON.stringify({
+        level: "error",
+        type: "runner",
+        event: "compensating_mirror_failed",
+        key: handle.key,
+        sessionId,
+        eventType,
+        pid: handle.child.pid,
+        error: errorMessage(error),
+    }));
+}
 function capabilityForkResult(result) {
     return result.ok
         ? { ok: true }